Source for java.lang.reflect.Constructor

   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: }