1 /*******************************************************************************
2 * Copyright (c) 2000, 2003 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v10.html
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core.jdom;
14 * A factory used to create document fragment (DF) nodes. An
15 * <code>IDOMCompilationUnit</code> represents the root of a complete JDOM (that
16 * is, a ".java" file). Other node types represent fragments of a compilation
19 * The factory can be used to create empty DFs or it can create DFs from source
20 * strings. All DFs created empty are assigned default values as required, such
21 * that a call to <code>IDOMNode.getContents</code> will generate a valid source
22 * string. See individual <code>create</code> methods for details on the default
23 * values supplied. The factory does its best to recognize Java structures in
24 * the source provided. If the factory is completely unable to recognize source
25 * constructs, the factory method returns <code>null</code>.
28 * Even if a DF is created successfully from source code, it does not guarantee
29 * that the source code will compile error free. Similarly, the contents of a DF
30 * are not guaranteed to compile error free. However, syntactically correct
31 * source code is guaranteed to be recognized and successfully generate a DF.
32 * Similarly, if all of the fragments of a JDOM are syntactically correct, the
33 * contents of the entire document will be correct too.
36 * The factory does not perform or provide any code formatting. Document
37 * fragments created on source strings must be pre-formatted. The JDOM attempts
38 * to maintain the formatting of documents as best as possible. For this reason,
39 * document fragments created for nodes that are to be strung together should
40 * end with a new-line character. Failing to do so will result in a document
41 * that has elements strung together on the same line. This is especially
42 * important if a source string ends with a // comment. In this case, it would
43 * be syntactically incorrect to omit the new line character.
46 * This interface is not intended to be implemented by clients.
51 public interface IDOMFactory {
53 * Creates and return an empty JDOM. The initial content is an empty string.
55 * @return the new compilation unit
57 public IDOMCompilationUnit createCompilationUnit();
59 * Creates a JDOM on the given source code. The syntax for the given source
60 * code corresponds to CompilationUnit (JLS2 7.3).
62 * @param sourceCode the source code character array, or <code>null</code>
63 * @param name the name of the compilation unit
64 * @return the new compilation unit, or <code>null</code> if unable to recognize
65 * the source code, or if the source code is <code>null</code>
67 public IDOMCompilationUnit createCompilationUnit(char[] sourceCode, String name);
69 * Creates a JDOM on the given source code. The syntax for the given source
70 * code corresponds to CompilationUnit (JLS2 7.3).
72 * @param sourceCode the source code string, or <code>null</code>
73 * @param name the name of the compilation unit
74 * @return the new compilation unit, or <code>null</code> if unable to recognize
75 * the source code, or if the source code is <code>null</code>
77 public IDOMCompilationUnit createCompilationUnit(String sourceCode, String name);
79 * Creates a default field document fragment. Initially the field will have
80 * default protection, type <code>"Object"</code>, name <code>"aField"</code>,
81 * no comment, and no initializer.
83 * @return the new field
85 //public IDOMField createField();
87 * Creates a field document fragment on the given source code. The given source
88 * string corresponds to FieldDeclaration (JLS2 8.3) and ConstantDeclaration
89 * (JLS2 9.3) restricted to a single VariableDeclarator clause.
91 * @param sourceCode the source code
92 * @return the new field, or <code>null</code> if unable to recognize
93 * the source code, if the source code is <code>null</code>, or when the source
94 * contains more than one VariableDeclarator clause
96 //public IDOMField createField(String sourceCode);
98 * Creates an empty import document fragment. Initially the import will have
99 * name <code>"java.lang.*"</code>.
101 * @return the new import
103 //public IDOMImport createImport();
105 * Creates an import document fragment on the given source code. The syntax for
106 * the given source string corresponds to ImportDeclaration (JLS2 7.5).
108 * @param sourceCode the source code
109 * @return the new import, or <code>null</code> if unable to recognize
110 * the source code, or if the source code is <code>null</code>
112 //public IDOMImport createImport(String sourceCode);
114 * Creates an empty initializer document fragment. Initially the initializer
115 * will be static and have no body or comment.
117 * @return the new initializer
119 //public IDOMInitializer createInitializer();
121 * Creates an initializer document fragment from the given source code. The
122 * syntax for the given source string corresponds to InstanceInitializer
123 * (JLS2 8.6) and StaticDeclaration (JLS2 8.7).
125 * @param sourceCode the source code
126 * @return the new initializer, or <code>null</code> if unable to recognize
127 * the source code, or if the source code is <code>null</code>
129 //public IDOMInitializer createInitializer(String sourceCode);
131 * Creates a default method document fragment. Initially the method
132 * will have public visibility, return type <code>"void"</code>, be named
133 * <code>"newMethod"</code>, have no parameters, no comment, and an empty body.
135 * @return the new method
137 //public IDOMMethod createMethod();
139 * Creates a method document fragment on the given source code. The syntax for
140 * the given source string corresponds to MethodDeclaration (JLS2 8.4),
141 * ConstructorDeclaration (JLS2 8.8), and AbstractMethodDeclaration (JLS2 9.4).
143 * @param sourceCode the source code
144 * @return the new method, or <code>null</code> if unable to recognize
145 * the source code, or if the source code is <code>null</code>
147 //public IDOMMethod createMethod(String sourceCode);
149 * Creates an empty package document fragment. Initially the package
150 * declaration will have no name.
152 * @return the new package
154 //public IDOMPackage createPackage();
156 * Creates a package document fragment on the given source code. The syntax for
157 * the given source string corresponds to PackageDeclaration (JLS2 7.4).
159 * @param sourceCode the source code
160 * @return the new package, or <code>null</code> if unable to recognize
161 * the source code, or if the source code is <code>null</code>
163 //public IDOMPackage createPackage(String sourceCode);
165 * Creates a default type document fragment. Initially the type will be
166 * a public class named <code>"AClass"</code>, with no members or comment.
168 * @return the new type
170 //public IDOMType createType();
172 * Creates a default type document fragment. Initially the type will be
173 * a public class named <code>"AClass"</code>, with no members or comment.
175 * @return the new class
178 //public IDOMType createClass();
180 * Creates a default type document fragment. Initially the type will be
181 * a public interface named <code>"AnInterface"</code>, with no members or comment.
183 * @return the new interface
186 //public IDOMType createInterface();
188 * Creates a type document fragment on the given source code. The syntax for the
189 * given source string corresponds to ClassDeclaration (JLS2 8.1) and
190 * InterfaceDeclaration (JLS2 9.1).
192 * @param sourceCode the source code
193 * @return the new type, or <code>null</code> if unable to recognize
194 * the source code, or if the source code is <code>null</code>
196 //public IDOMType createType(String sourceCode);