1 /* 2 * Copyright (c) 2004, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.mirror.declaration; 27 28 29 import java.lang.annotation.Annotation; 30 import java.util.Collection; 31 32 import com.sun.mirror.type.*; 33 import com.sun.mirror.util.*; 34 35 36 /** 37 * Represents the declaration of a program element such as a package, 38 * class, or method. Each declaration represents a static, language-level 39 * construct (and not, for example, a runtime construct of the virtual 40 * machine), and typically corresponds one-to-one with a particular 41 * fragment of source code. 42 * 43 * <p> Declarations should be compared using the {@link #equals(Object)} 44 * method. There is no guarantee that any particular declaration will 45 * always be represented by the same object. 46 * 47 * @deprecated All components of this API have been superseded by the 48 * standardized annotation processing API. The replacement for the 49 * functionality of this interface is {@link 50 * javax.lang.model.element.Element}. 51 * 52 * @author Joseph D. Darcy 53 * @author Scott Seligman 54 * 55 * @see Declarations 56 * @see TypeMirror 57 * @since 1.5 58 */ 59 @Deprecated 60 @SuppressWarnings("deprecation") 61 public interface Declaration { 62 63 /** 64 * Tests whether an object represents the same declaration as this. 65 * 66 * @param obj the object to be compared with this declaration 67 * @return <tt>true</tt> if the specified object represents the same 68 * declaration as this 69 */ 70 boolean equals(Object obj); 71 72 /** 73 * Returns the text of the documentation ("javadoc") comment of 74 * this declaration. 75 * 76 * @return the documentation comment of this declaration, or <tt>null</tt> 77 * if there is none 78 */ 79 String getDocComment(); 80 81 /** 82 * Returns the annotations that are directly present on this declaration. 83 * 84 * @return the annotations directly present on this declaration; 85 * an empty collection if there are none 86 */ 87 Collection<AnnotationMirror> getAnnotationMirrors(); 88 89 /** 90 * Returns the annotation of this declaration having the specified 91 * type. The annotation may be either inherited or directly 92 * present on this declaration. 93 * 94 * <p> The annotation returned by this method could contain an element 95 * whose value is of type <tt>Class</tt>. 96 * This value cannot be returned directly: information necessary to 97 * locate and load a class (such as the class loader to use) is 98 * not available, and the class might not be loadable at all. 99 * Attempting to read a <tt>Class</tt> object by invoking the relevant 100 * method on the returned annotation 101 * will result in a {@link MirroredTypeException}, 102 * from which the corresponding {@link TypeMirror} may be extracted. 103 * Similarly, attempting to read a <tt>Class[]</tt>-valued element 104 * will result in a {@link MirroredTypesException}. 105 * 106 * <blockquote> 107 * <i>Note:</i> This method is unlike 108 * others in this and related interfaces. It operates on run-time 109 * reflective information -- representations of annotation types 110 * currently loaded into the VM -- rather than on the mirrored 111 * representations defined by and used throughout these 112 * interfaces. It is intended for callers that are written to 113 * operate on a known, fixed set of annotation types. 114 * </blockquote> 115 * 116 * @param <A> the annotation type 117 * @param annotationType the <tt>Class</tt> object corresponding to 118 * the annotation type 119 * @return the annotation of this declaration having the specified type 120 * 121 * @see #getAnnotationMirrors() 122 */ 123 <A extends Annotation> A getAnnotation(Class<A> annotationType); 124 125 /** 126 * Returns the modifiers of this declaration, excluding annotations. 127 * Implicit modifiers, such as the <tt>public</tt> and <tt>static</tt> 128 * modifiers of interface members, are included. 129 * 130 * @return the modifiers of this declaration in undefined order; 131 * an empty collection if there are none 132 */ 133 Collection<Modifier> getModifiers(); 134 135 /** 136 * Returns the simple (unqualified) name of this declaration. 137 * The name of a generic type does not include any reference 138 * to its formal type parameters. 139 * For example, the simple name of the interface declaration 140 * {@code java.util.Set<E>} is <tt>"Set"</tt>. 141 * If this declaration represents the empty package, an empty 142 * string is returned. 143 * If it represents a constructor, the simple name of its 144 * declaring class is returned. 145 * 146 * @return the simple name of this declaration 147 */ 148 String getSimpleName(); 149 150 /** 151 * Returns the source position of the beginning of this declaration. 152 * Returns <tt>null</tt> if the position is unknown or not applicable. 153 * 154 * <p> This source position is intended for use in providing 155 * diagnostics, and indicates only approximately where a declaration 156 * begins. 157 * 158 * @return the source position of the beginning of this declaration, 159 * or null if the position is unknown or not applicable 160 */ 161 SourcePosition getPosition(); 162 163 /** 164 * Applies a visitor to this declaration. 165 * 166 * @param v the visitor operating on this declaration 167 */ 168 void accept(DeclarationVisitor v); 169 }