/*

 * Copyright (c) 2000, 2008, Oracle and/or its affiliates. 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.  Oracle designates this

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

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.management.openmbean;

import java.io.ObjectStreamException;

import java.lang.reflect.Array;

/**

 * The <code>ArrayType</code> class is the <i>open type</i> class whose instances describe

 * all <i>open data</i> values which are n-dimensional arrays of <i>open data</i> values.

 * <p>

 * Examples of valid {@code ArrayType} instances are:

 * // 2-dimension array of java.lang.String

 * ArrayType<String[][]> a1 = new ArrayType<String[][]>(2, SimpleType.STRING);

 *

 * // 1-dimension array of int

 * ArrayType<int[]> a2 = new ArrayType<int[]>(SimpleType.INTEGER, true);

 *

 * // 1-dimension array of java.lang.Integer

 * ArrayType<Integer[]> a3 = new ArrayType<Integer[]>(SimpleType.INTEGER, false);

 *

 * // 4-dimension array of int

 * ArrayType<int[][][][]> a4 = new ArrayType<int[][][][]>(3, a2);

 *

 * // 4-dimension array of java.lang.Integer

 * ArrayType<Integer[][][][]> a5 = new ArrayType<Integer[][][][]>(3, a3);

 *

 * // 1-dimension array of java.lang.String

 * ArrayType<String[]> a6 = new ArrayType<String[]>(SimpleType.STRING, false);

 *

 * // 1-dimension array of long

 * ArrayType<long[]> a7 = new ArrayType<long[]>(SimpleType.LONG, true);

 *

 * // 1-dimension array of java.lang.Integer

 * ArrayType<Integer[]> a8 = ArrayType.getArrayType(SimpleType.INTEGER);

 *

 * // 2-dimension array of java.lang.Integer

 * ArrayType<Integer[][]> a9 = ArrayType.getArrayType(a8);

 *

 * // 2-dimension array of int

 * ArrayType<int[][]> a10 = ArrayType.getPrimitiveArrayType(int[][].class);

 *

 * // 3-dimension array of int

 * ArrayType<int[][][]> a11 = ArrayType.getArrayType(a10);

 *

 * // 1-dimension array of float

 * ArrayType<float[]> a12 = ArrayType.getPrimitiveArrayType(float[].class);

 *

 * // 2-dimension array of float

 * ArrayType<float[][]> a13 = ArrayType.getArrayType(a12);

 *

 * // 1-dimension array of javax.management.ObjectName

 * ArrayType<ObjectName[]> a14 = ArrayType.getArrayType(SimpleType.OBJECTNAME);

 *

 * // 2-dimension array of javax.management.ObjectName

 * ArrayType<ObjectName[][]> a15 = ArrayType.getArrayType(a14);

 *

 * // 3-dimension array of java.lang.String

 * ArrayType<String[][][]> a16 = new ArrayType<String[][][]>(3, SimpleType.STRING);

 *

 * // 1-dimension array of java.lang.String

 * ArrayType<String[]> a17 = new ArrayType<String[]>(1, SimpleType.STRING);

 *

 * // 2-dimension array of java.lang.String

 * ArrayType<String[][]> a18 = new ArrayType<String[][]>(1, a17);

 *

 * // 3-dimension array of java.lang.String

 * ArrayType<String[][][]> a19 = new ArrayType<String[][][]>(1, a18);

 *

 *

 * @since 1.5

 */

/*

  Generification note: we could have defined a type parameter that is the

  element type, with class ArrayType<E> extends OpenType<E[]>.  However,

  that doesn't buy us all that much.  We can't say

    public OpenType<E> getElementOpenType()

  because this ArrayType could be a multi-dimensional array.

  For example, if we had

    ArrayType(2, SimpleType.INTEGER)

  then E would have to be Integer[], while getElementOpenType() would

  return SimpleType.INTEGER, which is an OpenType<Integer>.

  Furthermore, we would like to support int[] (as well as Integer[]) as

  an Open Type (RFE 5045358).  We would want this to be an OpenType<int[]>

  which can't be expressed as <E[]> because E can't be a primitive type

  like int.

 */

