--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.services.compiler.JavaFactory\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.services.compiler;\r
+\r
+import org.apache.derby.iapi.services.loader.ClassFactory;\r
+\r
+/**\r
+ * JavaFactory provides generators for Java constructs.\r
+ * Once Java constructs have been connected into\r
+ * a complete class definition, the class can be generated\r
+ * from them.\r
+ * The generated class is created as a byte-code array that\r
+ * can then be loaded by a class loader or, in our case,\r
+ * the class utilities wrapper around our special class loader.\r
+ * <p>\r
+ * Each method shows the equivalent Java in the line starting\r
+ * "Java:" in the header comment. Items in the java code that\r
+ * begin with # refer to parameters used in constructing the\r
+ * object. So, for example, newReturnStatement takes a parameter\r
+ * named value; its Java code is:\r
+ * <verbatim>\r
+ Java: return #value;\r
+ </verbatim>\r
+ * <p>\r
+ * This represents the fact that newReturnStatement returns a\r
+ * object that represents a return statement that returns the\r
+ * value represented by the parameter named value.\r
+ * <p>\r
+ * REVISIT: when StandardException is moved to BasicServices,\r
+ * all of these want to support it so they can throw\r
+ * real NotImplementedYet exceptions. It is expected that alot\r
+ * of this interface can be not-implemented for engines that\r
+ * do not need this complete treatment of the language.\r
+ * <p>\r
+ * Known Java constructs missing from this interface include:\r
+ * <ul>\r
+ * <li> array initializers\r
+ * <li> ,-lists of statements in for segments\r
+ * <li> accessing a field of the current object or class without\r
+ * including this or the class name\r
+ * <li> declaring a list of variables against one type\r
+ * <li> conversions/coercions/promotions of types\r
+ * <li> empty statement\r
+ * <li> labeled statement\r
+ * <li> switch statement\r
+ * <li> break, continue statements\r
+ * <li> "super" expression (akin to the "this" expression).\r
+ * <li> operations on multi-dimensional arrays\r
+ * </ul>\r
+ * <p>\r
+ * This interface also does not do real compilation -- there are no\r
+ * checks for things like initialization before use of variables,\r
+ * inclusion of catchs on throws, dead code, etc. Its purpose is to\r
+ * let other parts of the system piece together what they know is valid\r
+ * code and get bytecode out of doing that.\r
+ * <p>\r
+ * Also, implementations will require that the constructs be built\r
+ * appropriately or they may fail to produce a valid class. For example,\r
+ * newStaticMethodCall must be used to call static methods only,\r
+ * not non-static local instance methods.\r
+ * <p>\r
+ * Implementations may be more, or less strict. You are best off assuming\r
+ * you have to piece together each java construct and be as explicit as\r
+ * possible. So, constructors must be created with newConstructor, not\r
+ * newMethodBuilder; constructors must include the explicit call to\r
+ * super(...) or this(...), as their first statement; all methods and\r
+ * constructors must contain a final return statement at the end of\r
+ * their code path(s). Method calls will derive the method to call\r
+ * based on the type of the argument, so you must cast arguments as\r
+ * the system will not search for a close method and coerce arguments\r
+ * appropriately. This includes coercing them to be some superclass or\r
+ * interface that they already are.\r
+ *\r
+ */\r
+public interface JavaFactory {\r
+\r
+ public final static String JAVA_FACTORY_PROPERTY = "derby.module.JavaCompiler";\r
+\r
+ /**\r
+ * a class. Once it is created, fields, methods,\r
+ * interfaces, static initialization code, \r
+ * and constructors can be added to it.\r
+ * <verbatim>\r
+ Java: package #packageName;\r
+ #modifiers #className extends #superClass { }\r
+ // modifiers is the | of the JVM constants for\r
+ // the modifiers such as static, public, etc.\r
+ </verbatim>\r
+ *\r
+ @param cf ClassFactory to be used for class resolution (debug only)\r
+ and loading of the generated class.\r
+ * @param packageName the name of the package the class is in\r
+ including the trailing 'dot' if it is not the empty package.\r
+ Pass the empty package as "".\r
+ * @param modifiers the | of the Modifier\r
+ * constants representing the visibility and control of this\r
+ * method.\r
+ * @param className the name of the class or interface\r
+ * @param superClass the name of the superclass or superinterface\r
+ *\r
+ * @return the class builder.\r
+ * @see java.lang.reflect.Modifier\r
+ */\r
+ ClassBuilder newClassBuilder(ClassFactory cf, String packageName,\r
+ int modifiers, String className, String superClass);\r
+}\r