/*******************************************************************************
* Copyright (c) 2000, 2008 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jdt.core.jdom;
/**
* A factory used to create document fragment (DF) nodes. An <code>IDOMCompilationUnit</code>
* represents the root of a complete JDOM (that is, a source file with one of the
* {@link org.eclipse.jdt.core.JavaCore#getJavaLikeExtensions() Java-like extensions}). Other node
* types represent fragments of a compilation unit.
* <p>
* The factory can be used to create empty DFs or it can create DFs from source strings. All DFs
* created empty are assigned default values as required, such that a call to
* <code>IDOMNode.getContents</code> will generate a valid source string. See individual
* <code>create</code> methods for details on the default values supplied. The factory does its best
* to recognize Java structures in the source provided. If the factory is completely unable to
* recognize source constructs, the factory method returns <code>null</code>.
* </p>
* <p>
* Even if a DF is created successfully from source code, it does not guarantee that the source code
* will compile error free. Similarly, the contents of a DF are not guaranteed to compile error
* free. However, syntactically correct source code is guaranteed to be recognized and successfully
* generate a DF. Similarly, if all of the fragments of a JDOM are syntactically correct, the
* contents of the entire document will be correct too.
* </p>
* <p>
* The factory does not perform or provide any code formatting. Document fragments created on source
* strings must be pre-formatted. The JDOM attempts to maintain the formatting of documents as best
* as possible. For this reason, document fragments created for nodes that are to be strung together
* should end with a new-line character. Failing to do so will result in a document that has
* elements strung together on the same line. This is especially important if a source string ends
* with a // comment. In this case, it would be syntactically incorrect to omit the new line
* character.
* </p>
*
* @see IDOMNode
* @deprecated The JDOM was made obsolete by the addition in 2.0 of the more powerful, fine-grained
* DOM/AST API found in the org.eclipse.jdt.core.dom package.
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IDOMFactory {
/**
* Creates and return an empty JDOM. The initial content is an empty string.
*
* @return the new compilation unit
*/
public IDOMCompilationUnit createCompilationUnit();
/**
* Creates a JDOM on the given source code. The syntax for the given source code corresponds to
* CompilationUnit (JLS2 7.3).
*
* @param sourceCode the source code character array, or <code>null</code>
* @param name the name of the compilation unit
* @return the new compilation unit, or <code>null</code> if unable to recognize the source
* code, or if the source code is <code>null</code>
*/
public IDOMCompilationUnit createCompilationUnit(char[] sourceCode, String name);
/**
* Creates a JDOM on the given source code. The syntax for the given source code corresponds to
* CompilationUnit (JLS2 7.3).
*
* @param sourceCode the source code string, or <code>null</code>
* @param name the name of the compilation unit
* @return the new compilation unit, or <code>null</code> if unable to recognize the source
* code, or if the source code is <code>null</code>
*/
public IDOMCompilationUnit createCompilationUnit(String sourceCode, String name);
/**
* Creates a default field document fragment. Initially the field will have default protection,
* type <code>"Object"</code>, name <code>"aField"</code>, no comment, and no initializer.
*
* @return the new field
*/
public IDOMField createField();
/**
* Creates a field document fragment on the given source code. The given source string
* corresponds to FieldDeclaration (JLS2 8.3) and ConstantDeclaration (JLS2 9.3) restricted to a
* single VariableDeclarator clause.
*
* @param sourceCode the source code
* @return the new field, or <code>null</code> if unable to recognize the source code, if the
* source code is <code>null</code>, or when the source contains more than one
* VariableDeclarator clause
*/
public IDOMField createField(String sourceCode);
/**
* Creates an empty import document fragment. Initially the import will have name
* <code>"java.lang.*"</code> and be non-static.
*
* @return the new import
*/
public IDOMImport createImport();
/**
* Creates an import document fragment on the given source code. The syntax for the given source
* string corresponds to ImportDeclaration (JLS2 7.5).
*
* @param sourceCode the source code
* @return the new import, or <code>null</code> if unable to recognize the source code, or if
* the source code is <code>null</code>
*/
public IDOMImport createImport(String sourceCode);
/**
* Creates an empty initializer document fragment. Initially the initializer will be static and
* have no body or comment.
*
* @return the new initializer
*/
public IDOMInitializer createInitializer();
/**
* Creates an initializer document fragment from the given source code. The syntax for the given
* source string corresponds to InstanceInitializer (JLS2 8.6) and StaticDeclaration (JLS2 8.7).
*
* @param sourceCode the source code
* @return the new initializer, or <code>null</code> if unable to recognize the source code, or
* if the source code is <code>null</code>
*/
public IDOMInitializer createInitializer(String sourceCode);
/**
* Creates a default method document fragment. Initially the method will have public visibility,
* return type <code>"void"</code>, be named <code>"newMethod"</code>, have no parameters, no
* comment, and an empty body.
*
* @return the new method
*/
public IDOMMethod createMethod();
/**
* Creates a method document fragment on the given source code. The syntax for the given source
* string corresponds to MethodDeclaration (JLS2 8.4), ConstructorDeclaration (JLS2 8.8), and
* AbstractMethodDeclaration (JLS2 9.4).
*
* @param sourceCode the source code
* @return the new method, or <code>null</code> if unable to recognize the source code, or if
* the source code is <code>null</code>
*/
public IDOMMethod createMethod(String sourceCode);
/**
* Creates an empty package document fragment. Initially the package declaration will have no
* name.
*
* @return the new package
*/
public IDOMPackage createPackage();
/**
* Creates a package document fragment on the given source code. The syntax for the given source
* string corresponds to PackageDeclaration (JLS2 7.4).
*
* @param sourceCode the source code
* @return the new package, or <code>null</code> if unable to recognize the source code, or if
* the source code is <code>null</code>
*/
public IDOMPackage createPackage(String sourceCode);
/**
* Creates a default type document fragment. Initially the type will be a public class named
* <code>"AClass"</code>, with no members or comment.
*
* @return the new type
*/
public IDOMType createType();
/**
* Creates a default type document fragment. Initially the type will be a public class named
* <code>"AClass"</code>, with no members or comment.
*
* @return the new class
* @since 2.0
*/
public IDOMType createClass();
/**
* Creates a default type document fragment. Initially the type will be a public interface named
* <code>"AnInterface"</code>, with no members or comment.
*
* @return the new interface
* @since 2.0
*/
public IDOMType createInterface();
/**
* Creates a type document fragment on the given source code. The syntax for the given source
* string corresponds to ClassDeclaration (JLS2 8.1) and InterfaceDeclaration (JLS2 9.1).
*
* @param sourceCode the source code
* @return the new type, or <code>null</code> if unable to recognize the source code, or if the
* source code is <code>null</code>
*/
public IDOMType createType(String sourceCode);
}