public class ArrayType<T> extends OpenType<T> {

    /* Serial version */

    static final long serialVersionUID = 720504429830309770L;

    /**

     * @serial The dimension of arrays described by this {@link ArrayType}

     *         instance.

     */

    private int dimension;

    /**

     * @serial The <i>open type</i> of element values contained in the arrays

     *         described by this {@link ArrayType} instance.

     */

    private OpenType<?> elementType;

    /**

     * @serial This flag indicates whether this {@link ArrayType}

     *         describes a primitive array.

     *

     * @since 1.6

     */

    private boolean primitiveArray;

    private transient Integer  myHashCode = null;       // As this instance is immutable, these two values

    private transient String   myToString = null;       // need only be calculated once.

    // indexes refering to columns in the PRIMITIVE_ARRAY_TYPES table.

    private static final int PRIMITIVE_WRAPPER_NAME_INDEX = 0;

    private static final int PRIMITIVE_TYPE_NAME_INDEX = 1;

    private static final int PRIMITIVE_TYPE_KEY_INDEX  = 2;

    private static final int PRIMITIVE_OPEN_TYPE_INDEX  = 3;

    private static final Object[][] PRIMITIVE_ARRAY_TYPES = {

        { Boolean.class.getName(),   boolean.class.getName(), "Z", SimpleType.BOOLEAN },

        { Character.class.getName(), char.class.getName(),    "C", SimpleType.CHARACTER },

        { Byte.class.getName(),      byte.class.getName(),    "B", SimpleType.BYTE },

        { Short.class.getName(),     short.class.getName(),   "S", SimpleType.SHORT },

        { Integer.class.getName(),   int.class.getName(),     "I", SimpleType.INTEGER },

        { Long.class.getName(),      long.class.getName(),    "J", SimpleType.LONG },

        { Float.class.getName(),     float.class.getName(),   "F", SimpleType.FLOAT },

        { Double.class.getName(),    double.class.getName(),  "D", SimpleType.DOUBLE }

    };

    static boolean isPrimitiveContentType(final String primitiveKey) {

        for (Object[] typeDescr : PRIMITIVE_ARRAY_TYPES) {

            if (typeDescr[PRIMITIVE_TYPE_KEY_INDEX].equals(primitiveKey)) {

                return true;

            }

        }

        return false;

    }

    /**

     * Return the key used to identify the element type in

     * arrays - e.g. "Z" for boolean, "C" for char etc...

     * @param elementClassName the wrapper class name of the array

     *        element ("Boolean",  "Character", etc...)

     * @return the key corresponding to the given type ("Z", "C", etc...)

     *         return null if the given elementClassName is not a primitive

     *         wrapper class name.

     **/

    static String getPrimitiveTypeKey(String elementClassName) {

        for (Object[] typeDescr : PRIMITIVE_ARRAY_TYPES) {

            if (elementClassName.equals(typeDescr[PRIMITIVE_WRAPPER_NAME_INDEX]))

                return (String)typeDescr[PRIMITIVE_TYPE_KEY_INDEX];

        }

        return null;

    }

    /**

     * Return the primitive type name corresponding to the given wrapper class.

     * e.g. "boolean" for "Boolean", "char" for "Character" etc...

     * @param elementClassName the type of the array element ("Boolean",

     *        "Character", etc...)

     * @return the primitive type name corresponding to the given wrapper class

     *         ("boolean", "char", etc...)

     *         return null if the given elementClassName is not a primitive

     *         wrapper type name.

     **/

    static String getPrimitiveTypeName(String elementClassName) {

        for (Object[] typeDescr : PRIMITIVE_ARRAY_TYPES) {

            if (elementClassName.equals(typeDescr[PRIMITIVE_WRAPPER_NAME_INDEX]))

                return (String)typeDescr[PRIMITIVE_TYPE_NAME_INDEX];

        }

        return null;

    }

    /**

     * Return the primitive open type corresponding to the given primitive type.

     * e.g. SimpleType.BOOLEAN for "boolean", SimpleType.CHARACTER for

     * "char", etc...

     * @param primitiveTypeName the primitive type of the array element ("boolean",

     *        "char", etc...)

     * @return the OpenType corresponding to the given primitive type name

     *         (SimpleType.BOOLEAN, SimpleType.CHARACTER, etc...)

     *         return null if the given elementClassName is not a primitive

     *         type name.

     **/

