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.

  • First the parsers for Java source code and stc-files are initialized calling Java2C_Main.initZbnfParser(). Their syntax is defined in the external files Java2C.zbnf and Java2Cstc.zbnf located in the syntax path given by command line argument -syntax:SYNTAXDIR, see Java2C_Main#sSyntaxPath.
  • Second Java2C_Main#readConfigFile(java.util.Map, org.vishia.java2C.Java2C_Main.ListFileIn, String, org.vishia.mainCmd.Report) is called to get the content of the config file. The config file describes the package and file replacement from Java 2 C especially. The result is retrievable via Java2C_Main.inputCfg.
  • Third the standard types are created. It is done while creating the instance CRuntimeJavalikeClassData. The standard types contains the language scalar types, some special types which are present in C especially (CRuntimeJavalikeClassData.clazz_s0 for zero terminate string literals, CRuntimeJavalikeClassData.clazz_va_argRaw for variable arguments etc). Some classes of java.lang or java.util are defined their too. Therefore the standard packages are created as instances of JavaSrcTreePkg. The instance JavaSrcTreePkg.pkgIdents of the instance for package java.lang is used as CRuntimeJavalikeClassData.stdTypes. The language scalar types are stored there too. The types in java.lang are available without any package or import declaration, adequate to the behaviour of the Java compiling process.
    
    The existence of all respectively some files from the standard Java classes are declared also in CRuntimeJavalikeClassData. Its content is defined either in the associated stc-Files or it is defined hard-coded. The stc-Files are placed in the directories of the CRuntimeJavalike-Implementation of the basic system in C associated to the manually programmed C-sources of them.
  • Fourth all available Java source files in the given source path are gathered. The java source path is given by command line argument -srcpath: or in the config file. All files at all locations at file system are gathered. The Java files itself are not red, only their existence is tested. The packages (directories in file system) are red out. In future extension jar files and class files should be regarded too (not implemented in version 0.9). The class files are non-translate-able, but their existence for using are gathered. With this extension only that packages should be analyzed, which are really used, not all. The gathering process should be dispersed, first only the first needed packages etc. It is necessary because voluminous directory trees and jar archives shouldn't produce unnecessary informations.
    
    The result of this gathering processes is a tree of instances of JavaSrcTreePkg and JavaSrcTreeFile, which are available when calling LocalIdents.getTypeInfo(String, LocalIdents). The first level packages are assigned to the CRuntimeJavalikeClassData.stdTypes. Therefore all used types of the Java sources are able to locate starting with the first package.
    
    The return type of LocalIdents.getTypeInfo(String, LocalIdents) is a instance of JavaSrcTreeFile or JavaSrcTreePkg. The files may be translated yet or not. If the ClassData are need for another translation process, the translating process of the found file is started. Especially it is done calling LocalIdents.getType(String, LocalIdents) to get ClassData.
  • Fifth all files of JavaSources.listJavaSrcFilesToTranslate are used to run the first pass calling Java2C_Main#runFirstPassFile(JavaSrcTreeFile, boolean). The List JavaSourceFilesToTranslate were filled while gathering the Java Source tree.
    
    The first pass checks, whether the translation is necessary testing the time stamp. It is done in the called routine Java2C_Main#runFirstPassFile(JavaSrcTreeFile, boolean). Thereby instances of GenerateFile are created and stored in a List Java2C_Main.allJavaFilesToRunSecondPass.
  • Sixth the second pass is run for all classes which are processed in the first pass calling GenerateFile#runSecondPassFile(Report). The files for second pass are stored in the Java2C_Main.allJavaFilesToRunSecondPass.

  The sequence diagram shows this operations:
  
  The translation process is conditional and has its own order:

  • To translate? It is tested whether the a requested file is to translate or not, evaluating JavaSrcTreeFile.isToTranslate(). If it isn't to translate, the stc-file is parsed calling Java2C_Main#readStructToClassData(JavaSrcTreeFile, String, File) to get necessary ClassData. It is for library-represented C-compilation units of for hand-written C-Files.
  • should translate? If the file is to translate, the timestamp of java source and the translating results: C-source, header, stc-file are tested. If the java source is older, the stc-file is read too to get the ClassData. The result files are existing yet. The reasons to do so are twice:
    • First calculation time of translating is economized, because the parsing and translating of a complex Java source file needs some more calculation time (may be 1..2 seconds) in comparison to parsing the stc-file (milliseconds).
    • Second a new produces C-source should be tested more carefully in comparison to a source, which is not changed. The C-sources may be stored in a source-version-system, unnecessary produced sources are disturbing.
  • Translation process: The files will be parsed with the ZBNF-parser, than an instance of GenerateFile is created and added to the list Java2C_Main.allJavaFilesToRunSecondPass. With that instance the GenerateFile#runFirstPassFile(JavaSrcTreeFile, boolean) is execute. It produces and sets ClassData to the JavaSrcTreeFile.classData. The ClassData contains all informations to run the second pass and to use the class in other first or second passed.
  • Recursive call of first pass: If a type is need in any first or second pass, either its first pass is running recursively yet calling LocalIdents.getType(String, LocalIdents) and inside runFirstPassFile(JavaSrcTreeFile, boolean) with the found instance, or the stc-file is parsed instead to get the ClassData. The dependencies of sources determine the order of first passes.

