com.jacob.com
Class Variant

java.lang.Object
  extended by com.jacob.com.JacobObject
      extended by com.jacob.com.Variant
Direct Known Subclasses:
VariantViaEvent

public class Variant
extends JacobObject

The multi-format data type used for all call backs and most communications between Java and COM. It provides a single class that can handle all data types.

Just loading this class creates 3 variants that get added to the ROT

PROPVARIANT introduces new types so eventually Variant will need to be upgraded to support PropVariant types. http://blogs.msdn.com/benkaras/archive/2006/09/13/749962.aspx

This object no longer implements Serializable because serialization is broken (and has been since 2000/xp). The underlying marshalling/unmarshalling code is broken in the JNI layer.


Field Summary
static Variant DEFAULT
          Use this constant for optional parameters
static short VariantArray
          variant's type is array VT_ARRAY 0x2000
static short VariantBoolean
          variant's type is boolean VT_BOOL
static short VariantByref
          variant's type is a reference (to IDispatch?) VT_BYREF 0x4000
static short VariantByte
          variant's type is byte VT_UI1
static short VariantCurrency
          variant's type is currency VT_CY
static short VariantDate
          variant's type is date VT_DATE
static short VariantDecimal
          variant's type is object VT_DECIMAL
static short VariantDispatch
          variant's type is dispatch VT_DISPATCH
static short VariantDouble
          variant's type is double VT_R8
static short VariantEmpty
          variant's type is empty : equivalent to VB Nothing and VT_EMPTY
static short VariantError
          variant's type is error VT_ERROR
static short VariantFloat
          variant's type is float VT_R4
static short VariantInt
          variant's type is int VT_I4, a Long in VC
static short VariantLongInt
          variant's type is 64 bit long integer VT_I8 - not yet implemented in Jacob because we have to decide what to do with Currency and because its only supported on XP and later.
static short VariantNull
          variant's type is null : equivalent to VB Null and VT_NULL
static short VariantObject
          variant's type is object VT_UNKNOWN
static short VariantPointer
          This value is for reference only and is not to be used by any callers
static short VariantShort
          variant's type is short VT_I2
static short VariantString
          variant's type is string also known as VT_BSTR
static short VariantTypeMask
          what is this? VT_TYPEMASK && VT_BSTR_BLOB 0xfff
static short VariantVariant
          variant's type is variant it encapsulate another variant VT_VARIANT
static Variant VT_FALSE
          Use for true/false variant parameters
static Variant VT_MISSING
          Same than DEFAULT
static Variant VT_TRUE
          Use for true/false variant parameters
 
Constructor Summary
Variant()
          public constructor, initializes and sets type to VariantEmpty
Variant(boolean in)
          Constructor that accepts a primitive rather than an object
Variant(byte in)
          Constructor that accepts a primitive rather than an object
Variant(double in)
          Constructor that accepts a primitive rather than an object
Variant(float in)
          Constructor that accepts a primitive rather than an object
Variant(int in)
          Constructor that accepts a primitive rather than an object
Variant(long in)
          Constructor that accepts a primitive rather than an object
Variant(Object in)
          Convenience constructor that calls the main one with a byRef value of false
Variant(Object pValueObject, boolean fByRef)
          Constructor that accepts the data object and information about whether this is by reference or not.
Variant(short in)
          Constructor that accepts a primitive rather than an object
 
Method Summary
 Variant changeType(short in)
          Cover for native method so we can cover it.
 Object clone()
          this returns null
 Variant cloneIndirect()
          Deprecated. No longer used
