am f76b01c6: Merge "Document that Class.getSigners() always returns null."

Merge commit 'f76b01c6377ad4653dcdc37b2ca35db785219f80' into dalvik-dev

* commit 'f76b01c6377ad4653dcdc37b2ca35db785219f80':
  Document that Class.getSigners() always returns null.

1 files changed, 6 insertions, 60 deletions

diff --git a/luni-kernel/src/main/java/java/lang/Class.java b/luni-kernel/src/main/java/java/lang/Class.java
index d057643..571f5b1 100644
--- a/luni-kernel/src/main/java/java/lang/Class.java
+++ b/luni-kernel/src/main/java/java/lang/Class.java
@@ -179,7 +179,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @throws ExceptionInInitializerError
      *             if an exception occurs during static initialization of a
      *             class.
-     * @since Android 1.0
      */
     public static Class<?> forName(String className) throws ClassNotFoundException {
         return forName(className, true, VMStack.getCallingClassLoader());
@@ -212,7 +211,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @throws ExceptionInInitializerError
      *             if an exception occurs during static initialization of a
      *             class.
-     * @since Android 1.0
      */
     public static Class<?> forName(String className, boolean initializeBoolean,
             ClassLoader classLoader) throws ClassNotFoundException {
@@ -272,7 +270,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @throws SecurityException
      *             if a security manager exists and it does not allow member
      *             access.
-     * @since Android 1.0
      */
     public Class[] getClasses() {
         // BEGIN android-note
@@ -291,7 +288,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *            the annotation type.
      * @return the annotation of the given type, or {@code null} if there is no
      *         such annotation.
-     * @since Android 1.0
      */
     @SuppressWarnings("unchecked")
     public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {
@@ -311,7 +307,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return a copy of the array containing this class' annotations.
      * @see #getDeclaredAnnotations()         
-     * @since Android 1.0
      */
     public Annotation[] getAnnotations() {
         /*
@@ -355,7 +350,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return this class' canonical name, or {@code null} if it does not have a
      *         canonical name.
-     * @since Android 1.0
      */
     public String getCanonicalName() {
         if (isLocalClass() || isAnonymousClass())
@@ -405,7 +399,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow accessing
      *             the class loader.
      * @see ClassLoader
-     * @since Android 1.0
      */
     public ClassLoader getClassLoader() {
         SecurityManager smgr = System.getSecurityManager();
@@ -461,7 +454,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * the type of the elements of the array.
      * 
      * @return the component type of this class.
-     * @since Android 1.0
      */
     public native Class<?> getComponentType();
 
@@ -479,7 +471,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getDeclaredConstructor(Class...)
-     * @since Android 1.0
      */
     @SuppressWarnings("unchecked")
     public Constructor<T> getConstructor(Class... parameterTypes) throws NoSuchMethodException,
@@ -500,7 +491,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getDeclaredConstructors()
-     * @since Android 1.0
      */
     public Constructor[] getConstructors() throws SecurityException {
         // BEGIN android-note
@@ -520,7 +510,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @return a copy of the array containing the annotations defined for the
      *         class that this {@code Class} represents.
      * @see #getAnnotations()
-     * @since Android 1.0
      */
     native public Annotation[] getDeclaredAnnotations();
 
@@ -536,7 +525,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @throws SecurityException
      *             if a security manager exists and it does not allow member
      *             access.
-     * @since Android 1.0
      */
     public Class[] getDeclaredClasses() throws SecurityException {
         // BEGIN android-note
@@ -598,7 +586,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getConstructor(Class...)
-     * @since Android 1.0
      */
     @SuppressWarnings("unchecked")
     public Constructor<T> getDeclaredConstructor(Class... parameterTypes)
@@ -620,7 +607,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getConstructors()
-     * @since Android 1.0
      */
     public Constructor[] getDeclaredConstructors() throws SecurityException {
         // BEGIN android-note
@@ -690,7 +676,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getField(String)
-     * @since Android 1.0
      */
     public Field getDeclaredField(String name)
             throws NoSuchFieldException, SecurityException {
@@ -718,7 +703,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getFields()
-     * @since Android 1.0
      */
     public Field[] getDeclaredFields() throws SecurityException {
         checkDeclaredMemberAccess();
@@ -757,7 +741,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getMethod(String, Class...)
-     * @since Android 1.0
      */
     public Method getDeclaredMethod(String name, Class... parameterTypes)
             throws NoSuchMethodException, SecurityException {
@@ -785,7 +768,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getMethods()
-     * @since Android 1.0
      */
     public Method[] getDeclaredMethods() throws SecurityException {
         checkDeclaredMemberAccess();
@@ -831,7 +813,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * {@code Class} represents an array class, a primitive type or void.
      * 
      * @return the declaring {@code Class} or {@code null}.
-     * @since Android 1.0
      */
     native public Class<?> getDeclaringClass();
 
@@ -840,7 +821,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * enclosing class the method returns {@code null}.
      * 
      * @return the enclosing {@code Class} or {@code null}.
-     * @since Android 1.0
      */
     native public Class<?> getEnclosingClass();
 
@@ -849,7 +829,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * anonymous or local/automatic class; otherwise {@code null}.
      * 
      * @return the enclosing {@code Constructor} instance or {@code null}.
-     * @since Android 1.0
      */
     native public Constructor<?> getEnclosingConstructor();
 
@@ -858,7 +837,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * anonymous or local/automatic class; otherwise {@code null}.
      * 
      * @return the enclosing {@code Method} instance or {@code null}.
-     * @since Android 1.0
      */
     native public Method getEnclosingMethod();
 
@@ -868,7 +846,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * enum} type.
      * 
      * @return an array with the {@code enum} constants or {@code null}.
-     * @since Android 1.0
      */
     @SuppressWarnings("unchecked")
     public T[] getEnumConstants() {
@@ -898,7 +875,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getDeclaredField(String)
-     * @since Android 1.0
      */
     public Field getField(String name) throws NoSuchFieldException, SecurityException {
         checkPublicMemberAccess();
@@ -929,7 +905,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getDeclaredFields()
-     * @since Android 1.0
      */
     public Field[] getFields() throws SecurityException {
         checkPublicMemberAccess();
@@ -946,7 +921,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return an array of {@link Type} instances directly implemented by the
      *         class represented by this {@code class}.
-     * @since Android 1.0
      */
     public Type[] getGenericInterfaces() {
         GenericSignatureParser parser = new GenericSignatureParser(
@@ -960,7 +934,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * class}.
      * 
      * @return an instance of {@code Type} representing the superclass.
-     * @since Android 1.0
      */
     public Type getGenericSuperclass() {
         GenericSignatureParser parser = new GenericSignatureParser(
@@ -978,7 +951,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return an array with the interfaces of the class represented by this
      *         class.
-     * @since Android 1.0
      */
     public native Class[] getInterfaces();
     // BEGIN android-note
@@ -1006,7 +978,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getDeclaredMethod(String, Class...)
-     * @since Android 1.0
      */
     public Method getMethod(String name, Class... parameterTypes) throws NoSuchMethodException, 
             SecurityException {
@@ -1038,7 +1009,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *             if a security manager exists and it does not allow member
      *             access.
      * @see #getDeclaredMethods()
-     * @since Android 1.0
      */
     public Method[] getMethods() throws SecurityException {
         checkPublicMemberAccess();
@@ -1099,7 +1069,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * defined by constants in the {@link Modifier} class.
      * 
      * @return the modifiers of the class represented by this {@code Class}.
-     * @since Android 1.0
      */
     public int getModifiers() {
         return getModifiers(this, false);
@@ -1120,7 +1089,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * {@link Class}.
      * 
      * @return the name of the class represented by this {@code Class}.
-     * @since Android 1.0
      */
     public native String getName();
 
@@ -1132,7 +1100,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * example {@code &quot;Integer[]&quot;}) is returned.
      * 
      * @return the simple name of the class represented by this {@code Class}.
-     * @since Android 1.0
      */
     public String getSimpleName() {
         if (isArray()) {
@@ -1201,7 +1168,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @return the requested resource's {@code URL} object or {@code null} if
      *         the resource can not be found.
      * @see ClassLoader
-     * @since Android 1.0
      */
     public URL getResource(String resName) {
         // Get absolute resource name, but without the leading slash
@@ -1238,7 +1204,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @return a stream for the requested resource or {@code null} if no
      *         resource with the specified name can be found.
      * @see ClassLoader
-     * @since Android 1.0
      */    
     public InputStream getResourceAsStream(String resName) {
         // Get absolute resource name, but without the leading slash
@@ -1266,15 +1231,15 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
     }
 
     /**
-     * Returns the signers for the class represented by this {@code Class} or
-     * {@code null} if either there are no signers or this {@code Class}
-     * represents a primitive type or void.
+     * Returns null. (On Android, a {@code ClassLoader} can load classes from multiple dex files.
+     * All classes from any given dex file will have the same signers, but different dex
+     * files may have different signers. This does not fit well with the original
+     * {@code ClassLoader}-based model of {@code getSigners}.)
      * 
-     * @return the signers of the class represented by this {@code Class}.
-     * @since Android 1.0
+     * @return null.
      */
     public Object[] getSigners() {
-        // TODO Delegate this to class loader somehow? What are these signers?
+        // See http://code.google.com/p/android/issues/detail?id=1766.
         return null;
     }
 
@@ -1286,7 +1251,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * class then the {@code Object} class is returned.
      * 
      * @return the superclass of the class represented by this {@code Class}.
-     * @since Android 1.0
      */
     public native Class<? super T> getSuperclass();
 
@@ -1297,7 +1261,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return an array with the type variables of the class represented by this
      *         class.
-     * @since Android 1.0
      */
     @SuppressWarnings("unchecked")
     public synchronized TypeVariable<Class<T>>[] getTypeParameters() {
@@ -1312,7 +1275,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return {@code true} if this {@code Class} represents an annotation
      *         class; {@code false} otherwise.
-     * @since Android 1.0
      */
     public boolean isAnnotation() {
         final int ACC_ANNOTATION = 0x2000;  // not public in reflect.Modifiers
@@ -1328,7 +1290,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *            the annotation to look for.
      * @return {@code true} if the class represented by this {@code Class} is
      *         annotated with {@code annotationClass}; {@code false} otherwise.
-     * @since Android 1.0
      */
     public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) {
         return getAnnotation(annotationClass) != null;
@@ -1340,7 +1301,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return {@code true} if the class represented by this {@code Class} is
      *         anonymous; {@code false} otherwise.
-     * @since Android 1.0
      */
     native public boolean isAnonymousClass();
 
@@ -1350,7 +1310,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return {@code true} if the class represented by this {@code Class} is an
      *         array class; {@code false} otherwise.
-     * @since Android 1.0
      */
     public boolean isArray() {
         return getComponentType() != null;
@@ -1369,7 +1328,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      *         represented by this {@code Class}; {@code false} otherwise.
      * @throws NullPointerException
      *             if {@code cls} is {@code null}.
-     * @since Android 1.0
      */
     public native boolean isAssignableFrom(Class<?> cls);
 
@@ -1379,7 +1337,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return {@code true} if the class represented by this {@code Class} is an
      *         {@code enum}; {@code false} otherwise.
-     * @since Android 1.0
      */
     public boolean isEnum() {
         return ((getModifiers() & 0x4000) != 0) && (getSuperclass() == Enum.class);
@@ -1395,7 +1352,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @return {@code true} if {@code object} can be cast to the type
      *         represented by this {@code Class}; {@code false} if {@code
      *         object} is {@code null} or cannot be cast.
-     * @since Android 1.0
      */
     public native boolean isInstance(Object object);
 
@@ -1404,7 +1360,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return {@code true} if this {@code Class} represents an interface;
      *         {@code false} otherwise.
-     * @since Android 1.0
      */
     public native boolean isInterface();
 
@@ -1414,7 +1369,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return {@code true} if the class represented by this {@code Class} is
      *         defined locally; {@code false} otherwise.
-     * @since Android 1.0
      */
     public boolean isLocalClass() {
         boolean enclosed = (getEnclosingMethod() != null ||
@@ -1428,7 +1382,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return {@code true} if the class represented by this {@code Class} is a
      *         member class; {@code false} otherwise.
-     * @since Android 1.0
      */
     public boolean isMemberClass() {
         return getDeclaringClass() != null;
@@ -1439,7 +1392,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return {@code true} if this {@code Class} represents a primitive type;
      *         {@code false} otherwise.
-     * @since Android 1.0
      */
     public native boolean isPrimitive();
 
@@ -1448,7 +1400,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return {@code true} if this {@code Class} represents a synthetic type;
      *         {@code false} otherwise.
-     * @since Android 1.0
      */
     public boolean isSynthetic() {
         final int ACC_SYNTHETIC = 0x1000;   // not public in reflect.Modifiers
@@ -1473,7 +1424,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @throws SecurityException
      *             if a security manager exists and it does not allow creating
      *             new instances.
-     * @since Android 1.0
      */
     public T newInstance() throws IllegalAccessException,
             InstantiationException {
@@ -1500,7 +1450,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return Package the {@code Package} of which this {@code Class} is a
      *         member or {@code null}.
-     * @since Android 1.0
      */
     public Package getPackage() {
         // TODO This might be a hack, but the VM doesn't have the necessary info.
@@ -1521,7 +1470,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * 
      * @return the assertion status for the class represented by this {@code
      *         Class}.
-     * @since Android 1.0
      */
     public native boolean desiredAssertionStatus();
 
@@ -1535,7 +1483,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @return this {@code Class} cast as a subclass of the given type.
      * @throws ClassCastException
      *             if this {@code Class} cannot be cast to the specified type.
-     * @since Android 1.0
      */
     @SuppressWarnings("unchecked")
     public <U> Class<? extends U> asSubclass(Class<U> clazz) {
@@ -1554,7 +1501,6 @@ public final class Class<T> implements Serializable, AnnotatedElement, GenericDe
      * @return the object that has been cast.
      * @throws ClassCastException
      *             if the object cannot be cast to the specified type.
-     * @since Android 1.0
      */
     @SuppressWarnings("unchecked")
     public T cast(Object obj) {