libjava/java/lang/Class.java

   1 /* Class.java -- Representation of a Java class.
   2    Copyright (C) 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006
   3    Free Software Foundation
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20 02110-1301 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. */
  38
  39 package java.lang;
  40
  41 import java.io.InputStream;
  42 import java.io.Serializable;
  43 import java.lang.reflect.Constructor;
  44 import java.lang.reflect.Field;
  45 import java.lang.reflect.GenericDeclaration;
  46 import java.lang.reflect.Member;
  47 import java.lang.reflect.Method;
  48 import java.lang.reflect.Type;
  49 import java.lang.reflect.TypeVariable;
  50 import java.net.URL;
  51 import java.security.ProtectionDomain;
  52 import java.util.ArrayList;
  53 import java.util.Arrays;
  54 import java.util.HashSet;
  55
  56 /**
  57  * A Class represents a Java type.  There will never be multiple Class
  58  * objects with identical names and ClassLoaders. Primitive types, array
  59  * types, and void also have a Class object.
  60  *
  61  * <p>Arrays with identical type and number of dimensions share the same class.
  62  * The array class ClassLoader is the same as the ClassLoader of the element
  63  * type of the array (which can be null to indicate the bootstrap classloader).
  64  * The name of an array class is <code>[&lt;signature format&gt;;</code>.
  65  * <p> For example,
  66  * String[]'s class is <code>[Ljava.lang.String;</code>. boolean, byte,
  67  * short, char, int, long, float and double have the "type name" of
  68  * Z,B,S,C,I,J,F,D for the purposes of array classes.  If it's a
  69  * multidimensioned array, the same principle applies:
  70  * <code>int[][][]</code> == <code>[[[I</code>.
  71  *
  72  * <p>There is no public constructor - Class objects are obtained only through
  73  * the virtual machine, as defined in ClassLoaders.
  74  *
  75  * @serialData Class objects serialize specially:
  76  * <code>TC_CLASS ClassDescriptor</code>. For more serialization information,
  77  * see {@link ObjectStreamClass}.
  78  *
  79  * @author John Keiser
  80  * @author Eric Blake (ebb9@email.byu.edu)
  81  * @author Tom Tromey (tromey@cygnus.com)
  82  * @since 1.0
  83  * @see ClassLoader
  84  */
  85 public final class Class implements Type, GenericDeclaration, Serializable
  86 {
  87   /**
  88    * Class is non-instantiable from Java code; only the VM can create
  89    * instances of this class.
  90    */
  91   private Class ()
  92   {
  93   }
  94
  95   // Initialize the class.
  96   private native void initializeClass ();
  97
  98   // finalization
  99   protected native void finalize () throws Throwable;
 100
 101   /**
 102    * Use the classloader of the current class to load, link, and initialize
 103    * a class. This is equivalent to your code calling
 104    * <code>Class.forName(name, true, getClass().getClassLoader())</code>.
 105    *
 106    * @param name the name of the class to find
 107    * @return the Class object representing the class
 108    * @throws ClassNotFoundException if the class was not found by the
 109    *         classloader
 110    * @throws LinkageError if linking the class fails
 111    * @throws ExceptionInInitializerError if the class loads, but an exception
 112    *         occurs during initialization
 113    */
 114   public static native Class forName (String className)
 115     throws ClassNotFoundException;
 116
 117   // A private internal method that is called by compiler-generated code.
 118   private static Class forName (String className, Class caller)
 119     throws ClassNotFoundException
 120   {
 121     return forName(className, true, caller.getClassLoaderInternal());
 122   }
 123
 124
 125   /**
 126    * Use the specified classloader to load and link a class. If the loader
 127    * is null, this uses the bootstrap class loader (provide the security
 128    * check succeeds). Unfortunately, this method cannot be used to obtain
 129    * the Class objects for primitive types or for void, you have to use
 130    * the fields in the appropriate java.lang wrapper classes.
 131    *
 132    * <p>Calls <code>classloader.loadclass(name, initialize)</code>.
 133    *
 134    * @param name the name of the class to find
 135    * @param initialize whether or not to initialize the class at this time
 136    * @param classloader the classloader to use to find the class; null means
 137    *        to use the bootstrap class loader
 138    * @throws ClassNotFoundException if the class was not found by the
 139    *         classloader
 140    * @throws LinkageError if linking the class fails
 141    * @throws ExceptionInInitializerError if the class loads, but an exception
 142    *         occurs during initialization
 143    * @throws SecurityException if the <code>classloader</code> argument
 144    *         is <code>null</code> and the caller does not have the
 145    *         <code>RuntimePermission("getClassLoader")</code> permission
 146    * @see ClassLoader
 147    * @since 1.2
 148    */
 149   public static native Class forName (String className, boolean initialize,
 150                                       ClassLoader loader)
 151     throws ClassNotFoundException;
 152
 153   /**
 154    * Get all the public member classes and interfaces declared in this
 155    * class or inherited from superclasses. This returns an array of length
 156    * 0 if there are no member classes, including for primitive types. A
 157    * security check may be performed, with
 158    * <code>checkMemberAccess(this, Member.PUBLIC)</code> as well as
 159    * <code>checkPackageAccess</code> both having to succeed.
 160    *
 161    * @return all public member classes in this class
 162    * @throws SecurityException if the security check fails
 163    * @since 1.1
 164    */
 165   public Class[] getClasses()
 166   {
 167     memberAccessCheck(Member.PUBLIC);
 168     return internalGetClasses();
 169   }
 170
 171   /**
 172    * Like <code>getClasses()</code> but without the security checks.
 173    */
 174   private Class[] internalGetClasses()
 175   {
 176     ArrayList list = new ArrayList();
 177     list.addAll(Arrays.asList(getDeclaredClasses(true)));
 178     Class superClass = getSuperclass();
 179     if (superClass != null)
 180       list.addAll(Arrays.asList(superClass.internalGetClasses()));
 181     return (Class[])list.toArray(new Class[list.size()]);
 182   }
 183
 184   /**
 185    * Get the ClassLoader that loaded this class.  If the class was loaded
 186    * by the bootstrap classloader, this method will return null.
 187    * If there is a security manager, and the caller's class loader is not
 188    * an ancestor of the requested one, a security check of
 189    * <code>RuntimePermission("getClassLoader")</code>
 190    * must first succeed. Primitive types and void return null.
 191    *
 192    * @return the ClassLoader that loaded this class
 193    * @throws SecurityException if the security check fails
 194    * @see ClassLoader
 195    * @see RuntimePermission
 196    */
 197   public native ClassLoader getClassLoader ();
 198
 199   // A private internal method that is called by compiler-generated code.
 200   private final native ClassLoader getClassLoader (Class caller);
 201
 202   /**
 203    *  Internal method that circumvents the usual security checks when
 204    *  getting the class loader.
 205    */
 206   private native ClassLoader getClassLoaderInternal ();
 207
 208   /**
 209    * If this is an array, get the Class representing the type of array.
 210    * Examples: "[[Ljava.lang.String;" would return "[Ljava.lang.String;", and
 211    * calling getComponentType on that would give "java.lang.String".  If
 212    * this is not an array, returns null.
 213    *
 214    * @return the array type of this class, or null
 215    * @see Array
 216    * @since 1.1
 217    */
 218   public native Class getComponentType ();
 219
 220   /**
 221    * Get a public constructor declared in this class. If the constructor takes
 222    * no argument, an array of zero elements and null are equivalent for the
 223    * types argument. A security check may be performed, with
 224    * <code>checkMemberAccess(this, Member.PUBLIC)</code> as well as
 225    * <code>checkPackageAccess</code> both having to succeed.
 226    *
 227    * @param types the type of each parameter
 228    * @return the constructor
 229    * @throws NoSuchMethodException if the constructor does not exist
 230    * @throws SecurityException if the security check fails
 231    * @see #getConstructors()
 232    * @since 1.1
 233    */
 234   public native Constructor getConstructor(Class[] args)
 235     throws NoSuchMethodException;
 236
 237   /**
 238    * Get all the public constructors of this class. This returns an array of
 239    * length 0 if there are no constructors, including for primitive types,
 240    * arrays, and interfaces. It does, however, include the default
 241    * constructor if one was supplied by the compiler. A security check may
 242    * be performed, with <code>checkMemberAccess(this, Member.PUBLIC)</code>
 243    * as well as <code>checkPackageAccess</code> both having to succeed.
 244    *
 245    * @return all public constructors in this class
 246    * @throws SecurityException if the security check fails
 247    * @since 1.1
 248    */
 249   public Constructor[] getConstructors()
 250   {
 251     memberAccessCheck(Member.PUBLIC);
 252     return getDeclaredConstructors(true);
 253   }
 254
 255   /**
 256    * Get a constructor declared in this class. If the constructor takes no
 257    * argument, an array of zero elements and null are equivalent for the
 258    * types argument. A security check may be performed, with
 259    * <code>checkMemberAccess(this, Member.DECLARED)</code> as well as
 260    * <code>checkPackageAccess</code> both having to succeed.
 261    *
 262    * @param types the type of each parameter
 263    * @return the constructor
 264    * @throws NoSuchMethodException if the constructor does not exist
 265    * @throws SecurityException if the security check fails
 266    * @see #getDeclaredConstructors()
 267    * @since 1.1
 268    */
 269   public native Constructor getDeclaredConstructor(Class[] args)
 270     throws NoSuchMethodException;
 271
 272   /**
 273    * Get all the declared member classes and interfaces in this class, but
 274    * not those inherited from superclasses. This returns an array of length
 275    * 0 if there are no member classes, including for primitive types. A
 276    * security check may be performed, with
 277    * <code>checkMemberAccess(this, Member.DECLARED)</code> as well as
 278    * <code>checkPackageAccess</code> both having to succeed.
 279    *
 280    * @return all declared member classes in this class
 281    * @throws SecurityException if the security check fails
 282    * @since 1.1
 283    */
 284   public Class[] getDeclaredClasses()
 285   {
 286     memberAccessCheck(Member.DECLARED);
 287     return getDeclaredClasses(false);
 288   }
 289
 290   native Class[] getDeclaredClasses (boolean publicOnly);
 291
 292   /**
 293    * Get all the declared constructors of this class. This returns an array of
 294    * length 0 if there are no constructors, including for primitive types,
 295    * arrays, and interfaces. It does, however, include the default
 296    * constructor if one was supplied by the compiler. A security check may
 297    * be performed, with <code>checkMemberAccess(this, Member.DECLARED)</code>
 298    * as well as <code>checkPackageAccess</code> both having to succeed.
 299    *
 300    * @return all constructors in this class
 301    * @throws SecurityException if the security check fails
 302    * @since 1.1
 303    */
 304   public Constructor[] getDeclaredConstructors()
 305   {
 306     memberAccessCheck(Member.DECLARED);
 307     return getDeclaredConstructors(false);
 308   }
 309
 310   native Constructor[] getDeclaredConstructors (boolean publicOnly);
 311
 312   /**
 313    * Get a field declared in this class, where name is its simple name. The
 314    * implicit length field of arrays is not available. A security check may
 315    * be performed, with <code>checkMemberAccess(this, Member.DECLARED)</code>
 316    * as well as <code>checkPackageAccess</code> both having to succeed.
 317    *
 318    * @param name the name of the field
 319    * @return the field
 320    * @throws NoSuchFieldException if the field does not exist
 321    * @throws SecurityException if the security check fails
 322    * @see #getDeclaredFields()
 323    * @since 1.1
 324    */
 325   public native Field getDeclaredField(String fieldName)
 326     throws NoSuchFieldException;
 327
 328   /**
 329    * Get all the declared fields in this class, but not those inherited from
 330    * superclasses. This returns an array of length 0 if there are no fields,
 331    * including for primitive types. This does not return the implicit length
 332    * field of arrays. A security check may be performed, with
 333    * <code>checkMemberAccess(this, Member.DECLARED)</code> as well as
 334    * <code>checkPackageAccess</code> both having to succeed.
 335    *
 336    * @return all declared fields in this class
 337    * @throws SecurityException if the security check fails
 338    * @since 1.1
 339    */
 340   public Field[] getDeclaredFields()
 341   {
 342     memberAccessCheck(Member.DECLARED);
 343     return getDeclaredFields(false);
 344   }
 345
 346   native Field[] getDeclaredFields (boolean publicOnly);
 347
 348   private native Method _getDeclaredMethod(String methodName, Class[] args);
 349
 350   /**
 351    * Get a method declared in this class, where name is its simple name. The
 352    * implicit methods of Object are not available from arrays or interfaces.
 353    * Constructors (named "&lt;init&gt;" in the class file) and class initializers
 354    * (name "&lt;clinit&gt;") are not available.  The Virtual Machine allows
 355    * multiple methods with the same signature but differing return types; in
 356    * such a case the most specific return types are favored, then the final
 357    * choice is arbitrary. If the method takes no argument, an array of zero
 358    * elements and null are equivalent for the types argument. A security
 359    * check may be performed, with
 360    * <code>checkMemberAccess(this, Member.DECLARED)</code> as well as
 361    * <code>checkPackageAccess</code> both having to succeed.
 362    *
 363    * @param methodName the name of the method
 364    * @param types the type of each parameter
 365    * @return the method
 366    * @throws NoSuchMethodException if the method does not exist
 367    * @throws SecurityException if the security check fails
 368    * @see #getDeclaredMethods()
 369    * @since 1.1
 370    */
 371   public Method getDeclaredMethod(String methodName, Class[] args)
 372     throws NoSuchMethodException
 373   {
 374     memberAccessCheck(Member.DECLARED);
 375
 376     if ("<init>".equals(methodName) || "<clinit>".equals(methodName))
 377       throw new NoSuchMethodException(methodName);
 378
 379     Method match = _getDeclaredMethod(methodName, args);
 380     if (match == null)
 381       throw new NoSuchMethodException(methodName);
 382     return match;
 383   }
 384
 385   /**
 386    * Get all the declared methods in this class, but not those inherited from
 387    * superclasses. This returns an array of length 0 if there are no methods,
 388    * including for primitive types. This does include the implicit methods of
 389    * arrays and interfaces which mirror methods of Object, nor does it
 390    * include constructors or the class initialization methods. The Virtual
 391    * Machine allows multiple methods with the same signature but differing
 392    * return types; all such methods are in the returned array. A security
 393    * check may be performed, with
 394    * <code>checkMemberAccess(this, Member.DECLARED)</code> as well as
 395    * <code>checkPackageAccess</code> both having to succeed.
 396    *
 397    * @return all declared methods in this class
 398    * @throws SecurityException if the security check fails
 399    * @since 1.1
 400    */
 401   public native Method[] getDeclaredMethods();
 402
 403   /**
 404    * If this is a nested or inner class, return the class that declared it.
 405    * If not, return null.
 406    *
 407    * @return the declaring class of this class
 408    * @since 1.1
 409    */
 410   // This is marked as unimplemented in the JCL book.
 411   public native Class getDeclaringClass ();
 412
 413   private native Field getField (String fieldName, int hash)
 414     throws NoSuchFieldException;
 415
 416   /**
 417    * Get a public field declared or inherited in this class, where name is
 418    * its simple name. If the class contains multiple accessible fields by
 419    * that name, an arbitrary one is returned. The implicit length field of
 420    * arrays is not available. A security check may be performed, with
 421    * <code>checkMemberAccess(this, Member.PUBLIC)</code> as well as
 422    * <code>checkPackageAccess</code> both having to succeed.
 423    *
 424    * @param fieldName the name of the field
 425    * @return the field
 426    * @throws NoSuchFieldException if the field does not exist
 427    * @throws SecurityException if the security check fails
 428    * @see #getFields()
 429    * @since 1.1
 430    */
 431   public Field getField(String fieldName)
 432     throws NoSuchFieldException
 433   {
 434     memberAccessCheck(Member.PUBLIC);
 435     Field field = getField(fieldName, fieldName.hashCode());
 436     if (field == null)
 437       throw new NoSuchFieldException(fieldName);
 438     return field;
 439   }
 440
 441   /**
 442    * Get all the public fields declared in this class or inherited from
 443    * superclasses. This returns an array of length 0 if there are no fields,
 444    * including for primitive types. This does not return the implicit length
 445    * field of arrays. A security check may be performed, with
 446    * <code>checkMemberAccess(this, Member.PUBLIC)</code> as well as
 447    * <code>checkPackageAccess</code> both having to succeed.
 448    *
 449    * @return all public fields in this class
 450    * @throws SecurityException if the security check fails
 451    * @since 1.1
 452    */
 453   public Field[] getFields()
 454   {
 455     memberAccessCheck(Member.PUBLIC);
 456     return internalGetFields();
 457   }
 458
 459   /**
 460    * Like <code>getFields()</code> but without the security checks.
 461    */
 462   private Field[] internalGetFields()
 463   {
 464     HashSet set = new HashSet();
 465     set.addAll(Arrays.asList(getDeclaredFields(true)));
 466     Class[] interfaces = getInterfaces();
 467     for (int i = 0; i < interfaces.length; i++)
 468       set.addAll(Arrays.asList(interfaces[i].internalGetFields()));
 469     Class superClass = getSuperclass();
 470     if (superClass != null)
 471       set.addAll(Arrays.asList(superClass.internalGetFields()));
 472     return (Field[])set.toArray(new Field[set.size()]);
 473   }
 474
 475   /**
 476    * Returns the <code>Package</code> in which this class is defined
 477    * Returns null when this information is not available from the
 478    * classloader of this class.
 479    *
 480    * @return the package for this class, if it is available
 481    * @since 1.2
 482    */
 483   public Package getPackage()
 484   {
 485     ClassLoader cl = getClassLoaderInternal();
 486     if (cl != null)
 487       return cl.getPackage(getPackagePortion(getName()));
 488     else
 489       return VMClassLoader.getPackage(getPackagePortion(getName()));
 490   }
 491
 492   /**
 493    * Get the interfaces this class <em>directly</em> implements, in the
 494    * order that they were declared. This returns an empty array, not null,
 495    * for Object, primitives, void, and classes or interfaces with no direct
 496    * superinterface. Array types return Cloneable and Serializable.
 497    *
 498    * @return the interfaces this class directly implements
 499    */
 500   public native Class[] getInterfaces ();
 501
 502   private final native void getSignature(StringBuffer buffer);
 503   private static final native String getSignature(Class[] args,
 504                                                   boolean is_construtor);
 505
 506   public native Method _getMethod(String methodName, Class[] args);
 507
 508   /**
 509    * Get a public method declared or inherited in this class, where name is
 510    * its simple name. The implicit methods of Object are not available from
 511    * interfaces.  Constructors (named "&lt;init&gt;" in the class file) and class
 512    * initializers (name "&lt;clinit&gt;") are not available.  The Virtual
 513    * Machine allows multiple methods with the same signature but differing
 514    * return types, and the class can inherit multiple methods of the same
 515    * return type; in such a case the most specific return types are favored,
 516    * then the final choice is arbitrary. If the method takes no argument, an
 517    * array of zero elements and null are equivalent for the types argument.
 518    * A security check may be performed, with
 519    * <code>checkMemberAccess(this, Member.PUBLIC)</code> as well as
 520    * <code>checkPackageAccess</code> both having to succeed.
 521    *
 522    * @param methodName the name of the method
 523    * @param types the type of each parameter
 524    * @return the method
 525    * @throws NoSuchMethodException if the method does not exist
 526    * @throws SecurityException if the security check fails
 527    * @see #getMethods()
 528    * @since 1.1
 529    */
 530   public Method getMethod(String methodName, Class[] args)
 531     throws NoSuchMethodException
 532   {
 533     memberAccessCheck(Member.PUBLIC);
 534
 535     if ("<init>".equals(methodName) || "<clinit>".equals(methodName))
 536       throw new NoSuchMethodException(methodName);
 537
 538     Method method = _getMethod(methodName, args);
 539     if (method == null)
 540       throw new NoSuchMethodException(methodName);
 541     return method;
 542   }
 543
 544   private native int _getMethods (Method[] result, int offset);
 545
 546   /**
 547    * Get all the public methods declared in this class or inherited from
 548    * superclasses. This returns an array of length 0 if there are no methods,
 549    * including for primitive types. This does not include the implicit
 550    * methods of interfaces which mirror methods of Object, nor does it
 551    * include constructors or the class initialization methods. The Virtual
 552    * Machine allows multiple methods with the same signature but differing
 553    * return types; all such methods are in the returned array. A security
 554    * check may be performed, with
 555    * <code>checkMemberAccess(this, Member.PUBLIC)</code> as well as
 556    * <code>checkPackageAccess</code> both having to succeed.
 557    *
 558    * @return all public methods in this class
 559    * @throws SecurityException if the security check fails
 560    * @since 1.1
 561    */
 562   public native Method[] getMethods();
 563
 564   /**
 565    * Get the modifiers of this class.  These can be decoded using Modifier,
 566    * and is limited to one of public, protected, or private, and any of
 567    * final, static, abstract, or interface. An array class has the same
 568    * public, protected, or private modifier as its component type, and is
 569    * marked final but not an interface. Primitive types and void are marked
 570    * public and final, but not an interface.
 571    *
 572    * @return the modifiers of this class
 573    * @see Modifer
 574    * @since 1.1
 575    */
 576   public native int getModifiers ();
 577
 578   /**
 579    * Get the name of this class, separated by dots for package separators.
 580    * If the class represents a primitive type, or void, then the
 581    * name of the type as it appears in the Java programming language
 582    * is returned.  For instance, <code>Byte.TYPE.getName()</code>
 583    * returns "byte".
 584    *
 585    * Arrays are specially encoded as shown on this table.
 586    * <pre>
 587    * array type          [<em>element type</em>
 588    *                     (note that the element type is encoded per
 589    *                      this table)
 590    * boolean             Z
 591    * byte                B
 592    * char                C
 593    * short               S
 594    * int                 I
 595    * long                J
 596    * float               F
 597    * double              D
 598    * void                V
 599    * class or interface, alone: &lt;dotted name&gt;
 600    * class or interface, as element type: L&lt;dotted name&gt;;
 601    * </pre>
 602    *
 603    * @return the name of this class
 604    */
 605   public native String getName ();
 606
 607   /**
 608    * Get a resource URL using this class's package using the
 609    * getClassLoader().getResource() method.  If this class was loaded using
 610    * the system classloader, ClassLoader.getSystemResource() is used instead.
 611    *
 612    * <p>If the name you supply is absolute (it starts with a <code>/</code>),
 613    * then the leading <code>/</code> is removed and it is passed on to
 614    * getResource(). If it is relative, the package name is prepended, and
 615    * <code>.</code>'s are replaced with <code>/</code>.
 616    *
 617    * <p>The URL returned is system- and classloader-dependent, and could
 618    * change across implementations.
 619    *
 620    * @param resourceName the name of the resource, generally a path
 621    * @return the URL to the resource
 622    * @throws NullPointerException if name is null
 623    * @since 1.1
 624    */
 625   public URL getResource(String resourceName)
 626   {
 627     String name = resourcePath(resourceName);
 628     ClassLoader loader = getClassLoaderInternal();
 629     if (loader == null)
 630       return ClassLoader.getSystemResource(name);
 631     return loader.getResource(name);
 632   }
 633
 634   /**
 635    * Get a resource using this class's package using the
 636    * getClassLoader().getResourceAsStream() method.  If this class was loaded
 637    * using the system classloader, ClassLoader.getSystemResource() is used
 638    * instead.
 639    *
 640    * <p>If the name you supply is absolute (it starts with a <code>/</code>),
 641    * then the leading <code>/</code> is removed and it is passed on to
 642    * getResource(). If it is relative, the package name is prepended, and
 643    * <code>.</code>'s are replaced with <code>/</code>.
 644    *
 645    * <p>The URL returned is system- and classloader-dependent, and could
 646    * change across implementations.
 647    *
 648    * @param resourceName the name of the resource, generally a path
 649    * @return an InputStream with the contents of the resource in it, or null
 650    * @throws NullPointerException if name is null
 651    * @since 1.1
 652    */
 653   public InputStream getResourceAsStream(String resourceName)
 654   {
 655     String name = resourcePath(resourceName);
 656     ClassLoader loader = getClassLoaderInternal();
 657     if (loader == null)
 658       return ClassLoader.getSystemResourceAsStream(name);
 659     return loader.getResourceAsStream(name);
 660   }
 661
 662   private String resourcePath(String resourceName)
 663   {
 664     if (resourceName.length() > 0)
 665       {
 666         if (resourceName.charAt(0) != '/')
 667           {
 668             String pkg = getPackagePortion(getName());
 669             if (pkg.length() > 0)
 670               resourceName = pkg.replace('.','/') + '/' + resourceName;
 671           }
 672         else
 673           {
 674             resourceName = resourceName.substring(1);
 675           }
 676       }
 677     return resourceName;
 678   }
 679
 680   /**
 681    * Get the signers of this class. This returns null if there are no signers,
 682    * such as for primitive types or void.
 683    *
 684    * @return the signers of this class
 685    * @since 1.1
 686    */
 687   public native Object[] getSigners ();
 688
 689   /**
 690    * Set the signers of this class.
 691    *
 692    * @param signers the signers of this class
 693    */
 694   native void setSigners(Object[] signers);
 695
 696   /**
 697    * Get the direct superclass of this class.  If this is an interface,
 698    * Object, a primitive type, or void, it will return null. If this is an
 699    * array type, it will return Object.
 700    *
 701    * @return the direct superclass of this class
 702    */
 703   public native Class getSuperclass ();
 704
 705   /**
 706    * Return whether this class is an array type.
 707    *
 708    * @return whether this class is an array type
 709    * @since 1.1
 710    */
 711   public native boolean isArray ();
 712
 713   /**
 714    * Discover whether an instance of the Class parameter would be an
 715    * instance of this Class as well.  Think of doing
 716    * <code>isInstance(c.newInstance())</code> or even
 717    * <code>c.newInstance() instanceof (this class)</code>. While this
 718    * checks widening conversions for objects, it must be exact for primitive
 719    * types.
 720    *
 721    * @param c the class to check
 722    * @return whether an instance of c would be an instance of this class
 723    *         as well
 724    * @throws NullPointerException if c is null
 725    * @since 1.1
 726    */
 727   public native boolean isAssignableFrom (Class c);
 728
 729   /**
 730    * Discover whether an Object is an instance of this Class.  Think of it
 731    * as almost like <code>o instanceof (this class)</code>.
 732    *
 733    * @param o the Object to check
 734    * @return whether o is an instance of this class
 735    * @since 1.1
 736    */
 737   public native boolean isInstance (Object o);
 738
 739   /**
 740    * Check whether this class is an interface or not.  Array types are not
 741    * interfaces.
 742    *
 743    * @return whether this class is an interface or not
 744    */
 745   public native boolean isInterface ();
 746
 747   /**
 748    * Return whether this class is a primitive type.  A primitive type class
 749    * is a class representing a kind of "placeholder" for the various
 750    * primitive types, or void.  You can access the various primitive type
 751    * classes through java.lang.Boolean.TYPE, java.lang.Integer.TYPE, etc.,
 752    * or through boolean.class, int.class, etc.
 753    *
 754    * @return whether this class is a primitive type
 755    * @see Boolean#TYPE
 756    * @see Byte#TYPE
 757    * @see Character#TYPE
 758    * @see Short#TYPE
 759    * @see Integer#TYPE
 760    * @see Long#TYPE
 761    * @see Float#TYPE
 762    * @see Double#TYPE
 763    * @see Void#TYPE
 764    * @since 1.1
 765    */
 766   public native boolean isPrimitive ();
 767
 768   /**
 769    * Get a new instance of this class by calling the no-argument constructor.
 770    * The class is initialized if it has not been already. A security check
 771    * may be performed, with <code>checkMemberAccess(this, Member.PUBLIC)</code>
 772    * as well as <code>checkPackageAccess</code> both having to succeed.
 773    *
 774    * @return a new instance of this class
 775    * @throws InstantiationException if there is not a no-arg constructor
 776    *         for this class, including interfaces, abstract classes, arrays,
 777    *         primitive types, and void; or if an exception occurred during
 778    *         the constructor
 779    * @throws IllegalAccessException if you are not allowed to access the
 780    *         no-arg constructor because of scoping reasons
 781    * @throws SecurityException if the security check fails
 782    * @throws ExceptionInInitializerError if class initialization caused by
 783    *         this call fails with an exception
 784    */
 785   public native Object newInstance ()
 786     throws InstantiationException, IllegalAccessException;
 787
 788   // We need a native method to retrieve the protection domain, because we
 789   // can't add fields to java.lang.Class that are accessible from Java.
 790   private native ProtectionDomain getProtectionDomain0();
 791
 792   /**
 793    * Returns the protection domain of this class. If the classloader did not
 794    * record the protection domain when creating this class the unknown
 795    * protection domain is returned which has a <code>null</code> code source
 796    * and all permissions. A security check may be performed, with
 797    * <code>RuntimePermission("getProtectionDomain")</code>.
 798    *
 799    * @return the protection domain
 800    * @throws SecurityException if the security manager exists and the caller
 801    * does not have <code>RuntimePermission("getProtectionDomain")</code>.
 802    * @see RuntimePermission
 803    * @since 1.2
 804    */
 805   public ProtectionDomain getProtectionDomain()
 806   {
 807     SecurityManager sm = System.getSecurityManager();
 808     if (sm != null)
 809       sm.checkPermission(VMClassLoader.protectionDomainPermission);
 810
 811     ProtectionDomain protectionDomain = getProtectionDomain0();
 812
 813     if (protectionDomain == null)
 814       return VMClassLoader.unknownProtectionDomain;
 815     else
 816       return protectionDomain;
 817   }
 818
 819   /**
 820    * Return the human-readable form of this Object.  For an object, this
 821    * is either "interface " or "class " followed by <code>getName()</code>,
 822    * for primitive types and void it is just <code>getName()</code>.
 823    *
 824    * @return the human-readable form of this Object
 825    */
 826   public String toString()
 827   {
 828     if (isPrimitive())
 829       return getName();
 830     return (isInterface() ? "interface " : "class ") + getName();
 831   }
 832
 833   /**
 834    * Returns the desired assertion status of this class, if it were to be
 835    * initialized at this moment. The class assertion status, if set, is
 836    * returned; the backup is the default package status; then if there is
 837    * a class loader, that default is returned; and finally the system default
 838    * is returned. This method seldom needs calling in user code, but exists
 839    * for compilers to implement the assert statement. Note that there is no
 840    * guarantee that the result of this method matches the class's actual
 841    * assertion status.
 842    *
 843    * @return the desired assertion status
 844    * @see ClassLoader#setClassAssertionStatus(String, boolean)
 845    * @see ClassLoader#setPackageAssertionStatus(String, boolean)
 846    * @see ClassLoader#setDefaultAssertionStatus(boolean)
 847    * @since 1.4
 848    */
 849   public boolean desiredAssertionStatus()
 850   {
 851     ClassLoader c = getClassLoaderInternal();
 852     Object status;
 853     if (c == null)
 854       return VMClassLoader.defaultAssertionStatus();
 855     if (c.classAssertionStatus != null)
 856       synchronized (c)
 857         {
 858           status = c.classAssertionStatus.get(getName());
 859           if (status != null)
 860             return status.equals(Boolean.TRUE);
 861         }
 862     else
 863       {
 864         status = ClassLoader.systemClassAssertionStatus.get(getName());
 865         if (status != null)
 866           return status.equals(Boolean.TRUE);
 867       }
 868     if (c.packageAssertionStatus != null)
 869       synchronized (c)
 870         {
 871           String name = getPackagePortion(getName());
 872           if ("".equals(name))
 873             status = c.packageAssertionStatus.get(null);
 874           else
 875             do
 876               {
 877                 status = c.packageAssertionStatus.get(name);
 878                 name = getPackagePortion(name);
 879               }
 880             while (! "".equals(name) && status == null);
 881           if (status != null)
 882             return status.equals(Boolean.TRUE);
 883         }
 884     else
 885       {
 886         String name = getPackagePortion(getName());
 887         if ("".equals(name))
 888           status = ClassLoader.systemPackageAssertionStatus.get(null);
 889         else
 890           do
 891             {
 892               status = ClassLoader.systemPackageAssertionStatus.get(name);
 893               name = getPackagePortion(name);
 894             }
 895           while (! "".equals(name) && status == null);
 896         if (status != null)
 897           return status.equals(Boolean.TRUE);
 898       }
 899     return c.defaultAssertionStatus;
 900   }
 901
 902   /**
 903    * Strip the last portion of the name (after the last dot).
 904    *
 905    * @param name the name to get package of
 906    * @return the package name, or "" if no package
 907    */
 908   private static String getPackagePortion(String name)
 909   {
 910     int lastInd = name.lastIndexOf('.');
 911     if (lastInd == -1)
 912       return "";
 913     return name.substring(0, lastInd);
 914   }
 915
 916   /**
 917    * Perform security checks common to all of the methods that
 918    * get members of this Class.
 919    */
 920   private void memberAccessCheck(int which)
 921   {
 922     SecurityManager sm = System.getSecurityManager();
 923     if (sm != null)
 924       {
 925         sm.checkMemberAccess(this, which);
 926         Package pkg = getPackage();
 927         if (pkg != null)
 928           sm.checkPackageAccess(pkg.getName());
 929       }
 930   }
 931
 932   /**
 933    * Returns the simple name for this class, as used in the source
 934    * code.  For normal classes, this is the content returned by
 935    * <code>getName()</code> which follows the last ".".  Anonymous
 936    * classes have no name, and so the result of calling this method is
 937    * "".  The simple name of an array consists of the simple name of
 938    * its component type, followed by "[]".  Thus, an array with the
 939    * component type of an anonymous class has a simple name of simply
 940    * "[]".
 941    *
 942    * @return the simple name for this class.
 943    * @since 1.5
 944    */
 945   public String getSimpleName()
 946   {
 947     // FIXME write real implementation
 948     return "";
 949   }
 950
 951   /**
 952    * Returns the class which immediately encloses this class.  If this class
 953    * is a top-level class, this method returns <code>null</code>.
 954    *
 955    * @return the immediate enclosing class, or <code>null</code> if this is
 956    *         a top-level class.
 957    * @since 1.5
 958    */
 959    /* FIXME[GENERICS]: Should return Class<?> */
 960   public Class getEnclosingClass()
 961   {
 962     // FIXME write real implementation
 963     return null;
 964   }
 965
 966   /**
 967    * Returns the constructor which immediately encloses this class.  If
 968    * this class is a top-level class, or a local or anonymous class
 969    * immediately enclosed by a type definition, instance initializer
 970    * or static initializer, then <code>null</code> is returned.
 971    *
 972    * @return the immediate enclosing constructor if this class is
 973    *         declared within a constructor.  Otherwise, <code>null</code>
 974    *         is returned.
 975    * @since 1.5
 976    */
 977    /* FIXME[GENERICS]: Should return Constructor<?> */
 978   public Constructor getEnclosingConstructor()
 979   {
 980     // FIXME write real implementation
 981     return null;
 982   }
 983
 984   /**
 985    * Returns the method which immediately encloses this class.  If
 986    * this class is a top-level class, or a local or anonymous class
 987    * immediately enclosed by a type definition, instance initializer
 988    * or static initializer, then <code>null</code> is returned.
 989    *
 990    * @return the immediate enclosing method if this class is
 991    *         declared within a method.  Otherwise, <code>null</code>
 992    *         is returned.
 993    * @since 1.5
 994    */
 995   public Method getEnclosingMethod()
 996   {
 997     // FIXME write real implementation
 998     return null;
 999   }
1000
1001   /**
1002    * Returns an array of <code>TypeVariable</code> objects that represents
1003    * the type variables declared by this class, in declaration order.
1004    * An array of size zero is returned if this class has no type
1005    * variables.
1006    *
1007    * @return the type variables associated with this class.
1008    * @throws GenericSignatureFormatError if the generic signature does
1009    *         not conform to the format specified in the Virtual Machine
1010    *         specification, version 3.
1011    * @since 1.5
1012    */
1013    /* FIXME[GENERICS]: Should return TypeVariable<Class<T>> */
1014   public TypeVariable[] getTypeParameters()
1015   {
1016     // FIXME - provide real implementation.
1017     return new TypeVariable[0];
1018   }
1019
1020   /**
1021    * Returns true if this class is an <code>Enum</code>.
1022    *
1023    * @return true if this is an enumeration class.
1024    * @since 1.5
1025    */
1026   public boolean isEnum()
1027   {
1028     // FIXME - provide real implementation.
1029     return false;
1030   }
1031
1032 }