eclipse_jdt/src/org/eclipse/jdt/core/dom/BodyDeclaration.java

1	/*******************************************************************************
2	* Copyright (c) 2000, 2019 IBM Corporation and others.
3	*
4	* This program and the accompanying materials
5	* are made available under the terms of the Eclipse Public License 2.0
6	* which accompanies this distribution, and is available at
7	* https://www.eclipse.org/legal/epl-2.0/
8	*
9	* SPDX-License-Identifier: EPL-2.0
10	*
11	* Contributors:
12	* IBM Corporation - initial API and implementation
13	*******************************************************************************/
14
15	package org.eclipse.jdt.core.dom;
16
17	import java.util.Iterator;
18	import java.util.List;
19
20	/**
21	* Abstract base class of all AST nodes that represent body declarations
22	* that may appear in the body of some kind of class or interface declaration,
23	* including anonymous class declarations, enumeration declarations, and
24	* enumeration constant declarations.
25	* <pre>
26	* BodyDeclaration:
27	* {@link AbstractTypeDeclaration}
28	* {@link AnnotationTypeDeclaration}
29	* {@link EnumDeclaration}
30	* {@link TypeDeclaration} (for classes and interfaces)
31	* {@link AnnotationTypeMemberDeclaration}
32	* {@link EnumConstantDeclaration}
33	* {@link FieldDeclaration}
34	* {@link Initializer}
35	* {@link MethodDeclaration} (for methods and constructors)
36	* </pre>
37	* <p>
38	* All types of body declarations carry modifiers (and annotations), although they differ in
39	* which modifiers are allowed. Most types of body declarations can carry a
40	* doc comment; Initializer is the only ones that does not. The source range
41	* for body declarations always includes the doc comment if present.
42	* </p>
43	*
44	* @since 2.0
45	*/
46	@SuppressWarnings("rawtypes")
47	public abstract class BodyDeclaration extends ASTNode {
48
49	/**
50	* The doc comment, or <code>null</code> if none.
51	* Defaults to none.
52	*/
53	Javadoc optionalDocComment = null;
54
55	/**
56	* The modifier flags; bit-wise or of Modifier flags.
57	* Defaults to none. Not used in 3.0.
58	* @since 3.0 - field was moved up from subclasses
59	*/
60	private int modifierFlags = Modifier.NONE;
61
62	/**
63	* The extended modifiers (element type: {@link IExtendedModifier}).
64	* Null in JLS2. Added in JLS3; defaults to an empty list
65	* (see constructor).
66	*
67	* @since 3.0
68	*/
69	ASTNode.NodeList modifiers = null;
70
71	/**
72	* Returns structural property descriptor for the "modifiers" property
73	* of this node as used in JLS2 (type: {@link Integer}).
74	*
75	* @return the property descriptor
76	* @deprecated In the JLS3 API, this method is replaced by {@link #internalModifiers2Property()}.
77	*/
78	abstract SimplePropertyDescriptor internalModifiersProperty();
79
80	/**
81	* Returns structural property descriptor for the "modifiers" property
82	* of this node as used in JLS3 (element type: {@link IExtendedModifier}).
83	*
84	* @return the property descriptor
85	*/
86	abstract ChildListPropertyDescriptor internalModifiers2Property();
87
88	/**
89	* Returns structural property descriptor for the "modifiers" property
90	* of this node as used in JLS3 (element type: {@link IExtendedModifier}).
91	*
92	* @return the property descriptor
93	* @since 3.1
94	*/
95	public final ChildListPropertyDescriptor getModifiersProperty() {
96	// important: return property for AST.JLS3
97	return internalModifiers2Property();
98	}
99
100	/**
101	* Returns structural property descriptor for the "javadoc" property
102	* of this node (child type: {@link Javadoc}).
103	*
104	* @return the property descriptor
105	*/
106	abstract ChildPropertyDescriptor internalJavadocProperty();
107
108	/**
109	* Returns structural property descriptor for the "javadoc" property
110	* of this node (child type: {@link Javadoc}).
111	*
112	* @return the property descriptor
113	* @since 3.1
114	*/
115	public final ChildPropertyDescriptor getJavadocProperty() {
116	return internalJavadocProperty();
117	}
118
119	/**
120	* Creates and returns a structural property descriptor for the
121	* "javadoc" property declared on the given concrete node type (child type: {@link Javadoc}).
122	*
123	* @return the property descriptor
124	*/
125	static final ChildPropertyDescriptor internalJavadocPropertyFactory(Class nodeClass) {
126	return new ChildPropertyDescriptor(nodeClass, "javadoc", Javadoc.class, OPTIONAL, NO_CYCLE_RISK); //$NON-NLS-1$
127	}
128
129	/**
130	* Creates and returns a structural property descriptor for the
131	* "modifiers" property declared on the given concrete node type (type: {@link Integer}).
132	*
133	* @return the property descriptor
134	* @deprecated In the JLS3 API, this method is replaced by {@link #internalModifiers2PropertyFactory(Class)}.
135	*/
136	static final SimplePropertyDescriptor internalModifiersPropertyFactory(Class nodeClass) {
137	return new SimplePropertyDescriptor(nodeClass, "modifiers", int.class, MANDATORY); //$NON-NLS-1$
138	}
139
140	/**
141	* Creates and returns a structural property descriptor for the
142	* "modifiers" property declared on the given concrete node type (element type: {@link IExtendedModifier}).
143	*
144	* @return the property descriptor
145	*/
146	static final ChildListPropertyDescriptor internalModifiers2PropertyFactory(Class nodeClass) {
147	return new ChildListPropertyDescriptor(nodeClass, "modifiers", IExtendedModifier.class, CYCLE_RISK); //$NON-NLS-1$
148	}
149
150	/**
151	* Creates a new AST node for a body declaration node owned by the
152	* given AST.
153	* <p>
154	* N.B. This constructor is package-private.
155	* </p>
156	*
157	* @param ast the AST that is to own this node
158	*/
159	BodyDeclaration(AST ast) {
160	super(ast);
161	if (ast.apiLevel >= AST.JLS3_INTERNAL) {
162	this.modifiers = new ASTNode.NodeList(internalModifiers2Property());
163	}
164	}
165
166	/**
167	* Returns the doc comment node.
168	*
169	* @return the doc comment node, or <code>null</code> if none
170	*/
171	public Javadoc getJavadoc() {
172	return this.optionalDocComment;
173	}
174
175	/**
176	* Sets or clears the doc comment node.
177	*
178	* @param docComment the doc comment node, or <code>null</code> if none
179	* @exception IllegalArgumentException if the doc comment string is invalid
180	*/
181	public void setJavadoc(Javadoc docComment) {
182	ChildPropertyDescriptor p = internalJavadocProperty();
183	ASTNode oldChild = this.optionalDocComment;
184	preReplaceChild(oldChild, docComment, p);
185	this.optionalDocComment = docComment;
186	postReplaceChild(oldChild, docComment, p);
187	}
188
189	/**
190	* Returns the modifiers explicitly specified on this declaration.
191	* <p>
192	* In the JLS3 API, this method is a convenience method that
193	* computes these flags from {@link #modifiers()}.
194	* </p>
195	*
196	* @return the bit-wise "or" of <code>Modifier</code> constants
197	* @see Modifier
198	*/
199	public int getModifiers() {
200	// more efficient than checking getAST().API_LEVEL
201	if (this.modifiers == null) {
202	// JLS2 behavior - bona fide property
203	return this.modifierFlags;
204	} else {
205	// JLS3 behavior - convenience method
206	// performance could be improved by caching computed flags
207	// but this would require tracking changes to this.modifiers
208	int computedmodifierFlags = Modifier.NONE;
209	for (Iterator it = modifiers().iterator(); it.hasNext(); ) {
210	Object x = it.next();
211	if (x instanceof Modifier) {
212	computedmodifierFlags \|= ((Modifier) x).getKeyword().toFlagValue();
213	}
214	}
215	return computedmodifierFlags;
216	}
217	}
218
219	/**
220	* Sets the modifiers explicitly specified on this declaration (JLS2 API only).
221	*
222	* @param modifiers the given modifiers (bit-wise "or" of {@link Modifier} constants)
223	* @exception UnsupportedOperationException if this operation is used in
224	* an AST later than JLS2
225	* @see Modifier
226	* @deprecated In the JLS3 API, this method is replaced by
227	* {@link #modifiers()}, which contains a list of {@link Modifier} nodes.
228	*/
229	public void setModifiers(int modifiers) {
230	internalSetModifiers(modifiers);
231	}
232
233	/**
234	* Internal synonym for deprecated method. Used to avoid
235	* deprecation warnings.
236	* @since 3.1
237	*/
238	/package/ final void internalSetModifiers(int pmodifiers) {
239	// more efficient than just calling supportedOnlyIn2() to check
240	if (this.modifiers != null) {
241	supportedOnlyIn2();
242	}
243	SimplePropertyDescriptor p = internalModifiersProperty();
244	preValueChange(p);
245	this.modifierFlags = pmodifiers;
246	postValueChange(p);
247	}
248
249	/**
250	* Returns the live ordered list of modifiers and annotations
251	* of this declaration (added in JLS3 API).
252	*
253	* @return the live list of modifiers and annotations
254	* (element type: {@link IExtendedModifier})
255	* @exception UnsupportedOperationException if this operation is used in
256	* a JLS2 AST
257	* @since 3.1
258	*/
259	public List modifiers() {
260	// more efficient than just calling unsupportedIn2() to check
261	if (this.modifiers == null) {
262	unsupportedIn2();
263	}
264	return this.modifiers;
265	}
266
267	@Override
268	int memSize() {
269	return BASE_NODE_SIZE + 3 * 4;
270	}
271	}
272
273