001/****************************************************************************
002 * Copyright/Copyleft:
003 *
004 * For this source the LGPL Lesser General Public License,
005 * published by the Free Software Foundation is valid.
006 * It means:
007 * 1) You can use this source without any restriction for any desired purpose.
008 * 2) You can redistribute copies of this source to everybody.
009 * 3) Every user of this source, also the user of redistribute copies
010 *    with or without payment, must accept this license for further using.
011 * 4) But the LPGL is not appropriate for a whole software product,
012 *    if this source is only a part of them. It means, the user
013 *    must publish this part of source,
014 *    but don't need to publish the whole source of the own product.
015 * 5) You can study and modify (improve) this source
016 *    for own using or for redistribution, but you have to license the
017 *    modified sources likewise under this LGPL Lesser General Public License.
018 *    You mustn't delete this Copyright/Copyleft inscription in this source file.
019 *
020 * @author Hartmut Schorrig: hartmut.schorrig@vishia.de, www.vishia.org
021 * @version 0.93 2011-01-05  (year-month-day)
022 *******************************************************************************/ 
023package org.vishia.java2C;
024
025import org.vishia.java2C.SecondPass;
026
027
028/*Test
029
030 */
031
032
033/**This class contains no code, only documentation. Every spanned subject of the translator 
034 * is described associated to a method. The description contains some links to the java code.
035 * So javadoc generates a well readable documentation. Use the private-view documentation
036 * to trace to all links, because most of methods and fields are package private or private.  
037 * 
038 * @author JcHartmut
039 *
040 */
041public class Docu
042{
043  
044  /**This chapter provides an overview, where and how Java2C should be used. 
045   */
046  public class A_InvokationAndEnvironmentConditions
047  {
048    /**The writing of sources in Java instead in C or C++ has the advantage, that all features
049     * of new programming systems, where Java is a signifying member, can be used for the software development.
050     * The programming language C should be recognized as a language for machine-implementing closeness.
051     * C isn't the best appropriate language for modern software engineering. At example
052     * using UML with C as base language would be a non-effective solution.
053     * <br><br>
054     * The Java2C-Translator allows firstly writing a few sources in Java beside other sources in C, 
055     * than more and more using Java as source language by recommendation of using UML and Object Oriented technologies.
056     * The deciding matter is the usage of a modern software technology. Java2C is only a helper
057     * to link this software technology with the classic software development processes.   
058     */
059    void A1_applying_goals(){}
060    
061    /**The Java sources, which can translated to C, are not typical Java applications 
062     * in a Java-possible environment. For such requirements a Java-virtual machine should be used. 
063     * If some C- or C++-written parts should be integrated thereby, either
064     * the JNI (Java Native Interface) should be used, or some interfaces at example socket connection
065     * can be used to connect parts, which runs under Java, with parts, which are written in C(++).
066     * <br><br>
067     * The Java-sources can be conceptualize regarding requirements of embedded programming, 
068     * which are typical thinking in a C-matter. But it are formulated in the world of Java.
069     * At example that is:
070     * <ul>
071     * <li>Static data definition instead elaborately using of new Objects: 
072     *   Typical Java applications use the new-operator to define
073     *   data when it are necessary. The programming is more simple for dynamic tasks, because 
074     *   the data needn't be planned in detail. Last not least the garbage collection concept helps
075     *   to prevent unnecessary data garbage and to supply the necessary memory space.
076     *   <br><br> 
077     *   But in embedded applications such dynamic memory allocations
078     *   are undesirable. Therefore a static assessment of all necessary data can be done in Java too, 
079     *   all data should defined in an initial phase. In a UML-thinking they are <i>composition</i>-data than.
080     *   Java supports the building of compositions with the <code>final</code> keyword on references
081     *   used together with a new statement:
082     *   <pre>
083     *   final Type data = new Type(initialArguments);
084     *   </pre>
085     *   Such data are disposed in C as embedded data. It is possible to define the data in only one
086     *   memory block, which can instantiated as a static area in the ambient C main-definitions.
087     * <li>The usage of interfaces is another example. Interfaces are the first way to break dependencies
088     *   between software modules. The modules can be programmed and tested independently. The exchange
089     *   of data and control is defined using Java-interfaces. The interfaces can be implemented
090     *   in some test environment classes to test a module, though they are implemented 
091     *   in the conclusive classes for using. The interface concept is known in UML as a basic concept too.
092     *   <br><br>
093     *   The usage of interfaces needs a concept of <i>virtual methods</i> (C++-slang). It is either
094     *   an additional effort to use such, or it is a problem of safety. In C simple prototype declarations
095     *   of routines are used instead, the implementation of the routines is separated from them,
096     *   the implementation can be written and test as an independent module too while providing
097     *   test routines for the linking of a module test for the environment.
098     *   <br><br>
099     *   Java2C supports using interfaces at Java-level (source-writing, UML) and translating it to
100     *   simple method calls for the C-implementation level, if the implementation in the target system
101     *   is defined fix and no polymorphism is need.  
102     * <li>There are some other details too for embedded-like Java-programming, see some examples.
103     * </ul>
104     * 
105     *       
106     */
107    void A2_Java_sources_for_embeddedSoftware(){}
108    
109    
110    /**While translation of one Java files all types, which are used there, should be known, 
111     * a simple plain generation from one Java file to one C-file isn't possible. 
112     * There are some informations about used types to respect.
113     * Therefore either all Java sources which are depending together are translated in one session,
114     * or used classes have to be presented with so named stc-files (STruCture of classes). 
115     * The stc-files were produced from an previous other session of translating of the appropriate
116     * sources, or they were translated from header files of manual written C-parts (TODO) respectively hand written.
117     * The order of generation depends on the usage of the types. If a type-information is need, 
118     * the appropriate source is start to translate nested in the current translation. 
119     * To prevent cyclically dependencies, the translation process is separated in two passes, first and second.
120     * The first pass detects all types, the header file thereby, the second pass creates the C-file.
121     * <br><br>
122     * The java sources should be provided in the Java-well-known package structure maybe located at more as one
123     * path on file the system (the Java source path for Java2C). All found files are gathered, 
124     * a tree of known java files is built to declare package and file identifiers.  
125     * There is an assignment between Java package and file-in-package positions 
126     * and directories and pre- and suffixes for file names and class (<code>struct</code>-) names at C-side 
127     * to map the Java-file and class-structure to a C-file and namespace structure. The assignment is given
128     * as input for the translater in the config-file.
129     * <br><br>
130     * In the config-file is defined, which sources should be translated, and which sources mustn't translate
131     * because there are existent in C either in libraries provided from an extra session 
132     * or there are existent manually written in C. The Java2C-translator searches the appropriate stc-file
133     * for existent C-sources, therefore a stc-search-path is used. The stc-files for several libraries and
134     * other C-modules can be dispersed on the file system, adequate to Java-sources. 
135     * <br><br>
136     * It is possible that some types are not found as stc-file, because there contain 
137     * simple methods or data in a simple class. In this case their existence is presumed, and the types
138     * of identifiers are accepted as {@link CRuntimeJavalikeClassData#clazz_unknown}. 
139     * Than no additional type conversions are done. The expression with such identifier is submitted in C like found in Java.
140     * 
141     */
142    void A2_Java_sources_to_translate(){}
143    
144    /**The invocation of Java2C is command-line-oriented. Some settings are given in a config-file. Some options
145     * may be given per command-line argument. In this form the translator is able to embed at example
146     * in a ANT-environment of another maker.
147     * <br><br>
148     * <ul>
149     * <li>The command line options are explained appropriated to the {@link Java2C#main(String[])}.
150     * <li>The content of config-file is explained appropriated to 
151     * {@link Java2C_Main#setConfigFile(String)}. 
152     * see also {@link Docu.B_ProcessOfTranslation#B3_packageReplacement()}.
153     * <ul>
154     * In the Java2C-supplying bundle hosted at {@linkplain http://sourceforge.net/projects/java2c/} contains examples of usage.
155     * 
156     */
157    void A4_invoke_Java2C(){}
158  }
159  
160  
161  
162  /**In this chapter the tranlation process of all files is described. It is an overview-chapter.
163   */
164  public class B_ProcessOfTranslation
165  {
166    
167    /**This chapter describes the translation process in Java2C.
168     * Basic coherences are explained in {@link #B3_packageReplacement()} and {@link #b6_translatingOrGetStc()}.
169     * <br><br>
170     * The translation process starts calling {@link Java2C_Main#execute()}. The command line arguments 
171     * are parsed and stored before. 
172     * <ul><li>
173     * First the parsers for Java source code and stc-files are initialized 
174     * calling {@link Java2C_Main#initZbnfParser()}. Their syntax is defined in the external files 
175     * <code>Java2C.zbnf</code> and <code>Java2Cstc.zbnf</code> located in the syntax path given by
176     * command line argument <code>-syntax:SYNTAXDIR</code>, see {@link Java2C_Main#sSyntaxPath}.
177     * <li>
178     * Second {@link Java2C_Main#readConfigFile(java.util.Map, org.vishia.java2C.Java2C_Main.ListFileIn, String, org.vishia.mainCmd.Report)}
179     * is called to get the content of the config file. The config file describes 
180     * the package and file replacement from Java 2 C especially.
181     * The result is retrievable via {@link Java2C_Main#inputCfg}. 
182     * <li>
183     * Third the standard types are created. It is done while creating the instance {@link CRuntimeJavalikeClassData}.
184     * The standard types contains the language scalar types, some special types which are present in C especially
185     * ({@link CRuntimeJavalikeClassData#clazz_s0} for zero terminate string literals, {@link CRuntimeJavalikeClassData#clazz_va_argRaw}
186     * for variable arguments etc). Some classes of <code>java.lang</code> 
187     * or <code>java.util</code> are defined their too. Therefore the standard packages are created 
188     * as instances of {@link JavaSrcTreePkg}.
189     * The instance {@link JavaSrcTreePkg#pkgIdents} of the instance for package <code>java.lang</code>
190     * is used as {@link CRuntimeJavalikeClassData#stdTypes}. The language scalar types are stored there too.
191     * The types in <code>java.lang</code> are available without any package or import declaration, 
192     * adequate to the behaviour of the Java compiling process.
193     * <br><br>
194     * The existence of all respectively some files from the 
195     * standard Java classes are declared also in {@link CRuntimeJavalikeClassData}. 
196     * Its content is defined either in the associated stc-Files or it is defined hard-coded. 
197     * The stc-Files are placed in the directories of the <code>CRuntimeJavalike</code>-Implementation 
198     * of the basic system in C associated to the manually programmed C-sources of them.
199     * <li>
200     * Fourth all available Java source files in the given source path are gathered. 
201     * The java source path is given by command line argument
202     * <code>-srcpath:</code> or in the config file. All files at all locations at file system
203     * are gathered. The Java files itself are not red, only their existence is tested. 
204     * The packages (directories in file system) are red out. In future extension jar files and class files
205     * should be regarded too (not implemented in version 0.9). The class files are non-translate-able, 
206     * but their existence for using are gathered. With this extension only that packages should be analyzed, 
207     * which are really used, not all.
208     * The gathering process should be dispersed, first only the first needed packages etc. It is necessary
209     * because voluminous directory trees and jar archives shouldn't produce unnecessary informations. 
210     * <br><br>
211     * The result of this gathering processes is a tree of instances of {@link JavaSrcTreePkg} and 
212     * {@link JavaSrcTreeFile}, which are available when calling {@link LocalIdents#getTypeInfo(String, LocalIdents)}.
213     * The first level packages are assigned to the {@link CRuntimeJavalikeClassData#stdTypes}.
214     * Therefore all used types of the Java sources are able to locate starting with the first package.
215     * <br><br> 
216     * The return type of {@link LocalIdents#getTypeInfo(String, LocalIdents)} is a instance of {@link JavaSrcTreeFile}
217     * or {@link JavaSrcTreePkg}. The files may be translated yet or not. If the {@link ClassData}
218     * are need for another translation process, the translating process of the found file is started. 
219     * Especially it is done calling 
220     * {@link LocalIdents#getType(String, LocalIdents)} to get ClassData.
221     *     
222     * <li>
223     * Fifth all files of {@link JavaSources#listJavaSrcFilesToTranslate} are used to run the first pass 
224     * calling {@link Java2C_Main#runFirstPassFile(JavaSrcTreeFile, boolean)}. 
225     * The List JavaSourceFilesToTranslate were filled while gathering the Java Source tree.
226     * <br><br>
227     * The first pass checks, whether the translation is necessary testing the time stamp. It is done
228     * in the called routine {@link Java2C_Main#runFirstPassFile(JavaSrcTreeFile, boolean)}.
229     * Thereby instances of {@link GenerateFile} are created and stored in a List 
230     * {@link Java2C_Main#allJavaFilesToRunSecondPass}.
231     * 
232     * <li>
233     * Sixth the second pass is run for all classes which are processed in the first pass 
234     * calling {@link GenerateFile#runSecondPassFile(Report)}. The files for second pass
235     * are stored in the {@link Java2C_Main#allJavaFilesToRunSecondPass}. 
236     * </ul>
237     * The sequence diagram shows this operations: 
238     * <img src="../../../../Java2C/img/TranslationPrc_sqdJava2C.png" />
239     * <br><br>
240     * The translation process is conditional and has its own order:
241     * <ul>
242     * <li>
243     * To translate? It is tested whether the a requested file is to translate or not, 
244     * evaluating {@link JavaSrcTreeFile#isToTranslate()}. If it isn't to translate,
245     * the stc-file is parsed calling {@link Java2C_Main#readStructToClassData(JavaSrcTreeFile, String, File)}
246     * to get necessary {@link ClassData}.
247     * It is for library-represented C-compilation units of for hand-written C-Files.
248     * <li> 
249     * should translate? If the file is to translate, the timestamp of java source and the translating results:
250     * C-source, header, stc-file are tested. If the java source is older, the stc-file is read too 
251     * to get the {@link ClassData}. The result files are existing yet. 
252     * The reasons to do so are twice:
253     * <ul><li>First calculation time of translating is economized, because the parsing and translating 
254     *   of a complex Java source file needs some more calculation time (may be 1..2 seconds) 
255     *   in comparison to parsing the stc-file (milliseconds).
256     * <li>Second a new produces C-source should be tested more carefully in comparison to a source,
257     *   which is not changed. The C-sources may be stored in a source-version-system, unnecessary
258     *   produced sources are disturbing.
259     * </ul>    
260     * <li>
261     * Translation process: The files will be parsed with the ZBNF-parser,
262     * than an instance of {@link GenerateFile} is created and added to the list {@link Java2C_Main#allJavaFilesToRunSecondPass}.
263     * With that instance the {@link GenerateFile#runFirstPassFile(JavaSrcTreeFile, boolean)} is execute.
264     * It produces and sets {@link ClassData} to the {@link JavaSrcTreeFile#classData}. 
265     * The ClassData contains all informations to run the second pass and to use the class in other 
266     * first or second passed.
267     * <li>
268     * Recursive call of first pass: If a type is need in any first or second pass, 
269     * either its first pass is running recursively yet calling
270     * {@link LocalIdents#getType(String, LocalIdents)} and inside
271     * {@link runFirstPassFile(JavaSrcTreeFile, boolean)} with the found instance, or the stc-file is parsed instead 
272     * to get the {@link ClassData}. The dependencies of sources determine the order of first passes.
273     * </ul>
274     */
275    public void B1_makeAndDependentTypeProcessing(){}
276
277
278    
279    /**The diagramm shows the classes respectively instances which are created in translation process.
280     * <br>
281     * <img src="../../../../Java2C/img/overview_omdJava2C.png" />
282     * <br>
283     * The diagram shows the main instance {@link Java2C} top left. It contains the command line process
284     * and creates the singleton instance {@link Java2C_Main#singleton}. All blue colored instances are created
285     * before the translation process starts. The role of {@link CRuntimeJavalikeClassData} 
286     * is explained in {@link #B1_makeAndDependentTypeProcessing()} in step Three.
287     * <br><br>
288     * Below the JavaSources, referenced with {@link JavaSources#javaSrcTree}, there are the top-level packages.
289     * The package <code>java</code> is also found there, which is the root of <code>java/lang</code>, <code>java/io</code> etc.
290     * The package <code>org</code> as root of <code>org/vishia</code> or adequate are found there too. 
291     * A user root-package is arranged there also. All packages below the {@link JavaSrcTreePkg#subPkgs} are sub-packages from the root
292     * respectively from any other sub-package. The {@link JavaSrcTreePkg#pkgIdents} 
293     * then contain the {@link JavaSrcTreeFile}-instances of the package in its reference {@link LocalIdents#typeIdents}.
294     * The file may be translated or not. If its {@link ClassData} should be necessary, it will be translated.
295     * <br><br>
296     * The blue colored instances below {@link JavaSources} are a representation of the Java source tree 
297     * gathered in {@link JavaSrcTreeGetter#gatherAllJavaSrcFiles(LocalIdents, java.util.List)}.
298     * Only two packages and one file are shown, but the instances which are created an assigned in this tree
299     * are much more: Any Java file is representing with an instance of {@link JavaSrcTreeFile},
300     * any package is representing with an instance of {@link JavaSrcTreePkg}. 
301     * <br><br>
302     * The red bordered shadowy presented instance of {@link LocalIdents} is the instance of the
303     * package <code>java.lang</code> in the package tree. This instance is referenced 
304     * from {@link CRuntimeJavalikeClassData#stdTypes} too and contains also the standard scalar types
305     * and special types. This instance is used to search types per name in any case at least.
306     * <br><br>
307     * The dark yellow colored instances are created while running the first pass 
308     * and they are used to run the second pass.
309     * But the gray colored instances are temporary created while running the translation process of one file.
310     * <br><br>
311     * The cyan colored instances are created while running the first pass or read the stc-file,
312     * and they are stored in the {@link LocalIdents#typeIdents}-Index. They are able to search in the package path
313     * while using in any translation. The {@link ClassData} contains the relevant informations 
314     * about a class type to use from outside.
315     * <br><br>
316     * The dark green bordered instances are the instances of {@link LocalIdents}, which are created 
317     * associated to packages, files, classes. They are necessary to search types which were used.
318     * <br><br>
319     * The <code>fileLevelIdents</code> are built for translating a file and are stored between first and second pass.
320     * It references all identifiers which are visible at file level regarding the import statements
321     * and all types of the own package.
322     */
323    public void B2_umlDiagram_overview_Java2C(){}
324    
325    /**The package replacement describes, how java files, organized in packages, are mapped to C files, 
326     * maybe organized in sub directories and in abbreviated named files.
327     * <br><br>
328     * The situation in Java is: All files are placed in a well organized package structure. 
329     * Any java-file takes place in a directory, which is the package directory 
330     * as part of the package directory tree. 
331     * The package, which contains the file, is written in the package declaration in the Java source code.
332     * The javac-Compiler check that. Any java-file contains only one public class with the same name as the file.
333     * The class and file names are package-local valid. 
334     * It is possible, that more as one file respectively class with the same name is existing, 
335     * the distinction between files and classes with equal names are its arrangement in the package tree.
336     * If any public class is need in compilation process, the file with the equivalent name is searched
337     * and translated to get the class. The import statement in Java code declares the visible class names
338     * known without their package qualifier. Classes can accessed any time with the full qualified name 
339     * including the package tree, for example <code>java.util.List</code> instead <code>List</code>,
340     * than an import statement isn't necessary, but it's possible. The package tree is defined
341     * in a world wide unambiguousness, because it is a practiced rule, 
342     * that the package tree of a source pool follows the internet address (URL) of the owners,
343     * at example <b>org.vishia</b> for sources, which are hosted associated with the internet address
344     * <code>www.vishia.org</code>. That is the world of java.
345     * <br><br>
346     * In C an adequate file and name-space structure isn't conventional. 
347     * A namespace problematic is resolved manually often, at example with fine control of includes. 
348     * A typically problem is: An additional include necessary by software enhancement may cause name conflicts.
349     * The file and package structure in C is hand-made, without established rules.
350     * <br><br>
351     * The solution: A mapping between the Java-package-ruled identifications of classes and files 
352     * and its representation in C is necessary. That mapping is defined in the config file, 
353     * the config file is a input parameter of the translator: <code>-if:file</code>, 
354     * see {@link Java2C_Main#readConfigFile(java.util.Map, org.vishia.java2C.Java2C_Main.ListFileIn, String, org.vishia.mainCmd.Report)},
355     * {@link Java2C_Main#inputCfg}, {@link Java2C_Main#setConfigFile(String)}.
356     * <br><br>
357     * The config file contains lines such as
358     * <pre>
359     *   replace: org/vishia/mainCmd/* =: Jc/*Jc; 
360     *   replace: org.vishia.util.MsgDispatcher =: MsgDisp/*_MSG;
361     *   replace: org.vishia.util.LogMessageFile =: MsgDisp/*_MSG;
362     *   replace: org.vishia.util.* =: J1c/*Jc;
363     *   replace: org/vishia/java2C/test.* =: Java2cTest/*_TestAll;
364     * </pre>  
365     * At left side a package path for java files is named, the right side names the equivalent 
366     * for the C files and class names. A directory given at the right side (C) is regarded 
367     * to store the C- and header-files, and get or store the stc-files. The path is a relative path
368     * starting at the given output path (cmd line argument <code>-o:outpath</code>) for the generated files.
369     * For stc-Files the base is the output path for files, which are to translate, but for stc-files,
370     * which are not to translate, the here named path starts at any location of the stc-search path.
371     * <br><br>
372     * The parts of file-name before and after the asterisk <code>*</code> are pre- and suffixes both for the file name 
373     * and for the name of the <code>struct</code> which reperesents the java-class. The <code>*</code>-part 
374     * is replaced with the java file respectively class name. If no <code>*</code> is given at right side 
375     * in the file name part, the file name is given complete. Than the class replacement may be written
376     * in parenthesis after them with or without asterisk. 
377     * Therewith a file with an abbreviating name can named. 
378     * The <code>struct</code> in the file can be abbreviating too, if only one class is contained 
379     * in the Java-file, or it can be built regarding the Java class name.
380     * <br><br>
381     * This settings allow a relative free assignment between Java files and class names 
382     * and their representation in C. The user is responsible for the order of files and classes at C-side.
383     * It may be recommended to find out an adequate transparent rule to mapping the C files.
384     * <br><br>
385     * The named pathes of package and file replacement in this division are relative pathes 
386     * starting from the java source and class search-path (Java-side) respectively (C-side) 
387     * starting from the include and stc search path or starting from the output path. 
388     * The here named Java-package pathes should be equivalent the package structure. It means, 
389     * it should start with the first package (<code>org</code> etc.). The separator between package identifier
390     * may be the slash or backslash or the dot. Internally the slash is used. In opposite in Java sources
391     * the dot have to be used as separator in package and import statements. The synonymous using 
392     * of slash or dot allows the user to copy a path without need of correction of coseparators from several sources.
393     * <br><br>
394     * See also {@link #b6_translatingOrGetStc()}.
395     * <br><br>
396     * <b>Technical informations</b>:
397     * <br><br>
398     * <ul>
399     * <li>The config-file is read and parsed in the method {@link Java2C_Main#readConfigFile(Java2C_Main.ListFileIn, String, Report)}.
400     * <li>The configuration is written in {@link Java2C_Main.InputFileParseResult} using {@link org.vishia.zbnf.ZbnfJavaOutput}.
401     * <li>The package replacement is contained in {@link Java2C_Main#inputCfg} and there in
402     *     the implementation instance {@link Java2C_Main.InputFileParseResult#packageReplacement}.
403     * <li>A replacement for a given package can be searched using the public known {@link Java2C_Main#inputCfg}
404     *     and there calling {@link ConfigSrcPathPkg_ifc#getCPathPrePostfixForPackage(String)}.
405     * <li>The implementation of that interface method is {@link Java2C_Main.InputFileParseResult#getCPathPrePostfixForPackage(String)}.
406     *     It accesses the private known TreeMap {@link Java2C_Main.InputFileParseResult#packageReplacement}.
407     * <li>This method is called only inside {@link JavaSrcTreeGetter#gatherAllJavaSrcFiles(LocalIdents, java.util.List)}.
408     *     The replacement for the found Java-file is stored in the {@link JavaSrcTreeFile#sFilePathC} and adequate elements.    
409     * <li>Whether or not a Java-file is to translate to get the type informations, or whether a stc-file is to be read,
410     *     depends on the existing of a Java-file. It is tested calling TODO            
411     * </ul>     
412     */
413    public void B3_packageReplacement(){}
414    
415    
416    /**After the package replacement is recognized, all given source-pathes in the config-file are gathered
417     * to detect all java-source-files. Not all of them are necessary to translate, but all of them are known then.
418     * If any type is necessary, it will be looked after the java-file, which represents this type. If a java-file is found,
419     * then it's tested, whether the equivalent C-file with the {@link #B3_packageReplacement()} is existing 
420     * and whether it is newer as the Java-file. If it is newer, it must not be translated once again. 
421     * It is strongly, because the C-file may be checked in an source configuration management, it may be tested and so on.
422     * Then the stc-file should be exist, see {@link #b6_translatingOrGetStc()}. But if the Java-file are newer than the c-file,
423     * then it is translated. Therefore it is necessary to know all java-sources.
424     *  
425     * <br><br>
426     * <b>Technical informations</b>:
427     * <ul>
428     * <li>The config-file is read and parsed in the method {@link Java2C_Main#readConfigFile(Java2C_Main.ListFileIn, String, Report)}.
429     * <li>The configuration is written in {@link Java2C_Main.InputFileParseResult}.
430     * <li>The post-processing of the parse-result is done in {@link Java2C_Main#execute()}. There is filled or set:
431     * <li>{@link Java2C_Main#listJavaSrcpath}: All pathes in file system (maybe relative) where java-src-files are searched.
432     * <li>{@link Java2C_Main#listInputToTranslate}: All Input files to translate primary. More files will be translated of dependencies exists.
433     * <li>The class {@link JavaSrcTreeGetter} is created temporary,  
434     * <li>{@link JavaSrcTreeGetter#gatherAllJavaSrcFiles(LocalIdents, java.util.List)} is called. It checks all given pathes
435     *     in the file system, containing in the second argument {@link Java2C_Main#listJavaSrcpath}.
436     * <li>For all detect directories in the source-paths, instances of {@link JavaSrcTreePkg} are created and arranged 
437     *     as children of the top-level-container for the root-packages are created.
438     *     The root-packages are referenced in {@link Java2C_Main#javaSources} and there in
439     *     {@link JavaSources#javaSrcTree}.       
440     * <li>For all detect java-source-files in the source-paths, instances of {@link JavaSrcTreeFile}
441     *     are created and arranged in the {@link JavaSrcTreePkg#pkgIdents}.{@link LocalIdents#typeIdents}-reference. 
442     * <li>At least a report is written, which contains the situation of sources. 
443     *     This is included in the generated report-file in the chapter <code>===All found Java source files===</code>,
444     *     done in {@link JavaSrcTreeGetter#gatherAllJavaSrcFiles(LocalIdents, java.util.List)}
445     * </ul>     
446     * 
447     */
448    public void B4_gatherAllSourceFiles(){}
449    
450    /**If any type is need for the translation, its {@link ClassData} should be present. 
451     * They can be gotten calling {@link LocalIdents#getType(String, LocalIdents)} 
452     * with the String-given type-name. The type-name can be consists of a full qualified 
453     * package path, or of a partial path. 
454     * <br><br>
455     * If a partial path or only the type-name is given, either a import-statement is determined the package path,
456     * or the type is found in the current package, or it is a standard-type:
457     * <ul>
458     * <li>All classes of the package (in all files) are copied from the {@link JavaSrcTreePkg#pkgIdents} 
459     *     in the File-local valid {@link GenerateFile#fileLevelIdents}.         
460     * <li>The {@link GenerateFile#fileLevelIdents} is then filled with the types from all import-statements.
461     *     Either an import-statement represents one class, or it is written with <code>.*</code>
462     *     and all classes of the named package are added there.
463     *     This information is put calling {@link GenerateFile#evaluateImports(org.vishia.zbnf.ZbnfParseResultItem)},
464     *     which is called at begin of the first pass of translation.
465     * <li>All All type-informations of classes, which are contained in the own file beside the public class,
466     *     are contained in {@link JavaSrcTreePkg#pkgIdents}. 
467     *     There are filled calling {@link GenerateFile#registerClassInFile(ClassData)} in the first pass,
468     *     before any detail evaluation of a class of this file.
469     * </ul>
470     * <br><br>
471     * To get the {@link ClassData} for any string-given type, 
472     * the method {@link LocalIdents#getType(String, LocalIdents)} have to be called.
473     * The instance of {@link LocalIdents} should be the locally used one. 
474     * It may be the {@link ClassData#classLevelIdents}, if elements of a class are translated, 
475     * or a locally instance created in the parenthesis of code blocks.
476     * In that case the locally created instances are recognized and searched first. 
477     * Note, that it is possible to define a class in a code block. 
478     * <br><br>
479     * The second parameter of <code>getType(name, fileLevelIdents)</code> should be the
480     * {@link GenerateClass#fileLevelIdents} or {@link GenerateFile#fileLevelIdents},
481     * which refers the {@link LocalIdents} at the file level. It includes the import-statement-given one,
482     * and the indents of the package (see above). A separate parameter is need, because the fileLevelIdents
483     * are that idents from the translated file, where the instance to call 
484     * {@link LocalIdents#getType(String, LocalIdents)} can be a referenced instance with path. 
485     * Then the fileLevelIdents of the environment of that {@link LocalIdents} are not valid to search.
486     * Therefore they are not contained in any {@link LocalIdents} as member, instead there are either given
487     * from the {@link GenerateFile#fileLevelIdents} or they have to be <code>null</code>, if a referenced
488     * package is used:  
489     * <ul>
490     * <li><code>Type</code> - than the {@link GenerateFile#fileLevelIdents} should be used.
491     * <li><code>pkg.Type</code> - than the fileLevelIdents-parameter should be <code>null</code>
492     * to search <code>type</code>
493     * </ul> 
494     * <br><br>
495     * If {@link LocalIdents#getType(String, LocalIdents)} is called, it is not determined, 
496     * whether the requested type is existing and whether it is translated. Therefore,
497     * internally {@link LocalIdents#getTypeInfo(String, LocalIdents)} is called first. 
498     * This routine can be called from outside too. It doesn't return the ready-to-use {@link ClassData},
499     * but the {@link JavaSources.ClassDataOrJavaSrcFile}, which are either the ClassData already,
500     * or the instance for a translated or not-translated Java-file or package. 
501     * The interface is implemented at all three variants. 
502     * If the type isn't known, this routine returns <code>null</code>.
503     * <br><br>
504     * The {@link ClassData} are gotten then calling {@link JavaSources.ClassDataOrJavaSrcFile#getClassData()}.
505     * If the implementing instance are of type {@link ClassData}, it returns this. 
506     * A {@link JavaSrcTreePkg#getClassData()} returns <code>null</code> any time, 
507     * because a package isn't a class.
508     * But the {@link JavaSrcTreeFile#getClassData()} returns the {@link ClassData} of its public class,
509     * if the file is translated already, otherwise <code>null</code>.
510     * <br><br>
511     * If the gotten ClassData are <code>null</code>, the translation of the Java-Source 
512     * or the parsing of the stc-file is started inside {@link LocalIdents#getType(String, LocalIdents)}.
513     * Therefore {@link Java2C_Main#runRequestedFirstPass(JavaSrcTreeFile, String)} is called 
514     * with the given {@link JavaSrcTreeFile} - instance. 
515     * There, it is detected whether a translation is necessary
516     * or the parsing of the stc-file is proper to get the {@link ClassData} of the type.
517     * See {@link #b6_translatingOrGetStc()}.
518     * <br><br>  
519     * The standard-types from <code>java.lang</code> and the simple types <code>int</code>, <code>float</code> etc.
520     * are found because {@link LocalIdents#getTypeInfo(String, LocalIdents)} 
521     * searches in the {@link Java2C_Main#standardClassData}.{@link CRuntimeJavalikeClassData#stdTypes} too.
522     * <br><br>  
523     * Any type, which isn't a standard-type created and contained in {@link CRuntimeJavalikeClassData#singleton},
524     * is represented by a instance of {@link JavaSrcTreeFile}, independent whether it should be never translated. 
525     * But it isn't necessary, that a Java-file is represented too. Some files are existing as Java-files, 
526     * but there are not taken into account for translation, because they are present in C as library-content.
527     * Then they have to be presented by a stc-file (structure of Java-file). The stc-file maps the content 
528     * of the appearance in C (in the header-file) too.  
529     * <br><br>
530     * See also {@link #B3_packageReplacement()}. If a unknown Java-file is used, 
531     * but its package is named in the package-replacement it the form <code>pkg.*</code>, then a {@link JavaSrcTreeFile}
532     * is created with the known replacement-informations and the information 'not to translate'. 
533     * Because of the existence of the {@link JavaSrcTreeFile}, the associated stc-file is searched and parsed.
534     * It builds the {@link ClassData} then.
535     * 
536     * 
537     */
538    public void b5_getTypeInfoAndTranslate(){}
539    
540    /**Some Java sources should be translated, but some other sources mustn't translate, 
541     * because they are parts of built C libraries. There may be the absence of parallelism 
542     * in translation at Java side and at C side. At Java side the translation may be prevented by supply
543     * class files instead java sources. But in practice all files may be given as Java source. 
544     * The translation process detects the necessity of translation, it is lightweight alterable
545     * <br><br>
546     * But in C it is much stronger. Tested functionality is compiled into libraries 
547     * and offered to use in several applications. Therefore some Java sources may be translated to C
548     * and provided in a C library. They shouln't be re-translated, also if they may be adjusted in Java.
549     * If their modification is necessary to use to test in C, first the libraries should be built newly.
550     * than the usage is translated and linked.
551     * <br><br>
552     * Another issue for non-translating is: Some Java-files emulates parts of functionality, 
553     * which are implemented in another way in the target system. The implementing files of target 
554     * are written in C immediately, they are fitted to hardware requirements mostly.   
555     * <br><br>
556     * Therefore not all found Java sources should be translated into C in the current session. 
557     * The sources which may be translated are named in the config-file with lines (at ex)
558     * <pre>
559     *  translate: org / vishia/exampleJava2C/java4c/ *.java;
560     *  translate: org / vishia/util/MsgDispatcher.java;
561     * </pre>
562     * There may be named individually files or whole packages with all files. 
563     * <br><br>
564     * If a Java file is found as depending type, and this file is not in the list of files to translate,
565     * a equivalent <code>.stc</code>-File should be found (structure file). The stc-file is searched 
566     * with the same path and name as the translated C- or header-file, but with extension <code>.stc</code>.
567     * The physically directory is determined by the stc-search path. It is named in the config-file 
568     * with setting (at example):
569     * <pre>
570     * stcPath: ., ../../CRuntimeJavalike, "../../CRuntimeJavalike/J1c" , "../../CRuntimeJavalike/stc"; 
571     * </pre>
572     * or with cmd line argument <code>-stcpath:</code> too (planned).
573     * The shown relative path is related to the calling working directory, an absolute path is possible too.
574     * Thereby a library-provided C file may have its stc files adequate to header files for C compilation
575     * in a library-oriented stc-directory. It may be the same as the include directory, where the related
576     * headeres are stored.
577     * <br><br>
578     * While running the Java2C translation process found C- and header files are tested in timestamp
579     * against the Java source. If the java source is older as both C and H, and a actual stc-file 
580     * is existing too, the translation of the Java file is suppressed in favour of reading the stc-file.
581     * The stc-file contains all informations, which are necessary by usage of the class 
582     * in another translation context (available fields and methods of the class, their types, 
583     * override-able properties of methods etc). 
584     * <br><br>
585     * The stc-files are built automatically in the translation process, and they are is placed 
586     * beside the generated header files. There they are found for a later translation. 
587     * The stc-files which are associated to libraries or to manual written C code are searched 
588     * in the stc-search-path which can name more as one position in the file system. 
589     * 
590     */
591    public void b6_translatingOrGetStc(){}
592    
593    /**The import statements are not able to use for include generation, 
594     * because files from the same package are not imported in Java. But its include is necessary.
595     * The import statements are used to bring the imported classes in visibility.
596     * <br><br>
597     * An <code>#include "..."</code>statement is generated if an external type is used 
598     * and its definition have to be known. An include is not necessary 
599     * if a type is used only as a reference-type. For references a forward declaration of the type
600     * (<code>struct TYPE_t* name;</code>) declares the type as structure pointer. 
601     * The type-definition itself should not be known. It is a able-to-use property of C to do so
602     * and it economized the number of included files. That precaution is necessary to prevent
603     * circular includes: If a type is needed, but in that structure the current declared type is needed too,
604     * a circular include would be produced elsewhere. That would be force a compiler error at C level.
605     * <br><br>
606     * The {@link ClassData} of the type is searched
607     * calling {@link LocalIdents#getType(String, LocalIdents)}.
608     * There the {@link ClassData#sFileName} contains the file name contingently with a directory 
609     * where the header file is located adequate to the association between Java package path and C path 
610     * in the config file.
611     * <br><br>
612     * The using of the type may be occurred in the first or in the second pass of translation. 
613     * The first pass produces the .h-file, the second pass produced the .c-File. So a using of a type leads to include
614     * in the .h- or .c-File. The methods {@link GenerateFile#addIncludeC(String sFileName, String comment)} 
615     * and {@link GenerateFile#addIncludeH(String sFileName, String comment)} represents both possibilities. 
616     * This methods may be called more as one time for the same file. Therefore the TreeMap {@link GenerateFile#includes} 
617     * saves the types for including while running the first or second pass for this file, 
618     * and the lines for <code>#include "..."</code> in the H- and C-file are produced after finishing the passes.
619     * <br><br>
620     * The routine {@link GenerateFile#addIncludeH(String sFileName, String comment)} is called inside the first pass 
621     * <ul><li>in the routine {@link GenerateFile#write_HeaderContent(GenerateFile, ZbnfParseResultItem, String, ClassData, ClassData[])}
622     *   for super classes and interfaces.
623     * <li>in the routine {@link GenerateClass#createFieldDataNewObject(ZbnfParseResultItem, ZbnfParseResultItem, ZbnfParseResultItem, LocalIdents, String, ClassData, char, char, ClassData, char, ZbnfParseResultItem)}
624     *   if the new Object is created as class variable or static variable.
625     * <ul>
626     * In this cases an include of the type is necessary. The including of super classes and interfaces 
627     * can't force circular includes, 
628     * because the current class can't be a superclass of its superclass in Java too.
629     * <br><br>
630     * The routine {@link GenerateFile#addIncludeC(String,String)} is called sometimes in the second pass,
631     * if a type is need. It may be necessary mostly, because a needed type will be accessed mostly,
632     * than its structure should be known. Not necessary includes in the C-file are not a problem any time.
633     */
634    public void b7_includeGeneration(){}
635    
636  }
637  
638  
639  
640  /**While the translation processes the type or affiliation of some identifiers should be evaluated. 
641   * In java this is done by the javac-Compiler. In C some more informations should be appropriated
642   * to the C-Compiler. Therefore all identifiers are stored in Lists. This lists are TreeMap mostly
643   * to support a fast searching.
644   * <br><br>
645   * <img src="../../../../Java2C/img/ClassDataLocalIdents_omd.png" />
646   */
647  public class C_StaticDataOfConversion
648  {
649
650    /**<b>LocalIdents</b>
651     * <br>
652     * Identifiers are valid always in a local context. This context may be a class context, 
653     * a method context or a context of a statement block (some statements in <code>{...}</code>). 
654     * The class {@link LocalIdents} holds references to identifiers and types,
655     * with some add- and access methods, for all the contexts:
656     * <ul> 
657     * <li>{@link StatementBlock#localIdents}: for any statement block. 
658     * <li>{@link ClassData#classLevelIdents} for the class level context.
659     * <li>{@link JavaSrcTreePkg#pkgIdents} for the idents, which are associated to packages-local 
660     *   classes respectively files.
661     * <li>{@link GenerateFile#fileLevelIdents}: All visible types while translation a file are stored here.
662     *   It are a copy from the {@link JavaSrcTreePkg#pkgIdents} of the current package, the same one
663     *   form all imported packages and all imported class types. This LocalIdents are assembled
664     *   for translating a file running first and second passes. This LocalIdents aren't be visible or used
665     *   while accessing any classes from outside.  
666     * <li>{@link Method#methodIdents}: The methodIdents are the LocalIdents visible at start of body of the method.
667     *   It contains the parameter of the method especially. The body's LocalIdents is created as an own instance than,
668     *   because it is handled like an normal {@link StatementBlock}.
669     * <li>{@link CRuntimeJavalikeClassData#stdTypes} This referenced instance contains the global visible types.
670     *   It contains 
671     *   <ul>
672     *   <li>the C-language standard types <code>int</code> etc.,
673     *   <li>all packages visible at root of packages,
674     *   <li>all types from package <code>java.lang</code>, mostly implemented in CRuntimeJavalike-C-environment.
675     *   </ul>
676     *   This instance is the {@link JavaSrcTreePkg#pkgIdents} of the JavaSrcTreePkg-instance for <code>java.lang</code>. 
677     * </ul>
678     * <br>
679     * The {@link LocalIdents} contains TreeMaps for 
680     * <ul>
681     * <li>{@link LocalIdents#fieldIdents} identifier of all variables in this context. 
682     *     Especially in statement block some variable may be defined, they aren't known in the class context.
683     * <li>{@link LocalIdents#typeIdents} identifier of all types in this context. 
684     *     In a statement block local visible classes (defined in the block) are possible too.
685     * <li>Method identifications are not contained there, they are hold in Class context, see
686     *   {@link ClassData#methods} respectively {@link ClassData#searchMethod(String, java.util.List, boolean)}.       
687     * </ul>
688     * An instance of {@link LocalIdents} in any scope contains all field and type identifiers 
689     * from the super (parent) scope too as a copy of the identifier Strings and references 
690     * from the parents TreeMaps. To prevent effort, In {@link StatementBlock} 
691     * a new LocalIdents is created only with the first definition of an type or variable. But the types
692     * of the standard language level, it is {@link CRuntimeJavalikeClassData#stdTypes},isn't copy
693     * to prevent effort. It contains only types and the root packages. Therefore searching of types
694     * (see {@link LocalIdents#getTypeInfo(String, LocalIdents)}) should regard three locations:
695     * <ul>
696     * <li>The LocalIdents of the given local scope, it contains inner classes and classes defined
697     *   in a statement block (rarely used in practice),
698     * <li>The file level LocalIdents, given as extra parameter because it depends from the file to generate.
699     *   This LocalIdents contains the package level LocalIdents of the own package too, and with them
700     *   the own Class. Especially imported classes are contained there additionally.
701     * <li>The standard language idents given in the static {@link CRuntimeJavalikeClassData#stdTypes}. 
702     * </ul>
703     *     
704     * <br><br> 
705     * The searching of a identifier uses always the Java name of identifier. 
706     * In the found {@link FieldData} than the C name is contained.
707     */
708    void B1_LocalIdents(){}
709    
710    /** <br><br>
711     * <b>Identifiers of super and outer levels</b>
712     * <br>
713     * Super levels are the levels above a statement block; 
714     * <ul>
715     * <li>the parent statement block, 
716     * <li>the whole method,
717     * <li>the class
718     * <li>the super class and the outer class
719     * <li>the super.super class etc, the outer.outer class etc.
720     * <li>All global visible identifiers: {@link Java2C_Main#userTypes} and {@link Java2C_Main#stdTypes} 
721     * </ul>
722     * In generally, there may be two ways to search identifiers of super levels:
723     * <ol>
724     * <li>An instance of {@link LocalIdents} contains only the identifiers of the current level. 
725     *     It contains a reference to the super and outer LocalIdents. Than the searching process is lengthy,
726     *     if a identifier isn't found locally, it should be searched in the next super and outer level and so on.
727     * <li>An instance of {@link LocalIdents} contains all identifiers visible at this level. 
728     *     If a new instance of LocalIdents is created, the identifiers of the parent level should be copied
729     *     and designated with its context oriented from the current level. This copy process necessitates 
730     *     some calculation time, but only one time per new level. Some more memory spaces is needed, but only temporary
731     *     (the garbage collector have to be tidy up). But the searching is simple and fast.       
732     * </ol>
733     * The solution is: 
734     * <ul>
735     * <li>fields, variables are contained complete in the current {@link LocalIdents#fieldIdents}.
736     *   If a new level of statement block is created, first the reference to the {@link LocalIdents} 
737     *   of the super level is set. But if any block-local variable is found 
738     *   (calling {@link GenerateClass#gen_variableDefinition(org.vishia.zbnf.ZbnfParseResultItem, org.vishia.zbnf.ZbnfParseResultItem, LocalIdents, java.util.List, char)}),
739     *   a new instance of {@link LocalIdents} is created and all fieldIdent of the parent are copied into it.
740     *   So any instance of {@link LocalIdents} contains all visible identifier of variables and class fields.
741     *   The association is stored in the {@link FieldData}.
742     * <li>Types of a inner level starting from Class level ({@link ClassData#classLevelIdents}) 
743     *   are contained complete in the current {@link LocalIdents#fieldIdents} too. 
744     *   But Language Level types are found in {@link CRuntimeJavalikeClassData#stdTypes}. 
745     *   Third, all imported classes and the classes of the own package are found in the {@link GenerateFile#fileLevelIdents}.
746     *   Therefore to find out a type three search operations should be do.  
747     * <li>Methods are stored only in the accordingly instance of {@link ClassData}. 
748     *   If methods from the super classes are searched, the search operation is called for all super-classes.
749     *   The adequate problem is for interfaces and outer classes. TODO: It may be opportune to copy the methods 
750     *   in one TreeMap too.
751     * </ul>
752     * <br><br>
753     * The knowledge of field-identifiers and types of the outer classes and the sibling- inner classes
754     * in inner classes and the knowledge of this one of the super classes in the derived classes
755     * is an adequate topic. But additionally the field-idents should be designated as outer or super ones.
756     * That designation is contained in the fields {@link FieldData#nClassLevel} 
757     * and {@link FieldData#nOuterLevel}. See {@link Docu.E_Inner_classes}.
758     * 
759     */
760    void B2_identifiersForOuterOrSuperLevels(){}
761    
762   /** <br>
763     * <br>
764     * <br>
765     * <b>searching a method identifier with parameters</b>
766     * <br>
767     * Methods can't defined in a local context, only at class level. To know and search methods
768     * in the actual context, the {@link ClassData} of the appropriate class of the local context 
769     * can be used. They are access-able in the methods of {@link SecondPass} via {@link GenerateClass#classData}
770     * See {@link #methodCall_WithParameterSensitivity()}
771     */
772    void B3_searchMethodIdentifier(){}
773    
774    
775   /** <br>
776     * <br>
777     * <b>{@link ClassData}</b>
778     * <br>
779     * That are the type informations. The {@link ClassData} are referenced in 
780     * {@link LocalIdents.typeIdents}. Classes have their own {@link ClassData#classLevelIdents}.
781     * <br>
782     * <br>
783     * <b>{@link FieldData}</b>
784     * <br>
785     * That are the variable and field informations. The {@link FieldData} are referenced in 
786     * {@link LocalIdents.fieldIdents}. Fields based on {@link FieldData#typeClazz}, but have
787     * some additional properties, also especially for the C-Code-representation. 
788     * Also arrays with theire special properties are considered.
789     * <br>
790     * <br>
791     * <b>{@link CCodeData}</b>
792     * <br>
793     * That are peaces of C-Code with its type-information {@link CCodeData#identInfo},
794     * but also special properties. If an array element is addressed from a array-field,
795     * it may be possible to store the access information in an extra {@link CCodeData#identInfo}.
796     * But the solution is: The {@link FieldData} of the whole array is referenced, 
797     * and the access properties to the array element are stored in extra data fields:
798     * {@link CCodeData#dimensionArrayOrFixSize} and {@link CCodeData#modeAccess} of the element.
799     */
800    public void B4_InstancesWhichContainsStaticData(){}
801    
802  }
803  
804  
805  
806  
807  
808  
809  
810  
811  
812  
813  
814  /**Java knows simple inheritance but multiple usage of interfaces. 
815   * Interfaces may contain static final variables, they are constants, and method declarations.
816   * All method declarations should be implemented in a non-abstract inheriting class. 
817   * The super classes may contain also method declarations (using abstract keyword), which have to be 
818   * implemented in an inheriting class. 
819   * <br><br>
820   * Interface may contain complete classes as inner classes too.
821   * <br><br>
822   * All variables of super classes are available in the data of the inheriting class too, 
823   * only a private modifier prevents an access. Interface hasn't any class variable
824   * 
825   */
826  public class D_SuperClassesAndInterfaces
827  {
828    
829    /**A super class in Java is mapped in C using a base <code>struct</code> as first element 
830     * of the class representing <code>struct</code>. The following commonly form is used:
831     * <pre>
832     * typedef struct TheClass_t
833     * { union { ObjectJc object; SuperClass_s super; Interface1_s Interface1; Ifc2_s Ifc2; } base;
834     *   //rest of class data
835     * }
836     * </pre>
837     * A union is built in C because the <code>object</code>, all interfaces 
838     * and the data of the super class represents the same data: 
839     * The super class starts with the <code>object</code>, all interfaces contains only the same
840     * <code>object</code>. The SuperClass determines the size of the union's data. 
841     * <br><br>
842     * <ul>
843     * <li>The access to the Object base class is possible independent of the inheritance structure. 
844     * It is always able writing <code>&ref->base.object</code>. 
845     * <li>The access to the super class data
846     * should written like <code>&ref->base.super</code>. If a super-super-class should accessed,
847     * in Java written using <code>super.super</code>, the C-equivalent form is <code>&ref->base.super.base.super</code>.
848     * <li>The reference to interfaces is got
849     * writing <code>&ref->base.Interface1</code>, where the identified element is the name of the interface
850     * like in the Java code.
851     * </ul> 
852     * <br><br>
853     * The Types of super, Interfaces etc. are the built C-Types. It may have pre- and suffixes 
854     * (see {@link Docu.ProcessOfTranslation#packageReplacement()}) and it has the usual suffix <code>_s</code> to different it
855     * from a possible C++ type definition.         
856     */
857    public void D1_baseStructures(){}
858
859    /**The concept of virtual methods is necessary for implementation of interfaces and 
860     * for overridden methods in derived classes.
861     * <br><br>
862     * The class {@link ClassData} contains a field {@link ClassData#inheritanceInfo}. The Type
863     * {@link ClassData.InheritanceInfo} contains the reference to the superclass's and interfaces InheritanceInfo. 
864     * The referenced instances of the type {@link ClassData.InheritanceInfo} are not instances 
865     * of the inherited class, they are independent instances and built a data-private own InheritanceInfo-tree. 
866     * The reason for that plurality of InheritanceInfo is: 
867     * They contain the override-able (virtual) method names: {@link ClassData.InheritanceInfo#methodTable}. 
868     * The virtual methods are differently 
869     * for a class as superclass of another class (contains the derived virtual method) 
870     * and for the class able to instantiate in another context. The field 
871     * {@link ClassData.InheritanceInfo#methodTable} contains the overriding names of all 
872     * override-able methods of the current class. The override-able and overridden methods of interfaces
873     * and super classes are located in the {@link ClassData.InheritanceInfo#methodTable} 
874     * of the super-classes and interface referenced with {@link ClassData.InheritanceInfo#superInheritance}
875     * and {@link ClassData.InheritanceInfo#ifcInheritance}.
876     * <br><br>
877     * The constructor {@link ClassData.InheritanceInfo#InheritanceInfo(ClassData, ClassData, ClassData[])}
878     * uses the superclass and all interfaces to build its own tree of Inheritance objects. Thereby
879     * the names in {@link ClassData.MethodOverrideable#sNameOverriding} are copied from the original instance,
880     * the overridden method is the same: 
881     * <br><br>
882     * <br>
883     * <img src="../../../../Java2C/img/InheritanceInfo_omdJava2C.png" />
884     * <br><br>
885     */
886    public void D2_virtualMethodsAndInheritanceInfo(){}
887    
888     /**If a method of the current translated class is processed and adds to the class using
889     * {@link ClassData#addMethod(String, String, int, FieldData, FieldData[])}, 
890     * it is searched in all super classes
891     * and interfaces calling {@link ClassData#searchOverrideableMethod(String, FieldData[])}. 
892     * If it is found there, it is an overridden method. Therefore a new Instance of {@link Method}
893     * is created, but the information about the {@link Method#declaringClass} is taken 
894     * from the found method. The name in the {@link ClassData.InheritanceInfo#methodTable} is replaced
895     * with the actual method.
896     */  
897    public void D3_detectOverriddenMethods(){}
898    
899    
900     /** If a new method is created, and it is able to override, it is registered in 
901     * {@link ClassData#methodsOverrideableNew} just now. On finishing of translation the class
902     * the method {@link ClassData#completeInheritanceWithOwnMethods()} is called. It creates
903     * the array in {@link ClassData.InheritanceInfo#methodTable} with the correct array size 
904     * and adds the methods. Thereby the override-able methods of the current class, which are not
905     * defined in super classes or interfaces, where registered. A method is able to override 
906     * if it is non-final.
907     */
908    public void D4_newOverrideAbleMethods(){}
909    
910    
911    /**The overridden methods have the type of <code>ythis</code> from the first declaring class,
912     * because they have to be the same signature (type of method definition) as the first declaring ones.
913     * The type of <code>ythis</code> of interface-defined methods is <code>ObjectJc*</code> any time
914     * and not, like able to expect, the type of the interface. It is, because a method can be declared
915     * in more as one interface. If a class implements more as one interface with the same
916     * method declaration, it exists only one implementation. This implementation can't regard
917     * a type of one of the interfaces, it should be resolved both. The type <code>ObjectJc*</code>
918     * is the commonly of all.
919     * <br><br>
920     * The implementation of an override-able method is designated with the suffix <code>_F</code>
921     * (means Final). This method name is used as entry in the method table of the class.
922     * This name is used too if a method of a dedicated type is called 
923     * (annotation <code>@ java2c=instanceType:"Type".</code>).
924     * <br><br>
925     * Additionally a method with the normal built name of non-override-able methods are generated,
926     * but that method contains (example):
927     * <pre>
928     * / * J2C: dynamic call variant of the override-able method: * /
929     * int32 processIfcMethod_i_ImplIfc_Test(ObjectJc* ithis, int32 input, ThCxt* _thCxt)
930     * { Mtbl_Ifc_Test const* mtbl = (Mtbl_Ifc_Test const*)getMtbl_ObjectJc(ithis, sign_Mtbl_Ifc_Test);
931     *   return mtbl->processIfcMethod(ithis, input, _thCxt);
932     * }
933     * </pre>
934     * It is the variant ready to call at C-level which gets the pointer to the method table internally.
935     * A simple call from outside C sources can use this variant of method. But it isn't optimal
936     * in calculation time, because the call of <code>getMtbl_ObjectJc(...)</code> 
937     * needs additional time. See {@link #callingOverrideableMethods()} in its variants.
938     * <br><br>
939     * The implementation of a method in a derived class starts with a casting from the given data type,
940     * at example:
941     * <pre>
942     * int32 processIfcMethod_i_ImplIfc_Test_F(ObjectJc* ithis, int32 input, ThCxt* _thCxt)
943     * { ImplIfc_Test_s* ythis = (ImplIfc_Test_s*)ithis;
944     * </pre>
945     * The pointer casting should be accept as safe, because this method is only called in an context,
946     * where the really instance is of the correct type or a derived type, which contains the correct type
947     * as first part of data. The name of method is only used in an programming context of the method table,
948     * and in an context where the user declares a reference pointer from base or interface type
949     * as a pointer of a given instance using <code>@ java2c=instanceType:"Type".</code> That positions of code
950     * should be checked carefully.
951     * <br><br>
952     * It is possible to check the instance additionally, but this check needs additional calculation time.
953     * If it may be needed, at Java-level an <code>instanceof</code> operation can be written 
954     * either in the implementing method or, it may be better, at calling position of a method with designation
955     * <code>@ java2c=instanceType:"Type".</code> Than the declaration of a determined instance type
956     * will be checked at run time too. The <code>assert(ref instanceof Type)</code> produces a C-code like
957     * <pre>
958     * ASSERT(instanceof_ObjectJc(& ((* (ref)).base.object), &reflection_Type_s));
959     * </pre>
960     */
961    public void D5_cCodeForOverriddenMethods(){}
962    
963
964    
965    /**If a method is called in Java, which is override-able, the generated C-code depends on several conditions:
966     * <br><br>
967     * <b>Stack-local reference:</b><br>
968     * If the reference is a stack-local reference in Java, it may be generated in C as a so named 
969     * method-table-reference. The conditions for that are:
970     * <ul>
971     * <li>The referenced type is an interface type. Than all methods are dynamic, and the method table preparation
972     *   is proper.
973     * <li>The definition of this stack-local reference is designated with <code>@ java2c=dynamic-call.</code>,
974     *   at example
975     *   <pre class="Java">
976          /**Use local variable to enforce only one preparation of the method table for dynamic call:
977             <code>@ java2c=dynamic-call. </code>* /
978          final TestWaitNotify.WaitNotifyData theNotifyingDataMtbl = theNotifyingData;
979     *   </pre>
980     *   The translated C-code is than
981     *   <pre class="CCode">
982          TestWaitNotify_Test__WaitNotifyDataMTB theNotifyingDataMtbl;  
983          ...
984          SETMTBJc(theNotifyingDataMtbl, REFJc(ythis->theNotifyingData), TestWaitNotify_Test__WaitNotifyData);
985     *   </pre>   
986     * </ul>
987     * The method-table-reference is defined locally in the C-file in form (example)
988     * <pre>
989     *   typedef struct Type_t { struct Mtbl_Type_t const* mtbl; struct Type_t* ref; } TypeMTB;
990     * </pre>
991     * The named class in C is <code>Type</code>, The method-table-reference contains 
992     * the reference (pointer) to the data and additionally the reference to the method table.
993     * The reference variable should be set before using of course, The setting is generated (example)
994     * <pre>
995     *   SETMTBJc(ifc3, & ((ythis->implifc).base.Ifc_Test), Ifc_Test);
996     * </pre>
997     * It is a macro, defined in <code>ObjectJc.h</code>. The first parameter is the reference to set,
998     * the second parameter is the source, in this case the class-locally reference <code>implifc</code>,
999     * correct casted to the interface type using the access to base classes. The third parameter is the type.
1000     * The implementation of this macro is done with (objectJc.h)
1001     * <pre>
1002     *   #define SETMTBJc(DST, REF, TYPE) 
1003     *   { (DST).ref = REF; 
1004     *     (DST).mtbl = (Mtbl_##TYPE const*)
1005     *                  getMtbl_ObjectJc(&(DST).ref->base.object, sign_Mtbl_##TYPE); 
1006     *   } 
1007     * </pre>
1008     * The data-reference is set, the reference to the method table is got calling the showed method.
1009     * Therefore the pointer to the method table is checked, it isn't only a lightweight pointer in data area,
1010     * it is got with two significance checks, and therefore secure. Because the pointer is stored in the stack range,
1011     * it should be secure in the current thread, no other thread can disturb it (importend for safety critical software).
1012     * <br><br>
1013     * The access to virtual methods is generated in form (example)
1014     * <pre>
1015     *   ifc3.mtbl->processIfcMethod(&(( (ifc3.ref))->base.object), 5, _thCxt);
1016     * </pre>
1017     * It is an immediate access to the method table reference (in stack, therefore safety) with selecting
1018     * the correct method (a C-function-pointer in the method table). The first parameter is 
1019     * the reference to the data in form of the <code>ObjectJc*</code>-Type, the following parameters are normal.
1020     * <br><br>
1021     * If the method is called some times in the same context, or the method-table-reference is passed 
1022     * as parameter to called methods, the method table reference is used immediately, no additional
1023     * calculation time is need to get the method-tables reference once more. This is the optimized version
1024     * if dynamic linked calls are necessary, able to use in very hard realtime too.
1025     * <br><br>
1026     * 
1027     * 
1028     * <b>ythis-reference, own methods:</b>
1029     * <br>
1030     * If own methods are called in a subroutine, it can't be assumed that the methods are 
1031     * methods of the current type, it can be methods from a inheriting instance too. It is because 
1032     * the instance can be inherited, but the current method is a method implemented in base-class.
1033     * Therefore a call via method table is generated. If any own method is called, at start of routine
1034     * the reference to the method table of the instance <code>mthis</code> is built generating (example):
1035     * <pre>
1036     * Mtbl_TestAllConcepts_Test const* mtthis = 
1037     *     (Mtbl_TestAllConcepts_Test const*)
1038     *     getMtbl_ObjectJc(&ythis->base.object, sign_Mtbl_TestAllConcepts_Test);
1039     * </pre>
1040     * This reference is used to call own override-able methods (example):
1041     * <pre>
1042     * mtthis->Ifc_Test.processIfcMethod(&
1043     *           ((& ((* (ythis)).base.super.base.Ifc_Test))->base.object)
1044     *           , 4, _thCxt);
1045     * </pre>          
1046     * In the example a method from a super class is called which is override-able in the current class too.
1047     * It is an interface-defined method. Therefore the data pointer is the pointer to <code>ObjectJc*</code>,
1048     * got with access to the <b>&(...)->base.object</b>. The building of interface reference 
1049     * starting with the reference to the base class in the example <code>& ((* (ythis)).base.super.base.Ifc_Test</code>
1050     * is a unnecessary but automatic generated complexity, which are resolved from the C-compiler to a simple pointer,
1051     * because all offsets are zero. It isn't disturb.
1052     * <br><br>
1053     * The built of the <code>mthis</code> locally in the subroutine isn't optimal 
1054     * if it is repeated in called subroutines. It should be optimized (later versions): 
1055     * If a method calls own override-able methods, it shouldn't get the <code>ythis</code>-pointer of the data,
1056     * but instead a method-table-enhanced reference. The calling method, which has this enhanced reference already,
1057     * can use it directly without additional effort. Only a method which calls such a routine firstly, should built
1058     * the reference to the methodtable (calling <code>getMtbl_ObjectJc(...)</code>. The reference to the method table
1059     * can recognize as safety, because it is stored only in the stack area, not in thread-unbound data areas.
1060     * 
1061     * 
1062     * <br><br>
1063     * <b>reference in data area (ythis->ref)</b>
1064     * A dynamic call with a reference in the data area is the most non-economic, 
1065     * because the pointer to the method table is built in specially for this call. 
1066     * It is translated from Java2C in form (example):
1067     * <pre>
1068     * ((Mtbl_Ifc_Test const*)getMtbl_ObjectJc
1069     *   (&(REFJc(ythis->ifc))->base.object, sign_Mtbl_Ifc_Test) )->processIfcMethod
1070     *   (&((REFJc(ythis->ifc))->base.object), 56, _thCxt);
1071     * </pre>
1072     * The getting of the method table is generated inline before call the method (first+second line).
1073     * The third line contains the normal parameter (in reality its one line).
1074     * <br><br>
1075     * Because this operation need the call of <code>getMtbl_ObjectJc(...)</code> only for this intention,
1076     * it should only used for a simple single dynamic call. If the algorithm should be optimized
1077     * in calculation time, the class-visible reference is transfered 
1078     * in a reference in stack (statement-block-local)- variable). Than the call of 
1079     * <code>getMtbl_ObjectJc(...)</code> is done only one time, maybe before start of an loop,
1080     * and it is used many times. It is a mission for the Java programming. In pure-Java it is indifferent
1081     * using a class visible or block visible reference. But if an optimized C-source is need, 
1082     * use the block-local variant.
1083     * 
1084     * <br><br>
1085     * <b>prevent dynamic call, use static instead</b>
1086     * See {@link #preventCallingViaMethodTable()}, it is a signifying feature for optimal C code. 
1087     */
1088    public void D6_callingOverrideableMethods(){}
1089    
1090    
1091    
1092    /**In Java the methods are override-able normally, because a <code>final</code> designation
1093     * to prevent overriding is written only if the ability to override should prevent in inheriting classes.
1094     * Therefore the most of methods should be called in a override-able mode, using the method table-call.
1095     * But that is not economically in calculation time, and in some cases it is unnecessary. 
1096     * It is against the C-style of programming and testing.
1097     * <br><br>
1098     * The difference provocation is: In a object oriented architecture interfaces should be used 
1099     * to divide software in independent parts. Interfaces are the main choice to do so, base classes
1100     * are the other choice. So specific implementations can be implemented without cross effects.
1101     * But therefore the overridden methods appear as the only one solution. 
1102     * <br><br>
1103     * In opposite to Java the independence of modules are realizes in C using forward declarations of methods
1104     * in header files and their implementation in separated C-files (compiling units). The linker
1105     * have to link only with knowledge of the labels (method names) without knowledge of any implementation details.
1106     * This form of independence can't realize the polymorphism in opposite to interfaces and super classes, 
1107     * only the aspect of independence is regarded. But this aspect is the prior aspect mostly. 
1108     * <br><br>
1109     * The solution of this provocation is found in the following way: If it is known, that a reference
1110     * references a determined instance in the C-implementation, it can be designated with a
1111     * <code>@ java2c=instanceType:"Type".</code>-annotation in its comment block. Another way is 
1112     * using a final assignment <code>final IfcType ref = new Type();</code>, what generates 
1113     * an embedded instance. Than the Java2C-translator
1114     * generates a non-overridden calling of the method of the designated instance type 
1115     * for using that reference. The annotation is the decision written in the source 
1116     * in knowledge of the implementation goals. In Java it isn't active. So in Java several implementations
1117     * can be implemented, at example for testing.     
1118     * <br><br>
1119     * If the user is deceived in the usage of the reference, it is not detected in Java 
1120     * neither by compiling nor by testing, because it isn't active there. 
1121     * But it should be attracted attention in testing at C-(implementation)-level.
1122     * The Java2C-compiler may test the correctness of the designation <code>@ java2c="instancetype".</code>,
1123     * because it translates the assignments too. But than all temporary used references should be designated
1124     * too. That don't may be helpfully.
1125     * <br><br>
1126     * But the designated reference can be tested in Java in Runtime, whether at least the designated type
1127     * is referenced, using a <code>reference instanceof Type</code>-Java-sourcecode. 
1128     * Than fatal errors are excluded, only if the instance is from a derived type, it isn't detected.
1129     * The <code>instanceof</code>-check needs a small part of calculation time, 
1130     * if the instance is from the expected type. Such tests are slowly only if the instance is from a far derived type,
1131     * than the implementation type should be searched in reflections. In the current case
1132     * only 2 indirect accesses and a compare operation is necessary in the implementation of
1133     * <code>instanceof_ObjectJc(ref, reflection_Type).</code>  
1134     * <br><br>
1135     * A reference, which has a dedicated instance type, is determined in its {@link FieldData#instanceClazz}- element.
1136     * This element is able to seen in the stc-File of the translated class with notation <code>instance:<Type></code>
1137     * as part of the <code>fieldIdents {...}</code>.
1138     * <br><br>
1139     * The method-call is translated to C using the {@link Method#sImplementationName}.
1140     *   
1141     */
1142    public void D7_preventCallingViaMethodTable(){}
1143    
1144    /**The structure of a method table is generated into the header-file, but the definition
1145     * of a method table is generated into the C-file. 
1146     * <br><br>
1147     * <b>Method type definition:</b></br>
1148     * A method type definition is a type definition of a method. At example the definition of the 
1149     * basicly method <code>Object.toString</code> is contained in <code>Object.h</code> in the form
1150     * <pre>
1151     * typedef METHOD_C StringJc MT_toString_ObjectJc(ObjectJc* ythis);
1152     * </pre>
1153     * The generated form is the same (example):
1154     * <pre>
1155     * typedef int32 MT_testOverrideAble_ImplIfc_Test(ImplIfc_Test_s* ythis, float value, ThCxt* _thCxt);
1156     * </pre>
1157     * It looks like a simple forward declaration of a method, but it is the typedef of the so named <i>C-function pointer</i>.
1158     * The typedef of an method of an interface is at example:
1159     * <pre>
1160     * typedef int32 MT_processIfcMethod_Ifc_Test(ObjectJc* ithis, int32 input, ThCxt* _thCxt);
1161     * </pre>
1162     * The reference to the data for interface defined methods is the <code>ObjectJc*</code>-pointer in any time.
1163     * The defined interface pointer, in this case <code>struct Ifc_Test_t*</code> isn't use,
1164     * because if the same method is definded in more as one interface, it is implemented only one time.
1165     * The data reference should be the same. Therefore the base of all data is used. On calling an interface method
1166     * the correct type of reference is generated accessing the <code>&ref->base.object</code>-Part of a data structure. 
1167     * For methods not defined in interfaces the associated type is used.
1168     * <br><br>
1169     * <b>Method table definition:</b></br>
1170     * The form is (example):
1171     * <pre>
1172     * extern const char sign_Mtbl_ImplIfc_Test[]; //marker for methodTable check
1173     * typedef struct Mtbl_ImplIfc_Test_t
1174     * { MtblHeadJc head;
1175     *   MT_testOverrideAble_ImplIfc_Test* testOverrideAble;
1176     *   MT_returnThisA_ImplIfc_Test* returnThisA;
1177     *   Mtbl_SimpleClass_Test SimpleClass_Test;
1178     *   //Method table of interfaces:
1179     *   Mtbl_Ifc_Test Ifc_Test;
1180     *   Mtbl_Ifc2_Test Ifc2_Test;
1181     * } Mtbl_ImplIfc_Test;
1182     * </pre>
1183     * The example shows the generated method table of the class {@link org.vishia.java2C.test.ImplIfc}.
1184     * This <code>struct</code> is used as part of a method table of a class, which extends this class,
1185     * in the same kind like the method table <code>Mtbl_SimpleClass_Test</code> is used here. That
1186     * used method table is generated from {@link org.vishia.java2C.test.SimpleClass} with C-code:
1187     * <pre>
1188     * extern const char sign_Mtbl_SimpleClass_Test[]; //marker for methodTable check
1189     * typedef struct Mtbl_SimpleClass_Test_t
1190     * { MtblHeadJc head;
1191     *   Mtbl_ObjectJc ObjectJc;
1192     * } Mtbl_SimpleClass_Test;
1193     * </pre>
1194     * The method table definitions have the following parts:
1195     * <ul>
1196     * <li>The declaration of the <code>sign_Mtbl_<i>Type</i></code>: It is a zero-terminated string.
1197     *   But only the address is used to identify the method tables.
1198     * <li>The <code>MtblHeadJc</code> is defined in <code>ObjectJc.h</code> and contains 2 elements:
1199     *   <ul><li><code>char const* sign</code>: The value of sign hava to be identically 
1200     *     with the address of the sign_Mtbl_TYPE. It is checked for safe access respectively used
1201     *     to find out the method table part of a base class.
1202     *   <li><code>int sizeTable</code>, it is the number of byte (size) of the appropriate table.
1203     *   </ul>
1204     * <li>All override-able methods of the own class are defined after them, 
1205     *   its types starts with <code>MT_</code> (Method Type) anyway.
1206     * <li>The method table of the immediate super class follows. That method table contains 
1207     *   a <code>MtblHeadJc head</code> and than the own methods, its immediate superclass and so on.
1208     *   In this kind the method tables of derived classes are nested.
1209     * <li>The method tables of all interfaces follows after them.
1210     * </ul>
1211     * Because the <code>SimpleClass</code> in simple only, it contains no override-able method
1212     * and only the method table of its superclass <code>Mtbl_ObjectJc</code>. That is defined
1213     * in <code>ObjectJc</code> and contains:
1214     * <pre>
1215     * typedef struct Mtbl_ObjectJc_t
1216     * { MtblHeadJc head;
1217     *   MT_clone_ObjectJc*    clone;
1218     *   MT_equals_ObjectJc*   equals;
1219     *   MT_finalize_ObjectJc* finalize;
1220     *   MT_hashCode_ObjectJc* hashCode;
1221     *   MT_toString_ObjectJc* toString;
1222     * } Mtbl_ObjectJc;
1223     * </pre>         
1224     * It contains the 5 methods, which are override-able for any class.
1225     * <br>
1226     * <br>
1227     * <b>Definition of the instance of a method table for a Type/Class:</b></br>
1228     * The instance is defined in the C-file in the following form (example):
1229     * <br>
1230     * At start of C-file the constant is declared because it may be used inside the C-file to detect 
1231     * sub method table parts. The used type of the method table contains its commonly type declared in headerfile
1232     * plus the end-sign.
1233     * <pre>
1234     * typedef struct MtblDef_ImplIfc_Test_t { Mtbl_ImplIfc_Test mtbl; MtblHeadJc end; } MtblDef_ImplIfc_Test;
1235     * extern MtblDef_ImplIfc_Test const mtblImplIfc_Test;
1236     * </pre>
1237     * At end of C-file or methods are defined, than the content can be filled without additional prototype declarations
1238     * of implementing methods:
1239     * <pre>
1240     * const MtblDef_ImplIfc_Test mtblImplIfc_Test = {
1241      { { sign_Mtbl_ImplIfc_Test//J2C: Head of methodtable.
1242        , (struct Size_Mtbl_t*)((3 +2) * sizeof(void*)) //size. NOTE: all elements are standard-pointer-types.
1243        }
1244      , testOverrideAble_ImplIfc_Test_F //testOverrideAble
1245      , testOverridden_ImplIfc_Test_F //testOverridden
1246      , returnThisA_ImplIfc_Test_F //returnThisA
1247      , { { sign_Mtbl_SimpleClass_Test//J2C: Head of methodtable.
1248          , (struct Size_Mtbl_t*)((0 +2) * sizeof(void*)) //size. NOTE: all elements are standard-pointer-types.
1249          }
1250        , { { sign_Mtbl_ObjectJc//J2C: Head of methodtable.
1251            , (struct Size_Mtbl_t*)((5 +2) * sizeof(void*)) //size. NOTE: all elements are standard-pointer-types.
1252            }
1253          , clone_ObjectJc_F //clone
1254          , equals_ObjectJc_F //equals
1255          , finalize_ImplIfc_Test_F //finalize
1256          , hashCode_ObjectJc_F //hashCode
1257          , toString_ImplIfc_Test_F //toString
1258          }
1259        }
1260        / **J2C: Mtbl-interfaces of ImplIfc_Test: * /
1261      , { { sign_Mtbl_Ifc_Test//J2C: Head of methodtable.
1262          , (struct Size_Mtbl_t*)((3 +2) * sizeof(void*)) //size. NOTE: all elements are standard-pointer-types.
1263          }
1264        , processIfcMethod_i_ImplIfc_Test_F //processIfcMethod
1265        , anotherIfcmethod_i_ImplIfc_Test //anotherIfcmethod_i
1266        , anotherIfcmethod_f_ImplIfc_Test_F //anotherIfcmethod_f
1267        , { { sign_Mtbl_ObjectJc//J2C: Head of methodtable.
1268            , (struct Size_Mtbl_t*)((5 +2) * sizeof(void*)) //size. NOTE: all elements are standard-pointer-types.
1269            }
1270          , clone_ObjectJc_F //clone
1271          , equals_ObjectJc_F //equals
1272          , finalize_ImplIfc_Test_F //finalize
1273          , hashCode_ObjectJc_F //hashCode
1274          , toString_ImplIfc_Test_F //toString
1275          }
1276        }
1277      , { { sign_Mtbl_Ifc2_Test//J2C: Head of methodtable.
1278          , (struct Size_Mtbl_t*)((3 +2) * sizeof(void*)) //size. NOTE: all elements are standard-pointer-types.
1279          }
1280        , processIfcMethod_f_ImplIfc_Test //processIfcMethod
1281        , testIfc2_f_ImplIfc_Test //testIfc2
1282        , anotherIfcmethod_f_ImplIfc_Test_F //anotherIfcmethod
1283        , { { sign_Mtbl_ObjectJc//J2C: Head of methodtable.
1284            , (struct Size_Mtbl_t*)((5 +2) * sizeof(void*)) //size. NOTE: all elements are standard-pointer-types.
1285            }
1286          , clone_ObjectJc_F //clone
1287          , equals_ObjectJc_F //equals
1288          , finalize_ImplIfc_Test_F //finalize
1289          , hashCode_ObjectJc_F //hashCode
1290          , toString_ImplIfc_Test_F //toString
1291          }
1292        }
1293      }, { signEnd_Mtbl_ObjectJc, null } }; //Mtbl
1294      
1295     * </pre>
1296     * This method table is generated in the method {@link SecondPass#write_Reflections()} which calls
1297     * <br>{@link ClassData#genMethodTableContent(org.vishia.java2C.ClassData.InheritanceInfo, String, int)}.
1298     * <br>
1299     * It is a long term, because all method table parts of super classes and interfaces are contained
1300     * with the here implemented methods. The definition follows the type definition. Because the type definition
1301     * contains nested data, the data are extensive here in comparison to the type definition. 
1302     *  
1303     */
1304    public void D8_gen_MethodTable(){}
1305    
1306  }
1307  
1308  
1309  /**This chapter describes details of translation of inner classes. 
1310   * Inner classes are a essential element of programming. There are seven types:
1311   * <ul>
1312   * <li>Named static inner classes at class level: For that, the enclosing class is only a name spaces. 
1313   *     It is a strategy of building a union of closely depending parts. Such inner classes
1314   *     should be considerably only in the coherence with the enclosing class. It means,
1315   *     they should be private or protected mostly, or they should be need only in the same 
1316   *     code snippet together with the outer class. Elsewhere a primary class with its own file
1317   *     may be better to use. In static inner classes, all types and all static elements
1318   *     of the enclosing class are known directly without prefixing of the outer class. 
1319   * <li>Named non-static inner classes at class level: They have direct access to all elements of its enclosing 
1320   *     (outer) class, and they can be created with specification of an instance of the outer class 
1321   *     only. Internally there will be stored an aggregation (reference) to this outer class. 
1322   *     Such inner classes shouldn't be extensive. Elsewhere it may be better to have a primary class 
1323   *     with a named aggregation to the formerly other class.
1324         * <li>Anonymous non-static inner classes at class level: 
1325         *     They will be built in coherence with a class-level variable with a Java-construct like:
1326   *     <pre>
1327         *     final RefType name = new BaseType(param){
1328         *       //classBody of enhancing.
1329         *     };
1330         *     </pre>
1331         *     That classes are able to use in coherence with that variable only. Nevertheless there 
1332         *     are not binded to the variable, the variable holds the reference only. It is possible
1333         *     to assign the reference to another element. The class exists independently
1334         *     as definition and code snippet but is is access-able via the base-typed-reference only. 
1335         *     The variable-initialization may be final or not. The final usage is typical though
1336         *     the final keyword is missed in Java-sources often.
1337         *     <br><br>
1338         *     A static unnamed (anonymous) class can be implement
1339         *     and override methods of its BaseType to provide a specialized functionality. The access
1340         *     to a anonymous class can be done to the methods of the base type only. The anonymous class
1341         *     can have own variables, inner classes etc., all of the things like any other class-definition.
1342         *     But this elements are strong private. An access to private elements of a named inner class
1343         *     form the outer class is possible in Java, but an access to the elements of an anonymous class
1344         *     isn't possible from outside, because the class-type is not visible. 
1345         *     <br><br>
1346         *     Non-static classes have access to all elements of the enclosing (outer) class.
1347         *     Therefore anonymous non-static classes are probably able to use for implementing interfaces. 
1348         *     It may be the main usage
1349         *     of such classes and it substantiated the necessity of such constructs: If a primary class
1350         *     implements an interface, the implementing functionality may be subordinate, and it isn't
1351         *     documented and visible well enough. But if an inner class, which can or should be anonymous,
1352         *     and which need to be non-static, implements the interface, the implementing methods
1353         *     are the only one of these class. The access to all elements of the enclosing class
1354         *     supports usage of functionality of them.
1355         *     <br><br>
1356         *     For the Java2C-translation the anonymous class builds a normal struct adequate to named 
1357         *     non-static inner classes.
1358         *     The name of that CLASS_C-definition is derived from the variable-name.
1359         *     The access to the elements of the outer class is done in C using the <code>outer</code>-reference.
1360         *     
1361   * <li>Anonymous static inner classes at class level. 
1362   *     They will be built in coherence with static class-level variable with a Java-construct like:
1363   *     <pre>
1364         *     final static RefType name = new BaseType(param){
1365         *       //classBody of enhancing.
1366         *     };
1367         *     </pre>
1368         *     Its usage with the variable are equivalent with non-static-inner classed,
1369         *     but the variable is static and inside that class only static elements can be used.
1370         *     <br><br>
1371         *     For the Java2C-translation the anonymous class builds a normal struct adequate to named 
1372         *     static inner classes.
1373         *     The name of that CLASS_C-definition is derived from the variable-name.
1374         *     
1375         * <li>Static named classes at statement-block-level. 
1376         * <li>Non-static named classes at statement-block-level. 
1377         *        
1378         * <li>Non-static anonymous classes at statement-block-level.        
1379         *     They will be built inside a statement block. It is possible to initialize a block-level-
1380         *     variable with it, or use inside a expression like:
1381   *     <pre>
1382         *       methodCall(parameter, new BaseType(param){ ...body }, ...)
1383         *     </pre>
1384         *     or
1385         *     <pre>
1386         *       (new BaseType(param){ ...body }).executeMethod();
1387         *     </pre>
1388         *     In any case an instance is built with that type. The instance is referenced as is the rule.
1389         *     The reference can be assigned inside the called method. In the second example
1390         *     the reference may be stored in the <code>executeMethod()</code> because it is given
1391         *     as <code>this</code> there. The class is access-able with that reference only.
1392         * </ul>    
1393   */
1394  public class E_Inner_classes
1395  {
1396        
1397        /**Anonymous classes are a special construct of Java. They are written like:
1398         * <pre>
1399         * static RefType name = new BaseType(param){
1400         *   //classBody of enhancing.
1401         * };
1402         * </pre>
1403         * The <code>RefType</code> may be a super- or interface-Type of <code>BaseType</code>
1404         * or typical the same as <code>BaseType</code>. With this type the anoymous class is used.
1405         * <br><br>
1406         * The <code>BaseType</code> is the direct super type of the defined instance.
1407         * <br><br>
1408         * The <code>classBody for enhancing</code> may be overwrite some methods 
1409         * of the <code>BaseType</code> and can contain some variables or inner classes etc. too,
1410         * all what a class can be have. But it isn't possible to access other than the methods,
1411         * which are overridden. Only the overridden methods are visible in the <code>RefType</code>.
1412         * <br><br>
1413         * The constructor which is used is the adequate constructor of the <code>BaseType</code>.
1414         * The <code>classBody for enhancing</code> may define variable which can be initialized,
1415         * but an extra constructor is not possible to write.
1416         * <br><br>
1417         * The methods of the <code>classBody for enhancing</code> can access especially all elements
1418         * from the outer class, if this class is non-static, without the shown <b>static</b>-keyword.
1419         * Then a portal for example from an interface to the outer class through the anonymous class
1420         * is given. This is the most interisting aspect of inner anonymous classes. They implements
1421         * methods of the interface or overrides methods, but the methods are seperated from the outer class.
1422         * Not the outer class plays the role of the interface-implementer, but only the anonymous class.
1423         * That makes the implementing better supervise-able, respectively it allows the usage
1424         * of method names, which may be in coflicting with other interface implementations. 
1425         * Therefore it is an important concept for programming.
1426         * <br><br>
1427         * Such an anonymous class can be used whenever a new instance can be created. 
1428         * The anonymous class is bound only to the <code>new Type(param){ }</code>.
1429         * The suggestion, the declared <i>variable</i> is related immediate to the anonymous class is false.
1430         * The variable is only the reference to the instance of the anonymous class. 
1431         * A creation of an anonymous class-instance can also be done as part of an expression. 
1432         * If the anonymous class is defined inside a statement block, it is equal to definition it
1433         * as normal inner class at class level. It means the variables of the outer class body
1434         * can be accessed, but not the variables of the enclosing statement block.
1435         * <br><br>
1436         * <b>Translation of inner anoymous classes</b>
1437         * <br><br>
1438         * The inner anonymous class is translated in its first pass when the new-expression is evaluated.
1439         * This is inside {@link GenerateClass#createFieldDataNewObject(org.vishia.zbnf.ZbnfParseResultItem, org.vishia.zbnf.ZbnfParseResultItem, LocalIdents, LocalIdents, StatementBlock, String, ClassData, char, char, char, boolean)}
1440         * There the method {@link GenerateClass#gen_AnonymousClass(org.vishia.zbnf.ZbnfParseResultItem, org.vishia.zbnf.ZbnfParseResultItem, LocalIdents, StatementBlock, String, char, GenerateFile)}
1441         * is called. Inside that, the {@link FirstPass#runFirstPassClass(GenerateFile, String, String, String, String, org.vishia.zbnf.ZbnfParseResultItem, String, ClassData, java.util.List, boolean, ClassData)}
1442         * is called with an own instance of {@link FirstPass} and the {@link ClassData} 
1443         * of the anonymous type are produced.
1444         * <br><br>
1445         * The Definition of the struct of the inner class is placed in the header file in the same way
1446         * as for all other innerClasses, if the inner class can be used from outside.
1447         * The Definition of the struct is placed in the C-file, if the anonymous inner class is 
1448         * detected in the second pass only. But it is placed before the code of the current second path,
1449         * by using the {@link iWriteContent#writeCdefs(StringBuilder)}-method, 
1450         * which writes to {@link GenerateFile#uFileCDefinitions} buffer. This is placed before the 
1451         * adequate {@link GenerateFile#uFileCSecondPath} for the bodies. The definition of anonymous classes
1452         * in bodies of methods are never direct access-able outside, only via its base classes. 
1453         * So it shouldn't be defined in Headerfiles. But they are able to reference from outside.
1454         * Therefore, the reflection information is able to use unconditionally.
1455         * <br><br>
1456         * A adequate contruct of a 
1457         * <pre>
1458         * { //inside method body
1459         *   struct { data x; } stackVariable;
1460         * </pre>
1461         * which may be usual in C, it is not used in Java2C-translated codes.The machine code effort
1462         * is not lesser which such an construct against the extra definition of the struct with a internal-build-name
1463         * und use it with its name. But the representation of a extra definition is better. It is necessary 
1464         * for reflection and others. The anonymous class in Java has more capability as the anonymous struct
1465         * in C like shown above.
1466         * <br><br>
1467         * The constructor in an anonymous class is a overridden form of one of the constructors 
1468         * from the <code>BaseType</code>, selected by the actual parameters. It is overridden,
1469         * because the own local variables should be intialized too.
1470         * <br><br>
1471         * The anonymous classes are named in C. The name is built with a 
1472         * <code>C_</code><i>NameOfVariable</i><i>SuffixOuterClass</i> 
1473         * for all anonymous classes of variable initialization. if a new(..){...} outside of an variable
1474         * is translated, then <code>C</code><i>Nr</i><code>_</code><i>NameOfMethod</i><i>SuffixOuterClass</i>
1475         * is used to build the name, where <i>Nr</i> is the current number of anonymous class in the method,
1476         * started with 1 and mostly 1. This names mustn't be used as class-names by the user for other elements.
1477         * But there are specialized so that isn't suggest to do so. 
1478         *     
1479         */
1480        public void e1_anonymousClasses(){}
1481        
1482        
1483        /**The first pass of the inner classes are running while the first pass of the enclosing class
1484         * is processed. The inner classes are processed first, because there content may be known
1485         * while the first pass of the outer class runs.  At all events the {@link ClassData} of the 
1486         * inner classes may necessary to know, the ClassData are created as result of running its
1487         * first pass.
1488         * <br><br>
1489         * On the other hand, all elements of the outer class
1490         * are used only in the second pass of the inner class.
1491         * Inside the firstPass of the inner class, only types of other inner classes may be necessary to know.
1492         * TODO test complex constructs.  
1493         * 
1494         */
1495        public void firstPassOfInnerClasses(){}
1496        
1497        
1498        /**
1499         * The knowledge of field-identifiers and types of the outer classes and the sibling- inner classes
1500     * in inner classes and the knowledge of this one of the super classes in the derived classes
1501     * is necessary. But additionally the field-idents should be designated as outer or super ones.
1502     * That designation is contained in the fields {@link FieldData#nClassLevel} 
1503     * and {@link FieldData#nOuterLevel}. See {@link Docu.E_Inner_classes}    
1504     * 
1505     * The field-identifier of the outer class are registered for the inner class running 
1506     * {@link ClassData#completeFieldIdentsForInnerClasses()} at the end of the first pass. 
1507     * That is necessary because all idents are known only at the end of the first pass of the
1508     * outer class, but the first pass of the inner class is finished already, without knowledge
1509     * of the outer idents. All idents should be known while running the second pass only.
1510     * <br><br>
1511     * The method {@link ClassData#completeFieldIdentsFromOuterClass(LocalIdents)} is called unlike
1512     * if a class is generated in the second pass inside a block statement. In this case the 
1513     * first pass of this class is running only in the second pass of the environment.
1514     * <br><br>
1515     * The situation of same identifier in the outer and inner class is detected in that
1516     * complete-methods. The inner identifier covers the outer one.
1517     * 
1518         */
1519        public void fieldIdentsOfOuterClassAndSiblings(){}
1520        
1521        /**
1522     * The types of the outer class are registered for the inner class running 
1523     * {@link ClassData#completeTypesForInnerClasses()} at the end of the first stage of the 
1524     * first pass of the outer class. This is done after calling {@link FirstPass#buildType(StringBuilder, String, GenerateFile, String, String, String, String, org.vishia.zbnf.ZbnfParseResultItem, boolean, String, ClassData, java.util.List, boolean, ClassData, char)}
1525     * in the {@link GenerateFile#runFirstPassFile(org.vishia.zbnf.ZbnfParseResultItem, String, String, String)}
1526     * -routine respectively in {@link ReadStructure#postPrepare(org.vishia.java2C.ReadStructure.ZbnfToplevel)}
1527     * for creation of ClassData from the stc-file. 
1528     * That is necessary because all types are known only at the end of the first stage 
1529     * of the first pass of the
1530     * outer class, but the first passes of the inner classes are finished already, without knowledge
1531     * of the outer idents. All idents should be known while running the second stage of first pass
1532     * ({@link FirstPass#runFirstPass2(StringBuilder)}) and the second pass only.
1533     * <br><br>
1534     * 2014-08-16 ({@link FirstPass#gatherAllDefinitions(GenerateFile)}) run before runFirstPass2. It means there are 3 stages, because generation of methods inline or as macro.
1535     * <br><br>
1536     * For anonymous inner classes the types of the outer class are copied always in the 
1537     * {@link GenerateClass#gen_AnonymousClass(org.vishia.zbnf.ZbnfParseResultItem, org.vishia.zbnf.ZbnfParseResultItem, LocalIdents, StatementBlock, String, char, GenerateFile)}
1538     * -routine after processing the {@link FirstPass#buildType(StringBuilder, String, GenerateFile, String, String, String, String, org.vishia.zbnf.ZbnfParseResultItem, boolean, String, ClassData, java.util.List, boolean, ClassData, char)}
1539     * of the anonymous class. In that time all types are known already, because the first stage
1540     * of the outer class is running already and all types except the anonymous are known. 
1541     * <br><br>
1542     * The {@link ClassData} of the anonymous classes shouldn't be known as types, because there are
1543     * anonymous. It pertains to all class-level anonymous class and statement-block anonymous classes.
1544     * <br><br>
1545     * The {@link ClassData} of statement-block-level classes shouldn't be known as types, 
1546     * because there are visible only at that statement-block level.
1547     * 
1548         */
1549        public void typeIdentsOfOuterClassAndSiblings(){}
1550  }
1551
1552  /**This chapter describes details of translation.
1553   */
1554  public class F_Translation_Secondpass
1555  {
1556
1557  /**In Java a environment-type for a static method and a reference of a dynamic method are not differenced.
1558   * Both are written with a dot as separator:
1559   * <pre>
1560   * Arrays.binarySearch(..) //an example of static method of class Arrays
1561   * myInstance.method(...)  //a normal class method call.
1562   * </pre> 
1563   * The difference is detectable only searching the identifier in translator tables.
1564   * Therefore the identifier is tested in the method
1565   * in {@link StatementBlock#gen_reference(String[], ZbnfParseResultItem, LocalIdents, char, IdentInfos[] retIdentInfo)}.
1566   * The got association String from ZBNF-parse-result is tested calling {@link LocalIdents#getType(String, LocalIdents)}
1567   * in the given local environment. It includes especially standard types, 
1568   * but also local types in the class definition and the file-level types (package and import).
1569   * If the association String is recognized as Type, the associated type is used in the next reference levels
1570   * respectively it is returned in parameter retIdent. Because that type is the base type info for searching
1571   * the referenced identifier, the method calls in C are translated with the name_Type-info.    
1572   */  
1573    public void f1_referencesOrEnvironmentTypes()
1574    {
1575    }
1576
1577    
1578    
1579    /**There are four types of castings, it is the combination of 
1580     * <ul>
1581     * <li>implicitly or explicitly casts,
1582     * <li>casts of scalar types (int etc) or reference types.
1583     * </ul>
1584     * The casts of scalar types is equal in C and Java: Cast to a type with higher precision may be implicitly,
1585     * the cast to a type with less precision need s a explicitly cast. In Java it is necessary, 
1586     * in C it is a warning of compiler mostly, but it should done.
1587     * <br><br>
1588     * The casts of reference types may be separated in two cases:
1589     * <ul>
1590     * <li>downcast: From a class to a super class or interface.
1591     * <li>upcast: From a interface or super type to a derived type.
1592     * </ul>
1593     * The downcast may be implicit or explicit written in Java, both is correct. 
1594     * The compiler knows all possibilities of down-casting, tests and accepts it. 
1595     * In C a downcast have to be programmed  with an access to the correct and given super class or interface.
1596     * A simple pointer cast is the second properly variant. 
1597     * A pointer cast is always a possible sourse of errors. Therefore it should be avoid to use
1598     * if it isn't necessary. An access to a super class can be write with <code>&ref->base.super.base.super</code>
1599     * instead an equivalent <code>(SuperType*)(ref)</code>. The machine code is equal for both variants.
1600     * <br><br> 
1601     * A upcast is written explicitly also in Java. 
1602     * A upcast is correct if a reference given as super-class or interface reference references
1603     * really a instance which is from the casted type. In Java a runtime check is execute. 
1604     * The demand of upcast from programmer is an assumption. Therefore it should be done explicitely.
1605     * In C the adequate construct should be a cast also. Another way of solution isn't able. 
1606     * But the C runtime doesn't check the legitimacy of that cast. A goal to explain the cast
1607     * in a safety software check session is, the code is tested in Java. Another possibility may be,
1608     * also execute a instance type test. The second decision needs some calculation time, 
1609     * it's the same problem as check the array indices for IndexOutOfBoundsException. 
1610     * The decision in Java2C for this problem is: If a failed access is able to assume, the programmer
1611     * should be write a instance type test in Java explicitly. It is <code>assert(ref instance of Type);</code>.
1612     * It will be translated and executed in C too, and it is conspicuously and should sufficing for a safety software check.
1613     * <br><br>
1614     * For Java2C-translation the check of cast-ability and the production of a cast expression 
1615     * is necessary for some cases:
1616     * <ul>
1617     * <li>Check of type compatibleness for arguments of methods: See {@link #methodCall_WithParameterSensitivity()}.
1618     *   it should be tested if a given argument is matching to formal argument types. 
1619     *   The method {@link ClassData#matchedToTypeSrc(ClassData)} is provided for such check.
1620     * <li>Production of explicitly casts where Java allows an implicitly cast.
1621     * </ul>   
1622     * Another problem is the adaption of access. In Java only either primitive types or references
1623     * are addressed in a variable or with an expression. In C at least the embedded instances needs
1624     * a special handling, the reference operator <code>&ref->embeddedInstance</code>. 
1625     * Additionally there are some special cases like a <code>StringJc</code> or <code>OS_TimeStamp</code>,
1626     * which are taken as value arguments and returned as values in methods.
1627     * <br><br> 
1628     * <b>cast of an expression</b>: <br>
1629     * The method {@link FieldData#testAndcast(CCodeData, char)} produces the correct expression 
1630     * with given C-code including type and access mode of it in respect to a given field-type-description.
1631     * It is used at any assignments: method arguments, return value preparation and value assignments.
1632     * At example in Java it is coded <code>ref-embeddedInstance</code>, but a parameter or destination
1633     * variable is of an base or interface type. Than the method returns the necessary adaption 
1634     * for C language in form <code>&(ref->embeddedInstance.base.IfcType)</code>.
1635     * <br><br> 
1636     * <b>cast of the access</b>: <br>
1637     * The method {@link FieldData#testAndChangeAccess(char, String, char)} produces the correct expression
1638     * if only an access should be changed. 
1639     * <br><br>
1640     * <b>cast of an assignment</b>: <br>
1641     * See {@link StatementBlock#gen_AssignCheckCast(CCodeData, String, CCodeData)}. 
1642     * <br><br>
1643     * The methods {@link ClassData#addCastFromType(ClassData, String, String)} 
1644     * and {@link ClassData#addCastToType(ClassData, String, String)} adds a possibility of cast
1645     * to the a class. It is used explicitely for standard types, 
1646     * but also for declaring the possibility of access super and interface types, 
1647     * see {@link Docu.SuperClassesAndInterfaces}. 
1648     * It is called inside {@link ClassData#fillMethodsOverrideable(ClassData.InheritanceInfo inheritanceInfo, String sPathToMtbl, String sPathToBase)}
1649     * 
1650     */
1651    public void f2_casting(){}
1652    
1653    
1654    
1655    /**Methods in Java are parameter sensitive. This feature is known also as <i>overloading of methods</i>. 
1656     * It means, that an method of class StringBuilder
1657     * <code> append(int value)</code>
1658     * is another method as
1659     * <code> append(String value)</code>.
1660     * It is clear for Java users. Okay. In C++ it is the same concept.
1661     * <br><br>
1662     * But in C, the methods should have an unambiguously name. 
1663     * Therefore, the same steps have to be done which were done by a javac-compiler:
1664     * <ul>
1665     * <li>Ascertaining the type of all parameters of method call.
1666     * <li>Searching the appropriate method variant in the environment class, where the method is member of.
1667     * <li>If no appropriate method is found, variation of the type of parameters to their 
1668     *     generalized types, it means int from short, long from int or float from int etc., 
1669     *     but also detection of super classes and interface types of references. Search again.
1670     * <li>Building the C-like method name in a special style, considering the parameter types and the environment class name.
1671     * </ul>
1672     * This steps are done in Java2C-translation time. The result is visible in the generated C-code. 
1673     * This steps are done only if ambiguously method with the same names are exist. 
1674     * If only unambiguously method names in one class are given, a simple rule is used 
1675     * to build an unambiguously method name common spanned: <code>methodname_classname</code>.
1676     * <br><br><br>
1677     * For some lang and util-classes the methods have their fix names in the 
1678     * [[CRuntimeJavalike]]-C-Library, that is also useable for C-level-programming. Thats why, and also 
1679     * to support a testing at C-level the names of methods considering parameter types should be 
1680     * shortly, readable and understandable 
1681     * <br><br>
1682     * The translation of  Java method name plus parameter types to that C- method names are given 
1683     * in a translation table. There is no common fix rule to built it. 
1684     * But for method names of the users Java code to translate to C a rule  is given. 
1685     * <br><br>
1686     * The following things are implemented in the Java2C-Translator:
1687     * <ul>
1688     * <li>The <b>type of arguments</b> in the method call is detect calling 
1689     *     {@link StatementBlock#gen_value(ZbnfParseResultItem, char)}. 
1690     *     The type is returned in its {@link CCodeData}-return data. 
1691     *     The type of a value is build from 
1692     *     <ul>
1693     *     <li>The type of a variable, returned from 
1694     *         {@link StatementBlock#gen_variable(org.vishia.zbnf.ZbnfParseResultItem, LocalIdents, char, CCodeData)}
1695     *         {@link CCodeData}-return data.
1696     *     <li>The type of a constant value, returned from retType in
1697     *         {@link GenerateClass#genConstantValue(org.vishia.zbnf.ZbnfParseResultItem)}.
1698     *         The type of the constant value is detect while parsing the Java source code. The type of a numeric value
1699     *         is detect additional by testing the value range of the number. Especially the type of an string literal 
1700     *         in "string" is designated as {@link Java2C_Main.CRuntimeJavalikeClassData#clazz_s0}. 
1701     *         The <code>s0</code> means, C-like 0-terminated string. It is a special case of a String represented by
1702     *         { {@link Java2C_Main.CRuntimeJavalikeClassData#clazzStringJc}.
1703     *     <li>The type of a method is the return type. It is supplied in argument retType in
1704     *         {@link StatementBlock#gen_simpleMethodCall(org.vishia.zbnf.ZbnfParseResultItem, CCodeData, LocalIdents)}.
1705     *     <li>The type of a new Object is returned in retTypeValue from
1706     *         {@link StatementBlock#gen_newObject(org.vishia.zbnf.ZbnfParseResultItem, LocalIdents)} 
1707     *         or {@link StatementBlock#gen_newArray(org.vishia.zbnf.ZbnfParseResultItem, ClassData[], LocalIdents)}.
1708     *     </ul>
1709     * <li>Both a <b>method call and a constructor is translated</b> using 
1710     *     {@link StatementBlock#gen_simpleMethodCall(org.vishia.zbnf.ZbnfParseResultItem, CCodeData, LocalIdents)}.
1711     *     While translating the actual parameters are read from the ZbnfParseResultItem. The values are generated
1712     *     calling {@link StatementBlock#gen_value(org.vishia.zbnf.ZbnfParseResultItem, char)}.
1713     *     This method returns the type of the parameters. The types are used to search the method.
1714     * <li>To <b>search the method</b> {@link ClassData#searchMethod(String sNameJava, java.util.List paramsType)} 
1715     *     is called with the {@link ClassData}-instance of the environment type. 
1716     *     That is the type of the instance in Java left from point of method call. This ClassData are referenced from
1717     *     the parameter <code>envInstanceInfo</code> of <code>gen_simpleMethodCall()</code>.
1718     *     If the environment instance is <code>this</code>, the <code>envInstanceInfo</code> came from 
1719     *     {@link ClassData#classTypeInfo} of the own ClassData-Instance. 
1720     *     <ul>
1721     *     <li>The method is searched first with their number of arguments. It is possible that they are 
1722     *       more as one ambiguous method with the same name and the same number of arguments. 
1723     *       If there is only one method, its okay and unambiguous. Otherwise the types of the arguments
1724     *       are tested now.
1725     *     <li>If the types are matched directly, its okay. Elsewhere the routine {@link ClassData#matchedToTypeSrc(ClassData)}
1726     *         arbitrates whether the type is compatible. Than it is possible that a cast expression
1727     *         is necessary in C, without though an automatic casting in Java is done. 
1728     *         The cast expression is generated in 
1729     *         {@link StatementBlock#gen_simpleMethodCall(org.vishia.zbnf.ZbnfParseResultItem, CCodeData, LocalIdents)}.
1730     *     </ul> 
1731     * <li>The <b>method translating tables</b> from Java-name + parameter types to C-name are <b>created 
1732     *     for the CRuntimeJavalike-methods</b> in 
1733     *     {@link Java2C_Main.CRuntimeJavalikeClassData} - constructor. It is hand-made. 
1734     * <li>The method translating tables for translating classes will be created and filled 
1735     *     while executing 
1736     *     {@link FirstPass#runFirstPassFile(String, org.vishia.zbnf.ZbnfParseResultItem, String, ClassData, java.util.List, LocalIdents)}.
1737     *     <ul>
1738     *     <li>Before any other translation occurs, for all methods of the class,  {@link ClassData#testAndSetAmbiguousnessOfMethod(String)}
1739     *         is called with the java name of the method. If more as one method with the same name is found,
1740     *         the method name is ambiguous. Only than a complex method name for C should be built.
1741     *     <li>The methods are registered in first pass calling 
1742     *         {@link FirstPass#wrwrite_methodDeclaration(ZbnfParseResultItem parent, String sClassName, LocalIdents}.
1743     *         In this routine it is known whether or not the method is ambiguous, because all methods are tested before.
1744     *     <li>From there {@link FirstPass#gen_methodHeadAndRegisterMethod(org.vishia.zbnf.ZbnfParseResultItem, String, String, FieldData, boolean)},
1745     *         is called. In this routine the C-method-name is build either with argument-type-naming parts or not. 
1746     *         The argument-type-naming parts of the C-method-name are simple chars for standard types,
1747     *         see registration of standard types in {@link Java2C_Main.CRuntimeJavalikeClassData},
1748     *         calling the constructor of {@link ClassData#ClassData(String, String, String, String, String)}.
1749     *         A short name for user-Type-arguments is built with prominent chars of the type, 
1750     *         testing its unambiguously in global scope.
1751     *     <li>With that built C-Name and the argument types the method is registered in ClassData calling
1752     *         {@link ClassData#addMethod(String, String, FieldData, FieldData[])}.
1753     *     </ul>                 
1754     * </ul>        
1755     * 
1756     */
1757    public void f3_methodCall_WithParameterSensitivity()
1758    { SecondPass a;
1759      
1760    }
1761    
1762    
1763    /**Variable arguments are known both in Java and in C. 
1764     * In C the handling of variable arguments is more simple-primitive. 
1765     * The type of the arguments should be described somewhere else. The typical known application
1766     * of them is printf. Hereby the type of arguments are described in the printf-text 
1767     * combined with the format specification, at example 
1768     * <code>printf("values: %3.3f, %4d\n", floatValue, intValue);</code>. It is classic. 
1769     * Because the type of values may not correct (float or double, long, short), the compiler 
1770     * may convert a float value in double etc. to prevent errors. The originally idea was 
1771     * to determine the fine specification of the type with modifiers such as <code>%3hd</code> for short.
1772     * But already float and double are not possible to difference. Some compilers operates variedly.
1773     * That is C/C++.
1774     * <br><br>
1775     * In Java the problem of a printf-like formatting is some more separated from the variable argument handling.
1776     * Variable arguments are accepted as array of the same types. Because any complex type can downcast 
1777     * to the base Type Object, and any simple type has a representation as Object (int as class Integer etc.),
1778     * any argument can be provided as an Object:
1779     * <pre>
1780     *   method(Object ...){...} //declaration of a method
1781     *   method(5, 3.4, intVal, classInstance); //call of method.
1782     * </pre>
1783     * Java2C generated a type String as argument before a variable argument list in any case.
1784     * The type String contains the detect type of any actual argument as one letter. Especially
1785     * the primitive and some Standard types are detect in this way. All complex types are supplied as ObjectJc.
1786     * Therefore the method from example above has the following representation in C:
1787     * <pre>
1788     *   method(char const* typeArgs, ...);   //declaration of method
1789     *   method("IDIL", 5, 3.4, intVal, classInstance); //call
1790     * </pre>    
1791     *    ...TODO
1792     * 
1793     */
1794    public void f4_methodCallWithVariableArguments(){}
1795    
1796    
1797    
1798    
1799    public void f5_methodCallFromSuperClasses(){}
1800    
1801    public void f6_methodCallFromOuterClasses(){}
1802    
1803    
1804    /**A constructor is either a static method of the associated class, or it is understand as
1805     * a non-static method of the outer class, if the class is an non-static inner class.
1806     * The constructor is searched calling {@link ClassData#searchMethod(String, java.util.List, boolean)},
1807     * where the name is
1808     * <ul>
1809     * <li>"ctorO" for a static constructor with a class based on Object,
1810     * <li>"ctorM" for a static constructor with a class non-based on Object,
1811     * <li>"ctorO_InnerClassName" for a non-static constructor of a inner class based on Object.
1812     *     In this case the constructor is searched first in the given ClassData of the inner class,
1813     *     but it isn't found there. Because the inner-class has an outer one, the searching is continued
1814     *     in the outer class, and there the constructor is found as a non-static one.
1815     * <li>"ctorM_InnerClassName" adequate non-Object-based.
1816     * </ul>
1817     * To difference whether or not the associated class is a non-static-inner one,
1818     * the property {@link ClassData#isNonStaticInner} is checked.
1819     * This rules are regarded in 
1820     * <ul>
1821     * <li>{@link StatementBlock#genInitEmbeddedInstance(org.vishia.zbnf.ZbnfParseResultItem, org.vishia.zbnf.ZbnfParseResultItem, FieldData, String, int)}
1822     * <li>{@link StatementBlock#gen_newObject(org.vishia.zbnf.ZbnfParseResultItem, CCodeData, LocalIdents)}
1823     * </ul>
1824     * The correct constructor is found depending on its parameter, which are given as second param
1825     * while calling {@link ClassData#searchMethod(String, java.util.List, boolean)}.     
1826     * 
1827     */
1828    public void f7_constructorCall(){}
1829    
1830    
1831    
1832    /**The translation process of details should know informations about its environment of call. 
1833     * At example it is a difference whether a expression is evaluated for an assignment 
1834     * or to provide an actual parameter. Therefore a parameter named 'intension' is used often.
1835     * <ul>
1836     * <li> 'C' Class level variable def or inner class
1837     * <li> 'c' constructor body, 
1838     * <li> 'm' gen_statementBlock: -method body, 
1839     * <li> 'b' internal block, 
1840     * <li> 'z' part of if, while etc., 
1841     * <li> 'f' finalize body. 
1842     * <li> '=' . The argument retIdentInfo is a call by returned reference.
1843     * <li> 'R' the left element of a reference.
1844     * <li> 'r' for the next nested reference
1845     * <li> 'e' gen_value:-value in an expression, enhanced references are taken with .ref
1846     * <li> 'l' gen_value:-left value, 
1847     * <li> 'a' gen_value:-argument in c-file (head of routine)
1848     * <li> 'A' gen_value:-argument in h-file (prototype-definition)
1849     * <li> 't' gen_simpleMethodCall: String concatenation
1850     * <li> 'i' gen_assignValue: init value
1851     * <li> 's' Static variable
1852     * <li> 'P' top-level class
1853     * <li> 'Y' anonymous inner class at class level
1854     * <li> 'x' extern
1855     * <li> 'u' throw text expression, use String Buffer in Thread context.
1856     * </ul>       
1857     * Usage in several methods:
1858     * <table>
1859     * <th><td><code>Ccmbzf=RrelaAtisPYxu</code></td><td>method</td></th>
1860     * <tr><td><code>--------------------</code></td><td>{@link SecondPass#gen_statementBlock(org.vishia.zbnf.ZbnfParseResultItem, int, org.vishia.java2C.StatementBlock, FieldData, char)}</td></tr>
1861     * <tr><td><code>-cmb-f-----aA-------</code></td><td>{@link SecondPass#gen_variableDefinition(org.vishia.zbnf.ZbnfParseResultItem, org.vishia.zbnf.ZbnfParseResultItem, LocalIdents, java.util.List, char)}</td></tr>
1862     * <tr><td><code>C--------------s----</code></td><td>{@link GenerateClass#gen_AnonymousClass(org.vishia.zbnf.ZbnfParseResultItem, LocalIdents, String, char, GenerateFile)}</td></tr>
1863     * <tr><td><code>Ccmb------------P---</code></td><td> {@link FirstPass#buildType(StringBuilder, String, GenerateFile, String, String, String, String, org.vishia.zbnf.ZbnfParseResultItem, boolean, String, ClassData, java.util.List, boolean, ClassData, char)}</td></tr>
1864     * <tr><td><code>Ccmb------------PYx-</code></td><td> {@link ClassData#ClassData(String, GenerateFile, String, String, String, String, String, char, ClassData, ClassData, ClassData[], org.vishia.zbnf.ZbnfParseResultItem, String, char, LocalIdents)}</td></tr>
1865     * <tr><td><code>---------ela-------u</code></td><td> {@link StatementBlock#gen_simpleValue(org.vishia.zbnf.ZbnfParseResultItem, org.vishia.zbnf.ZbnfParseResultItem, org.vishia.zbnf.ZbnfParseResultItem, LocalIdents, boolean, char, boolean)}</td></tr>
1866     * </table>
1867     */
1868    public void f9_intension_of_call(){}
1869    
1870  }
1871  
1872  
1873  
1874  /**This chapter describes some cohesion of allocation, initializing (construction), finalizing, 
1875   * garbage collection. 
1876   * 
1877   *
1878   */
1879  class G_Instantiation
1880  {
1881        /**In Java there are two kinds of instances:
1882         * <ul><li>Primitive types such as int, float. This instances are created embedded or in stack.
1883         *   Their content is copied always if there are taken in a method call.
1884         * <li>Instances based on Object. This instances are created in the heap always, they are referenced.
1885         *   It the content is taken in a method call, a reference will be copied.
1886         * </ul>
1887         * In opposite, in C there are given four kinds of instances:
1888         * <ul>
1889         * <li>Primitive type, same as in Java.
1890         * <li>Embedded types. Their are only some types like <code>MemC</code>, <code>StringJC</code>
1891         *   or <code>OS_TimeStamp</code>, which are presented in that kind. This instances are used
1892         *   embedded only. They are taken as arguments or as return-value of methods per value anytime.
1893         *   They are never referenced. It is similar like primitive types. The embedded types are
1894         *   short structures, only consisting of less memory words. They should pass through registers
1895         *   as return value.   
1896         * <li>Structured instances not base on Object.
1897         * <li>Structured instances based on Object. Both kinds of structured instances can be allocated
1898         *   in the heap, may be embedded in another structure and may be created in static memory space. 
1899         *   It can be used with a reference, or maybe with given instance. If they are used as arguments
1900         *   or return values from methods, they are referenced anyway.   
1901         * </ul>
1902         * Embedded types are types, which are deployed in C with a simple small struct, 
1903         * handled call and return per value. There are applications for that concept for special cases.
1904         * * {@link FieldData#modeAccess} = '$'
1905         */
1906        void g1_kindOfInstances(){}
1907        
1908        void g2_allocation(){}
1909
1910        /**In the CRuntimeJavalike context a <code>struct MemC {int32 size_; MemAreaC* address;} </code>
1911         * is defined. 
1912         * It is placed in the header file <code>fw_MemC.h</code>, because it is not a own concept of 
1913         * CRuntimeJavalike, 
1914         * but an own concept of common C-programming. This struct MemC is an answer about the question: 
1915         * <i>I have a void*-pointer to the memory, but which and how many bytes....</i> 
1916         * In generally a void*-pointer is a undefined thing. No type is given, no size is known. 
1917         * A <code>void*</code> is a well concept in the C-language with its closure to machine level, 
1918         * but not for user-level programming.
1919         * <br><br>
1920         * An instance described with <code>MemC</code> is undefined in type, but defined in size. 
1921         * It is a representation of raw memory. An allocation of memory with <code>alloc_MemC(size)</code> 
1922         * returns this struct with the found address and the associated size. It is one parameter for using. 
1923         * Otherwise the size is separated from the void*-pointer and mistakes are possible. 
1924         * The MemC comprises only 2 register values. Therefore most of C compilers return it 
1925         * in machine level in 2 register, not in a copied struct. It is efficient.
1926         * 
1927         */
1928        void g3_referencingWithMemC(){}
1929        
1930        /**The four kinds of instances (see {@link #g1_kindOfInstances()}) uses several kinds of constructors
1931         * to initial them with given arguments:
1932         * <ul>
1933         * <li>Primitive types doesn't need a constructor. Initial values are assigned immediately.
1934         * <li>Embedded types are initialized calling a <code>INIT...(THIS, ...)</code>-routine. The first
1935         *   argument is the instance itself, not referenced. The <code>INIT...(THIS, ...)</code> should be
1936         *   implemented as a macro anyway. Mostly it is a simple macro.
1937         * <li>A non-ObjectJc-based instance is initialized with a <code>ctorM...(MemC mthis, ...)</code>-
1938         *   constructor. The memory space for the instance is given in a MemC-structure, which contains
1939         *   the pointer and the length information about the memory space of the instance. The MemC-value
1940         *   may be a return value of a <code>alloc_MemC(size)</code>-call or it is build from a given
1941         *   embedded instance using a build_MemC(ref, length)-method. The ctorM-method should check
1942         *   whether the memory space is large enough. It should not be assumed, that the data are initialized
1943         *   with 0. The initializing should be done in the constructor.
1944         * <li>A ObjectJc-based instance is initialized with a <code>ctorO...(ObjectJc* othis, ...)</code>-
1945         *   constructor. The memory space for the instance is given with the ObjectJc-pointer. The 
1946         *   ObjectJc-data should be initialized already, only the reflection information can't be set.
1947         *   The size of the instance is contained in the ObjectJc-objectIdentSize value. It can be seen
1948         *   as guaranteed, that the rest of values are initialized with 0 already. Either the 
1949         *   <code>alloc_ObjectJc(...)</code> method has initialized all allocated memory bytes with 0, 
1950         *   and it has initialized the ObjectJc-base data, or the <code>init_ObjectJc(...)</code>-method
1951         *   should be do that.
1952         *   <br><br>
1953         *   The ObjectJc-pointer
1954         *   may be a return value of a <code>alloc_ObjectJc(size)</code>-call or it is build from a given
1955         *   embedded instance with referencing it. The ctorO-method should check
1956         *   whether the memory space is large enough.< 
1957         *   <br><br>
1958         *   The initializing of an embedded instance should be done before calling the method
1959         *   <code>init_ObjectJc(ObjectJc* ythis, int sizeObj, int identObj)</code>.
1960         *   This routine sets the initial values of the ObjectJc-data and sets the rest of data to 0.
1961         * <ul>
1962         */
1963        void g5_ctor(){}
1964
1965        void g10_enhancedRefs(){}
1966
1967        void g11_garbageCollection(){}
1968
1969        void g12_blockHeap(){}
1970
1971        /**Java knows a method Object.finalize(), which is called from the system before the instance
1972         * is removed from memory. It is invoked in cohesion with the garbage collector. The finalize()-
1973         * method can be overridden in any instance. But this method should be used carefully. 
1974         * It is not deterministic when and whether at all this method is invoked because the garbage-
1975         * collector has its own rules. If the instance isn't use anymore, it is possible that it isn't
1976         * removed by the garbage collector, because there is enough memory and thereby no need of
1977         * freeing memory. A programmer shouldn't use this method for normal clearing up actions
1978         * for example to close files.
1979         * <br><br>
1980         * In the case of using the {@link #g5_blockHeap()} the finalize method is used especially
1981         * to remove enhanced references. The references may refer other instances which were in use,
1982         * although the instance itself isn't use and it is freed therefore. 
1983         * The referred instances contains backward references to the freed instance. If the enhanced
1984         * references are not cleaned, that backward references are faulty.
1985         * <br><br>
1986         * Therefore the finalize-method is generated from the Java2C-translator to clean the 
1987         * enhanced references. In the finalize()-method the finalized-methods of embedded instances
1988         * and of the super classes are called too. If a user-written finalize()-method is present in
1989         * the Java-code, its content will be included firstly.
1990         * <br><br>
1991         * Only for instances which aren't base on Object (simple data) and which doesn't contain
1992         * enhanced references no finalize method is generated. The property {@link ClassData#bFinalizeNeed}
1993         * contains the information about. It is set calling {@link ClassData#needFinalize()}
1994         * or {@link ClassData#setBodyForFinalize(org.vishia.zbnf.ZbnfParseResultItem)}.
1995         * It is able to quest calling {@link ClassData#isFinalizeNeed()}.
1996         * <br><br>
1997         * The finalize()-method is generated with 
1998         * {@link SecondPass#write_finalizeDefinition(org.vishia.zbnf.ZbnfParseResultItem, String, LocalIdents)}.
1999         */
2000        void g16_finalizing(){}
2001
2002        
2003        
2004        /**Embedded types are types, which are deployed in C with a simple small struct, 
2005         * handled call and return per value. There are applications for that concept for special cases.
2006         * * {@link FieldData#modeAccess} = '$'
2007         * 
2008         */
2009        void g7_embeddedTypes(){}
2010        
2011        
2012  }
2013  
2014  
2015  class H_StringProcessing
2016  {
2017        
2018  }
2019  
2020  /**All annotations
2021   * <ul>
2022   * <li>nonPersistent: to an reference: Designates, that the referenced data 
2023   *   may be non-persistent. The reference can be assigned only to another nonPersistent reference.
2024   *   Especially it can't be assigned to class-level references. But the reference can be used
2025   *   as instance-reference for method-calls.
2026   * <li>nonPersistent: to a method-parameter: Designates, that the parameter is used non-persistent
2027   *   in the called routine. It means, the referenced content isn't referenced independently
2028   *   with operations inside this routine in any other class-reference or static-reference.
2029   *   The Java2C-translator checks the assignment to a non-nonPersistent reference and causes
2030   *   an error if it os done.
2031   * <li>toStringNonPersist: to an expression containing a <code>toString()</code> especially
2032   *   with a StringBuilder.toString():
2033   *   Determines that the String is processed immediately before any other change on the StringBuilder-
2034   *   instance may be done. An access in any other thread is excluded too. The programmer should 
2035   *   declare this behavior, it should be able to supervise in less instructions. The java2c-translator
2036   *   can build a StringJc from the StringBuilder-content without any additional operation.
2037   *   It is optimal respectively usage of memory. 
2038   * </ul>
2039   * 
2040   */
2041  class N_annotations_Java2C
2042  {
2043        
2044  }
2045  
2046
2047  /**There are some Examples showing Java code and the generated C-Code. This Examples containing in
2048   * {@link org.vishia.java2C.test} are similar the type test exemplars.
2049   * <br>
2050   * <br>
2051   * See 
2052   * <ul>
2053   * <li>{@link org.vishia.java2C.test.SimpleClass}: A simple class
2054   * <li>{@link org.vishia.java2C.test.SimpleDataStruct}
2055   * <li>{@link org.vishia.java2C.test.ExpandedDataStruct}
2056   * <li>{@link org.vishia.java2C.test.Ifc}, {@link org.vishia.java2C.test.Ifc2}: interface definition
2057   * <li>{@link org.vishia.java2C.test.ImplIfc}: standard methods of implementation interfaces
2058   * <li>{@link org.vishia.java2C.test.TestString}: string processing
2059   * <li>{@link org.vishia.java2C.test.TestAllConcepts}: virtual methods etc.
2060   * </ul>
2061   */
2062  class X_Examples
2063  {
2064  }
2065  
2066  
2067}