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