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
  16  * (that is, a ".java" file). Other node types represent fragments of a
  17  * compilation 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
  22  * source string. See individual <code>create</code> methods for details on
  23  * the default values supplied. The factory does its best to recognize Java
  24  * structures in the source provided. If the factory is completely unable to
  25  * recognize source 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         /**
  60          * Creates a JDOM on the given source code. The syntax for the given source
  61          * code corresponds to CompilationUnit (JLS2 7.3).
  62          *
  63          * @param sourceCode
  64          *            the source code character array, or <code>null</code>
  65          * @param name
  66          *            the name of the compilation unit
  67          * @return the new compilation unit, or <code>null</code> if unable to
  68          *         recognize the source code, or if the source code is
  69          *         <code>null</code>
  70          */
  71         public IDOMCompilationUnit createCompilationUnit(char[] sourceCode,
  72                         String name);
  73
  74         /**
  75          * Creates a JDOM on the given source code. The syntax for the given source
  76          * code corresponds to CompilationUnit (JLS2 7.3).
  77          *
  78          * @param sourceCode
  79          *            the source code string, or <code>null</code>
  80          * @param name
  81          *            the name of the compilation unit
  82          * @return the new compilation unit, or <code>null</code> if unable to
  83          *         recognize the source code, or if the source code is
  84          *         <code>null</code>
  85          */
  86         public IDOMCompilationUnit createCompilationUnit(String sourceCode,
  87                         String name);
  88         /**
  89          * Creates a default field document fragment. Initially the field will have
  90          * default protection, type <code>"Object"</code>, name
  91          * <code>"aField"</code>, no comment, and no initializer.
  92          *
  93          * @return the new field
  94          */
  95         // public IDOMField createField();
  96         /**
  97          * Creates a field document fragment on the given source code. The given
  98          * source string corresponds to FieldDeclaration (JLS2 8.3) and
  99          * ConstantDeclaration (JLS2 9.3) restricted to a single VariableDeclarator
 100          * clause.
 101          *
 102          * @param sourceCode
 103          *            the source code
 104          * @return the new field, or <code>null</code> if unable to recognize the
 105          *         source code, if the source code is <code>null</code>, or when
 106          *         the source contains more than one VariableDeclarator clause
 107          */
 108         // public IDOMField createField(String sourceCode);
 109         /**
 110          * Creates an empty import document fragment. Initially the import will have
 111          * name <code>"java.lang.*"</code>.
 112          *
 113          * @return the new import
 114          */
 115         // public IDOMImport createImport();
 116         /**
 117          * Creates an import document fragment on the given source code. The syntax
 118          * for the given source string corresponds to ImportDeclaration (JLS2 7.5).
 119          *
 120          * @param sourceCode
 121          *            the source code
 122          * @return the new import, or <code>null</code> if unable to recognize the
 123          *         source code, or if the source code is <code>null</code>
 124          */
 125         // public IDOMImport createImport(String sourceCode);
 126         /**
 127          * Creates an empty initializer document fragment. Initially the initializer
 128          * will be static and have no body or comment.
 129          *
 130          * @return the new initializer
 131          */
 132         // public IDOMInitializer createInitializer();
 133         /**
 134          * Creates an initializer document fragment from the given source code. The
 135          * syntax for the given source string corresponds to InstanceInitializer
 136          * (JLS2 8.6) and StaticDeclaration (JLS2 8.7).
 137          *
 138          * @param sourceCode
 139          *            the source code
 140          * @return the new initializer, or <code>null</code> if unable to
 141          *         recognize the source code, or if the source code is
 142          *         <code>null</code>
 143          */
 144         // public IDOMInitializer createInitializer(String sourceCode);
 145         /**
 146          * Creates a default method document fragment. Initially the method will
 147          * have public visibility, return type <code>"void"</code>, be named
 148          * <code>"newMethod"</code>, have no parameters, no comment, and an empty
 149          * body.
 150          *
 151          * @return the new method
 152          */
 153         // public IDOMMethod createMethod();
 154         /**
 155          * Creates a method document fragment on the given source code. The syntax
 156          * for the given source string corresponds to MethodDeclaration (JLS2 8.4),
 157          * ConstructorDeclaration (JLS2 8.8), and AbstractMethodDeclaration (JLS2
 158          * 9.4).
 159          *
 160          * @param sourceCode
 161          *            the source code
 162          * @return the new method, or <code>null</code> if unable to recognize the
 163          *         source code, or if the source code is <code>null</code>
 164          */
 165         // public IDOMMethod createMethod(String sourceCode);
 166         /**
 167          * Creates an empty package document fragment. Initially the package
 168          * declaration will have no name.
 169          *
 170          * @return the new package
 171          */
 172         // public IDOMPackage createPackage();
 173         /**
 174          * Creates a package document fragment on the given source code. The syntax
 175          * for the given source string corresponds to PackageDeclaration (JLS2 7.4).
 176          *
 177          * @param sourceCode
 178          *            the source code
 179          * @return the new package, or <code>null</code> if unable to recognize
 180          *         the source code, or if the source code is <code>null</code>
 181          */
 182         // public IDOMPackage createPackage(String sourceCode);
 183         /**
 184          * Creates a default type document fragment. Initially the type will be a
 185          * public class named <code>"AClass"</code>, with no members or comment.
 186          *
 187          * @return the new type
 188          */
 189         // public IDOMType createType();
 190         /**
 191          * Creates a default type document fragment. Initially the type will be a
 192          * public class named <code>"AClass"</code>, with no members or comment.
 193          *
 194          * @return the new class
 195          * @since 2.0
 196          */
 197         // public IDOMType createClass();
 198         /**
 199          * Creates a default type document fragment. Initially the type will be a
 200          * public interface named <code>"AnInterface"</code>, with no members or
 201          * comment.
 202          *
 203          * @return the new interface
 204          * @since 2.0
 205          */
 206         // public IDOMType createInterface();
 207         /**
 208          * Creates a type document fragment on the given source code. The syntax for
 209          * the given source string corresponds to ClassDeclaration (JLS2 8.1) and
 210          * InterfaceDeclaration (JLS2 9.1).
 211          *
 212          * @param sourceCode
 213          *            the source code
 214          * @return the new type, or <code>null</code> if unable to recognize the
 215          *         source code, or if the source code is <code>null</code>
 216          */
 217         // public IDOMType createType(String sourceCode);
 218 }