org.jinterop.dcom.core

Class JIArray

java.lang.Object

org.jinterop.dcom.core.JIArray

All Implemented Interfaces:

Serializable

public final class JIArray
extends Object
implements Serializable

Represents a C++ array which can display both conformant and standard behaviors. Since this class forms a wrapper on the actual array, the developer is expected to provide complete and final arrays (of Objects) to this class. Modifying the wrapped array afterwards will have unexpected results.

Please refer to MSExcel examples for more details on how to use this class.

Note: Wrapped Arrays can be at most two dimensional in nature. Above that is not supported by the library.

Since:

1.0

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
JIArray(Class clazz, int[] upperBounds, int dimension, boolean isConformant) Creates an array object of the type specified by clazz.
JIArray(Class clazz, int[] upperBounds, int dimension, boolean isConformant, boolean isVarying) Refer to JIArray(Class, int[], int, boolean)
JIArray(Object array) Creates an object with array parameter as the nested Array.
JIArray(Object array, boolean isConformant) Creates an object with array parameter as the nested Array.
JIArray(Object array, boolean isConformant, boolean isVarying) Refer JIArray(Object, boolean)
JIArray(Object template, int[] upperBounds, int dimension, boolean isConformant) Creates an array object with members of the type template.
JIArray(Object template, int[] upperBounds, int dimension, boolean isConformant, boolean isVarying) Refer to JIArray(Object, int[], int, boolean) for details.

Method Summary

Modifier and Type	Method and Description
Class	getArrayClass() Class of the nested Array.
Object	getArrayInstance() Returns the nested Array.
int	getDimensions() Returns the dimensions of the Array.
int[]	getUpperBounds() Array of integers depicting highest index for each dimension.
boolean	isConformant() Status whether the array is conformant or not.
boolean	isVarying() Status whether the array is varying or not.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JIArray

public JIArray(Class clazz,
               int[] upperBounds,
               int dimension,
               boolean isConformant)

Creates an array object of the type specified by clazz. This is used to prepare a template for decoding an array of that type. Used only for setting as an [out] parameter in a JICallBuilder.

For example:-
This call creates a template for a single dimension Integer array of size 10.
JIArray array = new JIArray(Integer.class,new int[]{10},1,false);

Parameters:

clazz - class whose instances will be members of the deserialized array.

upperBounds - highest index for each dimension.

dimension - number of dimensions

isConformant - declares whether the array is conformant or not.

Throws:

IllegalArgumentException - if upperBounds is supplied and its length is not equal to the dimension parameter.

JIArray

public JIArray(Class clazz,
               int[] upperBounds,
               int dimension,
               boolean isConformant,
               boolean isVarying)

Refer to JIArray(Class, int[], int, boolean)

Parameters:

clazz - class whose instances will be members of the deserialized array.

upperBounds - highest index for each dimension.

dimension - number of dimensions

isConformant - declares whether the array is conformant or not.

isVarying - declares whether the array is varying or not.

Throws:

IllegalArgumentException - if upperBounds is supplied and its length is not equal to the dimension parameter.

JIArray

public JIArray(Object template,
               int[] upperBounds,
               int dimension,
               boolean isConformant)

Creates an array object with members of the type template. This constructor is used to prepare a template for decoding an array and is exclusively for composites like JIStruct, JIPointer, JIUnion, JIString where more information on the structure of the composite is required before trying to deserialize it.

Sample Usage:-
JIStruct safeArrayBounds = new JIStruct();
safeArrayBounds.addMember(Integer.class);
safeArrayBounds.addMember(Integer.class);

//arraydesc
JIStruct arrayDesc = new JIStruct();
//typedesc
JIStruct typeDesc = new JIStruct();

arrayDesc.addMember(typeDesc);
arrayDesc.addMember(Short.class);
arrayDesc.addMember(new JIArray(safeArrayBounds,new int[]{1},1,true));


Parameters:

template - can be only of the type JIStruct, JIPointer, JIUnion, JIString

upperBounds - highest index for each dimension.

dimension - number of dimensions

isConformant - declares whether the array is conformant or not.

Throws:

IllegalArgumentException - if upperBounds is supplied and its length is not equal to the dimension parameter.

IllegalArgumentException - if template is null or is not of the specified types.

JIArray

public JIArray(Object template,
               int[] upperBounds,
               int dimension,
               boolean isConformant,
               boolean isVarying)

Refer to JIArray(Object, int[], int, boolean) for details.

Parameters:

template - can be only of the type JIStruct, JIPointer, JIUnion, JIString

upperBounds - highest index for each dimension.

dimension - number of dimensions

isConformant - declares whether the array is conformant or not.

isVarying - declares whether the array is varying or not.

Throws:

IllegalArgumentException - if upperBounds is supplied and its length is not equal to the dimension parameter.

IllegalArgumentException - if template is null or is not of the specified types.

JIArray

public JIArray(Object array,
               boolean isConformant)

Creates an object with array parameter as the nested Array. This constructor is used when the developer wants to send an array to COM server.

Sample Usage :-
JIArray array = new JIArray(new JIString[]{new JIString(name)},true);


Parameters:

array - Array of any type. Primitive arrays are not allowed.

isConformant - declares whether the array is conformant or not.

Throws:

IllegalArgumentException - if the array is not an array or is of primitive type or is an array of java.lang.Object.

JIArray

public JIArray(Object array,
               boolean isConformant,
               boolean isVarying)

Refer JIArray(Object, boolean)

Parameters:

array - Array of any type. Primitive arrays are not allowed.

isConformant - declares whether the array is conformant or not.

isVarying - declares whether the array is varying or not.

Throws:

IllegalArgumentException - if the array is not an array or is of primitive type or is an array of java.lang.Object.

JIArray

public JIArray(Object array)

Creates an object with array parameter as the nested Array. This constructor forms a non-conformant array and is used when the developer wants to send an array to COM server.

Sample Usage :-
JIArray array = new JIArray(new JIString[]{new JIString(name)},true);


Parameters:

array - Array of any type. Primitive arrays are not allowed.

Throws:

IllegalArgumentException - if the array is not an array or is of primitive type or is an array of java.lang.Object.

Method Detail

getArrayInstance

public Object getArrayInstance()

Returns the nested Array.

Returns:

array Object which can be type casted based on value returned by getArrayClass().

getArrayClass

public Class getArrayClass()

Class of the nested Array.

Returns:

class

getUpperBounds

public int[] getUpperBounds()

Array of integers depicting highest index for each dimension.

Returns:

int[]

getDimensions

public int getDimensions()

Returns the dimensions of the Array.

Returns:

int

isConformant

public boolean isConformant()

Status whether the array is conformant or not.

Returns:

true is array is conformant.

isVarying

public boolean isVarying()

Status whether the array is varying or not.

Returns:

true is array is varying.

toString

public String toString()

Overrides:

toString in class Object