    static SimpleType<?> getPrimitiveOpenType(String primitiveTypeName) {

        for (Object[] typeDescr : PRIMITIVE_ARRAY_TYPES) {

            if (primitiveTypeName.equals(typeDescr[PRIMITIVE_TYPE_NAME_INDEX]))

                return (SimpleType<?>)typeDescr[PRIMITIVE_OPEN_TYPE_INDEX];

        }

        return null;

    }

    /* *** Constructor *** */

    /**

     * Constructs an <tt>ArrayType</tt> instance describing <i>open data</i> values which are

     * arrays with dimension <var>dimension</var> of elements whose <i>open type</i> is <var>elementType</var>.

     * <p>

     * When invoked on an <tt>ArrayType</tt> instance, the {@link OpenType#getClassName() getClassName} method

     * returns the class name of the array instances it describes (following the rules defined by the

     * {@link Class#getName() getName} method of <code>java.lang.Class</code>), not the class name of the array elements

     * (which is returned by a call to <tt>getElementOpenType().getClassName()</tt>).

     * <p>

     * The internal field corresponding to the type name of this <code>ArrayType</code> instance is also set to

     * the class name of the array instances it describes.

     * In other words, the methods <code>getClassName</code> and <code>getTypeName</code> return the same string value.

     * The internal field corresponding to the description of this <code>ArrayType</code> instance is set to a string value

     * which follows the following template:

     * <ul>

     * <li>if non-primitive array: <tt><i>&lt;dimension&gt;</i>-dimension array of <i>&lt;element_class_name&gt;</i></tt></li>

     * <li>if primitive array: <tt><i>&lt;dimension&gt;</i>-dimension array of <i>&lt;primitive_type_of_the_element_class_name&gt;</i></tt></li>

     * </ul>

     * <p>

     * As an example, the following piece of code:

     * ArrayType<String[][][]> t = new ArrayType<String[][][]>(3, SimpleType.STRING);

     * System.out.println("array class name       = " + t.getClassName());

     * System.out.println("element class name     = " + t.getElementOpenType().getClassName());

     * System.out.println("array type name        = " + t.getTypeName());

     * System.out.println("array type description = " + t.getDescription());

     * would produce the following output:

     * array class name       = [[[Ljava.lang.String;

     * element class name     = java.lang.String

     * array type name        = [[[Ljava.lang.String;

     * array type description = 3-dimension array of java.lang.String

     * And the following piece of code which is equivalent to the one listed

     * above would also produce the same output:

     * ArrayType<String[]> t1 = new ArrayType<String[]>(1, SimpleType.STRING);

     * ArrayType<String[][]> t2 = new ArrayType<String[][]>(1, t1);

     * ArrayType<String[][][]> t3 = new ArrayType<String[][][]>(1, t2);

     * System.out.println("array class name       = " + t3.getClassName());

     * System.out.println("element class name     = " + t3.getElementOpenType().getClassName());

     * System.out.println("array type name        = " + t3.getTypeName());

     * System.out.println("array type description = " + t3.getDescription());

     *

     * @param  dimension  the dimension of arrays described by this <tt>ArrayType</tt> instance;

     *                    must be greater than or equal to 1.

     *

     * @param  elementType  the <i>open type</i> of element values contained

     *                      in the arrays described by this <tt>ArrayType</tt>

     *                      instance; must be an instance of either

     *                      <tt>SimpleType</tt>, <tt>CompositeType</tt>,

     *                      <tt>TabularType</tt> or another <tt>ArrayType</tt>

     *                      with a <tt>SimpleType</tt>, <tt>CompositeType</tt>

     *                      or <tt>TabularType</tt> as its <tt>elementType</tt>.

     *

     * @throws IllegalArgumentException if {@code dimension} is not a positive

     *                                  integer.

     * @throws OpenDataException  if <var>elementType's className</var> is not

     *                            one of the allowed Java class names for open

     *                            data.

     */

