Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.vishia.java2C
Class Docu.B_ProcessOfTranslation

java.lang.Object
  extended by org.vishia.java2C.Docu.B_ProcessOfTranslation
Enclosing class:
Docu
public class Docu.B_ProcessOfTranslation
extends java.lang.Object

In this chapter the tranlation process of all files is described. It is an overview-chapter.

Constructor Summary
Docu.B_ProcessOfTranslation()
           
 
Method Summary
 void B1_makeAndDependentTypeProcessing()
          This chapter describes the translation process in Java2C.
 void B2_umlDiagram_overview_Java2C()
          The diagramm shows the classes respectively instances which are created in translation process.
 void B3_packageReplacement()
          The package replacement describes, how java files, organized in packages, are mapped to C files, maybe organized in sub directories and in abbreviated named files.
 void B4_gatherAllSourceFiles()
          After the package replacement is recognized, all given source-pathes in the config-file are gathered to detect all java-source-files.
 void b5_getTypeInfoAndTranslate()
          If any type is need for the translation, its ClassData should be present.
 void b6_translatingOrGetStc()
          Some Java sources should be translated, but some other sources mustn't translate, because they are parts of built C libraries.
 void b7_includeGeneration()
          The import statements are not able to use for include generation, because files from the same package are not imported in Java.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Docu.B_ProcessOfTranslation

public Docu.B_ProcessOfTranslation()
Method Detail

B1_makeAndDependentTypeProcessing

public void B1_makeAndDependentTypeProcessing()
This chapter describes the translation process in Java2C. Basic coherences are explained in B3_packageReplacement() and b6_translatingOrGetStc().

The translation process starts calling Java2C_Main.execute(). The command line arguments are parsed and stored before. The sequence diagram shows this operations:

The translation process is conditional and has its own order:

B2_umlDiagram_overview_Java2C

public void B2_umlDiagram_overview_Java2C()
The diagramm shows the classes respectively instances which are created in translation process.

The diagram shows the main instance Java2C top left. It contains the command line process and creates the singleton instance Java2C_Main.singleton. All blue colored instances are created before the translation process starts. The role of CRuntimeJavalikeClassData is explained in B1_makeAndDependentTypeProcessing() in step Three.

Below the JavaSources, referenced with JavaSources.javaSrcTree, there are the top-level packages. The package java is also found there, which is the root of java/lang, java/io etc. The package org as root of org/vishia or adequate are found there too. A user root-package is arranged there also. All packages below the JavaSrcTreePkg.subPkgs are sub-packages from the root respectively from any other sub-package. The JavaSrcTreePkg.pkgIdents then contain the JavaSrcTreeFile-instances of the package in its reference LocalIdents.typeIdents. The file may be translated or not. If its ClassData should be necessary, it will be translated.

The blue colored instances below JavaSources are a representation of the Java source tree gathered in JavaSrcTreeGetter.gatherAllJavaSrcFiles(LocalIdents, java.util.List). Only two packages and one file are shown, but the instances which are created an assigned in this tree are much more: Any Java file is representing with an instance of JavaSrcTreeFile, any package is representing with an instance of JavaSrcTreePkg.

The red bordered shadowy presented instance of LocalIdents is the instance of the package java.lang in the package tree. This instance is referenced from CRuntimeJavalikeClassData.stdTypes too and contains also the standard scalar types and special types. This instance is used to search types per name in any case at least.

The dark yellow colored instances are created while running the first pass and they are used to run the second pass. But the gray colored instances are temporary created while running the translation process of one file.

The cyan colored instances are created while running the first pass or read the stc-file, and they are stored in the LocalIdents.typeIdents-Index. They are able to search in the package path while using in any translation. The ClassData contains the relevant informations about a class type to use from outside.

The dark green bordered instances are the instances of LocalIdents, which are created associated to packages, files, classes. They are necessary to search types which were used.

The fileLevelIdents are built for translating a file and are stored between first and second pass. It references all identifiers which are visible at file level regarding the import statements and all types of the own package.

