1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/javax/lang/model/util/Elements.java Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,236 @@
1.4 +/*
1.5 + * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Sun designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Sun in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1.25 + * CA 95054 USA or visit www.sun.com if you need additional information or
1.26 + * have any questions.
1.27 + */
1.28 +
1.29 +package javax.lang.model.util;
1.30 +
1.31 +
1.32 +import java.util.List;
1.33 +import java.util.Map;
1.34 +
1.35 +import javax.lang.model.element.*;
1.36 +import javax.lang.model.type.*;
1.37 +
1.38 +
1.39 +/**
1.40 + * Utility methods for operating on program elements.
1.41 + *
1.42 + * <p><b>Compatibility Note:</b> Methods may be added to this interface
1.43 + * in future releases of the platform.
1.44 + *
1.45 + * @author Joseph D. Darcy
1.46 + * @author Scott Seligman
1.47 + * @author Peter von der Ahé
1.48 + * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils
1.49 + * @since 1.6
1.50 + */
1.51 +public interface Elements {
1.52 +
1.53 + /**
1.54 + * Returns a package given its fully qualified name.
1.55 + *
1.56 + * @param name fully qualified package name, or "" for an unnamed package
1.57 + * @return the named package, or {@code null} if it cannot be found
1.58 + */
1.59 + PackageElement getPackageElement(CharSequence name);
1.60 +
1.61 + /**
1.62 + * Returns a type element given its canonical name.
1.63 + *
1.64 + * @param name the canonical name
1.65 + * @return the named type element, or {@code null} if it cannot be found
1.66 + */
1.67 + TypeElement getTypeElement(CharSequence name);
1.68 +
1.69 + /**
1.70 + * Returns the values of an annotation's elements, including defaults.
1.71 + *
1.72 + * @see AnnotationMirror#getElementValues()
1.73 + * @param a annotation to examine
1.74 + * @return the values of the annotation's elements, including defaults
1.75 + */
1.76 + Map<? extends ExecutableElement, ? extends AnnotationValue>
1.77 + getElementValuesWithDefaults(AnnotationMirror a);
1.78 +
1.79 + /**
1.80 + * Returns the text of the documentation ("Javadoc")
1.81 + * comment of an element.
1.82 + *
1.83 + * @param e the element being examined
1.84 + * @return the documentation comment of the element, or {@code null}
1.85 + * if there is none
1.86 + */
1.87 + String getDocComment(Element e);
1.88 +
1.89 + /**
1.90 + * Returns {@code true} if the element is deprecated, {@code false} otherwise.
1.91 + *
1.92 + * @param e the element being examined
1.93 + * @return {@code true} if the element is deprecated, {@code false} otherwise
1.94 + */
1.95 + boolean isDeprecated(Element e);
1.96 +
1.97 + /**
1.98 + * Returns the <i>binary name</i> of a type element.
1.99 + *
1.100 + * @param type the type element being examined
1.101 + * @return the binary name
1.102 + *
1.103 + * @see TypeElement#getQualifiedName
1.104 + * @jls3 13.1 The Form of a Binary
1.105 + */
1.106 + Name getBinaryName(TypeElement type);
1.107 +
1.108 +
1.109 + /**
1.110 + * Returns the package of an element. The package of a package is
1.111 + * itself.
1.112 + *
1.113 + * @param type the element being examined
1.114 + * @return the package of an element
1.115 + */
1.116 + PackageElement getPackageOf(Element type);
1.117 +
1.118 + /**
1.119 + * Returns all members of a type element, whether inherited or
1.120 + * declared directly. For a class the result also includes its
1.121 + * constructors, but not local or anonymous classes.
1.122 + *
1.123 + * <p>Note that elements of certain kinds can be isolated using
1.124 + * methods in {@link ElementFilter}.
1.125 + *
1.126 + * @param type the type being examined
1.127 + * @return all members of the type
1.128 + * @see Element#getEnclosedElements
1.129 + */
1.130 + List<? extends Element> getAllMembers(TypeElement type);
1.131 +
1.132 + /**
1.133 + * Returns all annotations of an element, whether
1.134 + * inherited or directly present.
1.135 + *
1.136 + * @param e the element being examined
1.137 + * @return all annotations of the element
1.138 + * @see Element#getAnnotationMirrors
1.139 + */
1.140 + List<? extends AnnotationMirror> getAllAnnotationMirrors(Element e);
1.141 +
1.142 + /**
1.143 + * Tests whether one type, method, or field hides another.
1.144 + *
1.145 + * @param hider the first element
1.146 + * @param hidden the second element
1.147 + * @return {@code true} if and only if the first element hides
1.148 + * the second
1.149 + */
1.150 + boolean hides(Element hider, Element hidden);
1.151 +
1.152 + /**
1.153 + * Tests whether one method, as a member of a given type,
1.154 + * overrides another method.
1.155 + * When a non-abstract method overrides an abstract one, the
1.156 + * former is also said to <i>implement</i> the latter.
1.157 + *
1.158 + * <p> In the simplest and most typical usage, the value of the
1.159 + * {@code type} parameter will simply be the class or interface
1.160 + * directly enclosing {@code overrider} (the possibly-overriding
1.161 + * method). For example, suppose {@code m1} represents the method
1.162 + * {@code String.hashCode} and {@code m2} represents {@code
1.163 + * Object.hashCode}. We can then ask whether {@code m1} overrides
1.164 + * {@code m2} within the class {@code String} (it does):
1.165 + *
1.166 + * <blockquote>
1.167 + * {@code assert elements.overrides(m1, m2,
1.168 + * elements.getTypeElement("java.lang.String")); }
1.169 + * </blockquote>
1.170 + *
1.171 + * A more interesting case can be illustrated by the following example
1.172 + * in which a method in type {@code A} does not override a
1.173 + * like-named method in type {@code B}:
1.174 + *
1.175 + * <blockquote>
1.176 + * {@code class A { public void m() {} } }<br>
1.177 + * {@code interface B { void m(); } }<br>
1.178 + * ...<br>
1.179 + * {@code m1 = ...; // A.m }<br>
1.180 + * {@code m2 = ...; // B.m }<br>
1.181 + * {@code assert ! elements.overrides(m1, m2,
1.182 + * elements.getTypeElement("A")); }
1.183 + * </blockquote>
1.184 + *
1.185 + * When viewed as a member of a third type {@code C}, however,
1.186 + * the method in {@code A} does override the one in {@code B}:
1.187 + *
1.188 + * <blockquote>
1.189 + * {@code class C extends A implements B {} }<br>
1.190 + * ...<br>
1.191 + * {@code assert elements.overrides(m1, m2,
1.192 + * elements.getTypeElement("C")); }
1.193 + * </blockquote>
1.194 + *
1.195 + * @param overrider the first method, possible overrider
1.196 + * @param overridden the second method, possibly being overridden
1.197 + * @param type the type of which the first method is a member
1.198 + * @return {@code true} if and only if the first method overrides
1.199 + * the second
1.200 + * @jls3 8.4.8 Inheritance, Overriding, and Hiding
1.201 + * @jls3 9.4.1 Inheritance and Overriding
1.202 + */
1.203 + boolean overrides(ExecutableElement overrider, ExecutableElement overridden,
1.204 + TypeElement type);
1.205 +
1.206 + /**
1.207 + * Returns the text of a <i>constant expression</i> representing a
1.208 + * primitive value or a string.
1.209 + * The text returned is in a form suitable for representing the value
1.210 + * in source code.
1.211 + *
1.212 + * @param value a primitive value or string
1.213 + * @return the text of a constant expression
1.214 + * @throws IllegalArgumentException if the argument is not a primitive
1.215 + * value or string
1.216 + *
1.217 + * @see VariableElement#getConstantValue()
1.218 + */
1.219 + String getConstantExpression(Object value);
1.220 +
1.221 + /**
1.222 + * Prints a representation of the elements to the given writer in
1.223 + * the specified order. The main purpose of this method is for
1.224 + * diagnostics. The exact format of the output is <em>not</em>
1.225 + * specified and is subject to change.
1.226 + *
1.227 + * @param w the writer to print the output to
1.228 + * @param elements the elements to print
1.229 + */
1.230 + void printElements(java.io.Writer w, Element... elements);
1.231 +
1.232 + /**
1.233 + * Return a name with the same sequence of characters as the
1.234 + * argument.
1.235 + *
1.236 + * @param cs the character sequence to return as a name
1.237 + */
1.238 + Name getName(CharSequence cs);
1.239 +}
