/*
 * @(#)ArrayType.java	3.24 03/12/19
 * 
 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */


package javax.management.openmbean;


// java import
//
import java.io.Serializable;

// jmx import
//


/**
 * 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.
 *
 * @version     3.24  03/12/19
 * @author      Sun Microsystems, Inc.
 *
 * @since 1.5
 * @since.unbundled JMX 1.1
 */
public class ArrayType 
    extends OpenType
    implements Serializable {

    /* 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;

    private transient Integer  myHashCode = null;	// As this instance is immutable, these two values
    private transient String   myToString = null;	// need only be calculated once.


    /* *** 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:<br>
     * <tt><i><dimension></i>-dimension array of <i><element_class_name></i></tt>
     * <p>
     * As an example, the following piece of code:
     * <pre>
     * ArrayType t = new ArrayType(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());
     * </pre>
     * would produce the following output:
     * <pre>
     * array class name       = [[[java.lang.String;
     * element class name     = java.lang.String
     * array type name        = [[[java.lang.String;
     * array type description = 3-dimension array of java.lang.String
     * </pre>
     * 
     * @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> or <tt>TabularType</tt>.
     *
     * @throws IllegalArgumentException  if <var>dimension</var> is not a positive integer
     *
     * @throws OpenDataException  if <var>elementType</var> is an instance of <tt>ArrayType</tt>
     */
    public ArrayType(int      dimension,
		     OpenType elementType) throws OpenDataException {
	
	// Check and construct state defined by parent.
	//
	super(buildArrayClassName(dimension, elementType.getClassName()), 
	      buildArrayClassName(dimension, elementType.getClassName()), 
	      String.valueOf(dimension) +"-dimension array of "+ elementType.getClassName());
	
	// Check and construct state specific to ArrayType
	//
	this.dimension   = dimension;   // already checked >=1 in buildArrayClassName
	this.elementType = elementType; // cannot be ArrayType: super() would throw exception on the built classname
    }

    /**
     *
     */
    private static String buildArrayClassName(int dimension, String elementClassName) throws OpenDataException {

	if (dimension < 1) {
	    throw new IllegalArgumentException("Value of argument dimension must be greater than 0");
	}

	StringBuffer result = new StringBuffer();

	for (int i=1; i<dimension; i++) { // add (dimension - 1) '[' characters
	    result.append('[');
	}
	result.append("[L");
	result.append(elementClassName);
	result.append(';');

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

    /**
     * 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>:
     * <p><ul>
     * <li>if this <code>ArrayType</code> instance describes an array of <tt>SimpleType</tt> elements,
     * <var>obj</var>'s class name is the same as the className field defined for this <code>ArrayType</code> instance
     * (ie the class name returned by the {@link OpenType#getClassName() getClassName} method, 
     *  which includes the dimension information),<br> 
     * </li>
     * <li>if this <code>ArrayType</code> instance describes an array 
     * of classes implementing the TabularData interface or the CompositeData interface, 
     * <var>obj</var> is assignable to such a declared array,
     * and each element contained in <var>obj</var> is either null or a valid value for the element's open type
     * specified by this <code>ArrayType</code> instance.
     * </li></ul>
     * <p>
     *
     * @param obj the object to be tested.
     *
     * @return <code>true</code> if <var>obj</var> is a value for this <code>ArrayType</code> instance.
     */
    public boolean isValue(Object obj) {

	// if obj is null, return false
	//
	if (obj == null) {
	    return false;
	}

	Class  objClass     = obj.getClass();
	String objClassName = objClass.getName();

	// if obj is not an array, return false
	//
	if ( ! objClass.isArray() ) {
	    return false;
	}

	// Test if obj's class name is the same as for the array values that this instance describes
	// (this is fine if elements are of simple types, which are final classes)
	//
	if ( this.getClassName().equals(objClassName) ) {
	    return true;
	}

	// In case this ArrayType instance describes an array of classes implementing the TabularData or CompositeData interface,
	// we first check for the assignability of obj to such an array of TabularData or CompositeData, 
	// which ensures that:
	//  . obj is of the the same dimension as this ArrayType instance, 
	//  . it is declared as an array of elements which are either all TabularData or all CompositeData.
	//
	// If the assignment check is positive, 
	// then we have to check that each element in obj is of the same TabularType or CompositeType 
	// as the one described by this ArrayType instance.
	//
	// [About assignment check, note that the call below returns true: ]
	// [Class.forName("[Lpackage.CompositeData;").isAssignableFrom(Class.forName("[Lpackage.CompositeDataImpl;)")); ]
	//
	if ( (this.elementType.getClassName().equals(TabularData.class.getName()))  ||
	     (this.elementType.getClassName().equals(CompositeData.class.getName()))   ) {

	    /* this.getClassName() is
	     * "[Ljavax.management.openmbean.TabularData;" or the same
	     * thing for CompositeData, either one optionally preceded
	     * by n '[' characters.  So the class is necessarily known
	     * to the ClassLoader of ArrayType, and Class.forName is
	     * safe.  */
	    Class targetClass;
	    try {
		targetClass = Class.forName(this.getClassName());
	    } catch (ClassNotFoundException e) { // should not happen 
		return false; 
	    }
	    // assignment check: return false if negative
	    if  ( ! targetClass.isAssignableFrom(objClass) ) {
		return false;
	    }

	    // check that all elements in obj are valid values for this ArrayType
	    if ( ! checkElementsType( (Object[]) obj, this.dimension) ) { // we know obj's dimension is this.dimension
		return false;
	    }

	    return true;
	}

	// if previous tests did not return, then obj is not a value for this ArrayType instance
	return false;
    }

    /**
     * Returns true if and only if all elements contained in the array argument x_dim_Array of dimension dim
     * are valid values (ie either null or of the right openType) 
     * for the element open type specified by this ArrayType instance.
     * 
     * This method's implementation uses recursion to go down the dimensions of the array argument.
     */
    private boolean checkElementsType(Object[] x_dim_Array, int dim) {

	// if the elements of x_dim_Array are themselves array: go down recursively....
	if ( dim > 1 ) {
	    for (int i=0; i<x_dim_Array.length; i++) {
		if ( ! checkElementsType((Object[])x_dim_Array[i], dim-1) ) {
		    return false;
		}
	    }
	    return true;
	}
	// ...else, for a non-empty array, each element must be a valid value: either null or of the right openType
	else {
	    for (int i=0; i<x_dim_Array.length; i++) {
		if ( (x_dim_Array[i] != null) && (! this.getElementOpenType().isValue(x_dim_Array[i])) ) {
		    return false;
		}
	    }
	    return true;
	}
    }



    /* *** Methods overriden from class Object *** */

    /**
     * Compares the specified <code>obj</code> parameter with this <code>ArrayType</code> instance for equality.
     * <p> 
     * Two <code>ArrayType</code> instances are equal if and only if they describes array instances
     * which have the same dimension and elements' open type. 
     * 
     * @param  obj  the object to be compared for equality with this <code>ArrayType</code> instance;
     *		    if <var>obj</var> is <code>null</code> or is not an instance of the class <code>ArrayType</code>, 
     *              <code>equals</code> returns <code>false</code>.
     * 
     * @return  <code>true</code> if the specified object is equal to this <code>ArrayType</code> instance.
     */
    public boolean equals(Object obj) {

	// if obj is null, return false
	//
	if (obj == null) {
	    return false;
	}

	// if obj is not an ArrayType, return false
	//
	ArrayType other;
	try {
	    other = (ArrayType) obj;
	} catch (ClassCastException e) {
	    return false;
	}

	// if other's dimension is different than this instance's, return false
	//
	if (other.dimension != this.dimension) {
	    return false;
	}

	// Test if other's elementType field is the same as for this instance
	//
	return this.elementType.equals(other.elementType);
    }

    /**
     * Returns the hash code value for this <code>ArrayType</code> instance.
     * <p>
     * The hash code of a <code>ArrayType</code> instance is the sum of the hash codes
     * of all elements of information used in <code>equals</code> comparisons 
     * (ie: dimension and elements' type). 
     * This ensures that <code> t1.equals(t2) </code> implies that <code> t1.hashCode()==t2.hashCode() </code> 
     * for any two <code>ArrayType</code> instances <code>t1</code> and <code>t2</code>, 
     * as required by the general contract of the method
     * {@link Object#hashCode() Object.hashCode()}.
     * <p>
     * As <code>ArrayType</code> instances are immutable, the hash code for this instance is calculated once,
     * on the first call to <code>hashCode</code>, and then the same value is returned for subsequent calls.
     *
     * @return  the hash code value for this <code>ArrayType</code> instance
     */
    public int hashCode() {

	// Calculate the hash code value if it has not yet been done (ie 1st call to hashCode())
	//
	if (myHashCode == null) {
	    int value = 0;
	    value += this.dimension;
	    value += this.elementType.hashCode();
	    myHashCode = new Integer(value);
	}
	
	// return always the same hash code for this instance (immutable)
	//
	return myHashCode.intValue();
    }

    /**
     * Returns a string representation of this <code>ArrayType</code> instance.
     * <p>
     * The string representation consists of 
     * the name of this class (ie <code>javax.management.openmbean.ArrayType</code>), the type name,
     * the dimension and elements' type defined for this instance, 
     * <p>
     * As <code>ArrayType</code> instances are immutable, the string representation for this instance is calculated once,
     * on the first call to <code>toString</code>, and then the same value is returned for subsequent calls.
     * 
     * @return  a string representation of this <code>ArrayType</code> instance
     */
    public String toString() {

	// Calculate the string representation if it has not yet been done (ie 1st call to toString())
	//
	if (myToString == null) {
	    StringBuffer result = new StringBuffer();
	    result.append(this.getClass().getName());
	    result.append("(name=");
	    result.append(getTypeName());
	    result.append(",dimension=");
	    result.append(String.valueOf(this.dimension));
	    result.append(",elementType=");
	    result.append(this.elementType.toString());
	    result.append(")");
	    myToString = result.toString();
	}

	// return always the same string representation for this instance (immutable)
	//
	return myToString;
    }

}