/*

 * Copyright 1999-2006 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.management;

import java.io.IOException;

import java.io.StreamCorruptedException;

import java.io.Serializable;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.lang.reflect.Method;

import java.util.Arrays;

import java.util.Map;

import java.util.WeakHashMap;

import java.security.AccessController;

import java.security.PrivilegedAction;

import static javax.management.ImmutableDescriptor.nonNullDescriptor;

/**

 * <p>Describes the management interface exposed by an MBean; that is,

 * the set of attributes and operations which are available for

 * management operations.  Instances of this class are immutable.

 * Subclasses may be mutable but this is not recommended.</p>

 *

 * <p>The contents of the <code>MBeanInfo</code> for a Dynamic MBean

 * are determined by its {@link DynamicMBean#getMBeanInfo

 * getMBeanInfo()} method.  This includes Open MBeans and Model

 * MBeans, which are kinds of Dynamic MBeans.</p>

 *

 * <p>The contents of the <code>MBeanInfo</code> for a Standard MBean

 * are determined by the MBean server as follows:</p>

 *

 * <ul>

 *

 * <li>{@link #getClassName()} returns the Java class name of the MBean

 * object;

 *

 * <li>{@link #getConstructors()} returns the list of all public

 * constructors in that object;

 *

 * <li>{@link #getAttributes()} returns the list of all attributes

 * for Standard MBeans;

 *

 * the MBean interface that do not represent attributes;

 *

 * NotificationBroadcaster#getNotificationInfo()} on it;

 *

 * <li>{@link #getDescriptor()} returns a descriptor containing the contents

 *

 * </ul>

 *

 * <p>The description returned by {@link #getDescription()} and the

 * descriptions of the contained attributes and operations are determined

 * otherwise their contents are not specified.</p>

 *

 * <p>The remaining details of the <code>MBeanInfo</code> for a

 * Standard MBean are not specified.  This includes the description of

 * any contained constructors, and notifications; the names

 * of parameters to constructors and operations; and the descriptions of

 * constructor parameters.</p>

 *

 * @since 1.5

 */

public class MBeanInfo implements Cloneable, Serializable, DescriptorRead {

    /* Serial version */

    static final long serialVersionUID = -6451021435135161911L;

    /**

     * @serial The Descriptor for the MBean.  This field

     * can be null, which is equivalent to an empty Descriptor.

     */

    private transient Descriptor descriptor;

    /**

     * @serial The human readable description of the class.

     */

    private final String description;

    /**

     * @serial The MBean qualified name.

     */

    private final String className;

    /**

     * @serial The MBean attribute descriptors.

     */

    private final MBeanAttributeInfo[] attributes;

    /**

     * @serial The MBean operation descriptors.

     */

    private final MBeanOperationInfo[] operations;

     /**

     * @serial The MBean constructor descriptors.

     */

    private final MBeanConstructorInfo[] constructors;

    /**

     * @serial The MBean notification descriptors.

     */

    private final MBeanNotificationInfo[] notifications;

    private transient int hashCode;

    /**

     * <p>True if this class is known not to override the array-valued

     * getters of MBeanInfo.  Obviously true for MBeanInfo itself, and true

     * for a subclass where we succeed in reflecting on the methods

     * and discover they are not overridden.</p>

     *

     * <p>The purpose of this variable is to avoid cloning the arrays

     * when doing operations like {@link #equals} where we know they

     * will not be changed.  If a subclass overrides a getter, we

     * cannot access the corresponding array directly.</p>

     */

    private final transient boolean arrayGettersSafe;

    /**

     * Constructs an <CODE>MBeanInfo</CODE>.

     *

     * @param className The name of the Java class of the MBean described

     * by this <CODE>MBeanInfo</CODE>.  This value may be any

     * syntactically legal Java class name.  It does not have to be a

     * Java class known to the MBean server or to the MBean's

     * ClassLoader.  If it is a Java class known to the MBean's

     * ClassLoader, it is recommended but not required that the

     * class's public methods include those that would appear in a

     * Standard MBean implementing the attributes and operations in

     * this MBeanInfo.

     * @param description A human readable description of the MBean (optional).

     * @param attributes The list of exposed attributes of the MBean.

     * This may be null with the same effect as a zero-length array.

     * @param constructors The list of public constructors of the

     * MBean.  This may be null with the same effect as a zero-length

     * array.

     * @param operations The list of operations of the MBean.  This

     * may be null with the same effect as a zero-length array.

     * @param notifications The list of notifications emitted.  This

     * may be null with the same effect as a zero-length array.

     */

    public MBeanInfo(String className,

                     String description,

                     MBeanAttributeInfo[] attributes,

                     MBeanConstructorInfo[] constructors,

                     MBeanOperationInfo[] operations,

                     MBeanNotificationInfo[] notifications)

            throws IllegalArgumentException {

        this(className, description, attributes, constructors, operations,

             notifications, null);

    }

