variant.java

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

		} else {
			throw new IllegalStateException(
					"getShortRef() only legal on byRef Variants of type VariantShort, not "
							+ this.getvt());
		}
	}

	/**
	 * get the content of this variant as an int
	 * 
	 * @return int
	 */
	private native int getVariantIntRef();

	/**
	 * get the content of this variant as an int
	 * 
	 * @return int
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public int getIntRef() {
		if ((this.getvt() & VariantInt) == VariantInt
				&& (this.getvt() & VariantByref) == VariantByref) {
			return getVariantIntRef();
		} else {
			throw new IllegalStateException(
					"getIntRef() only legal on byRef Variants of type VariantInt, not "
							+ this.getvt());
		}
	}

	/**
	 * set the content of this variant to a short (VT_I2)
	 * 
	 * @param in
	 */
	private native void putVariantShort(short in);

	/**
	 * set the content of this variant to a short (VT_I2)
	 * 
	 * @param in
	 */
	public void putShort(short in) {
		// verify we aren't released
		getvt();
		putVariantShort(in);
	}

	/**
	 * get the content of this variant as a short
	 * 
	 * @return short
	 */
	private native short getVariantShort();

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

	/**
	 * get the content of this variant as a double
	 * 
	 * @return double
	 */
	private native double getVariantDoubleRef();

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

	/**
	 * get the content of this variant as a double representing a date
	 * 
	 * @return double
	 */
	private native double getVariantDateRef();

	/**
	 * 
	 * @return returns the date value as a double, throws exception if not a
	 *         date type
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public double getDateRef() {
		if ((this.getvt() & VariantDate) == VariantDate
				&& (this.getvt() & VariantByref) == VariantByref) {
			return getVariantDateRef();
		} else {
			throw new IllegalStateException(
					"getDateRef() only legal on byRef Variants of type VariantDate, not "
							+ this.getvt());
		}
	}

	/**
	 * 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
	 * 
	 * @return java.util.Date
	 */
	public Date getJavaDateRef() {
		double windowsDate = getDateRef();
		if (windowsDate == 0) {
			return null;
		} else {
			return DateUtilities.convertWindowsTimeToDate(windowsDate);
		}
	}

	/**
	 * get the content of this variant as a string
	 * 
	 * @return String
	 */
	private native String getVariantStringRef();

	/**
	 * gets the content of the veriant as a string ref
	 * 
	 * @return String retrieved from the COM area.
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public String getStringRef() {
		if ((this.getvt() & VariantString) == VariantString
				&& (this.getvt() & VariantByref) == VariantByref) {
			return getVariantStringRef();
		} else {
			throw new IllegalStateException(
					"getStringRef() only legal on byRef Variants of type VariantString, not "
							+ this.getvt());
		}
	}

	/**
	 * @deprecated superceded by SafeArray
	 * @return never returns anything
	 * @throws com.jacob.com.NotImplementedException
	 */
	@Deprecated
	public Object toCharArray() {
		throw new NotImplementedException("Not implemented");
	}

	/**
	 * Clear the content of this variant
	 */
	public native void VariantClear();

	/**
	 * @return the content of this variant as a Dispatch object (after possible
	 *         conversion)
	 */
	public Dispatch toDispatch() {
		// now make the native call
		return toVariantDispatch();
	}

	/**
	 * native method used by toDispatch()
	 * 
	 * @return
	 */
	private native Dispatch toVariantDispatch();

	/**
	 * this returns null
	 * 
	 * @return ?? comment says null?
	 */
	public native Object clone();

	/**
	 * This method now correctly implements java toString() semantics Attempts
	 * to return the content of this variant as a string
	 * <ul>
	 * <li>"not initialized" if not initialized
	 * <li>"null" if VariantEmpty,
	 * <li>"null" if VariantError
	 * <li>"null" if VariantNull
	 * <li>the value if we know how to describe one of that type
	 * <li>three question marks if can't convert
	 * 
	 * @return String value conversion,
	 * @throws IllegalStateException
	 *             if there is no underlying windows data structure
	 */
	public String toString() {
		try {
			// see if we are in a legal state
			getvt();
		} catch (IllegalStateException ise) {
			return "";
		}
		if (getvt() == VariantEmpty || getvt() == VariantError
				|| getvt() == VariantNull) {
			return "null";
		}
		if (getvt() == VariantString) {
			return getString();
		}
		try {
			Object foo = toJavaObject();
			// rely on java objects to do the right thing
			return foo.toString();
		} catch (NotImplementedException nie) {
			// some types do not generate a good description yet
			return "Description not available for type: " + getvt();
		}
	}

	/**
	 * return the int value held in this variant (fails on other types?)
	 * 
	 * @return int
	 */
	private native int getVariantInt();

	/**
	 * return the int value held in this variant if it is an int or a short.
	 * Throws for other types.
	 * 
	 * @return int contents of the windows membory
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public int getInt() {
		if (this.getvt() == VariantInt) {
			return getVariantInt();
		} else if (this.getvt() == VariantShort) {
			return getVariantShort();
		} else {
			throw new IllegalStateException(
					"getInt() only legal on Variants of type VariantInt, not "
							+ this.getvt());
		}
	}

	/**
	 * @return double return the date (as a double) value held in this variant
	 *         (fails on other types?)
	 */
	private native double getVariantDate();

	/**
	 * @return 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
	 */
	public double getDate() {
		if (this.getvt() == VariantDate) {
			return getVariantDate();
		} else {
			throw new IllegalStateException(
					"getDate() only legal on Variants of type VariantDate, not "
							+ this.getvt());
		}
	}

	/**
	 * returns the windows time contained in this Variant to a Java Date. should
	 * return null if this is not a date Variant SF 959382
	 * 
	 * @return 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
	 */
	public Date getJavaDate() {
		Date returnDate = null;
		if (getvt() == VariantDate) {
			double windowsDate = getDate();
			if (windowsDate != 0) {
				returnDate = DateUtilities.convertWindowsTimeToDate(getDate());
			}
		} else {
			throw new IllegalStateException(
					"getJavaDate() only legal on Variants of type VariantDate, not "
							+ this.getvt());
		}
		return returnDate;
	}

	/**
	 * set the value of this variant and set the type
	 * 
	 * @param in
	 */
	private native void putVariantInt(int in);

	/**
	 * set the value of this variant and set the type
	 * 
	 * @param in
	 */
	public void putInt(int in) {
		// verify we aren't released yet
		getvt();
		putVariantInt(in);
	}

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

	/**
	 * @return the value in this Variant (byref) as a decimal, null if not a
	 *         decimal
	 */
	private native Object getVariantDecRef();

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

	/**
	 * return the BigDecimal value held in this variant (fails on other types)
	 * 
	 * @return BigDecimal
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public BigDecimal getDecimalRef() {
		if ((this.getvt() & VariantDecimal) == VariantDecimal
				&& (this.getvt() & VariantByref) == VariantByref) {
			return (BigDecimal) (getVariantDecRef());
		} else {
			throw new IllegalStateException(
					"getDecimalRef() only legal on byRef Variants of type VariantDecimal, not "
							+ this.getvt());
		}
	}

	/**
	 * private JNI method called by putDecimal
	 * 
	 * @param signum
	 *            sign
	 * @param scale
	 *            BigDecimal's scale
	 * @param lo
	 *            low 32 bits
	 * @param mid
	 *            middle 32 bits
	 * @param hi
	 *            high 32 bits
	 */
	private native void putVariantDec(int signum, byte scale, int lo, int mid,
			int hi);

	/**
	 * 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.
	 * 
	 * @param in
	 *            the big decimal that will convert to the VT_DECIMAL type
	 * @throws IllegalArgumentException
	 *             if the scale is > 28, the maximum for VT_DECIMAL
	 */
	public void putDecimal(BigDecimal in) {
		// verify we aren't released yet
		getvt();
		if (in.scale() > 28) {
			// should this really cast to a string and call putStringRef()?
			throw new IllegalArgumentException(
					"VT_DECIMAL only supports a scale of 28 and the passed"
							+ " in value has a scale of " + in.scale());
		} else {
			int sign = in.signum();
			// MS decimals always have positive values with just the sign flipped
			if (in.signum() < 0){
				in = in.negate();
			}
			byte scale = (byte) in.scale();
			BigInteger unscaled = in.unscaledValue();
			BigInteger shifted = unscaled.shiftRight(32);
			putVariantDec(sign, scale, unscaled.intValue(), shifted
					.intValue(), shifted.shiftRight(32).intValue());
		}
	}

	/**
	 * set the value of this variant
	 * 
	 * @param in
	 */
	private native void putVariantDate(double in);

	/**
	 * puts a windows date double into the variant and sets the type
	 * 
	 * @param in
	 */
	public void putDate(double in) {
		// verify we aren't released yet
		getvt();
		putVariantDate(in);
	}

	/**
	 * converts a java date to a windows time and calls putDate(double) SF
	 * 959382
	 * 
	 * @param inDate
	 *            a Java date to be converted
	 * @throws IllegalArgumentException
	 *             if inDate = null
	 */
	public void putDate(Date inDate) {
		if (inDate == null) {
			throw new IllegalArgumentException(
					"Cannot put null in as windows date");
			// do nothing
		} else {
			putDate(DateUtilities.convertDateToWindowsTime(inDate));
		}
	}

	/**
	 * attempts to return the content of this variant as a double (after
	 * possible conversion)
	 * 
	 * @deprecated should be replaced by changeType() followed by getByte()
	 * @return byte
	 */
	@Deprecated
	public byte toByte() {
		changeType(Variant.VariantByte);
		return getByte();
	}

	/**
	 * cover for {@link #toDispatch()} This method now matches other getXXX()
	 * methods. It throws an IllegalStateException if the object is not of type
	 * VariantDispatch
	 * 
	 * @return this object as a dispatch
	 * @throws IllegalStateException
	 *             if wrong variant type
	 */
	public Dispatch getDispatch() {
		if ((this.getvt() & VariantDispatch) == VariantDispatch) {
			return toDispatch();
		} else {
			throw new IllegalStateException(
					"getDispatch() only legal on Variants of type VariantDispatch, not "
							+ this.getvt());
		}
	}

	/**
	 * This acts a cover for same as
	 * 
	 * Why isn't this typed as type Dispatch?
	 * @param in
	 */
	public void putDispatch(Dispatch in) {
		putVariantDispatch(in);
	}

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

	/**
	 * 
	 * @return returns the value as a boolean, throws an exception if its not.
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public boolean getBoolean() {
		if (this.getvt() == VariantBoolean) {
			return getVariantBoolean();
		} else {
			throw new IllegalStateException(
					"getBoolean() only legal on Variants of type VariantBoolean, not "
							+ this.getvt());
		}
	}

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

	/**
	 * 
	 * @return returns the value as a boolean, throws an exception if its not.
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public byte getByte() {
		if (this.getvt() == VariantByte) {
			return getVariantByte();
		} else {
			throw new IllegalStateException(
					"getByte() only legal on Variants of type VariantByte, not "
							+ this.getvt());
		}
	}

	/**
	 * puts a boolean into the variant and sets it's type
	 * 
	 * @param in
	 *            the new value
	 */
	private native void putVariantBoolean(boolean in);

	/**
	 * puts a boolean into the variant and sets it's type