protected  void finalize()
           
 boolean getBoolean()
           
 boolean getBooleanRef()
          public cover for native method
 byte getByte()
           
 byte getByteRef()
          public cover for native method
 Currency getCurrency()
          MS Currency objects are 64 bit fixed point numbers with 15 digits to the left and 4 to the right of the decimal place.
 Currency getCurrencyRef()
          MS Currency objects are 64 bit fixed point numbers with 15 digits to the left and 4 to the right of the decimal place.
 double getDate()
           
 double getDateRef()
           
 BigDecimal getDecimal()
          return the BigDecimal value held in this variant (fails on other types)
 BigDecimal getDecimalRef()
          return the BigDecimal value held in this variant (fails on other types)
 Dispatch getDispatch()
          cover for toDispatch() This method now matches other getXXX() methods.
 Dispatch getDispatchRef()
          Dispatch and dispatchRef are treated the same This is just a cover for toDispatch() with a flag check
 double getDouble()
           
 double getDoubleRef()
           
 void getEmpty()
          Deprecated. method never did anything
 int getError()
           
 int getErrorRef()
           
 float getFloat()
           
 float getFloatRef()
           
 int getInt()
          return the int value held in this variant if it is an int or a short.
 int getIntRef()
          get the content of this variant as an int
 Date getJavaDate()
          returns the windows time contained in this Variant to a Java Date.
 Date getJavaDateRef()
          returns the windows time contained in this Variant to a Java Date should return null if this is not a date reference Variant SF 959382
 long getLong()
          64 bit Longs only available on x64.
 long getLongRef()
          64 bit Longs only available on x64.
 void getNull()
          Deprecated. method never did anything
 short getShort()
          return the int value held in this variant (fails on other types?)
 short getShortRef()
          get the content of this variant as an int
 String getString()
           
 String getStringRef()
          gets the content of the variant as a string ref
 Object getVariant()
          Used to get the value from a windows type of VT_VARIANT or a jacob Variant type of VariantVariant.
 Variant[] getVariantArray()
          Deprecated. superseded by SafeArray
 Variant[] getVariantArrayRef()
          Deprecated. superseded by SafeArray
 short getvt()
          Reports the type of the underlying Variant object
protected  void init()
          initializes the COM Variant and puts its reference in this instance
 boolean isNull()
           
 void noParam()
          Deprecated. replaced by putNoParam()
protected  boolean objectIsAConstant(Variant pVariant)
          returns true if the passed in Variant is a constant that should not be freed
 void putBoolean(boolean in)
          puts a boolean into the variant and sets it's type
 void putBooleanRef(boolean in)
          pushes a boolean into the variant by ref and sets the type of the variant to boolean
 void putByte(byte in)
          pushes a byte into the varaint and sets the type
 void putByteArray(Object in)
          Deprecated. superseded by SafeArray
 void putByteRef(byte in)
          pushes a byte into the variant by ref and sets the type
 void putCharArray(Object in)
          Deprecated. superseded by SafeArray
 void putCurrency(Currency in)
          Puts a value in as a currency and sets the variant type.
 void putCurrencyRef(Currency in)
          Pushes a long into the variant as currency and sets the type.
 void putDate(Date inDate)
          converts a java date to a windows time and calls putDate(double) SF 959382
 void putDate(double in)
          puts a windows date double into the variant and sets the type
 void putDateRef(Date inDate)
          converts a java date to a windows time and calls putDateRef(double) SF 959382
 void putDateRef(double in)
          set the content of this variant to a date (VT_DATE|VT_BYREF)
 void putDecimal(BigDecimal in)
          EXPERIMENTAL 1.14 feature to support rounded decimals.
 void putDecimalRef(BigDecimal in)
          Set the value of this variant and set the type.
 void putDispatch(Dispatch in)
          This acts a cover for putVariant Dispatch.
 void putDispatchRef(Dispatch in)
          Dispatch and dispatchRef are treated the same This is a cover for putVariantDispatch().
 void putDouble(double in)
          wraps this Variant around the passed in double.
 void putDoubleRef(double in)
          set the content of this variant to a double (VT_R8|VT_BYREF)
 void putEmpty()
          sets the type to VariantEmpty
 void putError(int in)
          puts an error code (I think) into the variant and sets the type
 void putErrorRef(int in)
          pushes an error code into the variant by ref and sets the type
 void putFloat(float in)
          fills the Variant with a float and sets the type to float
 void putFloatRef(float in)
          pushes a float into the variant and sets the type
 void putInt(int in)
          set the value of this variant and set the type
 void putIntRef(int in)
          set the content of this variant to an int (VT_I4|VT_BYREF)
 void putLong(long in)
          Puts a 64 bit Java Long into a 64 bit Variant Long.
 void putLongRef(long in)
          Puts a 64 bit Java Long into a 64 bit Variant Long.
 void putNoParam()
          sets the type to VT_ERROR and the error message to DISP_E_PARAMNOTFOIUND
 void putNothing()
          Sets the type to VariantDispatch and sets the value to null Equivalent to VB's nothing
 void putNull()
          Set this Variant's type to VT_NULL (the VB equivalent of NULL)
 void putObject(Object in)
          Deprecated. should use putDispatch()
 void putObjectRef(Object in)
          Deprecated.  
 void putSafeArray(SafeArray in)
          have no idea...
 void putSafeArrayRef(SafeArray in)
          have no idea...
 void putShort(short in)
          set the content of this variant to a short (VT_I2)
 void putShortRef(short in)
          set the content of this variant to a short (VT_I2|VT_BYREF)
 void putString(String in)
          put a string into the variant and set its type
 void putStringRef(String in)
          set the content of this variant to a string (VT_BSTR|VT_BYREF)
 void putVariant(Object objectToBeWrapped)
          Puts a variant into this variant making it type VT_VARIANT.
 void putVariantArray(Variant[] in)
          Deprecated. superseded by SafeArray
 void putVariantArrayRef(Variant[] in)
          Deprecated. superseded by SafeArray
 void safeRelease()
          This will release the "C" memory for the Variant unless this Variant is one of the constants in which case we don't want to release the memory.
protected  void SerializationReadFromBytes(byte[] ba)
          this is supposed to cause the underlying variant object struct to be rebuilt from a previously serialized byte array.
protected  byte[] SerializationWriteToBytes()
          this is supposed to create a byte array that represents the underlying variant object structure
 boolean toBoolean()
          Deprecated. should be replaced by changeType() followed by getBoolean()
 byte toByte()
          Deprecated. should be replaced by changeType() followed by getByte()
 Object toByteArray()
          Deprecated. superseded by SafeArray
 Object toCharArray()
          Deprecated. superseded by SafeArray
 Currency toCurrency()
          Deprecated. should be replaced by changeType() followed by getCurrency
 double toDate()
          Deprecated. should use changeType() followed by getDate()
 Dispatch toDispatch()
           
 double toDouble()
          Deprecated. should call changeType() then getDouble()
 EnumVariant toEnumVariant()
           
 int toError()
          Deprecated. should use changeType() followed by getError()
 float toFloat()
          Deprecated. should use changeType() and getFloat() instead
 int toInt()
          Deprecated. should use changeType() followed by getInt()
 Date toJavaDate()
          Deprecated. callers should use getDate()
 Object toJavaObject()
          Convert a JACOB Variant value to a Java object (type conversions).
 Object toObject()
          Deprecated. this is a cover for toDispatch();
 SafeArray toSafeArray()
          By default toSafeArray makes a deep copy due to the fact that this Variant owns the embedded SafeArray and will destroy it when it gc's calls toSafeArray(true).
 SafeArray toSafeArray(boolean deepCopy)
          This lets folk turn into a safe array without a deep copy.
 Object toScriptObject()
          Deprecated.  
 short toShort()
          Deprecated. callers should use changeType() followed by getShort()
 String toString()
          This method now correctly implements java toString() semantics Attempts to return the content of this variant as a string "not initialized" if not initialized "null" if VariantEmpty, "null" if VariantError "null" if VariantNull the value if we know how to describe one of that type three question marks if can't convert
 Variant toVariant()
          Deprecated. superseded by "this"
 Variant[] toVariantArray()
          Deprecated. superseded by SafeArray
 void VariantClear()
          Clear the content of this variant
 
Methods inherited from class com.jacob.com.JacobObject
debug, getBuildDate, getBuildVersion, isDebugEnabled
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT

public static final Variant DEFAULT
Use this constant for optional parameters


VT_MISSING

public static final Variant VT_MISSING
Same than DEFAULT


VT_TRUE

public static final Variant VT_TRUE
Use for true/false variant parameters


VT_FALSE

public static final Variant VT_FALSE
Use for true/false variant parameters


VariantEmpty

public static final short VariantEmpty
variant's type is empty : equivalent to VB Nothing and VT_EMPTY

See Also:
Constant Field Values

VariantNull

public static final short VariantNull
variant's type is null : equivalent to VB Null and VT_NULL

See Also:
Constant Field Values

VariantShort

public static final short VariantShort
variant's type is short VT_I2

See Also:
Constant Field Values

VariantInt

public static final short VariantInt
variant's type is int VT_I4, a Long in VC

See Also:
Constant Field Values

VariantFloat

public static final short VariantFloat
variant's type is float VT_R4

See Also:
Constant Field Values

VariantDouble

public static final short VariantDouble
variant's type is double VT_R8

See Also:
Constant Field Values

VariantCurrency

public static final short VariantCurrency
variant's type is currency VT_CY

See Also:
Constant Field Values

VariantDate

public static final short VariantDate
variant's type is date VT_DATE

See Also:
Constant Field Values

VariantString

public static final short VariantString
variant's type is string also known as VT_BSTR

See Also:
Constant Field Values

VariantDispatch

public static final short VariantDispatch
variant's type is dispatch VT_DISPATCH

See Also:
Constant Field Values

VariantError

public static final short VariantError
variant's type is error VT_ERROR

See Also:
Constant Field Values

VariantBoolean

public static final short VariantBoolean
variant's type is boolean VT_BOOL

See Also:
Constant Field Values

VariantVariant

public static final short VariantVariant
variant's type is variant it encapsulate another variant VT_VARIANT

See Also:
Constant Field Values

VariantObject

public static final short VariantObject
variant's type is object VT_UNKNOWN

See Also:
Constant Field Values

VariantDecimal

public static final short VariantDecimal
variant's type is object VT_DECIMAL

See Also:
Constant Field Values

VariantByte

public static final short VariantByte
variant's type is byte VT_UI1

See Also:
Constant Field Values

VariantLongInt

public static final short VariantLongInt
variant's type is 64 bit long integer VT_I8 - not yet implemented in Jacob because we have to decide what to do with Currency and because its only supported on XP and later. No win2k, NT or 2003 server.

See Also:
Constant Field Values

VariantPointer

public static final short VariantPointer
This value is for reference only and is not to be used by any callers

See Also:
Constant Field Values

VariantTypeMask

public static final short VariantTypeMask
what is this? VT_TYPEMASK && VT_BSTR_BLOB 0xfff

See Also:
Constant Field Values

VariantArray

public static final short VariantArray
variant's type is array VT_ARRAY 0x2000

See Also:
Constant Field Values

VariantByref

public static final short VariantByref
variant's type is a reference (to IDispatch?) VT_BYREF 0x4000

See Also:
Constant Field Values
Constructor Detail

Variant

public Variant()
public constructor, initializes and sets type to VariantEmpty


Variant

public Variant(boolean in)
Constructor that accepts a primitive rather than an object

Parameters:
in -

Variant

public Variant(byte in)
Constructor that accepts a primitive rather than an object

Parameters:
in -

Variant

public Variant(double in)
Constructor that accepts a primitive rather than an object

Parameters:
in -

Variant

public Variant(float in)
Constructor that accepts a primitive rather than an object

Parameters:
in -

Variant

public Variant(int in)
Constructor that accepts a primitive rather than an object

Parameters:
in -

Variant

public Variant(long in)
Constructor that accepts a primitive rather than an object

Parameters:
in -

Variant

public Variant(Object in)
Convenience constructor that calls the main one with a byRef value of false

Parameters:
in - object to be made into variant

Variant

public Variant(Object pValueObject,
               boolean fByRef)
Constructor that accepts the data object and information about whether this is by reference or not. It calls the JavaVariantConverter to actually push the data into the newly created Variant.

Parameters:
pValueObject - The value object that will pushed down into windows memory. A null object sets this to "empty"
fByRef -

Variant

public Variant(short in)
Constructor that accepts a primitive rather than an object

Parameters:
in -
Method Detail

changeType

public Variant changeType(short in)
Cover for native method so we can cover it.

This cannot convert an object to a byRef. It can convert from byref to not byref

Parameters:
in - type to convert this variant too
Returns:
Variant returns this same object so folks can change when replacing calls toXXX() with changeType().getXXX()

clone

public Object clone()
this returns null

Overrides:
clone in class Object
Returns:
?? comment says null?

cloneIndirect

@Deprecated
public Variant cloneIndirect()
Deprecated. No longer used

Returns:
null !

finalize

protected void finalize()
Overrides:
finalize in class Object

getBoolean

public boolean getBoolean()
Returns:
returns the value as a boolean, throws an exception if its not.
Throws:
IllegalStateException - if variant is not of the requested type

getBooleanRef

public boolean getBooleanRef()
public cover for native method

Returns:
the boolean from a booleanRef
Throws:
IllegalStateException - if variant is not of the requested type

getByte

public byte getByte()
Returns:
returns the value as a boolean, throws an exception if its not.
Throws:
IllegalStateException - if variant is not of the requested type

getByteRef

public byte getByteRef()
public cover for native method

Returns:
the byte from a booleanRef
Throws:
IllegalStateException - if variant is not of the requested type

getCurrency

public Currency getCurrency()
MS Currency objects are 64 bit fixed point numbers with 15 digits to the left and 4 to the right of the decimal place.

Returns:
returns the currency value as a long, throws exception if not a currency type..
Throws:
IllegalStateException - if variant is not of the requested type

getCurrencyRef

public Currency getCurrencyRef()
MS Currency objects are 64 bit fixed point numbers with 15 digits to the left and 4 to the right of the decimal place.

Returns:
returns the currency value as a long, throws exception if not a currency type
Throws:
IllegalStateException - if variant is not of the requested type

getDate

public double getDate()
Returns:
double return the date (as a double) value held in this variant (fails on other types?)
Throws:
IllegalStateException - if variant is not of the requested type

getDateRef

public double getDateRef()
Returns:
returns the date value as a double, throws exception if not a date type
Throws:
IllegalStateException - if variant is not of the requested type

getDecimal

public BigDecimal getDecimal()
return the BigDecimal value held in this variant (fails on other types)

Returns:
BigDecimal
Throws:
IllegalStateException - if variant is not of the requested type

getDecimalRef

public BigDecimal getDecimalRef()
return the BigDecimal value held in this variant (fails on other types)

Returns:
BigDecimal
Throws:
IllegalStateException - if variant is not of the requested type

getDispatch

public Dispatch getDispatch()
cover for toDispatch() This method now matches other getXXX() methods. It throws an IllegalStateException if the object is not of type VariantDispatch

Returns:
this object as a dispatch
Throws:
IllegalStateException - if wrong variant type

getDispatchRef

public Dispatch getDispatchRef()
Dispatch and dispatchRef are treated the same This is just a cover for toDispatch() with a flag check

Returns:
the results of toDispatch()
Throws:
IllegalStateException - if variant is not of the requested type

getDouble

public double getDouble()
Returns:
double return the double value held in this variant (fails on other types?)
Throws:
IllegalStateException - if variant is not of the requested type

getDoubleRef

public double getDoubleRef()
Returns:
returns the double value, throws exception if not a Double type
Throws:
IllegalStateException - if variant is not of the requested type

getEmpty

@Deprecated
public void getEmpty()
Deprecated. method never did anything

Pointless method that was put here so that putEmpty() has a get method. This would have returned null if the value was VT_EMPTY or if it wasn't so it would have always returned the same value.


getError

public int getError()
Returns:
double return the error value held in this variant (fails on other types?)
Throws:
IllegalStateException - if variant is not of the requested type

getErrorRef

public int getErrorRef()
Returns:
returns the error value as an int, throws exception if not a Error type
Throws:
IllegalStateException - if variant is not of the requested type

getFloat

public float getFloat()
Returns:
returns the value as a float if the type is of type float
Throws:
IllegalStateException - if variant is not of the requested type

getFloatRef

public float getFloatRef()
Returns:
returns the float value, throws exception if not a Float type
Throws:
IllegalStateException - if variant is not of the requested type

getInt

public int getInt()
return the int value held in this variant if it is an int or a short. Throws for other types.

Returns:
int contents of the windows memory
Throws:
IllegalStateException - if variant is not of the requested type

getIntRef

public int getIntRef()
get the content of this variant as an int

Returns:
int
Throws:
IllegalStateException - if variant is not of the requested type

getJavaDate

public Date getJavaDate()
returns the windows time contained in this Variant to a Java Date. should return null if this is not a date Variant SF 959382

Returns:
java.util.Date returns the date if this is a VariantDate != 0, null if it is a VariantDate == 0 and throws an IllegalStateException if this isn't a date.
Throws:
IllegalStateException - if variant is not of the requested type

getJavaDateRef

public Date getJavaDateRef()
returns the windows time contained in this Variant to a Java Date should return null if this is not a date reference Variant SF 959382

Returns:
java.util.Date

getLong

public long getLong()
64 bit Longs only available on x64. 64 bit long support added 1.14

Returns:
returns the value as a long, throws exception if not a Long type..
Throws:
IllegalStateException - if variant is not of the requested type

getLongRef

public long getLongRef()
64 bit Longs only available on x64. 64 bit long support added 1.14

Returns:
returns the value as a long, throws exception if not a long type
Throws:
IllegalStateException - if variant is not of the requested type

getNull

@Deprecated
public void getNull()
Deprecated. method never did anything

This method would have returned null if the type was VT_NULL. But because we return null if the data is not of the right type, this method should have always returned null


getShort

public short getShort()
return the int value held in this variant (fails on other types?)

Returns:
int
Throws:
IllegalStateException - if variant is not of the requested type

getShortRef

public short getShortRef()
get the content of this variant as an int

Returns:
int
Throws:
IllegalStateException - if variant is not of the requested type

getString

public String getString()
Returns:
string contents of the variant.
Throws:
IllegalStateException - if this variant is not of type String

getStringRef

public String getStringRef()
gets the content of the variant as a string ref

Returns:
String retrieved from the COM area.
Throws:
IllegalStateException - if variant is not of the requested type

getVariant

public Object getVariant()
Used to get the value from a windows type of VT_VARIANT or a jacob Variant type of VariantVariant. Added 1.12 pre 6 - VT_VARIANT support is at an alpha level

Returns:
Object a java Object that represents the content of the enclosed Variant

getVariantArray

@Deprecated
public Variant[] getVariantArray()
Deprecated. superseded by SafeArray

Returns:
never returns anything
Throws:
NotImplementedException

getVariantArrayRef

@Deprecated
public Variant[] getVariantArrayRef()
Deprecated. superseded by SafeArray

Returns:
the Variant Array that represents the data in the Variant
Throws:
NotImplementedException

getvt

public short getvt()
Reports the type of the underlying Variant object

Returns:
returns the variant type as a short, one of the Variantxxx values defined as statics in this class. returns VariantNull if not initialized
Throws:
IllegalStateException - if there is no underlying windows data structure

init

protected void init()
initializes the COM Variant and puts its reference in this instance


isNull

public boolean isNull()
Returns:
returns true if the variant is considered null
Throws:
IllegalStateException - if there is no underlying windows memory

noParam

@Deprecated
public void noParam()
Deprecated. replaced by putNoParam()

sets the type to VT_ERROR and the error message to DISP_E_PARAMNOTFOIUND


objectIsAConstant

protected boolean objectIsAConstant(Variant pVariant)
returns true if the passed in Variant is a constant that should not be freed

Parameters:
pVariant -
Returns:
boolean that is true if Variant is a type of constant, VT_FALSE, VT_TRUE, VT_MISSING, DEFAULT

putBoolean

public void putBoolean(boolean in)
puts a boolean into the variant and sets it's type

Parameters:
in - the new value

putBooleanRef

public void putBooleanRef(boolean in)
pushes a boolean into the variant by ref and sets the type of the variant to boolean

Parameters:
in -

putByte

public void putByte(byte in)
pushes a byte into the varaint and sets the type

Parameters:
in -

putByteArray

@Deprecated
public void putByteArray(Object in)
Deprecated. superseded by SafeArray

Parameters:
in - doesn't matter because this method does nothing
Throws:
NotImplementedException

putByteRef

public void putByteRef(byte in)
pushes a byte into the variant by ref and sets the type

Parameters:
in -

putCharArray

@Deprecated
public void putCharArray(Object in)
Deprecated. superseded by SafeArray

Parameters:
in - the object that would be wrapped by the Variant if this method was implemented
Throws:
NotImplementedException

putCurrency

public void putCurrency(Currency in)
Puts a value in as a currency and sets the variant type. MS Currency objects are 64 bit fixed point numbers with 15 digits to the left and 4 to the right of the decimal place.

Parameters:
in - the long that will be put into the 64 bit currency object.

putCurrencyRef

public void putCurrencyRef(Currency in)
Pushes a long into the variant as currency and sets the type. MS Currency objects are 64 bit fixed point numbers with 15 digits to the left and 4 to the right of the decimal place.

Parameters:
in - the long that will be put into the 64 bit currency object

putDate

public void putDate(Date inDate)
converts a java date to a windows time and calls putDate(double) SF 959382

Parameters:
inDate - a Java date to be converted
Throws:
IllegalArgumentException - if inDate = null

putDate

public void putDate(double in)
puts a windows date double into the variant and sets the type

Parameters:
in -

putDateRef

public void putDateRef(Date inDate)
converts a java date to a windows time and calls putDateRef(double) SF 959382

Parameters:
inDate - a Java date to be converted
Throws:
IllegalArgumentException - if inDate = null

putDateRef

public void putDateRef(double in)
set the content of this variant to a date (VT_DATE|VT_BYREF)

Parameters:
in -

putDecimal

public void putDecimal(BigDecimal in)
EXPERIMENTAL 1.14 feature to support rounded decimals.

Set the value of this variant and set the type. This may throw exceptions more often than the caller expects because most callers don't manage the scale of their BigDecimal objects.

This default set method throws exceptions if precision or size is out of bounds

There are 12 bytes available for the integer number.

There is 1 byte for the scale.

Parameters:
in - the BigDecimal that will be converted to VT_DECIMAL
Throws:
IllegalArgumentException - if the scale is > 28, the maximum for VT_DECIMAL or if there are more than 12 bytes worth the digits

putDecimalRef

public void putDecimalRef(BigDecimal in)
Set the value of this variant and set the type. This may throw exceptions more often than the caller expects because most callers don't manage the scale of their BigDecimal objects.

This default set method throws exceptions if precision or size is out of bounds

There are 12 bytes available for the integer number.

There is 1 byte for the scale.

Parameters:
in - the BigDecimal that will be converted to VT_DECIMAL
Throws:
IllegalArgumentException - if the scale is > 28, the maximum for VT_DECIMAL or if there are more than 12 bytes worth the digits

putDispatch

public void putDispatch(Dispatch in)
This acts a cover for putVariant Dispatch.

Parameters:
in - the Dispatch we're putting down in the COM variant space.

putDispatchRef

public void putDispatchRef(Dispatch in)
Dispatch and dispatchRef are treated the same This is a cover for putVariantDispatch(). putDispatch and putDispatchRef are treated the same because no one has written the COM code for putDispatchRef.

Parameters:
in - the Dispatch we're putting down in the COM variant space.

putDouble

public void putDouble(double in)
wraps this Variant around the passed in double.

Parameters:
in -

putDoubleRef

public void putDoubleRef(double in)
set the content of this variant to a double (VT_R8|VT_BYREF)

Parameters:
in -

putEmpty

public void putEmpty()
sets the type to VariantEmpty


putError

public void putError(int in)
puts an error code (I think) into the variant and sets the type

Parameters:
in -

putErrorRef

public void putErrorRef(int in)
pushes an error code into the variant by ref and sets the type

Parameters:
in -

putFloat

public void putFloat(float in)
fills the Variant with a float and sets the type to float

Parameters:
in -

putFloatRef

public void putFloatRef(float in)
pushes a float into the variant and sets the type

Parameters:
in -

putInt

public void putInt(int in)
set the value of this variant and set the type

Parameters:
in -

putIntRef

public void putIntRef(int in)
set the content of this variant to an int (VT_I4|VT_BYREF)

Parameters:
in -

putLong

public void putLong(long in)
Puts a 64 bit Java Long into a 64 bit Variant Long. Only works on x64 systems otherwise throws an error. 64 bit long support added 1.14

Parameters:
in - the long that will be put into the 64 bit Long object.

putLongRef

public void putLongRef(long in)
Puts a 64 bit Java Long into a 64 bit Variant Long. Only works on x64 systems otherwise throws an error. 64 bit long support added 1.14

Parameters:
in - the long that will be put into the 64 bit Long object.

putNoParam

public void putNoParam()
sets the type to VT_ERROR and the error message to DISP_E_PARAMNOTFOIUND


putNothing

public void putNothing()
Sets the type to VariantDispatch and sets the value to null Equivalent to VB's nothing


putNull

public void putNull()
Set this Variant's type to VT_NULL (the VB equivalent of NULL)


putObject

@Deprecated
public void putObject(Object in)
Deprecated. should use putDispatch()

Puts an object into the Variant -- converts to Dispatch. Acts as a cover for putVariantDispatch(); This primarily exists to support jacobgen. This should be deprecated.

Parameters:
in - the object we are putting into the Variant, assumes a
See Also:
putDispatch(Dispatch)

putObjectRef

@Deprecated
public void putObjectRef(Object in)
Deprecated. 

Just a cover for putObject(). We shouldn't accept any old random object. This has been left in to support jacobgen. This should be deprecated.

Parameters:
in -

putSafeArray

public void putSafeArray(SafeArray in)
have no idea...

Parameters:
in -

putSafeArrayRef

public void putSafeArrayRef(SafeArray in)
have no idea...

Parameters:
in -

putShort

public void putShort(short in)
set the content of this variant to a short (VT_I2)

Parameters:
in -

putShortRef

public void putShortRef(short in)
set the content of this variant to a short (VT_I2|VT_BYREF)

Parameters:
in -

putString

public void putString(String in)
put a string into the variant and set its type

Parameters:
in -

putStringRef

public void putStringRef(String in)
set the content of this variant to a string (VT_BSTR|VT_BYREF)

Parameters:
in -

putVariant

public void putVariant(Object objectToBeWrapped)
Puts a variant into this variant making it type VT_VARIANT. Added 1.12 pre 6

Parameters:
objectToBeWrapped - A object that is to be referenced by this variant. If objectToBeWrapped is already of type Variant, then it is used. If objectToBeWrapped is not Variant then new Variant(objectToBeWrapped) is called and the result is passed into the com layer
Throws:
IllegalArgumentException - if inVariant = null or if inVariant is a Varint

putVariantArray

@Deprecated
public void putVariantArray(Variant[] in)
Deprecated. superseded by SafeArray

Parameters:
in - doesn't matter because this method does nothing
Throws:
NotImplementedException

putVariantArrayRef

@Deprecated
public void putVariantArrayRef(Variant[] in)
Deprecated. superseded by SafeArray

Parameters:
in - the thing that would be come an array if this method was implemented
Throws:
NotImplementedException

safeRelease

public void safeRelease()
This will release the "C" memory for the Variant unless this Variant is one of the constants in which case we don't want to release the memory.

Overrides:
safeRelease in class JacobObject
See Also:
JacobObject.safeRelease()

SerializationReadFromBytes

protected void SerializationReadFromBytes(byte[] ba)
this is supposed to cause the underlying variant object struct to be rebuilt from a previously serialized byte array.

Parameters:
ba -

SerializationWriteToBytes

protected byte[] SerializationWriteToBytes()
this is supposed to create a byte array that represents the underlying variant object structure


toBoolean

@Deprecated
public boolean toBoolean()
Deprecated. should be replaced by changeType() followed by getBoolean()

Returns:
the value of this variant as boolean (after possible conversion)

toByte

@Deprecated
public byte toByte()
Deprecated. should be replaced by changeType() followed by getByte()

attempts to return the content of this variant as a double (after possible conversion)

Returns:
byte

toByteArray

@Deprecated
public Object toByteArray()
Deprecated. superseded by SafeArray

Returns:
nothing because this method is not implemented
Throws:
NotImplementedException

toCharArray

@Deprecated
public Object toCharArray()
Deprecated. superseded by SafeArray

Returns:
never returns anything
Throws:
NotImplementedException

toCurrency

@Deprecated
public Currency toCurrency()
Deprecated. should be replaced by changeType() followed by getCurrency

Returns:
the content of this variant as a long representing a monetary amount

toDate

@Deprecated
public double toDate()
Deprecated. should use changeType() followed by getDate()

Returns:
the value of this variant as a date (after possible conversion)

toDispatch

public Dispatch toDispatch()
Returns:
the content of this variant as a Dispatch object (after possible conversion)

toDouble

@Deprecated
public double toDouble()
Deprecated. should call changeType() then getDouble()

Returns:
the content of this variant as a double (after possible conversion)

toEnumVariant

public EnumVariant toEnumVariant()
Returns:
the value of this variant as an enumeration (java style)

toError

@Deprecated
public int toError()
Deprecated. should use changeType() followed by getError()

converts to an error type and returns the error

Returns:
the error as an int (after conversion)

toFloat

@Deprecated
public float toFloat()
Deprecated. should use changeType() and getFloat() instead

attempts to return the contents of this variant as a float (after possible conversion)

Returns:
float

toInt

@Deprecated
public int toInt()
Deprecated. should use changeType() followed by getInt()

Returns:
the value of this variant as an int (after possible conversion)

toJavaDate

@Deprecated
public Date toJavaDate()
Deprecated. callers should use getDate()

Returns the windows time contained in this Variant as a Java Date converts to a date like many of the other toXXX() methods SF 959382.

This method added 12/2005 for possible use by jacobgen instead of its conversion code

This does not convert the data

Returns:
java.util.Date version of this variant if it is a date, otherwise null

toJavaObject

public Object toJavaObject()
                    throws JacobException
Convert a JACOB Variant value to a Java object (type conversions). provided in Sourceforge feature request 959381. See JavaVariantConverter..convertVariantTJavaObject(Variant) for more information.

Returns:
Corresponding Java object of the type matching the Variant type.
Throws:
IllegalStateException - if no underlying windows data structure
NotImplementedException - if unsupported conversion is requested
JacobException - if the calculated result was a JacobObject usually as a result of error

toObject

@Deprecated
public Object toObject()
Deprecated. this is a cover for toDispatch();

Acts a a cover for toDispatch. This primarily exists to support jacobgen.

Returns:
Object returned by toDispatch()
See Also:
instead

toSafeArray

public SafeArray toSafeArray()
By default toSafeArray makes a deep copy due to the fact that this Variant owns the embedded SafeArray and will destroy it when it gc's calls toSafeArray(true).

Returns:
the object converted to a SafeArray

toSafeArray

public SafeArray toSafeArray(boolean deepCopy)
This lets folk turn into a safe array without a deep copy. Should this API be public?

Parameters:
deepCopy -
Returns:
SafeArray constructed

toScriptObject

@Deprecated
public Object toScriptObject()
Deprecated. 

I don't know what this is. Is it some legacy (pre 1.8) thing?

Returns:
this object as a dispatch object by calling toDispatch()

toShort

@Deprecated
public short toShort()
Deprecated. callers should use changeType() followed by getShort()

attempts to return the contents of this Variant as a short (after possible conversion)

Returns:
short

toString

public String toString()
This method now correctly implements java toString() semantics Attempts to return the content of this variant as a string

toVariant

@Deprecated
public Variant toVariant()
Deprecated. superseded by "this"

Exists to support jacobgen. This would be deprecated if it weren't for jacobgen

Returns:
this same object

toVariantArray

@Deprecated
public Variant[] toVariantArray()
Deprecated. superseded by SafeArray

Returns:
nothing because this method is not implemented
Throws:
NotImplementedException

VariantClear

public void VariantClear()
Clear the content of this variant



http://jacob-project.sourceforge.net