    /**

     * Constructs an <CODE>MBeanInfo</CODE>.

     *

     * @param className The name of the Java class of the MBean described

     * by this <CODE>MBeanInfo</CODE>.  This value may be any

     * syntactically legal Java class name.  It does not have to be a

     * Java class known to the MBean server or to the MBean's

     * ClassLoader.  If it is a Java class known to the MBean's

     * ClassLoader, it is recommended but not required that the

     * class's public methods include those that would appear in a

     * Standard MBean implementing the attributes and operations in

     * this MBeanInfo.

     * @param description A human readable description of the MBean (optional).

     * @param attributes The list of exposed attributes of the MBean.

     * This may be null with the same effect as a zero-length array.

     * @param constructors The list of public constructors of the

     * MBean.  This may be null with the same effect as a zero-length

     * array.

     * @param operations The list of operations of the MBean.  This

     * may be null with the same effect as a zero-length array.

     * @param notifications The list of notifications emitted.  This

     * may be null with the same effect as a zero-length array.

     * @param descriptor The descriptor for the MBean.  This may be null

     * which is equivalent to an empty descriptor.

     *

     * @since 1.6

     */

    public MBeanInfo(String className,

                     String description,

                     MBeanAttributeInfo[] attributes,

                     MBeanConstructorInfo[] constructors,

                     MBeanOperationInfo[] operations,

                     MBeanNotificationInfo[] notifications,

                     Descriptor descriptor)

            throws IllegalArgumentException {

        this.className = className;

        this.description = description;

        if (attributes == null)

            attributes = MBeanAttributeInfo.NO_ATTRIBUTES;

        this.attributes = attributes;

        if (operations == null)

            operations = MBeanOperationInfo.NO_OPERATIONS;

        this.operations = operations;

        if (constructors == null)

            constructors = MBeanConstructorInfo.NO_CONSTRUCTORS;

        this.constructors = constructors;

        if (notifications == null)

            notifications = MBeanNotificationInfo.NO_NOTIFICATIONS;

        this.notifications = notifications;

        if (descriptor == null)

            descriptor = ImmutableDescriptor.EMPTY_DESCRIPTOR;

        this.descriptor = descriptor;

        this.arrayGettersSafe =

                arrayGettersSafe(this.getClass(), MBeanInfo.class);

    }

    /**

     * <p>Returns a shallow clone of this instance.

     * The clone is obtained by simply calling <tt>super.clone()</tt>,

     * thus calling the default native shallow cloning mechanism

     * implemented by <tt>Object.clone()</tt>.

     * No deeper cloning of any internal field is made.</p>

     *

     * <p>Since this class is immutable, the clone method is chiefly of

     * interest to subclasses.</p>

     */

     public Object clone () {

         try {

             return super.clone() ;

         } catch (CloneNotSupportedException e) {

             // should not happen as this class is cloneable

             return null;

         }

     }

    /**

     * Returns the name of the Java class of the MBean described by

     * this <CODE>MBeanInfo</CODE>.

     *

     * @return the class name.

     */

    public String getClassName()  {

        return className;

    }

    /**

     * Returns a human readable description of the MBean.

     *

     * @return the description.

     */

    public String getDescription()  {

        return description;

    }

    /**

     * Returns the list of attributes exposed for management.

     * Each attribute is described by an <CODE>MBeanAttributeInfo</CODE> object.

     *

     * The returned array is a shallow copy of the internal array,

     * which means that it is a copy of the internal array of

     * references to the <CODE>MBeanAttributeInfo</CODE> objects

     * but that each referenced <CODE>MBeanAttributeInfo</CODE> object is not copied.

     *

     * @return  An array of <CODE>MBeanAttributeInfo</CODE> objects.

     */

    public MBeanAttributeInfo[] getAttributes()   {

        MBeanAttributeInfo[] as = nonNullAttributes();

        if (as.length == 0)

            return as;

        else

            return as.clone();

    }

    private MBeanAttributeInfo[] fastGetAttributes() {

        if (arrayGettersSafe)

            return nonNullAttributes();

        else

            return getAttributes();

    }

    /**

     * Return the value of the attributes field, or an empty array if

     * the field is null.  This can't happen with a

     * normally-constructed instance of this class, but can if the

     * instance was deserialized from another implementation that

     * allows the field to be null.  It would be simpler if we enforced

     * the class invariant that these fields cannot be null by writing

     * a readObject() method, but that would require us to define the

     * various array fields as non-final, which is annoying because

     * conceptually they are indeed final.

     */

    private MBeanAttributeInfo[] nonNullAttributes() {

        return (attributes == null) ?

            MBeanAttributeInfo.NO_ATTRIBUTES : attributes;

    }

    /**

     * Returns the list of operations  of the MBean.

     * Each operation is described by an <CODE>MBeanOperationInfo</CODE> object.

     *

     * The returned array is a shallow copy of the internal array,

     * which means that it is a copy of the internal array of

     * references to the <CODE>MBeanOperationInfo</CODE> objects

     * but that each referenced <CODE>MBeanOperationInfo</CODE> object is not copied.

     *

     * @return  An array of <CODE>MBeanOperationInfo</CODE> objects.

     */

    public MBeanOperationInfo[] getOperations()  {

        MBeanOperationInfo[] os = nonNullOperations();

        if (os.length == 0)

            return os;

        else

            return os.clone();

    }

