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
26package javax.management;
27
28import com.sun.jmx.mbeanserver.Introspector;
29import java.lang.annotation.Annotation;
30import java.lang.reflect.Constructor;
31import java.util.Arrays;
32import 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 */
41public 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} 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}
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} object.
76     *
77     * @param name The name of the constructor.
78     * @param signature {@code MBeanParameterInfo} 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} object.
91     *
92     * @param name The name of the constructor.
93     * @param signature {@code MBeanParameterInfo} 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 {@code super.clone()}, thus calling
122     * the default native shallow cloning mechanism implemented by
123     * {@code Object.clone()}.  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}
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} objects but
146     * that each referenced {@code MBeanParameterInfo} object is
147     * not copied.</p>
148     *
149     * @return  An array of {@code MBeanParameterInfo} 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} 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}
216