Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: dd4e8a4a198a19bf46be69828a41c02644d8edbf (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
/*******************************************************************************
 * Copyright (c) 2010, 2012 Oracle. 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:
 *     Oracle - initial API and implementation
 ******************************************************************************/
package org.eclipse.jpt.common.core.resource.java;

import org.eclipse.jdt.core.dom.ASTNode;
import org.eclipse.jpt.common.core.AnnotationProvider;
import org.eclipse.jpt.common.core.utility.TextRange;
import org.eclipse.jpt.common.utility.iterable.ListIterable;

/**
 * Java source code or binary annotated element.
 * <p>
 * Provisional API: This interface is part of an interim API that is still
 * under development and expected to change significantly before reaching
 * stability. It is available at this early stage to solicit feedback from
 * pioneering adopters on the understanding that any code that uses this API
 * will almost certainly be broken (repeatedly) as the API evolves.
 */
public interface JavaResourceAnnotatedElement
	extends JavaResourceNode
{
	// ********** annotations **********
	
	/**
	 * String associated with changes to the "annotations" collection
	 */
	String ANNOTATIONS_COLLECTION = "annotations"; //$NON-NLS-1$
	
	/**
	 * String associated with changes to the "nestableAnnotations" collection
	 */
	String NESTABLE_ANNOTATIONS_COLLECTION = "nestableAnnotations"; //$NON-NLS-1$
	
	/**
	 * Return the member's top-level stand-alone annotations in the order that they appear.
	 * <br>
	 * Do not return duplicate annotations as this error is handled by the Java
	 * compiler.
	 * <br>
	 * This is only used to return top-level annotations that are not container
	 * or nestable annotations.
	 * @see {@link #getContainerAnnotation(String)}
	 * @see {@link #getAnnotations(String)}
	 */
	Iterable<Annotation> getAnnotations();
	
	/**
	 * Return the number of top-level stand-alone annotations.
	 * This does not include the number of container or nestable annotations
	 * 
	 * @see #getAnnotationsSize(String)
	 */
	int getAnnotationsSize();
	
	/**
	 * Return the annotation with the specified name.
	 * Return the first if there are duplicates in the source code.
	 * <br>
	 * This is only used to return a top-level standalone annotation.
	 * It will not return container or nestable annotations
	 * 
	 * @see #getContainerAnnotation(String)
	 * @see #getAnnotation(int, String)
	 */
	Annotation getAnnotation(String annotationName);

	/**
	 * Return the "container" annotation with the specified name.
	 * Return the first if there are duplicates in the source code.
	 * <br>
	 * This is only used to return a top-level container annotations.
	 * 
	 * @see #getAnnotation(String)
	 * @see #getAnnotation(int, String)
	 */
	Annotation getContainerAnnotation(String containerAnnotationName);

	/**
	 * Return the specified top-level stand-alone annotation.
	 * Return the first if there are duplicates in the source code.
	 * Do not return null, but a Null Object instead if no annotation
	 * with the specified name exists in the source code.
	 */
	Annotation getNonNullAnnotation(String annotationName);
	
	/**
	 * Return the nestable annotations with the specified name in the order that
	 * they appear.
	 * If nestable and container annotations are both specified on the
	 * member directly, the behavior is undefined
	 * 
	 * @see #getAnnotations()
	 * @see #getContainerAnnotation(String)
	 */
	ListIterable<NestableAnnotation> getAnnotations(String nestableAnnotationName);
	
	/**
	 * Return the number of nestable annotations with the specified name.
	 * If nestable and container annotations are both specified on the
	 * member directly, the behavior is undefined
	 */
	int getAnnotationsSize(String nestableAnnotationName);
	
	/**
	 * Return the nestable annotation at the specified index with the specified name.
	 * If nestable and container annotations are both specified on the
	 * member directly, the behavior is undefined
	 */
	NestableAnnotation getAnnotation(int index, String nestableAnnotationName);
	
	/**
	 * Add a top-level stand-alone annotation with the specified name
	 * and return the newly-created annotation.
	 * <br>
	 * Do not use this to add nestable annotations or container annotations
	 * @see #addAnnotation(int, String)
	 */
	Annotation addAnnotation(String annotationName);
	
	/**
	 * Add a new nestable annotation with the specified name.
	 * Create a new container annotation if necessary and add the nestable
	 * annotation to it.
	 * If both the nestable annotation and the container annotation already
	 * exist, then add to the container annotation, leaving the existing
	 * nestable annotation alone.
	 * If only the nestable annotation exists, then create the new container
	 * annotation and move the existing nestable annotation to it along with
	 * the new one. If neither annotation exists, then create a new nestable
	 * annotation.
	 */
	NestableAnnotation addAnnotation(int index, String nestableAnnotationName);
	
	/**
	 * Move the nestable annotation at the specified source index to the specified target index.
	 */
	void moveAnnotation(int targetIndex, int sourceIndex, String nestableAnnotationName);
	
	/**
	 * Remove the specified top-level standalone annotation.
	 * <br>
	 * Do not use this to remove container or nestable annotations
	 *
	 * @see #removeAnnotation(int, String)
	 */
	void removeAnnotation(String annotationName);
	
	/**
	 * Remove the specified nestable annotation from the container annotation at the specified
	 * index.
	 * If there is no container, assume the index is zero and just remove the nestable annotation
	 */
	void removeAnnotation(int index, String nestableAnnotationName);
	
	
	// ********** queries **********
		
	/**
	 * Return the element's "top level" annotations.
	 * For "combination" annotations (i.e. a virtual array of annotations that
	 * can be either a single <em>standalone</em> annotation [representing an
	 * array of length one] or an array of annotations witin a
	 * <em>container</em> annotation), only the <em>container</em> annotation is
	 * included (if it is present) or the single <em>standalone</em> annotation.
	 */
	Iterable<Annotation> getTopLevelAnnotations();
	
	/**
	 * Return whether the underlying JDT member is currently annotated with any recognized
	 * annotations.
	 */
	boolean isAnnotated();

	/**
	 * Return whether the underlying JDT member is annotated with any of the given annotations.
	 */
	boolean isAnnotatedWithAnyOf(Iterable<String> annotationNames);

	/**
	 * Return the element's ASTNode type
	 */
	AstNodeType getAstNodeType();
	
	/**
	 * Return the text range for the member's name.
	 */
	TextRange getNameTextRange();
	
	/**
	 * Return the text range for the nestable annotation if it is currently
	 * unnested. If it is nested, return the text range for the corresponding
	 * container annotation.
	 * This is not used for stand-alone annotations
	 * 
	 * @see Annotation#getTextRange()
	 * @see AnnotationProvider#getContainerAnnotationName(String)
	 */
	TextRange getTextRange(String nestableAnnotationName);
	
	/**
	 * The java element's ASTNode type. These are the only ASTNode types that
	 * our resource model supports
	 */
	public enum AstNodeType {
		
		/**
		 * Represents an annotatable package.
		 * An {@link JavaResourceAnnotatedElement} of {@link AstNodeType} PACKAGE may safely be cast as a 
		 * {@link JavaResourcePackage}
		 */
		PACKAGE(ASTNode.PACKAGE_DECLARATION),
		
		/**
		 * Represents a class or interface.
		 * An {@link JavaResourceAnnotatedElement} of {@link AstNodeType} TYPE may safely be cast as a 
		 * {@link JavaResourceType}
		 */
		TYPE(ASTNode.TYPE_DECLARATION),
		
		/**
		 * Represents an enum.
		 * An {@link JavaResourceAnnotatedElement} of {@link AstNodeType} ENUM may safely be cast as a 
		 * {@link JavaResourceEnum}
		 */
		ENUM(ASTNode.ENUM_DECLARATION),
		
		/**
		 * Represents a method.
		 * An {@link JavaResourceAnnotatedElement} of {@link AstNodeType} METHOD may safely be cast as a 
		 * {@link JavaResourceMethod}
		 */
		METHOD(ASTNode.METHOD_DECLARATION),
		
		/**
		 * Represents a type field.
		 * An {@link JavaResourceAnnotatedElement} of {@link AstNodeType} FIELD may safely be cast as a 
		 * {@link JavaResourceField}
		 */
		FIELD(ASTNode.FIELD_DECLARATION),
		
		/**
		 * Represents an enum constant.
		 * An {@link JavaResourceAnnotatedElement} of {@link AstNodeType} ENUM_CONSTANT may safely be cast as a 
		 * {@link JavaResourceEnumConstant}
		 */
		ENUM_CONSTANT(ASTNode.ENUM_CONSTANT_DECLARATION);


		private int astNodeType;

		AstNodeType(int astNodeType) {
			this.astNodeType = astNodeType;
		}

		/**
		 * Return whether the given astNodeType matches this type
		 */
		public boolean matches(int astNodeType) {
			return this.astNodeType == astNodeType;
		}
	}
}

Back to the top