B3_packageReplacement

public void B3_packageReplacement()
The package replacement describes, how java files, organized in packages, are mapped to C files, maybe organized in sub directories and in abbreviated named files.

The situation in Java is: All files are placed in a well organized package structure. Any java-file takes place in a directory, which is the package directory as part of the package directory tree. The package, which contains the file, is written in the package declaration in the Java source code. The javac-Compiler check that. Any java-file contains only one public class with the same name as the file. The class and file names are package-local valid. It is possible, that more as one file respectively class with the same name is existing, the distinction between files and classes with equal names are its arrangement in the package tree. If any public class is need in compilation process, the file with the equivalent name is searched and translated to get the class. The import statement in Java code declares the visible class names known without their package qualifier. Classes can accessed any time with the full qualified name including the package tree, for example java.util.List instead List, than an import statement isn't necessary, but it's possible. The package tree is defined in a world wide unambiguousness, because it is a practiced rule, that the package tree of a source pool follows the internet address (URL) of the owners, at example org.vishia for sources, which are hosted associated with the internet address www.vishia.org. That is the world of java.

In C an adequate file and name-space structure isn't conventional. A namespace problematic is resolved manually often, at example with fine control of includes. A typically problem is: An additional include necessary by software enhancement may cause name conflicts. The file and package structure in C is hand-made, without established rules.

The solution: A mapping between the Java-package-ruled identifications of classes and files and its representation in C is necessary. That mapping is defined in the config file, the config file is a input parameter of the translator: -if:file, see Java2C_Main#readConfigFile(java.util.Map, org.vishia.java2C.Java2C_Main.ListFileIn, String, org.vishia.mainCmd.Report), Java2C_Main.inputCfg, Java2C_Main#setConfigFile(String).

