net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/jdom/IDOMFactory.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2003 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core.jdom;
  12
  13 /**
  14  * A factory used to create document fragment (DF) nodes. An
  15  * <code>IDOMCompilationUnit</code> represents the root of a complete JDOM (that
  16  * is, a ".java" file). Other node types represent fragments of a compilation
  17  * unit.
  18  * <p>
  19  * The factory can be used to create empty DFs or it can create DFs from source
  20  * strings. All DFs created empty are assigned default values as required, such
  21  * that a call to <code>IDOMNode.getContents</code> will generate a valid source
  22  * string. See individual <code>create</code> methods for details on the default
  23  * values supplied. The factory does its best to recognize Java structures in
  24  * the source provided. If the factory is completely unable to recognize source
  25  * constructs, the factory method returns <code>null</code>.
  26  * </p>
  27  * <p>
  28  * Even if a DF is created successfully from source code, it does not guarantee
  29  * that the source code will compile error free. Similarly, the contents of a DF
  30  * are not guaranteed to compile error free. However, syntactically correct
  31  * source code is guaranteed to be recognized and successfully generate a DF.
  32  * Similarly, if all of the fragments of a JDOM are syntactically correct, the
  33  * contents of the entire document will be correct too.
  34  * </p>
  35  * <p>
  36  * The factory does not perform or provide any code formatting. Document
  37  * fragments created on source strings must be pre-formatted. The JDOM attempts
  38  * to maintain the formatting of documents as best as possible. For this reason,
  39  * document fragments created for nodes that are to be strung together should
  40  * end with a new-line character. Failing to do so will result in a document
  41  * that has elements strung together on the same line. This is especially
  42  * important if a source string ends with a // comment. In this case, it would
  43  * be syntactically incorrect to omit the new line character.
  44  * </p>
  45  * <p>
  46  * This interface is not intended to be implemented by clients.
  47  * </p>
  48  *
  49  * @see IDOMNode
  50  */
  51 public interface IDOMFactory {
  52 /**
  53  * Creates and return an empty JDOM. The initial content is an empty string.
  54  *
  55  * @return the new compilation unit
  56  */
  57 public IDOMCompilationUnit createCompilationUnit();
  58 /**
  59  * Creates a JDOM on the given source code. The syntax for the given source
  60  * code corresponds to CompilationUnit (JLS2 7.3).
  61  *
  62  * @param sourceCode the source code character array, or <code>null</code>
  63  * @param name the name of the compilation unit
  64  * @return the new compilation unit, or <code>null</code> if unable to recognize
  65  *   the source code, or if the source code is <code>null</code>
  66  */
  67 public IDOMCompilationUnit createCompilationUnit(char[] sourceCode, String name);
  68 /**
  69  * Creates a JDOM on the given source code. The syntax for the given source
  70  * code corresponds to CompilationUnit (JLS2 7.3).
  71  *
  72  * @param sourceCode the source code string, or <code>null</code>
  73  * @param name the name of the compilation unit
  74  * @return the new compilation unit, or <code>null</code> if unable to recognize
  75  *   the source code, or if the source code is <code>null</code>
  76  */
  77 public IDOMCompilationUnit createCompilationUnit(String sourceCode, String name);
  78 /**
  79  * Creates a default field document fragment. Initially the field will have
  80  * default protection, type <code>"Object"</code>, name <code>"aField"</code>,
  81  * no comment, and no initializer.
  82  *
  83  * @return the new field
  84  */
  85 //public IDOMField createField();
  86 /**
  87  * Creates a field document fragment on the given source code. The given source
  88  * string corresponds to FieldDeclaration (JLS2 8.3) and ConstantDeclaration
  89  * (JLS2 9.3) restricted to a single VariableDeclarator clause.
  90  *
  91  * @param sourceCode the source code
  92  * @return the new field, or <code>null</code> if unable to recognize
  93  *   the source code, if the source code is <code>null</code>, or when the source
  94  *   contains more than one VariableDeclarator clause
  95  */
  96 //public IDOMField createField(String sourceCode);
  97 /**
  98  * Creates an empty import document fragment. Initially the import will have
  99  * name <code>"java.lang.*"</code>.
 100  *
 101  * @return the new import
 102  */
 103 //public IDOMImport createImport();
 104 /**
 105  * Creates an import document fragment on the given source code. The syntax for
 106  * the given source string corresponds to ImportDeclaration (JLS2 7.5).
 107  *
 108  * @param sourceCode the source code
 109  * @return the new import, or <code>null</code> if unable to recognize
 110  *   the source code, or if the source code is <code>null</code>
 111  */
 112 //public IDOMImport createImport(String sourceCode);
 113 /**
 114  * Creates an empty initializer document fragment. Initially the initializer
 115  * will be static and have no body or comment.
 116  *
 117  * @return the new initializer
 118  */
 119 //public IDOMInitializer createInitializer();
 120 /**
 121  * Creates an initializer document fragment from the given source code. The
 122  * syntax for the given source string corresponds to InstanceInitializer
 123  * (JLS2 8.6) and StaticDeclaration (JLS2 8.7).
 124  *
 125  * @param sourceCode the source code
 126  * @return the new initializer, or <code>null</code> if unable to recognize
 127  *   the source code, or if the source code is <code>null</code>
 128  */
 129 //public IDOMInitializer createInitializer(String sourceCode);
 130 /**
 131  * Creates a default method document fragment. Initially the method
 132  * will have public visibility, return type <code>"void"</code>, be named
 133  * <code>"newMethod"</code>, have no parameters, no comment, and an empty body.
 134  *
 135  * @return the new method
 136  */
 137 //public IDOMMethod createMethod();
 138 /**
 139  * Creates a method document fragment on the given source code. The syntax for
 140  * the given source string corresponds to MethodDeclaration (JLS2 8.4),
 141  * ConstructorDeclaration (JLS2 8.8), and AbstractMethodDeclaration (JLS2 9.4).
 142  *
 143  * @param sourceCode the source code
 144  * @return the new method, or <code>null</code> if unable to recognize
 145  *   the source code, or if the source code is <code>null</code>
 146  */
 147 //public IDOMMethod createMethod(String sourceCode);
 148 /**
 149  * Creates an empty package document fragment. Initially the package
 150  * declaration will have no name.
 151  *
 152  * @return the new package
 153  */
 154 //public IDOMPackage createPackage();
 155 /**
 156  * Creates a package document fragment on the given source code. The syntax for
 157  * the given source string corresponds to PackageDeclaration (JLS2 7.4).
 158  *
 159  * @param sourceCode the source code
 160  * @return the new package, or <code>null</code> if unable to recognize
 161  *   the source code, or if the source code is <code>null</code>
 162  */
 163 //public IDOMPackage createPackage(String sourceCode);
 164 /**
 165  * Creates a default type document fragment. Initially the type will be
 166  * a public class named <code>"AClass"</code>, with no members or comment.
 167  *
 168  * @return the new type
 169  */
 170 //public IDOMType createType();
 171 /**
 172  * Creates a default type document fragment. Initially the type will be
 173  * a public class named <code>"AClass"</code>, with no members or comment.
 174  *
 175  * @return the new class
 176  * @since 2.0
 177  */
 178 //public IDOMType createClass();
 179 /**
 180  * Creates a default type document fragment. Initially the type will be
 181  * a public interface named <code>"AnInterface"</code>, with no members or comment.
 182  *
 183  * @return the new interface
 184  * @since 2.0
 185  */
 186 //public IDOMType createInterface();
 187 /**
 188  * Creates a type document fragment on the given source code. The syntax for the
 189  * given source string corresponds to ClassDeclaration (JLS2 8.1) and
 190  * InterfaceDeclaration (JLS2 9.1).
 191  *
 192  * @param sourceCode the source code
 193  * @return the new type, or <code>null</code> if unable to recognize
 194  *   the source code, or if the source code is <code>null</code>
 195  */
 196 //public IDOMType createType(String sourceCode);
 197 }