• 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:
  
  

  • The config-file is read and parsed in the method Java2C_Main.readConfigFile(Java2C_Main.ListFileIn, String, Report).
  • The configuration is written in Java2C_Main.InputFileParseResult using org.vishia.zbnf.ZbnfJavaOutput.
  • The package replacement is contained in Java2C_Main.inputCfg and there in the implementation instance Java2C_Main.InputFileParseResult.packageReplacement.
  • A replacement for a given package can be searched using the public known Java2C_Main.inputCfg and there calling ConfigSrcPathPkg_ifc.getCPathPrePostfixForPackage(String).
  • The implementation of that interface method is Java2C_Main.InputFileParseResult.getCPathPrePostfixForPackage(String). It accesses the private known TreeMap Java2C_Main.InputFileParseResult.packageReplacement.
  • This method is called only inside JavaSrcTreeGetter.gatherAllJavaSrcFiles(LocalIdents, java.util.List). The replacement for the found Java-file is stored in the JavaSrcTreeFile.sFilePathC and adequate elements.
  • Whether or not a Java-file is to translate to get the type informations, or whether a stc-file is to be read, depends on the existing of a Java-file. It is tested calling TODO

• 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:

  • The config-file is read and parsed in the method Java2C_Main.readConfigFile(Java2C_Main.ListFileIn, String, Report).
  • The configuration is written in Java2C_Main.InputFileParseResult.
  • The post-processing of the parse-result is done in Java2C_Main.execute(). There is filled or set:
  • Java2C_Main.listJavaSrcpath: All pathes in file system (maybe relative) where java-src-files are searched.
  • Java2C_Main.listInputToTranslate: All Input files to translate primary. More files will be translated of dependencies exists.
  • The class JavaSrcTreeGetter is created temporary,
  • JavaSrcTreeGetter.gatherAllJavaSrcFiles(LocalIdents, java.util.List) is called. It checks all given pathes in the file system, containing in the second argument Java2C_Main.listJavaSrcpath.
  • For all detect directories in the source-paths, instances of JavaSrcTreePkg are created and arranged as children of the top-level-container for the root-packages are created. The root-packages are referenced in Java2C_Main.javaSources and there in JavaSources.javaSrcTree.
  • For all detect java-source-files in the source-paths, instances of JavaSrcTreeFile are created and arranged in the JavaSrcTreePkg.pkgIdents.LocalIdents.typeIdents-reference.
  • At least a report is written, which contains the situation of sources. This is included in the generated report-file in the chapter ===All found Java source files===, done in JavaSrcTreeGetter.gatherAllJavaSrcFiles(LocalIdents, java.util.List)

• 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:

  • All classes of the package (in all files) are copied from the JavaSrcTreePkg.pkgIdents in the File-local valid GenerateFile.fileLevelIdents.
  • The GenerateFile.fileLevelIdents is then filled with the types from all import-statements. Either an import-statement represents one class, or it is written with .* and all classes of the named package are added there. This information is put calling GenerateFile#evaluateImports(org.vishia.zbnf.ZbnfParseResultItem), which is called at begin of the first pass of translation.
  • All All type-informations of classes, which are contained in the own file beside the public class, are contained in JavaSrcTreePkg.pkgIdents. There are filled calling GenerateFile.registerClassInFile(ClassData) in the first pass, before any detail evaluation of a class of this file.

  
  
  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:

  • Type - than the GenerateFile.fileLevelIdents should be used.
  • pkg.Type - than the fileLevelIdents-parameter should be null to search type

  
  
  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

  • in the routine GenerateFile#write_HeaderContent(GenerateFile, ZbnfParseResultItem, String, ClassData, ClassData[]) for super classes and interfaces.
  • in the routine GenerateClass#createFieldDataNewObject(ZbnfParseResultItem, ZbnfParseResultItem, ZbnfParseResultItem, LocalIdents, String, ClassData, char, char, ClassData, char, ZbnfParseResultItem) if the new Object is created as class variable or static variable.
    In this cases an include of the type is necessary. The including of super classes and interfaces can't force circular includes, because the current class can't be a superclass of its superclass in Java too.
    
    The routine GenerateFile.addIncludeC(String,String) is called sometimes in the second pass, if a type is need. It may be necessary mostly, because a needed type will be accessed mostly, than its structure should be known. Not necessary includes in the C-file are not a problem any time.