1 /*
   2  * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.management;
  27 
  28 import com.sun.jmx.mbeanserver.Introspector;
  29 import java.lang.annotation.Annotation;
  30 import java.lang.reflect.Constructor;
  31 import java.util.Arrays;
  32 import java.util.Objects;
  33 
  34 /**
  35  * Describes a constructor exposed by an MBean.  Instances of this
  36  * class are immutable.  Subclasses may be mutable but this is not
  37  * recommended.
  38  *
  39  * @since 1.5
  40  */
  41 public class MBeanConstructorInfo extends MBeanFeatureInfo implements Cloneable {
  42 
  43     /* Serial version */
  44     static final long serialVersionUID = 4433990064191844427L;
  45 
  46     static final MBeanConstructorInfo[] NO_CONSTRUCTORS =
  47         new MBeanConstructorInfo[0];
  48 
  49     /** @see MBeanInfo#arrayGettersSafe */
  50     private final transient boolean arrayGettersSafe;
  51 
  52     /**
  53      * @serial The signature of the method, that is, the class names of the arguments.
  54      */
  55     private final MBeanParameterInfo[] signature;
  56 
  57     /**
  58      * Constructs an <CODE>MBeanConstructorInfo</CODE> object.  The
  59      * {@link Descriptor} of the constructed object will include
  60      * fields contributed by any annotations on the {@code
  61      * Constructor} object that contain the {@link DescriptorKey}
  62      * meta-annotation.
  63      *
  64      * @param description A human readable description of the operation.
  65      * @param constructor The <CODE>java.lang.reflect.Constructor</CODE>
  66      * object describing the MBean constructor.
  67      */
  68     public MBeanConstructorInfo(String description, Constructor<?> constructor) {
  69         this(constructor.getName(), description,
  70              constructorSignature(constructor),
  71              Introspector.descriptorForElement(constructor));
  72     }
  73 
  74     /**
  75      * Constructs an <CODE>MBeanConstructorInfo</CODE> object.
  76      *
  77      * @param name The name of the constructor.
  78      * @param signature <CODE>MBeanParameterInfo</CODE> objects
  79      * describing the parameters(arguments) of the constructor.  This
  80      * may be null with the same effect as a zero-length array.
  81      * @param description A human readable description of the constructor.
  82      */
  83     public MBeanConstructorInfo(String name,
  84                                 String description,
  85                                 MBeanParameterInfo[] signature) {
  86         this(name, description, signature, null);
  87     }
  88 
  89     /**
  90      * Constructs an <CODE>MBeanConstructorInfo</CODE> object.
  91      *
  92      * @param name The name of the constructor.
  93      * @param signature <CODE>MBeanParameterInfo</CODE> objects
  94      * describing the parameters(arguments) of the constructor.  This
  95      * may be null with the same effect as a zero-length array.
  96      * @param description A human readable description of the constructor.
  97      * @param descriptor The descriptor for the constructor.  This may be null
  98      * which is equivalent to an empty descriptor.
  99      *
 100      * @since 1.6
 101      */
 102     public MBeanConstructorInfo(String name,
 103                                 String description,
 104                                 MBeanParameterInfo[] signature,
 105                                 Descriptor descriptor) {
 106         super(name, description, descriptor);
 107 
 108         if (signature == null || signature.length == 0)
 109             signature = MBeanParameterInfo.NO_PARAMS;
 110         else
 111             signature = signature.clone();
 112         this.signature = signature;
 113         this.arrayGettersSafe =
 114             MBeanInfo.arrayGettersSafe(this.getClass(),
 115                                        MBeanConstructorInfo.class);
 116     }
 117 
 118 
 119     /**
 120      * <p>Returns a shallow clone of this instance.  The clone is
 121      * obtained by simply calling <tt>super.clone()</tt>, thus calling
 122      * the default native shallow cloning mechanism implemented by
 123      * <tt>Object.clone()</tt>.  No deeper cloning of any internal
 124      * field is made.</p>
 125      *
 126      * <p>Since this class is immutable, cloning is chiefly of
 127      * interest to subclasses.</p>
 128      */
 129      public Object clone () {
 130          try {
 131              return super.clone() ;
 132          } catch (CloneNotSupportedException e) {
 133              // should not happen as this class is cloneable
 134              return null;
 135          }
 136      }
 137 
 138     /**
 139      * <p>Returns the list of parameters for this constructor.  Each
 140      * parameter is described by an <CODE>MBeanParameterInfo</CODE>
 141      * object.</p>
 142      *
 143      * <p>The returned array is a shallow copy of the internal array,
 144      * which means that it is a copy of the internal array of
 145      * references to the <CODE>MBeanParameterInfo</CODE> objects but
 146      * that each referenced <CODE>MBeanParameterInfo</CODE> object is
 147      * not copied.</p>
 148      *
 149      * @return  An array of <CODE>MBeanParameterInfo</CODE> objects.
 150      */
 151     public MBeanParameterInfo[] getSignature() {
 152         if (signature.length == 0)
 153             return signature;
 154         else
 155             return signature.clone();
 156     }
 157 
 158     private MBeanParameterInfo[] fastGetSignature() {
 159         if (arrayGettersSafe)
 160             return signature;
 161         else
 162             return getSignature();
 163     }
 164 
 165     public String toString() {
 166         return
 167             getClass().getName() + "[" +
 168             "description=" + getDescription() + ", " +
 169             "name=" + getName() + ", " +
 170             "signature=" + Arrays.asList(fastGetSignature()) + ", " +
 171             "descriptor=" + getDescriptor() +
 172             "]";
 173     }
 174 
 175     /**
 176      * Compare this MBeanConstructorInfo to another.
 177      *
 178      * @param o the object to compare to.
 179      *
 180      * @return true if and only if <code>o</code> is an MBeanConstructorInfo such
 181      * that its {@link #getName()}, {@link #getDescription()},
 182      * {@link #getSignature()}, and {@link #getDescriptor()}
 183      * values are equal (not necessarily
 184      * identical) to those of this MBeanConstructorInfo.  Two
 185      * signature arrays are equal if their elements are pairwise
 186      * equal.
 187      */
 188     public boolean equals(Object o) {
 189         if (o == this)
 190             return true;
 191         if (!(o instanceof MBeanConstructorInfo))
 192             return false;
 193         MBeanConstructorInfo p = (MBeanConstructorInfo) o;
 194         return (Objects.equals(p.getName(), getName()) &&
 195                 Objects.equals(p.getDescription(), getDescription()) &&
 196                 Arrays.equals(p.fastGetSignature(), fastGetSignature()) &&
 197                 Objects.equals(p.getDescriptor(), getDescriptor()));
 198     }
 199 
 200     /* Unlike attributes and operations, it's quite likely we'll have
 201        more than one constructor with the same name and even
 202        description, so we include the parameter array in the hashcode.
 203        We don't include the description, though, because it could be
 204        quite long and yet the same between constructors.  Likewise for
 205        the descriptor.  */
 206     public int hashCode() {
 207         return Objects.hash(getName()) ^ Arrays.hashCode(fastGetSignature());
 208     }
 209 
 210     private static MBeanParameterInfo[] constructorSignature(Constructor<?> cn) {
 211         final Class<?>[] classes = cn.getParameterTypes();
 212         final Annotation[][] annots = cn.getParameterAnnotations();
 213         return MBeanOperationInfo.parameters(classes, annots);
 214     }
 215 }