libjava/java/lang/reflect/Constructor.java

   1 // Constructor.java - Represents a constructor for a class.
   2
   3 /* Copyright (C) 1998, 1999, 2000, 2001, 2003  Free Software Foundation
   4
   5    This file is part of libgcj.
   6
   7 This software is copyrighted work licensed under the terms of the
   8 Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
   9 details.  */
  10
  11 package java.lang.reflect;
  12
  13 /**
  14  * The Constructor class represents a constructor of a class. It also allows
  15  * dynamic creation of an object, via reflection. Invocation on Constructor
  16  * objects knows how to do widening conversions, but throws
  17  * {@link IllegalArgumentException} if a narrowing conversion would be
  18  * necessary. You can query for information on this Constructor regardless
  19  * of location, but construction access may be limited by Java language
  20  * access controls. If you can't do it in the compiler, you can't normally
  21  * do it here either.<p>
  22  *
  23  * <B>Note:</B> This class returns and accepts types as Classes, even
  24  * primitive types; there are Class types defined that represent each
  25  * different primitive type.  They are <code>java.lang.Boolean.TYPE,
  26  * java.lang.Byte.TYPE,</code>, also available as <code>boolean.class,
  27  * byte.class</code>, etc.  These are not to be confused with the
  28  * classes <code>java.lang.Boolean, java.lang.Byte</code>, etc., which are
  29  * real classes.<p>
  30  *
  31  * Also note that this is not a serializable class.  It is entirely feasible
  32  * to make it serializable using the Externalizable interface, but this is
  33  * on Sun, not me.
  34  *
  35  * @author John Keiser
  36  * @author Eric Blake <ebb9@email.byu.edu>
  37  * @author Tom Tromey <tromey@redhat.com>
  38  * @see Member
  39  * @see Class
  40  * @see java.lang.Class#getConstructor(Object[])
  41  * @see java.lang.Class#getDeclaredConstructor(Object[])
  42  * @see java.lang.Class#getConstructors()
  43  * @see java.lang.Class#getDeclaredConstructors()
  44  * @since 1.1
  45  * @status updated to 1.4
  46  */
  47 public final class Constructor extends AccessibleObject implements Member
  48 {
  49   /**
  50    * This class is uninstantiable except from native code.
  51    */
  52   private Constructor ()
  53   {
  54   }
  55
  56   /**
  57    * Gets the class that declared this constructor.
  58    * @return the class that declared this member
  59    */
  60   public Class getDeclaringClass ()
  61   {
  62     return declaringClass;
  63   }
  64
  65   /**
  66    * Gets the name of this constructor (the non-qualified name of the class
  67    * it was declared in).
  68    * @return the name of this constructor
  69    */
  70   public String getName ()
  71   {
  72     return declaringClass.getName();
  73   }
  74
  75   /**
  76    * Gets the modifiers this constructor uses.  Use the <code>Modifier</code>
  77    * class to interpret the values. A constructor can only have a subset of the
  78    * following modifiers: public, private, protected.
  79    *
  80    * @return an integer representing the modifiers to this Member
  81    * @see Modifier
  82    */
  83   public native int getModifiers ();
  84
  85   /**
  86    * Get the parameter list for this constructor, in declaration order. If the
  87    * constructor takes no parameters, returns a 0-length array (not null).
  88    *
  89    * @return a list of the types of the constructor's parameters
  90    */
  91   public Class[] getParameterTypes ()
  92   {
  93     if (parameter_types == null)
  94       getType ();
  95     return (Class[]) parameter_types.clone();
  96   }
  97
  98   /**
  99    * Get the exception types this constructor says it throws, in no particular
 100    * order. If the constructor has no throws clause, returns a 0-length array
 101    * (not null).
 102    *
 103    * @return a list of the types in the constructor's throws clause
 104    */
 105   public Class[] getExceptionTypes ()
 106   {
 107     if (exception_types == null)
 108       getType();
 109     return (Class[]) exception_types.clone();
 110   }
 111
 112   /**
 113    * Compare two objects to see if they are semantically equivalent.
 114    * Two Constructors are semantically equivalent if they have the same
 115    * declaring class and the same parameter list.
 116    *
 117    * @param o the object to compare to
 118    * @return <code>true</code> if they are equal; <code>false</code> if not.
 119    */
 120   public boolean equals (Object obj)
 121   {
 122     if (! (obj instanceof Constructor))
 123       return false;
 124     Constructor c = (Constructor) obj;
 125     return declaringClass == c.declaringClass && offset == c.offset;
 126   }
 127
 128   /**
 129    * Get the hash code for the Constructor.
 130    *
 131    * @return the hash code for the object
 132    */
 133   public int hashCode ()
 134   {
 135     // FIXME.
 136     return getName().hashCode() + declaringClass.getName().hashCode();
 137   }
 138
 139   /**
 140    * Get a String representation of the Constructor. A Constructor's String
 141    * representation is "&lt;modifier&gt; &lt;classname&gt;(&lt;paramtypes&gt;)
 142    * throws &lt;exceptions&gt;", where everything after ')' is omitted if
 143    * there are no exceptions.<br> Example:
 144    * <code>public java.io.FileInputStream(java.lang.Runnable)
 145    * throws java.io.FileNotFoundException</code>
 146    *
 147    * @return the String representation of the Constructor
 148    */
 149   public String toString ()
 150   {
 151     if (parameter_types == null)
 152       getType ();
 153     StringBuffer b = new StringBuffer ();
 154     int mods = getModifiers();
 155     if (mods != 0)
 156       {
 157         Modifier.toString(mods, b);
 158         b.append(" ");
 159       }
 160     Method.appendClassName (b, declaringClass);
 161     b.append("(");
 162     for (int i = 0; i < parameter_types.length; ++i)
 163       {
 164         Method.appendClassName (b, parameter_types[i]);
 165         if (i < parameter_types.length - 1)
 166           b.append(",");
 167       }
 168     b.append(")");
 169     return b.toString();
 170   }
 171
 172   /**
 173    * Create a new instance by invoking the constructor. Arguments are
 174    * automatically unwrapped and widened, if needed.<p>
 175    *
 176    * If this class is abstract, you will get an
 177    * <code>InstantiationException</code>. If the constructor takes 0
 178    * arguments, you may use null or a 0-length array for <code>args</code>.<p>
 179    *
 180    * If this Constructor enforces access control, your runtime context is
 181    * evaluated, and you may have an <code>IllegalAccessException</code> if
 182    * you could not create this object in similar compiled code. If the class
 183    * is uninitialized, you trigger class initialization, which may end in a
 184    * <code>ExceptionInInitializerError</code>.<p>
 185    *
 186    * Then, the constructor is invoked. If it completes normally, the return
 187    * value will be the new object. If it completes abruptly, the exception is
 188    * wrapped in an <code>InvocationTargetException</code>.
 189    *
 190    * @param args the arguments to the constructor
 191    * @return the newly created object
 192    * @throws IllegalAccessException if the constructor could not normally be
 193    *         called by the Java code (i.e. it is not public)
 194    * @throws IllegalArgumentException if the number of arguments is incorrect;
 195    *         or if the arguments types are wrong even with a widening
 196    *         conversion
 197    * @throws InstantiationException if the class is abstract
 198    * @throws InvocationTargetException if the constructor throws an exception
 199    * @throws ExceptionInInitializerError if construction triggered class
 200    *         initialization, which then failed
 201    */
 202   public native Object newInstance (Object[] args)
 203     throws InstantiationException, IllegalAccessException,
 204     IllegalArgumentException, InvocationTargetException;
 205
 206   // Update cached values from method descriptor in class.
 207   private native void getType ();
 208
 209   // Declaring class.
 210   private Class declaringClass;
 211
 212   // Exception types.
 213   private Class[] exception_types;
 214   // Parameter types.
 215   private Class[] parameter_types;
 216
 217   // Offset in bytes from the start of declaringClass's methods array.
 218   private int offset;
 219 }