variant.java

Very Nice library for using ActiveX controls directly from java without heavy knowledge of JNI, simp

	 * 
	 * @param in
	 *            the new value
	 */
	public void putBoolean(boolean in) {
		// verify we aren't released yet
		getvt();
		putVariantBoolean(in);
	}

	private native void putVariantByte(byte in);

	/**
	 * pushes a byte into the varaint and sets the type
	 * 
	 * @param in
	 */
	public void putByte(byte in) {
		// verify we aren't released yet
		getvt();
		putVariantByte(in);
	}

	/**
	 * converts to an error type and returns the error
	 * 
	 * @deprecated should use changeType() followed by getError()
	 * @return the error as an int (after conversion)
	 */
	@Deprecated
	public int toError() {
		changeType(Variant.VariantError);
		return getError();
	}

	/**
	 * Acts a a cover for toDispatch. This primarily exists to support jacobgen.
	 * 
	 * @deprecated this is a cover for toDispatch();
	 * @return Object returned by toDispatch()
	 * @see Variant#toDispatch() instead
	 */
	@Deprecated
	public Object toObject() {
		return toDispatch();
	}

	/**
	 * 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.
	 * 
	 * @deprecated method never did anything
	 */
	@Deprecated
	public void getEmpty() {
	};

	/**
	 * Sets the type to VariantEmpty. No values needed
	 */
	private native void putVariantEmpty();

	/**
	 * sets the type to VariantEmpty
	 * 
	 */
	public void putEmpty() {
		// verify we aren't released yet
		getvt();
		putVariantEmpty();
	}

	/**
	 * Sets the type to VariantDispatch and sets the value to null Equivalent to
	 * VB's nothing
	 */
	private native void putVariantNothing();

	/**
	 * Sets the type to VariantDispatch and sets the value to null Equivalent to
	 * VB's nothing
	 */
	public void putNothing() {
		// verify we aren't released yet
		getvt();
		putVariantNothing();
	}

	private native int getVariantError();

	/**
	 * @return double return the error value held in this variant (fails on
	 *         other types?)
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public int getError() {
		if (this.getvt() == VariantError) {
			return getVariantError();
		} else {
			throw new IllegalStateException(
					"getError() only legal on Variants of type VariantError, not "
							+ this.getvt());
		}
	}

	private native void putVariantError(int in);

	/**
	 * puts an error code (I think) into the variant and sets the type
	 * 
	 * @param in
	 */
	public void putError(int in) {
		// verify we aren't released yet
		getvt();
		putVariantError(in);
	}

	private native double getVariantDouble();

	/**
	 * @return double return the double value held in this variant (fails on
	 *         other types?)
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public double getDouble() {
		if (this.getvt() == VariantDouble) {
			return getVariantDouble();
		} else {
			throw new IllegalStateException(
					"getDouble() only legal on Variants of type VariantDouble, not "
							+ this.getvt());
		}
	}

	private native void putVariantCurrency(long 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.
	 * 
	 * @param in
	 *            the long that will be put into the 64 bit currency object.
	 */
	public void putCurrency(long in) {
		// verify we aren't released yet
		getvt();
		putVariantCurrency(in);
	}

	/**
	 * 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.
	 * 
	 * @param in
	 *            the object we are putting into the Variant, assumes a
	 * @see Variant#putDispatch(Dispatch)
	 * @deprecated should use putDispatch()
	 */
	@Deprecated
	public void putObject(Object in) {
		// this should verify in instanceof Dispatch
		putVariantDispatch(in);
	}

	/**
	 * the JNI implementation for putDispatch() so that we can screen the
	 * incoming dispatches in putDispatch() before this is invoked
	 * 
	 * @param in
	 *            should be a dispatch object
	 */
	private native void putVariantDispatch(Object in);

	private native void putVariantDouble(double in);

	/**
	 * wraps this Vaariant around the passed in double.
	 * 
	 * @param in
	 */
	public void putDouble(double in) {
		// verify we aren't released yet
		getvt();
		putVariantDouble(in);
	}

	/**
	 * 
	 * @return the value in this Variant as a long, null if not a long
	 */
	private native long getVariantCurrency();

	/**
	 * MS Currency objects are 64 bit fixed point numbers with 15 digits to the
	 * left and 4 to the right of the decimal place.
	 * 
	 * @return returns the currency value as a long, throws exception if not a
	 *         currency type..
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public long getCurrency() {
		if (this.getvt() == VariantCurrency) {
			return getVariantCurrency();
		} else {
			throw new IllegalStateException(
					"getCurrency() only legal on Variants of type VariantCurrency, not "
							+ this.getvt());
		}
	}

	private native void putVariantFloatRef(float in);

	/**
	 * pushes a float into the variant and sets the type
	 * 
	 * @param in
	 */
	public void putFloatRef(float in) {
		// verify we aren't released yet
		getvt();
		putVariantFloatRef(in);
	}

	private native void putVariantCurrencyRef(long 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.
	 * 
	 * @param in
	 *            the long that will be put into the 64 bit currency object
	 */
	public void putCurrencyRef(long in) {
		// verify we aren't released yet
		getvt();
		putVariantCurrencyRef(in);
	}

	private native void putVariantErrorRef(int in);

	/**
	 * pushes an error code into the variant by ref and sets the type
	 * 
	 * @param in
	 */
	public void putErrorRef(int in) {
		// verify we aren't released yet
		getvt();
		putVariantErrorRef(in);
	}

	private native void putVariantBooleanRef(boolean in);

	/**
	 * pushes a boolean into the variant by ref and sets the type of the variant
	 * to boolean
	 * 
	 * @param in
	 */
	public void putBooleanRef(boolean in) {
		// verify we aren't released yet
		getvt();
		putVariantBooleanRef(in);
	}

	/**
	 * 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.
	 * 
	 * @param in
	 * @deprecated
	 */
	@Deprecated
	public void putObjectRef(Object in) {
		putObject(in);
	}

	private native void putVariantByteRef(byte in);

	/**
	 * pushes a byte into the variant by ref and sets the type
	 * 
	 * @param in
	 */
	public void putByteRef(byte in) {
		// verify we aren't released yet
		getvt();
		putVariantByteRef(in);
	}

	/**
	 * Native method that actually extracts a string value from the variant
	 * 
	 * @return
	 */
	private native String getVariantString();

	/**
	 * 
	 * @return string contents of the variant.
	 * @throws IllegalStateException
	 *             if this variant is not of type String
	 */
	public String getString() {
		if (getvt() == Variant.VariantString) {
			return getVariantString();
		} else {
			throw new IllegalStateException(
					"getString() only legal on Variants of type VariantString, not "
							+ this.getvt());
		}
	}

	private native void putVariantString(String in);

	/**
	 * put a string into the variant and set its type
	 * 
	 * @param in
	 */
	public void putString(String in) {
		// verify we aren't released yet
		getvt();
		putVariantString(in);
	}

	private native float getVariantFloatRef();

	/**
	 * 
	 * @return returns the float value, throws exception if not a Float type
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public float getFloatRef() {
		if ((this.getvt() & VariantFloat) == VariantFloat
				&& (this.getvt() & VariantByref) == VariantByref) {
			return getVariantFloatRef();
		} else {
			throw new IllegalStateException(
					"getFloatRef() only legal on byRef Variants of type VariantFloat, not "
							+ this.getvt());
		}
	}

	private native long getVariantCurrencyRef();

	/**
	 * MS Currency objects are 64 bit fixed point numbers with 15 digits to the
	 * left and 4 to the right of the decimal place.
	 * 
	 * @return returns the currency value as a long, throws exception if not a
	 *         currency type
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public long getCurrencyRef() {
		if ((this.getvt() & VariantCurrency) == VariantCurrency
				&& (this.getvt() & VariantByref) == VariantByref) {
			return getVariantCurrencyRef();
		} else {
			throw new IllegalStateException(
					"getCurrencyRef() only legal on byRef Variants of type VariantCurrency, not "
							+ this.getvt());
		}
	}

	private native int getVariantErrorRef();

	/**
	 * 
	 * @return returns the error value as an int, throws exception if not a
	 *         Error type
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public int getErrorRef() {
		if ((this.getvt() & VariantError) == VariantError
				&& (this.getvt() & VariantByref) == VariantByref) {
			return getVariantErrorRef();
		} else {
			throw new IllegalStateException(
					"getErrorRef() only legal on byRef Variants of type VariantError, not "
							+ this.getvt());
		}
	}

	private native boolean getVariantBooleanRef();

	/**
	 * public cover for native method
	 * 
	 * @return the boolean from a booleanRef
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public boolean getBooleanRef() {
		if ((this.getvt() & VariantBoolean) == VariantBoolean
				&& (this.getvt() & VariantByref) == VariantByref) {
			return getVariantBooleanRef();
		} else {
			throw new IllegalStateException(
					"getBooleanRef() only legal on byRef Variants of type VariantBoolean, not "
							+ this.getvt());
		}
	}

	private native byte getVariantByteRef();

	/**
	 * public cover for native method
	 * 
	 * @return the byte from a booleanRef
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public byte getByteRef() {
		if ((this.getvt() & VariantByte) == VariantByte
				&& (this.getvt() & VariantByref) == VariantByref) {
			return getVariantByteRef();
		} else {
			throw new IllegalStateException(
					"getByteRef() only legal on byRef Variants of type VariantByte, not "
							+ this.getvt());
		}
	}

	/**
	 * attempts to return the contents of this variant as a float (after
	 * possible conversion)
	 * 
	 * @deprecated should use changeType() and getFloat() instead
	 * @return float
	 */
	@Deprecated
	public float toFloat() {
		changeType(Variant.VariantFloat);
		return getFloat();
	}

	private native SafeArray toVariantSafeArray(boolean deepCopy);

	/**
	 * 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).
	 * 
	 * @return the object converted to a SafeArray
	 */
	public SafeArray toSafeArray() {
		// verify we haven't been released yet
		getvt();
		return toSafeArray(true);
	}

	/**
	 * This lets folk turn into a safe array without a deep copy. Should this
	 * API be public?
	 * 
	 * @param deepCopy
	 * @return SafeArray constructed
	 */
	public SafeArray toSafeArray(boolean deepCopy) {
		// verify we haven't been released yet
		getvt();
		return toVariantSafeArray(deepCopy);
	}

	private native void putVariantSafeArrayRef(SafeArray in);

	/**
	 * have no idea...
	 * 
	 * @param in
	 */
	public void putSafeArrayRef(SafeArray in) {
		// verify we haven't been released yet
		getvt();
		putVariantSafeArrayRef(in);
	}

	private native void putVariantSafeArray(SafeArray in);

	/**
	 * have no idea...
	 * 
	 * @param in
	 */
	public void putSafeArray(SafeArray in) {
		// verify we haven't been released yet
		getvt();
		putVariantSafeArray(in);
	}

	/**
	 * sets the type to VT_ERROR and the error message to DISP_E_PARAMNOTFOIUND
	 */
	private native void putVariantNoParam();

	/**
	 * sets the type to VT_ERROR and the error message to DISP_E_PARAMNOTFOIUND
	 */
	public void putNoParam() {
		// verify we aren't released yet
		getvt();
		putVariantNoParam();
	}

	/**
	 * sets the type to VT_ERROR and the error message to DISP_E_PARAMNOTFOIUND
	 * 
	 * @deprecated replaced by putNoParam()
	 */
	@Deprecated
	public void noParam() {
		putNoParam();
	}

	/**
	 * @param in
	 *            the object that would be wrapped by the Variant if this method
	 *            was implemented
	 * @deprecated superseded by SafeArray
	 * @throws com.jacob.com.NotImplementedException
	 */
	@Deprecated
	public void putCharArray(Object in) {
		throw new NotImplementedException("Not implemented");
	}

	/**
	 * 
	 * @return returns the value as a float if the type is of type float
	 */
	private native float getVariantFloat();

	/**
	 * @return returns the value as a float if the type is of type float
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public float getFloat() {
		if (this.getvt() == VariantFloat) {
			return getVariantFloat();
		} else {
			throw new IllegalStateException(
					"getFloat() only legal on Variants of type VariantFloat, not "
							+ this.getvt());
		}
	}

	/**