net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IAnnotation.java

   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
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 /**
  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.
  16  * <p>
  17  * Annotations are obtained using {@link IAnnotatable#getAnnotation(String)}.
  18  * </p><p>
  19  * Note that annotations are not children of their declaring element.
  20  * To get a list of the annotations use {@link IAnnotatable#getAnnotations()}.
  21  * </p>
  22  * <p>
  23  * This interface is not intended to be implemented or extended by clients.
  24  * </p>
  25  *
  26  * @since 3.4
  27  */
  28 public interface IAnnotation extends IJavaElement, ISourceReference {
  29
  30         /**
  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
  35          * qualified name.
  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()}.
  38          * </p><p>
  39          * This is a handle-only method.  The annotation may or may not be present.
  40          * </p>
  41          *
  42          * @return the name of this annotation
  43          */
  44         String getElementName();
  45
  46         /**
  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>.
  51          *
  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
  55          */
  56         IMemberValuePair[] getMemberValuePairs() throws JavaModelException;
  57
  58         /**
  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).
  62          *
  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)
  68          */
  69         ISourceRange getNameRange() throws JavaModelException;
  70
  71         /**
  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).
  74          * <p>
  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.
  79          * </p><p>
  80          * This is a handle-only method.  The annotation may or may not be present.
  81          * </p>
  82          *
  83          * @return the position relative to the order this annotation is defined in the source
  84          */
  85         int getOccurrenceCount();
  86 }