The config file contains lines such as 
   replace: org/vishia/mainCmd/* =: Jc/*Jc; 
   replace: org.vishia.util.MsgDispatcher =: MsgDisp/*_MSG;
   replace: org.vishia.util.LogMessageFile =: MsgDisp/*_MSG;
   replace: org.vishia.util.* =: J1c/*Jc;
   replace: org/vishia/java2C/test.* =: Java2cTest/*_TestAll;
At left side a package path for java files is named, the right side names the equivalent for the C files and class names. A directory given at the right side (C) is regarded to store the C- and header-files, and get or store the stc-files. The path is a relative path starting at the given output path (cmd line argument -o:outpath) for the generated files. For stc-Files the base is the output path for files, which are to translate, but for stc-files, which are not to translate, the here named path starts at any location of the stc-search path.

The parts of file-name before and after the asterisk * are pre- and suffixes both for the file name and for the name of the struct which reperesents the java-class. The *-part is replaced with the java file respectively class name. If no * is given at right side in the file name part, the file name is given complete. Than the class replacement may be written in parenthesis after them with or without asterisk. Therewith a file with an abbreviating name can named. The struct in the file can be abbreviating too, if only one class is contained in the Java-file, or it can be built regarding the Java class name.

This settings allow a relative free assignment between Java files and class names and their representation in C. The user is responsible for the order of files and classes at C-side. It may be recommended to find out an adequate transparent rule to mapping the C files.

The named pathes of package and file replacement in this division are relative pathes starting from the java source and class search-path (Java-side) respectively (C-side) starting from the include and stc search path or starting from the output path. The here named Java-package pathes should be equivalent the package structure. It means, it should start with the first package (org etc.). The separator between package identifier may be the slash or backslash or the dot. Internally the slash is used. In opposite in Java sources the dot have to be used as separator in package and import statements. The synonymous using of slash or dot allows the user to copy a path without need of correction of coseparators from several sources.

See also b6_translatingOrGetStc().

Technical informations:

B4_gatherAllSourceFiles

public void B4_gatherAllSourceFiles()
After the package replacement is recognized, all given source-pathes in the config-file are gathered to detect all java-source-files. Not all of them are necessary to translate, but all of them are known then. If any type is necessary, it will be looked after the java-file, which represents this type. If a java-file is found, then it's tested, whether the equivalent C-file with the B3_packageReplacement() is existing and whether it is newer as the Java-file. If it is newer, it must not be translated once again. It is strongly, because the C-file may be checked in an source configuration management, it may be tested and so on. Then the stc-file should be exist, see b6_translatingOrGetStc(). But if the Java-file are newer than the c-file, then it is translated. Therefore it is necessary to know all java-sources.

Technical informations:

b5_getTypeInfoAndTranslate

public void b5_getTypeInfoAndTranslate()
If any type is need for the translation, its ClassData should be present. They can be gotten calling LocalIdents.getType(String, LocalIdents) with the String-given type-name. The type-name can be consists of a full qualified package path, or of a partial path.

If a partial path or only the type-name is given, either a import-statement is determined the package path, or the type is found in the current package, or it is a standard-type:

To get the ClassData for any string-given type, the method LocalIdents.getType(String, LocalIdents) have to be called. The instance of LocalIdents should be the locally used one. It may be the ClassData.classLevelIdents, if elements of a class are translated, or a locally instance created in the parenthesis of code blocks. In that case the locally created instances are recognized and searched first. Note, that it is possible to define a class in a code block.

The second parameter of getType(name, fileLevelIdents) should be the GenerateClass.fileLevelIdents or GenerateFile.fileLevelIdents, which refers the LocalIdents at the file level. It includes the import-statement-given one, and the indents of the package (see above). A separate parameter is need, because the fileLevelIdents are that idents from the translated file, where the instance to call LocalIdents.getType(String, LocalIdents) can be a referenced instance with path. Then the fileLevelIdents of the environment of that LocalIdents are not valid to search. Therefore they are not contained in any LocalIdents as member, instead there are either given from the GenerateFile.fileLevelIdents or they have to be null, if a referenced package is used:

If LocalIdents.getType(String, LocalIdents) is called, it is not determined, whether the requested type is existing and whether it is translated. Therefore, internally LocalIdents.getTypeInfo(String, LocalIdents) is called first. This routine can be called from outside too. It doesn't return the ready-to-use ClassData, but the JavaSources.ClassDataOrJavaSrcFile, which are either the ClassData already, or the instance for a translated or not-translated Java-file or package. The interface is implemented at all three variants. If the type isn't known, this routine returns null.

The ClassData are gotten then calling JavaSources.ClassDataOrJavaSrcFile.getClassData(). If the implementing instance are of type ClassData, it returns this. A JavaSrcTreePkg.getClassData() returns null any time, because a package isn't a class. But the JavaSrcTreeFile.getClassData() returns the ClassData of its public class, if the file is translated already, otherwise null.

If the gotten ClassData are null, the translation of the Java-Source or the parsing of the stc-file is started inside LocalIdents.getType(String, LocalIdents). Therefore Java2C_Main.runRequestedFirstPass(JavaSrcTreeFile, String) is called with the given JavaSrcTreeFile - instance. There, it is detected whether a translation is necessary or the parsing of the stc-file is proper to get the ClassData of the type. See b6_translatingOrGetStc().

The standard-types from java.lang and the simple types int, float etc. are found because LocalIdents.getTypeInfo(String, LocalIdents) searches in the Java2C_Main.standardClassData.CRuntimeJavalikeClassData.stdTypes too.

Any type, which isn't a standard-type created and contained in CRuntimeJavalikeClassData.singleton, is represented by a instance of JavaSrcTreeFile, independent whether it should be never translated. But it isn't necessary, that a Java-file is represented too. Some files are existing as Java-files, but there are not taken into account for translation, because they are present in C as library-content. Then they have to be presented by a stc-file (structure of Java-file). The stc-file maps the content of the appearance in C (in the header-file) too.

See also B3_packageReplacement(). If a unknown Java-file is used, but its package is named in the package-replacement it the form pkg.*, then a JavaSrcTreeFile is created with the known replacement-informations and the information 'not to translate'. Because of the existence of the JavaSrcTreeFile, the associated stc-file is searched and parsed. It builds the ClassData then.

b6_translatingOrGetStc

public void b6_translatingOrGetStc()
Some Java sources should be translated, but some other sources mustn't translate, because they are parts of built C libraries. There may be the absence of parallelism in translation at Java side and at C side. At Java side the translation may be prevented by supply class files instead java sources. But in practice all files may be given as Java source. The translation process detects the necessity of translation, it is lightweight alterable

But in C it is much stronger. Tested functionality is compiled into libraries and offered to use in several applications. Therefore some Java sources may be translated to C and provided in a C library. They shouln't be re-translated, also if they may be adjusted in Java. If their modification is necessary to use to test in C, first the libraries should be built newly. than the usage is translated and linked.

Another issue for non-translating is: Some Java-files emulates parts of functionality, which are implemented in another way in the target system. The implementing files of target are written in C immediately, they are fitted to hardware requirements mostly.

Therefore not all found Java sources should be translated into C in the current session. The sources which may be translated are named in the config-file with lines (at ex) 
  translate: org / vishia/exampleJava2C/java4c/ *.java;
  translate: org / vishia/util/MsgDispatcher.java;
There may be named individually files or whole packages with all files.

If a Java file is found as depending type, and this file is not in the list of files to translate, a equivalent .stc-File should be found (structure file). The stc-file is searched with the same path and name as the translated C- or header-file, but with extension .stc. The physically directory is determined by the stc-search path. It is named in the config-file with setting (at example): 
 stcPath: ., ../../CRuntimeJavalike, "../../CRuntimeJavalike/J1c" , "../../CRuntimeJavalike/stc";
or with cmd line argument -stcpath: too (planned). The shown relative path is related to the calling working directory, an absolute path is possible too. Thereby a library-provided C file may have its stc files adequate to header files for C compilation in a library-oriented stc-directory. It may be the same as the include directory, where the related headeres are stored.

While running the Java2C translation process found C- and header files are tested in timestamp against the Java source. If the java source is older as both C and H, and a actual stc-file is existing too, the translation of the Java file is suppressed in favour of reading the stc-file. The stc-file contains all informations, which are necessary by usage of the class in another translation context (available fields and methods of the class, their types, override-able properties of methods etc).

The stc-files are built automatically in the translation process, and they are is placed beside the generated header files. There they are found for a later translation. The stc-files which are associated to libraries or to manual written C code are searched in the stc-search-path which can name more as one position in the file system.

b7_includeGeneration

public void b7_includeGeneration()
The import statements are not able to use for include generation, because files from the same package are not imported in Java. But its include is necessary. The import statements are used to bring the imported classes in visibility.

An #include "..."statement is generated if an external type is used and its definition have to be known. An include is not necessary if a type is used only as a reference-type. For references a forward declaration of the type (struct TYPE_t* name;) declares the type as structure pointer. The type-definition itself should not be known. It is a able-to-use property of C to do so and it economized the number of included files. That precaution is necessary to prevent circular includes: If a type is needed, but in that structure the current declared type is needed too, a circular include would be produced elsewhere. That would be force a compiler error at C level.

The ClassData of the type is searched calling LocalIdents.getType(String, LocalIdents). There the ClassData.sFileName contains the file name contingently with a directory where the header file is located adequate to the association between Java package path and C path in the config file.

The using of the type may be occurred in the first or in the second pass of translation. The first pass produces the .h-file, the second pass produced the .c-File. So a using of a type leads to include in the .h- or .c-File. The methods GenerateFile.addIncludeC(String sFileName, String comment) and GenerateFile.addIncludeH(String sFileName, String comment) represents both possibilities. This methods may be called more as one time for the same file. Therefore the TreeMap GenerateFile.includes saves the types for including while running the first or second pass for this file, and the lines for #include "..." in the H- and C-file are produced after finishing the passes.

The routine GenerateFile.addIncludeH(String sFileName, String comment) is called inside the first pass
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD