PackageDeclaration


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.jdt.core.dom;
13  
14  import java.util.ArrayList  ;
15  import java.util.List  ;
16  
17  /**
18   * Package declaration AST node type.
19   * For JLS2:
20   * <pre>
21   * PackageDeclaration:
22   *    <b>package</b> Name <b>;</b>
23   * </pre>
24   * For JLS3, annotations and doc comment
25   * were added:
26   * <pre>
27   * PackageDeclaration:
28   *    [ Javadoc ] { Annotation } <b>package</b> Name <b>;</b>
29   * </pre>
30   * 
31   * @since 2.0
32   */
33  public class PackageDeclaration extends ASTNode {
34      
35      /**
36       * The "javadoc" structural property of this node type.
37       * @since 3.0
38       */
39      public static final ChildPropertyDescriptor JAVADOC_PROPERTY = 
40          new ChildPropertyDescriptor(PackageDeclaration.class, "javadoc", Javadoc.class, OPTIONAL, NO_CYCLE_RISK); //$NON-NLS-1$
41  
42      /**
43       * The "annotations" structural property of this node type (added in JLS3 API).
44       * @since 3.1
45       */
46      public static final ChildListPropertyDescriptor ANNOTATIONS_PROPERTY = 
47          new ChildListPropertyDescriptor(PackageDeclaration.class, "annotations", Annotation.class, CYCLE_RISK); //$NON-NLS-1$
48      
49      /**
50       * The "name" structural property of this node type.
51       * @since 3.0
52       */
53      public static final ChildPropertyDescriptor NAME_PROPERTY = 
54          new ChildPropertyDescriptor(PackageDeclaration.class, "name", Name.class, MANDATORY, NO_CYCLE_RISK); //$NON-NLS-1$
55  
56      /**
57       * A list of property descriptors (element type: 
58       * {@link StructuralPropertyDescriptor}),
59       * or null if uninitialized.
60       * @since 3.0
61       */
62      private static final List   PROPERTY_DESCRIPTORS_2_0;
63      
64      /**
65       * A list of property descriptors (element type: 
66       * {@link StructuralPropertyDescriptor}),
67       * or null if uninitialized.
68       * @since 3.1
69       */
70      private static final List   PROPERTY_DESCRIPTORS_3_0;
71      
72      static {
73          List   propertyList = new ArrayList  (2);
74          createPropertyList(PackageDeclaration.class, propertyList);
75          addProperty(NAME_PROPERTY, propertyList);
76          PROPERTY_DESCRIPTORS_2_0 = reapPropertyList(propertyList);
77          
78          propertyList = new ArrayList  (4);
79          createPropertyList(PackageDeclaration.class, propertyList);
80          addProperty(JAVADOC_PROPERTY, propertyList);
81          addProperty(ANNOTATIONS_PROPERTY, propertyList);
82          addProperty(NAME_PROPERTY, propertyList);
83          PROPERTY_DESCRIPTORS_3_0 = reapPropertyList(propertyList);
84      }
85  
86      /**
87       * Returns a list of structural property descriptors for this node type.
88       * Clients must not modify the result.
89       * 
90       * @param apiLevel the API level; one of the
91       * <code>AST.JLS&ast;</code> constants
92  
93       * @return a list of property descriptors (element type: 
94       * {@link StructuralPropertyDescriptor})
95       * @since 3.0
96       */
97      public static List   propertyDescriptors(int apiLevel) {
98          if (apiLevel == AST.JLS2_INTERNAL) {
99              return PROPERTY_DESCRIPTORS_2_0;
100         } else {
101             return PROPERTY_DESCRIPTORS_3_0;
102         }
103     }
104             
105     /**
106      * The doc comment, or <code>null</code> if none.
107      * Defaults to none.
108      * @since 3.0
109      */
110     Javadoc optionalDocComment = null;
111 
112     /**
113      * The annotations (element type: <code>Annotation</code>). 
114      * Null in JLS2. Added in JLS3; defaults to an empty list
115      * (see constructor).
116      * @since 3.1
117      */
118     private ASTNode.NodeList annotations = null;
119     
120     /**
121      * The package name; lazily initialized; defaults to a unspecified,
122      * legal Java package identifier.
123      */
124     private Name packageName = null;
125 
126     /**
127      * Creates a new AST node for a package declaration owned by the
128      * given AST. The package declaration initially has an unspecified,
129      * but legal, Java identifier; and an empty list of annotations.
130      * <p>
131      * N.B. This constructor is package-private; all subclasses must be 
132      * declared in the same package; clients are unable to declare 
133      * additional subclasses.
134      * </p>
135      * 
136      * @param ast the AST that is to own this node
137      */
138     PackageDeclaration(AST ast) {
139         super(ast);
140         if (ast.apiLevel >= AST.JLS3) {
141             this.annotations = new ASTNode.NodeList(ANNOTATIONS_PROPERTY);
142         }
143     }
144 
145     /* (omit javadoc for this method)
146      * Method declared on ASTNode.
147      */
148     final List   internalStructuralPropertiesForType(int apiLevel) {
149         return propertyDescriptors(apiLevel);
150     }
151     
152     /* (omit javadoc for this method)
153      * Method declared on ASTNode.
154      */
155     final ASTNode internalGetSetChildProperty(ChildPropertyDescriptor property, boolean get, ASTNode child) {
156         if (property == JAVADOC_PROPERTY) {
157             if (get) {
158                 return getJavadoc();
159             } else {
160                 setJavadoc((Javadoc) child);
161                 return null;
162             }
163         }
164         if (property == NAME_PROPERTY) {
165             if (get) {
166                 return getName();
167             } else {
168                 setName((Name) child);
169                 return null;
170             }
171         }
172         // allow default implementation to flag the error
173         return super.internalGetSetChildProperty(property, get, child);
174     }
175     
176     /* (omit javadoc for this method)
177      * Method declared on ASTNode.
178      */
179     final List   internalGetChildListProperty(ChildListPropertyDescriptor property) {
180         if (property == ANNOTATIONS_PROPERTY) {
181             return annotations();
182         }
183         // allow default implementation to flag the error
184         return super.internalGetChildListProperty(property);
185     }
186 
187     /* (omit javadoc for this method)
188      * Method declared on ASTNode.
189      */
190     final int getNodeType0() {
191         return PACKAGE_DECLARATION;
192     }
193 
194     /* (omit javadoc for this method)
195      * Method declared on ASTNode.
196      */
197     ASTNode clone0(AST target) {
198         PackageDeclaration result = new PackageDeclaration(target);
199         result.setSourceRange(this.getStartPosition(), this.getLength());
200         if (this.ast.apiLevel >= AST.JLS3) {
201             result.setJavadoc((Javadoc) ASTNode.copySubtree(target, getJavadoc()));
202             result.annotations().addAll(ASTNode.copySubtrees(target, annotations()));
203         }
204         result.setName((Name) getName().clone(target));
205         return result;
206     }
207 
208     /* (omit javadoc for this method)
209      * Method declared on ASTNode.
210      */
211     final boolean subtreeMatch0(ASTMatcher matcher, Object   other) {
212         // dispatch to correct overloaded match method
213         return matcher.match(this, other);
214     }
215 
216     /* (omit javadoc for this method)
217      * Method declared on ASTNode.
218      */
219     void accept0(ASTVisitor visitor) {
220         boolean visitChildren = visitor.visit(this);
221         if (visitChildren) {
222             if (this.ast.apiLevel >= AST.JLS3) {
223                 acceptChild(visitor, getJavadoc());
224                 acceptChildren(visitor, this.annotations);
225             }
226             acceptChild(visitor, getName());
227         }
228         visitor.endVisit(this);
229     }
230     
231     /**
232      * Returns the live ordered list of annotations of this 
233      * package declaration (added in JLS3 API).
234      * 
235      * @return the live list of annotations
236      *    (element type: <code>Annotation</code>)
237      * @exception UnsupportedOperationException if this operation is used in
238      * a JLS2 AST
239      * @since 3.1
240      */ 
241     public List   annotations() {
242         // more efficient than just calling unsupportedIn2() to check
243         if (this.annotations == null) {
244             unsupportedIn2();
245         }
246         return this.annotations;
247     }
248     
249     /**
250      * Returns the doc comment node.
251      * 
252      * @return the doc comment node, or <code>null</code> if none
253      * @exception UnsupportedOperationException if this operation is used in
254      * a JLS2 AST
255      * @since 3.0
256      */
257     public Javadoc getJavadoc() {
258         // more efficient than just calling unsupportedIn2() to check
259         if (this.annotations == null) {
260             unsupportedIn2();
261         }
262         return this.optionalDocComment;
263     }
264 
265     /**
266      * Sets or clears the doc comment node.
267      * 
268      * @param docComment the doc comment node, or <code>null</code> if none
269      * @exception IllegalArgumentException if the doc comment string is invalid
270      * @exception UnsupportedOperationException if this operation is used in
271      * a JLS2 AST
272      * @since 3.0
273      */
274     public void setJavadoc(Javadoc docComment) {
275         // more efficient than just calling unsupportedIn2() to check
276         if (this.annotations == null) {
277             unsupportedIn2();
278         }
279         ASTNode oldChild = this.optionalDocComment;
280         preReplaceChild(oldChild, docComment, JAVADOC_PROPERTY);
281         this.optionalDocComment = docComment;
282         postReplaceChild(oldChild, docComment, JAVADOC_PROPERTY);
283     }
284 
285     /**
286      * Returns the package name of this package declaration.
287      * 
288      * @return the package name node
289      */ 
290     public Name getName() {
291         if (this.packageName == null) {
292             // lazy init must be thread-safe for readers
293             synchronized (this) {
294                 if (this.packageName == null) {
295                     preLazyInit();
296                     this.packageName = new SimpleName(this.ast);
297                     postLazyInit(this.packageName, NAME_PROPERTY);
298                 }
299             }
300         }
301         return this.packageName;
302     }
303     
304     /**
305      * Sets the package name of this package declaration to the given name.
306      * 
307      * @param name the new package name
308      * @exception IllegalArgumentException if`:
309      * <ul>
310      * <li>the node belongs to a different AST</li>
311      * <li>the node already has a parent</li>
312      * </ul>
313      */ 
314     public void setName(Name name) {
315         if (name == null) {
316             throw new IllegalArgumentException  ();
317         }
318         ASTNode oldChild = this.packageName;
319         preReplaceChild(oldChild, name, NAME_PROPERTY);
320         this.packageName = name;
321         postReplaceChild(oldChild, name, NAME_PROPERTY);
322     }
323     
324     /**
325      * Resolves and returns the binding for the package declared in this package
326      * declaration.
327      * <p>
328      * Note that bindings are generally unavailable unless requested when the
329      * AST is being built.
330      * </p>
331      * 
332      * @return the binding, or <code>null</code> if the binding cannot be 
333      *    resolved
334      */ 
335     public IPackageBinding resolveBinding() {
336         return this.ast.getBindingResolver().resolvePackage(this);
337     }
338     
339     /* (omit javadoc for this method)
340      * Method declared on ASTNode.
341      */
342     int memSize() {
343         return BASE_NODE_SIZE + 3 * 4;
344     }
345     
346     /* (omit javadoc for this method)
347      * Method declared on ASTNode.
348      */
349     int treeSize() {
350         return
351             memSize()
352             + (this.optionalDocComment == null ? 0 : getJavadoc().treeSize())
353             + (this.annotations == null ? 0 : this.annotations.listSize())
354             + (this.packageName == null ? 0 : getName().treeSize());
355     }
356 }
357 
358
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags