KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > services > compiler > JavaFactory


1 /*
2
3    Derby - Class org.apache.derby.iapi.services.compiler.JavaFactory
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.services.compiler;
23
24 import org.apache.derby.iapi.services.loader.ClassFactory;
25
26 /**
27  * JavaFactory provides generators for Java constructs.
28  * Once Java constructs have been connected into
29  * a complete class definition, the class can be generated
30  * from them.
31  * The generated class is created as a byte-code array that
32  * can then be loaded by a class loader or, in our case,
33  * the class utilities wrapper around our special class loader.
34  * <p>
35  * Each method shows the equivalent Java in the line starting
36  * "Java:" in the header comment. Items in the java code that
37  * begin with # refer to parameters used in constructing the
38  * object. So, for example, newReturnStatement takes a parameter
39  * named value; its Java code is:
40  * <verbatim>
41    Java: return #value;
42    </verbatim>
43  * <p>
44  * This represents the fact that newReturnStatement returns a
45  * object that represents a return statement that returns the
46  * value represented by the parameter named value.
47  * <p>
48  * REVISIT: when StandardException is moved to BasicServices,
49  * all of these want to support it so they can throw
50  * real NotImplementedYet exceptions. It is expected that alot
51  * of this interface can be not-implemented for engines that
52  * do not need this complete treatment of the language.
53  * <p>
54  * Known Java constructs missing from this interface include:
55  * <ul>
56  * <li> array initializers
57  * <li> ,-lists of statements in for segments
58  * <li> accessing a field of the current object or class without
59  * including this or the class name
60  * <li> declaring a list of variables against one type
61  * <li> conversions/coercions/promotions of types
62  * <li> empty statement
63  * <li> labeled statement
64  * <li> switch statement
65  * <li> break, continue statements
66  * <li> "super" expression (akin to the "this" expression).
67  * <li> operations on multi-dimensional arrays
68  * </ul>
69  * <p>
70  * This interface also does not do real compilation -- there are no
71  * checks for things like initialization before use of variables,
72  * inclusion of catchs on throws, dead code, etc. Its purpose is to
73  * let other parts of the system piece together what they know is valid
74  * code and get bytecode out of doing that.
75  * <p>
76  * Also, implementations will require that the constructs be built
77  * appropriately or they may fail to produce a valid class. For example,
78  * newStaticMethodCall must be used to call static methods only,
79  * not non-static local instance methods.
80  * <p>
81  * Implementations may be more, or less strict. You are best off assuming
82  * you have to piece together each java construct and be as explicit as
83  * possible. So, constructors must be created with newConstructor, not
84  * newMethodBuilder; constructors must include the explicit call to
85  * super(...) or this(...), as their first statement; all methods and
86  * constructors must contain a final return statement at the end of
87  * their code path(s). Method calls will derive the method to call
88  * based on the type of the argument, so you must cast arguments as
89  * the system will not search for a close method and coerce arguments
90  * appropriately. This includes coercing them to be some superclass or
91  * interface that they already are.
92  *
93  * @author ames
94  */
95 public interface JavaFactory {
96
97     public final static String JavaDoc JAVA_FACTORY_PROPERTY = "derby.module.JavaCompiler";
98
99     /**
100      * a class. Once it is created, fields, methods,
101      * interfaces, static initialization code,
102      * and constructors can be added to it.
103      * <verbatim>
104        Java: package #packageName;
105          #modifiers #className extends #superClass { }
106             // modifiers is the | of the JVM constants for
107             // the modifiers such as static, public, etc.
108        </verbatim>
109      *
110        @param cf ClassFactory to be used for class resolution (debug only)
111        and loading of the generated class.
112      * @param packageName the name of the package the class is in
113         including the trailing 'dot' if it is not the empty package.
114         Pass the empty package as "".
115      * @param modifiers the | of the Modifier
116      * constants representing the visibility and control of this
117      * method.
118      * @param className the name of the class or interface
119      * @param superClass the name of the superclass or superinterface
120      *
121      * @return the class builder.
122      * @see java.lang.reflect.Modifier
123      */
124     ClassBuilder newClassBuilder(ClassFactory cf, String JavaDoc packageName,
125         int modifiers, String JavaDoc className, String JavaDoc superClass);
126 }
127
Popular Tags