org.eclipse.jdt.core.jdom.IDOMFactory Maven / Gradle / Ivy

/*******************************************************************************
 * 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
 * IDOMCompilationUnit 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.
 * 
 * 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 IDOMNode.getContents will generate a valid source
 * string. See individual create 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 null.
 * 
 * 
 * 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.
 * 
 * 
 * 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.
 * 
 *
 * @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 null
 * @param name the name of the compilation unit
 * @return the new compilation unit, or null if unable to recognize
 *   the source code, or if the source code is null
 */
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 null
 * @param name the name of the compilation unit
 * @return the new compilation unit, or null if unable to recognize
 *   the source code, or if the source code is null
 */
public IDOMCompilationUnit createCompilationUnit(String sourceCode, String name);
/**
 * Creates a default field document fragment. Initially the field will have
 * default protection, type "Object", name "aField",
 * 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 null if unable to recognize
 *   the source code, if the source code is null, 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 "java.lang.*" 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 null if unable to recognize
 *   the source code, or if the source code is null
 */
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 null if unable to recognize
 *   the source code, or if the source code is null
 */
public IDOMInitializer createInitializer(String sourceCode);
/**
 * Creates a default method document fragment. Initially the method
 * will have public visibility, return type "void", be named
 * "newMethod", 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 null if unable to recognize
 *   the source code, or if the source code is null
 */
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 null if unable to recognize
 *   the source code, or if the source code is null
 */
public IDOMPackage createPackage(String sourceCode);
/**
 * Creates a default type document fragment. Initially the type will be
 * a public class named "AClass", 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 "AClass", 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 "AnInterface", 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 null if unable to recognize
 *   the source code, or if the source code is null
 */
public IDOMType createType(String sourceCode);
}