IDOMFactory


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jdt.core.jdom;
12  
13  /**
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 source file with one of the 
17   * {@link org.eclipse.jdt.core.JavaCore#getJavaLikeExtensions() 
18   * Java-like extensions}). Other node types represent fragments of a compilation
19   * unit.
20   * <p>
21   * The factory can be used to create empty DFs or it can create DFs from source
22   * strings. All DFs created empty are assigned default values as required, such
23   * that a call to <code>IDOMNode.getContents</code> will generate a valid source
24   * string. See individual <code>create</code> methods for details on the default
25   * values supplied. The factory does its best to recognize Java structures in
26   * the source provided. If the factory is completely unable to recognize source
27   * constructs, the factory method returns <code>null</code>.
28   * </p>
29   * <p>
30   * Even if a DF is created successfully from source code, it does not guarantee
31   * that the source code will compile error free. Similarly, the contents of a DF
32   * are not guaranteed to compile error free. However, syntactically correct 
33   * source code is guaranteed to be recognized and successfully generate a DF.
34   * Similarly, if all of the fragments of a JDOM are syntactically correct, the
35   * contents of the entire document will be correct too.
36   * </p>
37   * <p>
38   * The factory does not perform or provide any code formatting. Document 
39   * fragments created on source strings must be pre-formatted. The JDOM attempts
40   * to maintain the formatting of documents as best as possible. For this reason,
41   * document fragments created for nodes that are to be strung together should 
42   * end with a new-line character. Failing to do so will result in a document
43   * that has elements strung together on the same line. This is especially
44   * important if a source string ends with a // comment. In this case, it would
45   * be syntactically incorrect to omit the new line character.
46   * </p>
47   * <p>
48   * This interface is not intended to be implemented by clients.
49   * </p>
50   *
51   * @see IDOMNode
52   * @deprecated The JDOM was made obsolete by the addition in 2.0 of the more
53   * powerful, fine-grained DOM/AST API found in the 
54   * org.eclipse.jdt.core.dom package.
55   */
56  public interface IDOMFactory {
57  /**
58   * Creates and return an empty JDOM. The initial content is an empty string.
59   *
60   * @return the new compilation unit
61   */
62  public IDOMCompilationUnit createCompilationUnit();
63  /**
64   * Creates a JDOM on the given source code. The syntax for the given source
65   * code corresponds to CompilationUnit (JLS2 7.3).
66   *
67   * @param sourceCode the source code character array, or <code>null</code>
68   * @param name the name of the compilation unit
69   * @return the new compilation unit, or <code>null</code> if unable to recognize
70   *   the source code, or if the source code is <code>null</code>
71   */
72  public IDOMCompilationUnit createCompilationUnit(char[] sourceCode, String   name);
73  /**
74   * Creates a JDOM on the given source code. The syntax for the given source
75   * code corresponds to CompilationUnit (JLS2 7.3).
76   *
77   * @param sourceCode the source code string, or <code>null</code>
78   * @param name the name of the compilation unit
79   * @return the new compilation unit, or <code>null</code> if unable to recognize
80   *   the source code, or if the source code is <code>null</code>
81   */
82  public IDOMCompilationUnit createCompilationUnit(String   sourceCode, String   name);
83  /**
84   * Creates a default field document fragment. Initially the field will have
85   * default protection, type <code>"Object"</code>, name <code>"aField"</code>,
86   * no comment, and no initializer.
87   *
88   * @return the new field
89   */
90  public IDOMField createField();
91  /**
92   * Creates a field document fragment on the given source code. The given source
93   * string corresponds to FieldDeclaration (JLS2 8.3) and ConstantDeclaration 
94   * (JLS2 9.3) restricted to a single VariableDeclarator clause.
95   *
96   * @param sourceCode the source code
97   * @return the new field, or <code>null</code> if unable to recognize
98   *   the source code, if the source code is <code>null</code>, or when the source
99   *   contains more than one VariableDeclarator clause
100  */
101 public IDOMField createField(String   sourceCode);
102 /**
103  * Creates an empty import document fragment. Initially the import will have
104  * name <code>"java.lang.*"</code> and be non-static.
105  *
106  * @return the new import
107  */
108 public IDOMImport createImport();
109 /**
110  * Creates an import document fragment on the given source code. The syntax for
111  * the given source string corresponds to ImportDeclaration (JLS2 7.5).
112  *
113  * @param sourceCode the source code
114  * @return the new import, or <code>null</code> if unable to recognize
115  *   the source code, or if the source code is <code>null</code>
116  */
117 public IDOMImport createImport(String   sourceCode);
118 /**
119  * Creates an empty initializer document fragment. Initially the initializer
120  * will be static and have no body or comment.
121  *
122  * @return the new initializer
123  */
124 public IDOMInitializer createInitializer();
125 /**
126  * Creates an initializer document fragment from the given source code. The
127  * syntax for the given source string corresponds to InstanceInitializer 
128  * (JLS2 8.6) and StaticDeclaration (JLS2 8.7).
129  *
130  * @param sourceCode the source code
131  * @return the new initializer, or <code>null</code> if unable to recognize
132  *   the source code, or if the source code is <code>null</code>
133  */
134 public IDOMInitializer createInitializer(String   sourceCode);
135 /**
136  * Creates a default method document fragment. Initially the method
137  * will have public visibility, return type <code>"void"</code>, be named 
138  * <code>"newMethod"</code>, have no parameters, no comment, and an empty body.
139  *
140  * @return the new method
141  */
142 public IDOMMethod createMethod();
143 /**
144  * Creates a method document fragment on the given source code. The syntax for
145  * the given source string corresponds to MethodDeclaration (JLS2 8.4),  
146  * ConstructorDeclaration (JLS2 8.8), and AbstractMethodDeclaration (JLS2 9.4).
147  *
148  * @param sourceCode the source code
149  * @return the new method, or <code>null</code> if unable to recognize
150  *   the source code, or if the source code is <code>null</code>
151  */
152 public IDOMMethod createMethod(String   sourceCode);
153 /**
154  * Creates an empty package document fragment. Initially the package 
155  * declaration will have no name.
156  *
157  * @return the new package
158  */
159 public IDOMPackage createPackage();
160 /**
161  * Creates a package document fragment on the given source code. The syntax for
162  * the given source string corresponds to PackageDeclaration (JLS2 7.4).
163  *
164  * @param sourceCode the source code
165  * @return the new package, or <code>null</code> if unable to recognize
166  *   the source code, or if the source code is <code>null</code>
167  */
168 public IDOMPackage createPackage(String   sourceCode);
169 /**
170  * Creates a default type document fragment. Initially the type will be
171  * a public class named <code>"AClass"</code>, with no members or comment.
172  *
173  * @return the new type
174  */
175 public IDOMType createType();
176 /**
177  * Creates a default type document fragment. Initially the type will be
178  * a public class named <code>"AClass"</code>, with no members or comment.
179  *
180  * @return the new class
181  * @since 2.0
182  */
183 public IDOMType createClass();
184 /**
185  * Creates a default type document fragment. Initially the type will be
186  * a public interface named <code>"AnInterface"</code>, with no members or comment.
187  *
188  * @return the new interface
189  * @since 2.0
190  */
191 public IDOMType createInterface();
192 /**
193  * Creates a type document fragment on the given source code. The syntax for the
194  * given source string corresponds to ClassDeclaration (JLS2 8.1) and 
195  * InterfaceDeclaration (JLS2 9.1).
196  *
197  * @param sourceCode the source code
198  * @return the new type, or <code>null</code> if unable to recognize
199  *   the source code, or if the source code is <code>null</code>
200  */
201 public IDOMType createType(String   sourceCode);
202 }
203
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags