org.isis.jaut
Class Variant

java.lang.Object
  extended byorg.isis.jaut.ApartmentObject
      extended byorg.isis.jaut.Variant

public class Variant
extends ApartmentObject

The Variant class is a peer object to an uderlying VARIANT Automation structure. It provides the basic methods to create, access, modify and release this structure. We say that a Variant is a reference (or an array) if the VT_BYREF (or the VT_ARRAY) bit is set in the variant type that getVartype() returns. Every Variant that is not a reference owns all its Win32 data structures and resources (VT_BSTR, VT_DISPATCH, VT_UNKNOWN and VT_ARRAY). Reference Variants do not own their referred resources. Typically, these resources are owned by other Variants, or obtained from other Win32 applications.


Field Summary
static int defaultChangeFlags
          Holds the default change flags when coercing the value of the Variant to a native Java type with the toXXX() methods.
 int pVariant
          This holds a pointer to the underlying VARIANT.
static int VARIANT_ALPHABOOL
          Converts a boolean value to a string containing either "True" or "False".
static int VARIANT_LOCALBOOL
          For conversions between boolean and string, uses the language of the user selected locale on the computer.
static int VARIANT_NOUSEROVERRIDE
          For conversions to and from strings prevents the use of the user selected locale on the computer.
static int VARIANT_NOVALUEPROP
          Converts an object to a simple type by invoking the Value property.
static int VT_ARRAY
          An array variant type.
static int VT_BOOL
          A boolean variant type.
static int VT_BSTR
          A string variant type.
static int VT_BYREF
          A reference variant type.
static int VT_CY
          A currency variant type.
static int VT_DATE
          A variant type denoting a date.
static int VT_DECIMAL
          A decimal value variant type.
static int VT_DISPATCH
          A Dispatch Automation object variant type.
static int VT_EMPTY
          The no value variant type.
static int VT_ERROR
          An error code variant type.
static int VT_I1
          1-byte integer variant type.
static int VT_I2
          2-byte integer variant type.
static int VT_I4
          4-byte integer variant type.
static int VT_INT
          machine dependent (4-byte) integer variant type.
static int VT_NULL
          A propagating null variant type.
static int VT_R4
          An IEEE 4-byte real variant type.
static int VT_R8
          An IEEE 8-byte real variant type.
static int VT_UI1
          1-byte unsigned integer variant type.
static int VT_UI2
          2-byte unsigned integer variant type.
static int VT_UI4
          4-byte unsigned integer variant type.
static int VT_UINT
          machine dependent (4-byte) unsigned integer variant type.
static int VT_UNKNOWN
          An IUnknown interface pointer variant type.
static int VT_VARIANT
          A variant type for referring to another Variant object.
 
Fields inherited from class org.isis.jaut.ApartmentObject
apartment
 
Constructor Summary
Variant()
          Creates a Variant with no underlying VARIANT.
Variant(boolean value)
          Creates a Variant of type VT_BOOL.
Variant(byte value)
          Creates a Variant of type VT_UI1.
Variant(java.util.Date value)
          Creates a Variant of type VT_DATE.
Variant(Dispatch value)
          Creates a Variant of type VT_DISPATCH.
Variant(double value)
          Creates a Variant of type VT_R8.
Variant(float value)
          Creates a Variant of type VT_R4.
Variant(int value)
          Creates a Variant of type VT_I4.
Variant(java.lang.Object value)
          Creates a Variant of from an Object.
Variant(short value)
          Creates a Variant of type VT_I2.
Variant(java.lang.String value)
          Creates a Variant of type VT_BSTR.
Variant(Variant value)
          Creates a Variant of a reference type.
 
Method Summary
 SafeArray accessArray()
          Retrives the SafeArray object in the Variant.
 void allocate(int vartype)
          Allocates the underlying VARIANT of a simple datatype.
 void allocateArray(int vartype, int[] lowerBounds, int[] elements)
          Allocates the underlying VARIANT of an array type.
 void allocateReference(int vartype, SafeArray target, int index)
          Not implemented yet.
 void allocateReference(int vartype, Variant target)
          Allocates the underlying VARIANT of a reference type.
 void changeType(Variant destination, int changeFlag, int vartype)
          Converts the Variant to another type.
 void clear()
          Clears the Variant and releases all owned resources other the the underlying VARIANT.
 void copy(Variant destination)
          Frees the destination Variant and makes a copy of this Variant.
 void copyInd(Variant destination)
          Frees the destination Variant and copies the value of this Variant, performing all necessary indirections for references.
static Variant create(int vartype)
          Creates a Variant of a simple datatype.
 void finalize()
          Clears and releases the Variant, can be called from any Thread.
 boolean getBoolean()
          Retrives the boolean value in the Variant.
 byte getByte()
          Retrives the byte value in the Variant.
 java.util.Date getDate()
          Retrives the Date in the Variant.
 Dispatch getDispatch()
          Retrives the Dispatch object in the Variant.
 double getDouble()
          Retrives the double value in the Variant.
 float getFloat()
          Retrives the float value in the Variant.
 int getInt()
          Retrives the int value in the Variant.
 long getLong()
          Retrives the long value in the Variant.
 short getShort()
          Retrives the short value in the Variant.
 java.lang.String getString()
          Retrives the String value in the Variant.
 int getVartype()
          Returns the type of the Variant.
 boolean isCreated()
          Tests if the underlying VARIANT exists.
 void release()
          Clears and releases the underlying VARIANT.
 void setBoolean(boolean value)
          Sets the boolean value in the Variant.
 void setByte(byte value)
          Sets the byte value in the Variant.
 void setDate(java.util.Date value)
          Sets the Date in the Variant.
 void setDispatch(Dispatch value)
          Sets the Dispatch object in the Variant.
 void setDouble(double value)
          Sets the double value in the Variant.
 void setFloat(float value)
          Sets the float value in the Variant.
 void setInt(int value)
          Sets the int value in the Variant.
 void setLong(long value)
          Sets the long value in the Variant.
 void setShort(short value)
          Sets the short value in the Variant.
 void setString(java.lang.String value)
          Sets the String value in the Variant.
 boolean toBoolean()
          Coerces the Varian to a VT_BOOL and returns the coerced value.
 byte toByte()
          Coerces the Varian to a VT_UI1 and returns the coerced value.
 java.util.Date toDate()
          Coerces the Varian to a VT_DATE and returns the coerced value.
 Dispatch toDispatch()
          Coerces the Varian to a VT_DISPATCH and returns the coerced Automation object.
 double toDouble()
          Coerces the Varian to a VT_R8 and returns the coerced value.
 float toFloat()
          Coerces the Varian to a VT_R4 and returns the coerced value.
 int toInt()
          Coerces the Varian to a VT_I4 and returns the coerced value.
 long toLong()
          Coerces the Varian to a VT_CY and returns the coerced value.
 java.lang.Object toObject()
          Returns the value of the Variant in a Java object.
 short toShort()
          Coerces the Varian to a VT_I2 and returns the coerced value.
 java.lang.String toString()
          Coerces the Varian to a VT_BSTR and returns the coerced value.
 
Methods inherited from class org.isis.jaut.ApartmentObject
finalizeInApartment, getApartment
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

VT_EMPTY

public static final int VT_EMPTY
The no value variant type. Cannot be combined with VT_BYREF or VT_ARRAY. This is the type of the Variant after clear().

See Also:
getVartype(), Constant Field Values

VT_NULL

public static final int VT_NULL
A propagating null variant type. This has nothing to do with a null pointer, rather, it is used for tri-state logic, as with SQL. Cannot be combined with VT_BYREF or VT_ARRAY.

See Also:
getVartype(), Constant Field Values

VT_I2

public static final int VT_I2
2-byte integer variant type. This is mapped to short.

See Also:
getVartype(), Constant Field Values

VT_I4

public static final int VT_I4
4-byte integer variant type. This is mapped to int.

See Also:
getVartype(), Constant Field Values

VT_R4

public static final int VT_R4
An IEEE 4-byte real variant type. This is mapped to float

See Also:
getVartype(), Constant Field Values

VT_R8

public static final int VT_R8
An IEEE 8-byte real variant type. This is mapped to double.

See Also:
getVartype(), Constant Field Values

VT_CY

public static final int VT_CY
A currency variant type. It is an 8-byte integer, scaled by 10000 to give a fixed point number with 15-digits to the left of the decimal point and 4-digits to the right. This is mapped to long.

See Also:
getVartype(), getLong(), setLong(long), Constant Field Values

VT_DATE

public static final int VT_DATE
A variant type denoting a date. This is mapped to double, but the correct Java Date can be retrived and set with the methods getDate() and setDate(java.util.Date).

See Also:
getVartype(), Constant Field Values

VT_BSTR

public static final int VT_BSTR
A string variant type. This is mapped to String.

See Also:
getVartype(), Constant Field Values

VT_DISPATCH

public static final int VT_DISPATCH
A Dispatch Automation object variant type.

See Also:
getVartype(), Constant Field Values

VT_ERROR

public static final int VT_ERROR
An error code variant type. This can hold HRESULT error codes. It is mapped to int.

See Also:
getVartype(), Constant Field Values

VT_BOOL

public static final int VT_BOOL
A boolean variant type. It is mapped to boolean.

See Also:
getVartype(), Constant Field Values

VT_VARIANT

public static final int VT_VARIANT
A variant type for referring to another Variant object. It must be a reference, that is, combined with VT_BYREF.

See Also:
getVartype(), Constant Field Values

VT_UNKNOWN

public static final int VT_UNKNOWN
An IUnknown interface pointer variant type. This cannot be used directly; one must try to obtain an IDispatch interface pointer via the getDispatch() method.

See Also:
getVartype(), Constant Field Values

VT_DECIMAL

public static final int VT_DECIMAL
A decimal value variant type. This is currently not mapped, and cannot be retrived directly.

See Also:
getVartype(), Constant Field Values

VT_I1

public static final int VT_I1
1-byte integer variant type. This is mapped to byte.

See Also:
getVartype(), Constant Field Values

VT_UI1

public static final int VT_UI1
1-byte unsigned integer variant type. This is mapped to byte.

See Also:
getVartype(), Constant Field Values

VT_UI2

public static final int VT_UI2
2-byte unsigned integer variant type. This is mapped to short.

See Also:
getVartype(), Constant Field Values

VT_UI4

public static final int VT_UI4
4-byte unsigned integer variant type. This is mapped to int.

See Also:
getVartype(), Constant Field Values

VT_INT

public static final int VT_INT
machine dependent (4-byte) integer variant type. This is mapped to int.

See Also:
getVartype(), Constant Field Values

VT_UINT

public static final int VT_UINT
machine dependent (4-byte) unsigned integer variant type. This is mapped to int.

See Also:
getVartype(), Constant Field Values

VT_ARRAY

public static final int VT_ARRAY
An array variant type. This must be combined with one of the simple data types, except with VT_EMPTY and VT_NULL. The array (actually, the underlying SAFEARRAY) is owned by this Variant, and it is copied and cleared as any other basic data type.

See Also:
getVartype(), Constant Field Values

VT_BYREF

public static final int VT_BYREF
A reference variant type. This must be combined with one of the simple data types. If combined with VT_ARRAY, it is a reference to an array, rather than an array of references.

See Also:
getVartype(), Constant Field Values

pVariant

public int pVariant
This holds a pointer to the underlying VARIANT. It is 0, if the underlying VARIANT is not allocated yet or already released.


VARIANT_NOVALUEPROP

public static final int VARIANT_NOVALUEPROP
Converts an object to a simple type by invoking the Value property. The use of this flag is not recommended.

See Also:
changeType(org.isis.jaut.Variant, int, int), Constant Field Values

VARIANT_ALPHABOOL

public static final int VARIANT_ALPHABOOL
Converts a boolean value to a string containing either "True" or "False".

See Also:
changeType(org.isis.jaut.Variant, int, int), Constant Field Values

VARIANT_NOUSEROVERRIDE

public static final int VARIANT_NOUSEROVERRIDE
For conversions to and from strings prevents the use of the user selected locale on the computer.

See Also:
changeType(org.isis.jaut.Variant, int, int), Constant Field Values

VARIANT_LOCALBOOL

public static final int VARIANT_LOCALBOOL
For conversions between boolean and string, uses the language of the user selected locale on the computer.

See Also:
changeType(org.isis.jaut.Variant, int, int), Constant Field Values

defaultChangeFlags

public static int defaultChangeFlags
Holds the default change flags when coercing the value of the Variant to a native Java type with the toXXX() methods. Acceptable values are combined from the VARIANT_NOVALUEPROP, VARIANT_ALPHABOOL, VARIANT_NOUSEROVERRIDE and VARIANT_LOCALBOOL constants.

Constructor Detail

Variant

public Variant()
Creates a Variant with no underlying VARIANT. Users must call one of the allocate methods to allocate the underlying VARIANT structure. To create a Variant of type VT_EMPTY call new Variant(null).


Variant

public Variant(boolean value)
Creates a Variant of type VT_BOOL.


Variant

public Variant(byte value)
Creates a Variant of type VT_UI1.


Variant

public Variant(short value)
Creates a Variant of type VT_I2.


Variant

public Variant(int value)
Creates a Variant of type VT_I4.


Variant

public Variant(float value)
Creates a Variant of type VT_R4.


Variant

public Variant(double value)
Creates a Variant of type VT_R8.


Variant

public Variant(java.lang.String value)
Creates a Variant of type VT_BSTR.


Variant

public Variant(java.util.Date value)
Creates a Variant of type VT_DATE.


Variant

public Variant(Dispatch value)
Creates a Variant of type VT_DISPATCH.


Variant

public Variant(Variant value)
Creates a Variant of a reference type. If value is of type VT_EMPTY or VT_NULL, then a Variant of type VT_VARIANT|VT_BYREF, otherwise a Variant of type value.getVartype()|VT_BYREF will be created.

Parameters:
value - the Variant holding the actual value that this Variant will refer to.

Variant

public Variant(java.lang.Object value)
Creates a Variant of from an Object. If value is null, then a Variant of type VT_EMPTY is created. Otherwise, a Variant will be created with one of the constructors that accept a single parameter. Note, that if value is a Variant, then a Variant reffering to the data in value will be created by Variant(Variant).

Parameters:
value - an Object
Throws:
JAutException - if value is not one of the allowed types.
See Also:
toObject()
Method Detail

allocate

public void allocate(int vartype)
              throws ComException
Allocates the underlying VARIANT of a simple datatype. If an underlying VARIANT already exists, then it is cleared, otherwise a new VARIANT is allocated. Then the VARIANT is initialized and the variant type is set to vartype.

Parameters:
vartype - the type of the Variant to be allocated. It cannot be an array (VT_ARRAY) or reference (VT_BYREF).
Throws:
JAutException - if vartype is not one of the simple types.
ComException - if the VariantClear function fails when clearing the the content of the previous variant.
java.lang.OutOfMemoryError - if memory could not be allocated for the VARIANT.

create

public static Variant create(int vartype)
                      throws ComException
Creates a Variant of a simple datatype.

Returns:
the newly created Variant object.
Throws:
ComException
See Also:
allocate(int)

release

public void release()
             throws ComException
Clears and releases the underlying VARIANT. If there is no underlying VARIANT, then this method does nothing. Otherwise, the VARIANT is cleared, like with clear(), and the allocated memory for the VARIANT is freed.

Specified by:
release in class ApartmentObject
Throws:
ComException - if the VariantClear function fails.

finalize

public void finalize()
Clears and releases the Variant, can be called from any Thread. Calls the release() or #releaseInApartment methods depending on the type of the current variant.


isCreated

public boolean isCreated()
Tests if the underlying VARIANT exists.

Returns:
true if the underlying VARIANT exsists, false otherwise.
See Also:
allocate(int)

getVartype

public int getVartype()
Returns the type of the Variant. This is a wrapper method to access the vt field of the underlying VARIANT. The returned value is of type VARTYPE. Note that VARTYPE is an unsigned 2-byte integer, but we map this to int for convenience.

Returns:
the type of the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated.

changeType

public void changeType(Variant destination,
                       int changeFlag,
                       int vartype)
                throws ComException
Converts the Variant to another type. This is a direct wrapper method around the VariantChangeType Automation function.

Parameters:
destination - the destination Variant to hold the coerced value. If destionation is the same as this or null, the Variant will be converted in place.
changeFlag - flags controlling the coercion. Acceptable values are combined from the four VARIANT_XXX constants.
vartype - The type to coerce to. After a successful conversion the type of the destination Variant is vartype.
Throws:
JAutException - if the underlying VARIANT is not allocated.
ComException - if the VariantChangeType function fails.

clear

public void clear()
           throws ComException
Clears the Variant and releases all owned resources other the the underlying VARIANT. We say that the Variant is cleared if its underlying VARIANT is allocated and its type is VT_EMPTY. Variants of type VT_BSTR, VT_UNKNOWN, VT_DISPATCH and VT_ARRAY own the corresponding resources. In the case of VT_ARRAY the corresponding SAFEARRAY is freed and its content is released. If the type of the Variant is a reference (anything with VT_BYREF), the corresponding resource is not owned by this Variant and it is not released. This method is a direct wrapper around the VariantClear Automation function. This method will fail if the type of the variant is an array and a SafeArray object is attached to this Variant.

Throws:
JAutException - if the underlying VARIANT is not allocated.
ComException - if the VariantClear function fails.
java.lang.OutOfMemoryError - if memory could not be allocated for the conversion.

copy

public void copy(Variant destination)
          throws ComException
Frees the destination Variant and makes a copy of this Variant. First, the destination Variant is cleared, like with clear(). Then destination receives an exact copy of this Variant and all of its owned resources (in the case of VT_BSTR, VT_UNKNOWN, VT_DISPATCH and VT_ARRAY). If the Variant is a reference (anything with VT_BYREF), the corresponding resouce is not owned and is not copied. This method is a direct wrapper around the VariantCopy Automation function.

Parameters:
destination - the destination Variant to hold the copied value.
Throws:
JAutException - if the underlying VARIANT is not allocated.
ComException - if the VariantCopy function fails.
java.lang.OutOfMemoryError - if memory could not be allocated for the copy.

copyInd

public void copyInd(Variant destination)
             throws ComException
Frees the destination Variant and copies the value of this Variant, performing all necessary indirections for references. First, the destination Variant is cleared, like with clear(). Then destination receives an exact copy of the value of this Variant and all of its owned resources (in the case of VT_BSTR, VT_UNKNOWN, VT_DISPATCH and VT_ARRAY). If this Variant is a reference (anything with VT_BYREF), then it is recursively dereferenced, and the corresponding value and its resources are copied. After successful completion, the destination Variant is never a reference. This method is a direct wrapper around the VariantCopyInd Automation function.

Parameters:
destination - the destination Variant to hold the copied value.
Throws:
JAutException - if the underlying VARIANT is not allocated.
ComException - if the VariantCopyInd function fails.
java.lang.OutOfMemoryError - if memory could not be allocated for the copy.

getBoolean

public boolean getBoolean()
Retrives the boolean value in the Variant. The type of the Variant must be VT_BOOL or VT_BOOL|VT_BYREF.

Returns:
the boolean value in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

setBoolean

public void setBoolean(boolean value)
Sets the boolean value in the Variant. The type of the Variant must be VT_BOOL or VT_BOOL|VT_BYREF.

Parameters:
value - the new boolean value.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

getByte

public byte getByte()
Retrives the byte value in the Variant. The type of the Variant must be VT_UI1, VT_I1, VT_UI1|VT_BYREF or VT_I1|VT_BYREF.

Returns:
the byte value in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

setByte

public void setByte(byte value)
Sets the byte value in the Variant. The type of the Variant must be VT_UI1, VT_I1, VT_UI1|VT_BYREF or VT_I1|VT_BYREF.

Parameters:
value - the new byte value.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

getShort

public short getShort()
Retrives the short value in the Variant. The type of the Variant must be VT_I2, VT_UI1, VT_I1|VT_BYREF or VT_UI1|VT_BYREF.

Returns:
the short value in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

setShort

public void setShort(short value)
Sets the short value in the Variant. The type of the Variant must be VT_I2, VT_UI2, VT_I2|VT_BYREF or VT_UI2|VT_BYREF.

Parameters:
value - the new short value.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

getInt

public int getInt()
Retrives the int value in the Variant. The type of the Variant must be VT_I4, VT_UI4, VT_ERROR, VT_INT, VT_UINT, VT_I1|VT_BYREF, VT_UI1|VT_BYREF, VT_ERROR|VT_BYREF, VT_INT|VT_BYREF or VT_UINT|VT_BYREF.

Returns:
the int value in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

setInt

public void setInt(int value)
Sets the int value in the Variant. The type of the Variant must be VT_I4, VT_UI4, VT_ERROR, VT_INT, VT_UINT, VT_I1|VT_BYREF, VT_UI1|VT_BYREF, VT_ERROR|VT_BYREF, VT_INT|VT_BYREF or VT_UINT|VT_BYREF.

Parameters:
value - the new int value.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

getLong

public long getLong()
Retrives the long value in the Variant. The type of the Variant must be VT_CY or VT_CY|VT_BYREF.

Returns:
the long value in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.
See Also:
VT_CY

setLong

public void setLong(long value)
Sets the long value in the Variant. The type of the Variant must be VT_CY or VT_CY|VT_BYREF.

Parameters:
value - the new long value.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.
See Also:
VT_CY

getFloat

public float getFloat()
Retrives the float value in the Variant. The type of the Variant must be VT_R4 or VT_R4|VT_BYREF.

Returns:
the float value in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

setFloat

public void setFloat(float value)
Sets the float value in the Variant. The type of the Variant must be VT_R4 or VT_R4|VT_BYREF.

Parameters:
value - the new float value.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

getDouble

public double getDouble()
Retrives the double value in the Variant. The type of the Variant must be VT_R8, VT_R8|VT_BYREF, VT_DATE or VT_DATE|VT_BYREF. Note, that Win32 dates are stored as doubles in a VARIANT.

Returns:
the double value in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

setDouble

public void setDouble(double value)
Sets the double value in the Variant. The type of the Variant must be VT_R8, VT_R8|VT_BYREF, VT_DATE or VT_DATE|VT_BYREF. Note, that Win32 dates are stored as doubles in a VARIANT.

Parameters:
value - the new double value.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

getString

public java.lang.String getString()
Retrives the String value in the Variant. The type of the Variant must be VT_BSTR or VT_BSTR|VT_BYREF.

Returns:
the String value in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.
java.lang.OutOfMemoryError - if memory could not be allocated for the string.

setString

public void setString(java.lang.String value)
Sets the String value in the Variant. The type of the Variant must be VT_BSTR or VT_BSTR|VT_BYREF.

Parameters:
value - the new String value.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.
java.lang.OutOfMemoryError - if memory could not be allocated for the string.

getDate

public java.util.Date getDate()
Retrives the Date in the Variant. This method performs the neccessary transformation from the Win32 date to the Jave date. The type of the Variant must be VT_DATE, VT_DATE|VT_BYREF, VT_R8 or VT_R8|VT_BYREF.

Returns:
the Date in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.
See Also:
getDouble()

setDate

public void setDate(java.util.Date value)
Sets the Date in the Variant. This method performs the neccessary transformation from the Java date to the Win32 date. The returned object is the correct Java date corresponding to the Win32 date in the VARIANT. The type of the Variant must be VT_DATE, VT_DATE|VT_BYREF, VT_R8 or VT_R8|VT_BYREF.

Parameters:
value - the new Date.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.
See Also:
setDouble(double)

getDispatch

public Dispatch getDispatch()
                     throws ComException
Retrives the Dispatch object in the Variant. The type of the Variant must be VT_DISPATCH, VT_DISPATCH|VT_BYREF, VT_UNKNOWN or VT_UNKNOWN|VT_BYREF. The method invokes QueryInterface to obtain the IDispatch interface when the type of the variant is VT_UNKNOWN or VT_UNKNOWN|VT_BYREF.

Returns:
the Dispatch object in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.
ComException - if the QueryInterface method fails.
java.lang.OutOfMemoryError - if memory could not be allocated for the new object.
See Also:
Dispatch.attach(Variant)

setDispatch

public void setDispatch(Dispatch value)
Sets the Dispatch object in the Variant. The type of the Variant must be VT_DISPATCH, VT_DISPATCH|VT_BYREF, VT_UNKNOWN or VT_UNKNOWN|VT_BYREF.

Parameters:
value - the new Dispatch object, or null.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.

allocateArray

public void allocateArray(int vartype,
                          int[] lowerBounds,
                          int[] elements)
                   throws ComException
Allocates the underlying VARIANT of an array type. First, a new SAFEARRAY is created with the SafeArrayCreate Automation function. Then, if an underlying VARIANT already exists, it is cleared, otherwise a new VARIANT is allocated. Finally, the VARIANT is initialized and the variant type is set to vartype|VT_ARRAY. The created SAFEARRAY is onwed by this Variant.

Parameters:
vartype - the simple datatype of the array. It cannot be VT_EMPTY, VT_NULL, an array (VT_ARRAY) or a reference (VT_BYREF).
lowerBounds - a vector of lower bounds, one for each dimension.
elements - a vector of integers holding the number of elements in each dimension.
Throws:
JAutException - if vartype is not one of allowed simple types, or the bounds of the array is not valid.
ComException - if the VariantClear function fails when clearing the the content of the previous variant.
java.lang.OutOfMemoryError - if the system run out of memory.
See Also:
accessArray()

accessArray

public SafeArray accessArray()
Retrives the SafeArray object in the Variant. The underlying SAFEARRAY structure is always owned by the Variant, the SafeArray object has only access to it. SafeArray locks the SAFEARRAY with the SafeArrayLock Automation function, until SafeArray.release() is called. While the SAFEARRAY is locked, the type of the variant cannot be changed, and the clear() method will fail. The type of the Variant must be an array (VT_ARRAY) or a reference to an array (VT_ARRAY|VT_BYREF).

Returns:
the SafeArray object in the Variant.
Throws:
JAutException - if the underlying VARIANT is not allocated, or it is not of the proper type.
java.lang.OutOfMemoryError - if memory could not be allocated for the new object.
See Also:
SafeArray.attach(Variant), clear()

allocateReference

public void allocateReference(int vartype,
                              Variant target)
                       throws ComException
Allocates the underlying VARIANT of a reference type. If an underlying VARIANT already exists, then it is cleared, otherwise a new VARIANT is allocated. Then the VARIANT is initialized and the variant type is set to vartype. It is the callers responsibility to guarantee that the Variant holding the target data is not released, cleared or its type changed while a reference exists to it.

Parameters:
vartype - the type of the Variant to be allocated. It must be combined with VT_BYREF, it cannot be VT_EMPTY|VT_BYREF, VT_NULL|VT_BYREF, or an array (VT_ARRAY).
target - the Variant holding the data, or a reference to the data, that this Variant will refer to.
Throws:
JAutException - if the underlying VARIANT of the target is not allocated, or if vartype is not one of the allowed types, or it is not compatible with the type of the target Variant.
ComException - if the VariantClear function fails when clearing the the content of the previous variant.
java.lang.OutOfMemoryError - if memory could not be allocated for the VARIANT.

allocateReference

public void allocateReference(int vartype,
                              SafeArray target,
                              int index)
Not implemented yet.


toBoolean

public boolean toBoolean()
                  throws ComException
Coerces the Varian to a VT_BOOL and returns the coerced value.

Returns:
the coerced bool value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags

toByte

public byte toByte()
            throws ComException
Coerces the Varian to a VT_UI1 and returns the coerced value.

Returns:
the coerced byte value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags

toShort

public short toShort()
              throws ComException
Coerces the Varian to a VT_I2 and returns the coerced value.

Returns:
the coerced short value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags

toInt

public int toInt()
          throws ComException
Coerces the Varian to a VT_I4 and returns the coerced value.

Returns:
the coerced int value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags

toLong

public long toLong()
            throws ComException
Coerces the Varian to a VT_CY and returns the coerced value.

Returns:
the coerced currency as a long value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags, VT_CY

toFloat

public float toFloat()
              throws ComException
Coerces the Varian to a VT_R4 and returns the coerced value.

Returns:
the coerced float value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags

toDouble

public double toDouble()
                throws ComException
Coerces the Varian to a VT_R8 and returns the coerced value.

Returns:
the coerced double value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags

toString

public java.lang.String toString()
                          throws ComException
Coerces the Varian to a VT_BSTR and returns the coerced value.

Returns:
the coerced String value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags

toDate

public java.util.Date toDate()
                      throws ComException
Coerces the Varian to a VT_DATE and returns the coerced value.

Returns:
the coerced Data value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags

toDispatch

public Dispatch toDispatch()
                    throws ComException
Coerces the Varian to a VT_DISPATCH and returns the coerced Automation object.

Returns:
the coerced Dispatch value.
Throws:
ComException
See Also:
changeType(org.isis.jaut.Variant, int, int), defaultChangeFlags

toObject

public java.lang.Object toObject()
                          throws ComException
Returns the value of the Variant in a Java object. If the Variant is of a simple datetype or referes to a simple datatype, then a new inmutable Java object is returned of the correspnding type (for example Double for VT_R8). Otherwise, the value is already represented as an Object, and that object is returned. If the type is VT_EMPTY or VT_NULL, then the returned object is null. This method does not work for arrays and Variants of type VT_VARIANT|VT_BYREF.

Returns:
a Java object holding the value of the Variant, it cannot be an array.
Throws:
JAutException - if the underlying VARIANT is not allocated, or cannot be represented as an Object.
ComException - if the Variant is of type VT_UNKNOWN and it cannot be coerced to VT_DISPATCH.
See Also:
Variant(Object)