/*******************************************************************************
* Copyright (c) 2000, 2003 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/cpl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package net.sourceforge.phpdt.core.jdom;
/**
* A factory used to create document fragment (DF) nodes. An
* IDOMCompilationUnit
represents the root of a complete JDOM (that
* is, a ".java" file). 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. *
** This interface is not intended to be implemented by clients. *
* * @see IDOMNode */ 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, ornull
* @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.*"
.
*
* @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);
}