    public ArrayType(int dimension,

                     OpenType<?> elementType) throws OpenDataException {

        // Check and construct state defined by parent.

        // We can't use the package-private OpenType constructor because

        // we don't know if the elementType parameter is sane.

        super(buildArrayClassName(dimension, elementType),

              buildArrayClassName(dimension, elementType),

              buildArrayDescription(dimension, elementType));

        // Check and construct state specific to ArrayType

        //

        if (elementType.isArray()) {

            ArrayType<?> at = (ArrayType<?>) elementType;

            this.dimension = at.getDimension() + dimension;

            this.elementType = at.getElementOpenType();

            this.primitiveArray = at.isPrimitiveArray();

        } else {

            this.dimension = dimension;

            this.elementType = elementType;

            this.primitiveArray = false;

        }

    }

    /**

     * Constructs a unidimensional {@code ArrayType} instance for the

     * supplied {@code SimpleType}.

     * <p>

     * This constructor supports the creation of arrays of primitive

     * types when {@code primitiveArray} is {@code true}.

     * <p>

     * For primitive arrays the {@link #getElementOpenType()} method

     * returns the {@link SimpleType} corresponding to the wrapper

     * type of the primitive type of the array.

     * <p>

     * When invoked on an <tt>ArrayType</tt> instance, the {@link OpenType#getClassName() getClassName} method

     * returns the class name of the array instances it describes (following the rules defined by the

     * {@link Class#getName() getName} method of <code>java.lang.Class</code>), not the class name of the array elements

     * (which is returned by a call to <tt>getElementOpenType().getClassName()</tt>).

     * <p>

     * The internal field corresponding to the type name of this <code>ArrayType</code> instance is also set to

     * the class name of the array instances it describes.

     * In other words, the methods <code>getClassName</code> and <code>getTypeName</code> return the same string value.

     * The internal field corresponding to the description of this <code>ArrayType</code> instance is set to a string value

     * which follows the following template:

     * <ul>

     * <li>if non-primitive array: <tt>1-dimension array of <i>&lt;element_class_name&gt;</i></tt></li>

     * <li>if primitive array: <tt>1-dimension array of <i>&lt;primitive_type_of_the_element_class_name&gt;</i></tt></li>

     * </ul>

     * <p>

     * As an example, the following piece of code:

     * ArrayType<int[]> t = new ArrayType<int[]>(SimpleType.INTEGER, true);

     * System.out.println("array class name       = " + t.getClassName());

     * System.out.println("element class name     = " + t.getElementOpenType().getClassName());

     * System.out.println("array type name        = " + t.getTypeName());

     * System.out.println("array type description = " + t.getDescription());

     * would produce the following output:

     * array class name       = [I

     * element class name     = java.lang.Integer

     * array type name        = [I

     * array type description = 1-dimension array of int

     *

     * @param elementType the {@code SimpleType} of the element values

     *                    contained in the arrays described by this

     *                    {@code ArrayType} instance.

     *

     * @param primitiveArray {@code true} when this array describes

     *                       primitive arrays.

     *

     * @throws IllegalArgumentException if {@code dimension} is not a positive

     * integer.

     * @throws OpenDataException if {@code primitiveArray} is {@code true} and

     * {@code elementType} is not a valid {@code SimpleType} for a primitive

     * type.

     *

     * @since 1.6

     */

    public ArrayType(SimpleType<?> elementType,

                     boolean primitiveArray) throws OpenDataException {

        // Check and construct state defined by parent.

        // We can call the package-private OpenType constructor because the

        // set of SimpleTypes is fixed and SimpleType can't be subclassed.

        super(buildArrayClassName(1, elementType, primitiveArray),

              buildArrayClassName(1, elementType, primitiveArray),

              buildArrayDescription(1, elementType, primitiveArray),

              true);

        // Check and construct state specific to ArrayType

        //

        this.dimension = 1;

        this.elementType = elementType;

        this.primitiveArray = primitiveArray;

    }

    /* Package-private constructor for callers we trust to get it right. */

