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
16 * (that is, a ".java" file). Other node types represent fragments of a
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
22 * source string. See individual <code>create</code> methods for details on
23 * the default values supplied. The factory does its best to recognize Java
24 * structures in the source provided. If the factory is completely unable to
25 * recognize source 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();
60 * Creates a JDOM on the given source code. The syntax for the given source
61 * code corresponds to CompilationUnit (JLS2 7.3).
64 * the source code character array, or <code>null</code>
66 * the name of the compilation unit
67 * @return the new compilation unit, or <code>null</code> if unable to
68 * recognize the source code, or if the source code is
71 public IDOMCompilationUnit createCompilationUnit(char[] sourceCode,
75 * Creates a JDOM on the given source code. The syntax for the given source
76 * code corresponds to CompilationUnit (JLS2 7.3).
79 * the source code string, or <code>null</code>
81 * the name of the compilation unit
82 * @return the new compilation unit, or <code>null</code> if unable to
83 * recognize the source code, or if the source code is
86 public IDOMCompilationUnit createCompilationUnit(String sourceCode,
89 * Creates a default field document fragment. Initially the field will have
90 * default protection, type <code>"Object"</code>, name
91 * <code>"aField"</code>, no comment, and no initializer.
93 * @return the new field
95 // public IDOMField createField();
97 * Creates a field document fragment on the given source code. The given
98 * source string corresponds to FieldDeclaration (JLS2 8.3) and
99 * ConstantDeclaration (JLS2 9.3) restricted to a single VariableDeclarator
104 * @return the new field, or <code>null</code> if unable to recognize the
105 * source code, if the source code is <code>null</code>, or when
106 * the source contains more than one VariableDeclarator clause
108 // public IDOMField createField(String sourceCode);
110 * Creates an empty import document fragment. Initially the import will have
111 * name <code>"java.lang.*"</code>.
113 * @return the new import
115 // public IDOMImport createImport();
117 * Creates an import document fragment on the given source code. The syntax
118 * for the given source string corresponds to ImportDeclaration (JLS2 7.5).
122 * @return the new import, or <code>null</code> if unable to recognize the
123 * source code, or if the source code is <code>null</code>
125 // public IDOMImport createImport(String sourceCode);
127 * Creates an empty initializer document fragment. Initially the initializer
128 * will be static and have no body or comment.
130 * @return the new initializer
132 // public IDOMInitializer createInitializer();
134 * Creates an initializer document fragment from the given source code. The
135 * syntax for the given source string corresponds to InstanceInitializer
136 * (JLS2 8.6) and StaticDeclaration (JLS2 8.7).
140 * @return the new initializer, or <code>null</code> if unable to
141 * recognize the source code, or if the source code is
144 // public IDOMInitializer createInitializer(String sourceCode);
146 * Creates a default method document fragment. Initially the method will
147 * have public visibility, return type <code>"void"</code>, be named
148 * <code>"newMethod"</code>, have no parameters, no comment, and an empty
151 * @return the new method
153 // public IDOMMethod createMethod();
155 * Creates a method document fragment on the given source code. The syntax
156 * for the given source string corresponds to MethodDeclaration (JLS2 8.4),
157 * ConstructorDeclaration (JLS2 8.8), and AbstractMethodDeclaration (JLS2
162 * @return the new method, or <code>null</code> if unable to recognize the
163 * source code, or if the source code is <code>null</code>
165 // public IDOMMethod createMethod(String sourceCode);
167 * Creates an empty package document fragment. Initially the package
168 * declaration will have no name.
170 * @return the new package
172 // public IDOMPackage createPackage();
174 * Creates a package document fragment on the given source code. The syntax
175 * for the given source string corresponds to PackageDeclaration (JLS2 7.4).
179 * @return the new package, or <code>null</code> if unable to recognize
180 * the source code, or if the source code is <code>null</code>
182 // public IDOMPackage createPackage(String sourceCode);
184 * Creates a default type document fragment. Initially the type will be a
185 * public class named <code>"AClass"</code>, with no members or comment.
187 * @return the new type
189 // public IDOMType createType();
191 * Creates a default type document fragment. Initially the type will be a
192 * public class named <code>"AClass"</code>, with no members or comment.
194 * @return the new class
197 // public IDOMType createClass();
199 * Creates a default type document fragment. Initially the type will be a
200 * public interface named <code>"AnInterface"</code>, with no members or
203 * @return the new interface
206 // public IDOMType createInterface();
208 * Creates a type document fragment on the given source code. The syntax for
209 * the given source string corresponds to ClassDeclaration (JLS2 8.1) and
210 * InterfaceDeclaration (JLS2 9.1).
214 * @return the new type, or <code>null</code> if unable to recognize the
215 * source code, or if the source code is <code>null</code>
217 // public IDOMType createType(String sourceCode);