/*******************************************************************************
 * Copyright (c) 2000, 2004 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 ".java" file). 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>
 * <p>
 * This interface is not intended to be implemented by clients.
 * </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.
 */
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);
}