    private MBeanOperationInfo[] fastGetOperations() {

        if (arrayGettersSafe)

            return nonNullOperations();

        else

            return getOperations();

    }

    private MBeanOperationInfo[] nonNullOperations() {

        return (operations == null) ?

            MBeanOperationInfo.NO_OPERATIONS : operations;

    }

    /**

     * <p>Returns the list of the public constructors of the MBean.

     * Each constructor is described by an

     * <CODE>MBeanConstructorInfo</CODE> object.</p>

     *

     * <p>The returned array is a shallow copy of the internal array,

     * which means that it is a copy of the internal array of

     * references to the <CODE>MBeanConstructorInfo</CODE> objects but

     * that each referenced <CODE>MBeanConstructorInfo</CODE> object

     * is not copied.</p>

     *

     * <p>The returned list is not necessarily exhaustive.  That is,

     * the MBean may have a public constructor that is not in the

     * list.  In this case, the MBean server can construct another

     * instance of this MBean's class using that constructor, even

     * though it is not listed here.</p>

     *

     * @return  An array of <CODE>MBeanConstructorInfo</CODE> objects.

     */

    public MBeanConstructorInfo[] getConstructors()  {

        MBeanConstructorInfo[] cs = nonNullConstructors();

        if (cs.length == 0)

            return cs;

        else

            return cs.clone();

    }

    private MBeanConstructorInfo[] fastGetConstructors() {

        if (arrayGettersSafe)

            return nonNullConstructors();

        else

            return getConstructors();

    }

    private MBeanConstructorInfo[] nonNullConstructors() {

        return (constructors == null) ?

            MBeanConstructorInfo.NO_CONSTRUCTORS : constructors;

    }

    /**

     * Returns the list of the notifications emitted by the MBean.

     * Each notification is described by an <CODE>MBeanNotificationInfo</CODE> object.

     *

     * The returned array is a shallow copy of the internal array,

     * which means that it is a copy of the internal array of

     * references to the <CODE>MBeanNotificationInfo</CODE> objects

     * but that each referenced <CODE>MBeanNotificationInfo</CODE> object is not copied.

     *

     * @return  An array of <CODE>MBeanNotificationInfo</CODE> objects.

     */

    public MBeanNotificationInfo[] getNotifications()  {

        MBeanNotificationInfo[] ns = nonNullNotifications();

        if (ns.length == 0)

            return ns;

        else

            return ns.clone();

    }

    private MBeanNotificationInfo[] fastGetNotifications() {

        if (arrayGettersSafe)

            return nonNullNotifications();

        else

            return getNotifications();

    }

    private MBeanNotificationInfo[] nonNullNotifications() {

        return (notifications == null) ?

            MBeanNotificationInfo.NO_NOTIFICATIONS : notifications;

    }

    /**

     * Get the descriptor of this MBeanInfo.  Changing the returned value

     * will have no affect on the original descriptor.

     *

     * @return a descriptor that is either immutable or a copy of the original.

     *

     * @since 1.6

     */

    public Descriptor getDescriptor() {

        return (Descriptor) nonNullDescriptor(descriptor).clone();

    }

    public String toString() {

        return

            getClass().getName() + "[" +

            "description=" + getDescription() + ", " +

            "attributes=" + Arrays.asList(fastGetAttributes()) + ", " +

            "constructors=" + Arrays.asList(fastGetConstructors()) + ", " +

            "operations=" + Arrays.asList(fastGetOperations()) + ", " +

            "notifications=" + Arrays.asList(fastGetNotifications()) + ", " +

            "descriptor=" + getDescriptor() +

            "]";

    }

    /**

     * <p>Compare this MBeanInfo to another.  Two MBeanInfo objects

     * are equal if and only if they return equal values for {@link

     * #getClassName()}, for {@link #getDescription()}, and for

     * {@link #getDescriptor()}, and the

     * arrays returned by the two objects for {@link

     * #getAttributes()}, {@link #getOperations()}, {@link

     * #getConstructors()}, and {@link #getNotifications()} are

     * pairwise equal.  Here "equal" means {@link

     * Object#equals(Object)}, not identity.</p>

     *

     * <p>If two MBeanInfo objects return the same values in one of

     * their arrays but in a different order then they are not equal.</p>

     *

     * @param o the object to compare to.

     *

     * @return true if and only if <code>o</code> is an MBeanInfo that is equal

     * to this one according to the rules above.

     */

    public boolean equals(Object o) {

        if (o == this)

            return true;

        if (!(o instanceof MBeanInfo))

            return false;

        MBeanInfo p = (MBeanInfo) o;

        if (!isEqual(getClassName(),  p.getClassName()) ||

                !isEqual(getDescription(), p.getDescription()) ||

                !getDescriptor().equals(p.getDescriptor())) {

            return false;

        }

        return

            (Arrays.equals(p.fastGetAttributes(), fastGetAttributes()) &&

             Arrays.equals(p.fastGetOperations(), fastGetOperations()) &&

             Arrays.equals(p.fastGetConstructors(), fastGetConstructors()) &&

             Arrays.equals(p.fastGetNotifications(), fastGetNotifications()));