001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.core.jdom;
011:
012: /**
013: * A factory used to create document fragment (DF) nodes. An
014: * <code>IDOMCompilationUnit</code> represents the root of a complete JDOM (that
015: * is, a source file with one of the
016: * {@link org.eclipse.jdt.core.JavaCore#getJavaLikeExtensions()
017: * Java-like extensions}). Other node types represent fragments of a compilation
018: * unit.
019: * <p>
020: * The factory can be used to create empty DFs or it can create DFs from source
021: * strings. All DFs created empty are assigned default values as required, such
022: * that a call to <code>IDOMNode.getContents</code> will generate a valid source
023: * string. See individual <code>create</code> methods for details on the default
024: * values supplied. The factory does its best to recognize Java structures in
025: * the source provided. If the factory is completely unable to recognize source
026: * constructs, the factory method returns <code>null</code>.
027: * </p>
028: * <p>
029: * Even if a DF is created successfully from source code, it does not guarantee
030: * that the source code will compile error free. Similarly, the contents of a DF
031: * are not guaranteed to compile error free. However, syntactically correct
032: * source code is guaranteed to be recognized and successfully generate a DF.
033: * Similarly, if all of the fragments of a JDOM are syntactically correct, the
034: * contents of the entire document will be correct too.
035: * </p>
036: * <p>
037: * The factory does not perform or provide any code formatting. Document
038: * fragments created on source strings must be pre-formatted. The JDOM attempts
039: * to maintain the formatting of documents as best as possible. For this reason,
040: * document fragments created for nodes that are to be strung together should
041: * end with a new-line character. Failing to do so will result in a document
042: * that has elements strung together on the same line. This is especially
043: * important if a source string ends with a // comment. In this case, it would
044: * be syntactically incorrect to omit the new line character.
045: * </p>
046: * <p>
047: * This interface is not intended to be implemented by clients.
048: * </p>
049: *
050: * @see IDOMNode
051: * @deprecated The JDOM was made obsolete by the addition in 2.0 of the more
052: * powerful, fine-grained DOM/AST API found in the
053: * org.eclipse.jdt.core.dom package.
054: */
055: public interface IDOMFactory {
056: /**
057: * Creates and return an empty JDOM. The initial content is an empty string.
058: *
059: * @return the new compilation unit
060: */
061: public IDOMCompilationUnit createCompilationUnit();
062:
063: /**
064: * Creates a JDOM on the given source code. The syntax for the given source
065: * code corresponds to CompilationUnit (JLS2 7.3).
066: *
067: * @param sourceCode the source code character array, or <code>null</code>
068: * @param name the name of the compilation unit
069: * @return the new compilation unit, or <code>null</code> if unable to recognize
070: * the source code, or if the source code is <code>null</code>
071: */
072: public IDOMCompilationUnit createCompilationUnit(char[] sourceCode,
073: String name);
074:
075: /**
076: * Creates a JDOM on the given source code. The syntax for the given source
077: * code corresponds to CompilationUnit (JLS2 7.3).
078: *
079: * @param sourceCode the source code string, or <code>null</code>
080: * @param name the name of the compilation unit
081: * @return the new compilation unit, or <code>null</code> if unable to recognize
082: * the source code, or if the source code is <code>null</code>
083: */
084: public IDOMCompilationUnit createCompilationUnit(String sourceCode,
085: String name);
086:
087: /**
088: * Creates a default field document fragment. Initially the field will have
089: * default protection, type <code>"Object"</code>, name <code>"aField"</code>,
090: * no comment, and no initializer.
091: *
092: * @return the new field
093: */
094: public IDOMField createField();
095:
096: /**
097: * Creates a field document fragment on the given source code. The given source
098: * string corresponds to FieldDeclaration (JLS2 8.3) and ConstantDeclaration
099: * (JLS2 9.3) restricted to a single VariableDeclarator clause.
100: *
101: * @param sourceCode the source code
102: * @return the new field, or <code>null</code> if unable to recognize
103: * the source code, if the source code is <code>null</code>, or when the source
104: * contains more than one VariableDeclarator clause
105: */
106: public IDOMField createField(String sourceCode);
107:
108: /**
109: * Creates an empty import document fragment. Initially the import will have
110: * name <code>"java.lang.*"</code> and be non-static.
111: *
112: * @return the new import
113: */
114: public IDOMImport createImport();
115:
116: /**
117: * Creates an import document fragment on the given source code. The syntax for
118: * the given source string corresponds to ImportDeclaration (JLS2 7.5).
119: *
120: * @param sourceCode the source code
121: * @return the new import, or <code>null</code> if unable to recognize
122: * the source code, or if the source code is <code>null</code>
123: */
124: public IDOMImport createImport(String sourceCode);
125:
126: /**
127: * Creates an empty initializer document fragment. Initially the initializer
128: * will be static and have no body or comment.
129: *
130: * @return the new initializer
131: */
132: public IDOMInitializer createInitializer();
133:
134: /**
135: * Creates an initializer document fragment from the given source code. The
136: * syntax for the given source string corresponds to InstanceInitializer
137: * (JLS2 8.6) and StaticDeclaration (JLS2 8.7).
138: *
139: * @param sourceCode the source code
140: * @return the new initializer, or <code>null</code> if unable to recognize
141: * the source code, or if the source code is <code>null</code>
142: */
143: public IDOMInitializer createInitializer(String sourceCode);
144:
145: /**
146: * Creates a default method document fragment. Initially the method
147: * will have public visibility, return type <code>"void"</code>, be named
148: * <code>"newMethod"</code>, have no parameters, no comment, and an empty body.
149: *
150: * @return the new method
151: */
152: public IDOMMethod createMethod();
153:
154: /**
155: * Creates a method document fragment on the given source code. The syntax for
156: * the given source string corresponds to MethodDeclaration (JLS2 8.4),
157: * ConstructorDeclaration (JLS2 8.8), and AbstractMethodDeclaration (JLS2 9.4).
158: *
159: * @param sourceCode the source code
160: * @return the new method, or <code>null</code> if unable to recognize
161: * the source code, or if the source code is <code>null</code>
162: */
163: public IDOMMethod createMethod(String sourceCode);
164:
165: /**
166: * Creates an empty package document fragment. Initially the package
167: * declaration will have no name.
168: *
169: * @return the new package
170: */
171: public IDOMPackage createPackage();
172:
173: /**
174: * Creates a package document fragment on the given source code. The syntax for
175: * the given source string corresponds to PackageDeclaration (JLS2 7.4).
176: *
177: * @param sourceCode the source code
178: * @return the new package, or <code>null</code> if unable to recognize
179: * the source code, or if the source code is <code>null</code>
180: */
181: public IDOMPackage createPackage(String sourceCode);
182:
183: /**
184: * Creates a default type document fragment. Initially the type will be
185: * a public class named <code>"AClass"</code>, with no members or comment.
186: *
187: * @return the new type
188: */
189: public IDOMType createType();
190:
191: /**
192: * Creates a default type document fragment. Initially the type will be
193: * a public class named <code>"AClass"</code>, with no members or comment.
194: *
195: * @return the new class
196: * @since 2.0
197: */
198: public IDOMType createClass();
199:
200: /**
201: * Creates a default type document fragment. Initially the type will be
202: * a public interface named <code>"AnInterface"</code>, with no members or comment.
203: *
204: * @return the new interface
205: * @since 2.0
206: */
207: public IDOMType createInterface();
208:
209: /**
210: * Creates a type document fragment on the given source code. The syntax for the
211: * given source string corresponds to ClassDeclaration (JLS2 8.1) and
212: * InterfaceDeclaration (JLS2 9.1).
213: *
214: * @param sourceCode the source code
215: * @return the new type, or <code>null</code> if unable to recognize
216: * the source code, or if the source code is <code>null</code>
217: */
218: public IDOMType createType(String sourceCode);
219: }
|