001: /*
002:
003: Derby - Class org.apache.derby.iapi.services.compiler.JavaFactory
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.services.compiler;
023:
024: import org.apache.derby.iapi.services.loader.ClassFactory;
025:
026: /**
027: * JavaFactory provides generators for Java constructs.
028: * Once Java constructs have been connected into
029: * a complete class definition, the class can be generated
030: * from them.
031: * The generated class is created as a byte-code array that
032: * can then be loaded by a class loader or, in our case,
033: * the class utilities wrapper around our special class loader.
034: * <p>
035: * Each method shows the equivalent Java in the line starting
036: * "Java:" in the header comment. Items in the java code that
037: * begin with # refer to parameters used in constructing the
038: * object. So, for example, newReturnStatement takes a parameter
039: * named value; its Java code is:
040: * <verbatim>
041: Java: return #value;
042: </verbatim>
043: * <p>
044: * This represents the fact that newReturnStatement returns a
045: * object that represents a return statement that returns the
046: * value represented by the parameter named value.
047: * <p>
048: * REVISIT: when StandardException is moved to BasicServices,
049: * all of these want to support it so they can throw
050: * real NotImplementedYet exceptions. It is expected that alot
051: * of this interface can be not-implemented for engines that
052: * do not need this complete treatment of the language.
053: * <p>
054: * Known Java constructs missing from this interface include:
055: * <ul>
056: * <li> array initializers
057: * <li> ,-lists of statements in for segments
058: * <li> accessing a field of the current object or class without
059: * including this or the class name
060: * <li> declaring a list of variables against one type
061: * <li> conversions/coercions/promotions of types
062: * <li> empty statement
063: * <li> labeled statement
064: * <li> switch statement
065: * <li> break, continue statements
066: * <li> "super" expression (akin to the "this" expression).
067: * <li> operations on multi-dimensional arrays
068: * </ul>
069: * <p>
070: * This interface also does not do real compilation -- there are no
071: * checks for things like initialization before use of variables,
072: * inclusion of catchs on throws, dead code, etc. Its purpose is to
073: * let other parts of the system piece together what they know is valid
074: * code and get bytecode out of doing that.
075: * <p>
076: * Also, implementations will require that the constructs be built
077: * appropriately or they may fail to produce a valid class. For example,
078: * newStaticMethodCall must be used to call static methods only,
079: * not non-static local instance methods.
080: * <p>
081: * Implementations may be more, or less strict. You are best off assuming
082: * you have to piece together each java construct and be as explicit as
083: * possible. So, constructors must be created with newConstructor, not
084: * newMethodBuilder; constructors must include the explicit call to
085: * super(...) or this(...), as their first statement; all methods and
086: * constructors must contain a final return statement at the end of
087: * their code path(s). Method calls will derive the method to call
088: * based on the type of the argument, so you must cast arguments as
089: * the system will not search for a close method and coerce arguments
090: * appropriately. This includes coercing them to be some superclass or
091: * interface that they already are.
092: *
093: * @author ames
094: */
095: public interface JavaFactory {
096:
097: public final static String JAVA_FACTORY_PROPERTY = "derby.module.JavaCompiler";
098:
099: /**
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 packageName,
125: int modifiers, String className, String superClass);
126: }
|