    ArrayType(String className, String typeName, String description,

              int dimension, OpenType<?> elementType,

              boolean primitiveArray) {

        super(className, typeName, description, true);

        this.dimension = dimension;

        this.elementType = elementType;

        this.primitiveArray = primitiveArray;

    }

    private static String buildArrayClassName(int dimension,

                                              OpenType<?> elementType)

        throws OpenDataException {

        boolean isPrimitiveArray = false;

        if (elementType.isArray()) {

            isPrimitiveArray = ((ArrayType<?>) elementType).isPrimitiveArray();

        }

        return buildArrayClassName(dimension, elementType, isPrimitiveArray);

    }

    private static String buildArrayClassName(int dimension,

                                              OpenType<?> elementType,

                                              boolean isPrimitiveArray)

        throws OpenDataException {

        if (dimension < 1) {

            throw new IllegalArgumentException(

                "Value of argument dimension must be greater than 0");

        }

        StringBuilder result = new StringBuilder();

        String elementClassName = elementType.getClassName();

        // Add N (= dimension) additional '[' characters to the existing array

        for (int i = 1; i <= dimension; i++) {

            result.append('[');

        }

        if (elementType.isArray()) {

            result.append(elementClassName);

        } else {

            if (isPrimitiveArray) {

                final String key = getPrimitiveTypeKey(elementClassName);

                // Ideally we should throw an IllegalArgumentException here,

                // but for compatibility reasons we throw an OpenDataException.

                // (used to be thrown by OpenType() constructor).

                //

                if (key == null)

                    throw new OpenDataException("Element type is not primitive: "

                            + elementClassName);

                result.append(key);

            } else {

                result.append("L");

                result.append(elementClassName);

                result.append(';');

            }

        }

        return result.toString();

    }

    private static String buildArrayDescription(int dimension,

                                                OpenType<?> elementType)

        throws OpenDataException {

        boolean isPrimitiveArray = false;

        if (elementType.isArray()) {

            isPrimitiveArray = ((ArrayType<?>) elementType).isPrimitiveArray();

        }

        return buildArrayDescription(dimension, elementType, isPrimitiveArray);

    }

    private static String buildArrayDescription(int dimension,

                                                OpenType<?> elementType,

                                                boolean isPrimitiveArray)

        throws OpenDataException {

        if (elementType.isArray()) {

            ArrayType<?> at = (ArrayType<?>) elementType;

            dimension += at.getDimension();

            elementType = at.getElementOpenType();

            isPrimitiveArray = at.isPrimitiveArray();

        }

        StringBuilder result =

            new StringBuilder(dimension + "-dimension array of ");

        final String elementClassName = elementType.getClassName();

        if (isPrimitiveArray) {

            // Convert from wrapper type to primitive type

            final String primitiveType =

                    getPrimitiveTypeName(elementClassName);

            // Ideally we should throw an IllegalArgumentException here,

            // but for compatibility reasons we throw an OpenDataException.

            // (used to be thrown by OpenType() constructor).

            //

            if (primitiveType == null)

                throw new OpenDataException("Element is not a primitive type: "+

                        elementClassName);

            result.append(primitiveType);

        } else {

            result.append(elementClassName);

        }

        return result.toString();

    }

    /* *** ArrayType specific information methods *** */

    /**

     * Returns the dimension of arrays described by this <tt>ArrayType</tt> instance.

     *

     * @return the dimension.

     */

    public int getDimension() {

        return dimension;

    }

    /**

     * Returns the <i>open type</i> of element values contained in the arrays described by this <tt>ArrayType</tt> instance.

     *

     * @return the element type.

     */

    public OpenType<?> getElementOpenType() {

        return elementType;

    }

    /**

     * Returns <code>true</code> if the open data values this open

     * type describes are primitive arrays, <code>false</code> otherwise.

     *

     * @return true if this is a primitive array type.

     *

     * @since 1.6

     */

    public boolean isPrimitiveArray() {

        return primitiveArray;

    }

    /**

     * Tests whether <var>obj</var> is a value for this <code>ArrayType</code>

     * instance.

     * <p>

     * This method returns <code>true</code> if and only if <var>obj</var>

     * is not null, <var>obj</var> is an array and any one of the following

     * is <tt>true</tt>: