1 /*******************************************************************************
2 * Copyright (c) 2000, 2007 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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
14 * Represents an annotation on a package declaration, a type, a method, a field
15 * or a local variable in a compilation unit or a class file.
17 * Annotations are obtained using {@link IAnnotatable#getAnnotation(String)}.
19 * Note that annotations are not children of their declaring element.
20 * To get a list of the annotations use {@link IAnnotatable#getAnnotations()}.
23 * This interface is not intended to be implemented or extended by clients.
28 public interface IAnnotation extends IJavaElement, ISourceReference {
31 * Returns the name of this annotation. If this annotation is coming from
32 * a compilation unit, this is either a simple name (e.g. for <code>@MyAnnot</code>, the name
33 * is "MyAnnot"), or a qualified name (e.g. for <code>@x. y. MyAnnot</code>, the name is
34 * "x.y.MyAnnot"). If this annotation is coming from a class file, this is always a fully
36 * <p>Note that the name has been trimmed from its whitespaces. To extract the name as it
37 * appears in the source, use {@link #getNameRange()}.
39 * This is a handle-only method. The annotation may or may not be present.
42 * @return the name of this annotation
44 String getElementName();
47 * Returns the member-value pairs of this annotation. Returns an empty
48 * array if this annotation is a marker annotation. Returns a size-1 array if this
49 * annotation is a single member annotation. In this case, the member
50 * name is always <code>"value"</code>.
52 * @return the member-value pairs of this annotation
53 * @throws JavaModelException if this element does not exist or if an
54 * exception occurs while accessing its corresponding resource
56 IMemberValuePair[] getMemberValuePairs() throws JavaModelException;
59 * Returns the source range of this annotation's name,
60 * or <code>null</code> if this annotation does not have
61 * associated source code (for example, in a binary type).
63 * @exception JavaModelException if this element does not exist or if an
64 * exception occurs while accessing its corresponding resource.
65 * @return the source range of this annotation's name,
66 * or <code>null</code> if this annotation does not have
67 * associated source code (for example, in a binary type)
69 ISourceRange getNameRange() throws JavaModelException;
72 * Returns the position relative to the order this annotation is defined in the source.
73 * Numbering starts at 1 (thus the first occurrence is occurrence 1, not occurrence 0).
75 * Two annotations ann1 and ann2 that are equal (e.g. 2 annotations with the same name on
76 * the same type) can be distinguished using their occurrence counts. If annotation
77 * ann1 appears first in the source, it will have an occurrence count of 1. If annotation
78 * ann2 appears right after annotation ann1, it will have an occurrence count of 2.
80 * This is a handle-only method. The annotation may or may not be present.
83 * @return the position relative to the order this annotation is defined in the source
85 int getOccurrenceCount();