variant.java

java与windows的com桥,可以用来操作所有的com程序如word或者excel等

	 * 
	 * @param in
	 *            the new value
	 */
	private native void putVariantByte(byte in);

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

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

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

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

	/**
	 * set the content of this variant to a date (VT_DATE|VT_BYREF)
	 * 
	 * @param in
	 */
	private native void putVariantDateRef(double in);

	/**
	 * 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);

	/**
	 * private JNI method called by putDecimalRef
	 * 
	 * @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 putVariantDecRef(int signum, byte scale, int lo,
			int mid, int hi);

	/**
	 * 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);

	/**
	 * set the content of this variant to a double (VT_R8|VT_BYREF)
	 * 
	 * @param in
	 */
	private native void putVariantDoubleRef(double in);

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

	private native void putVariantError(int in);

	private native void putVariantErrorRef(int in);

	/**
	 * fills the Variant with a float and sets the type to float
	 * 
	 * @param in
	 */
	private native void putVariantFloat(float in);

	private native void putVariantFloatRef(float in);

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

	/**
	 * set the content of this variant to an int (VT_I4|VT_BYREF)
	 * 
	 * @param in
	 */
	private native void putVariantIntRef(int in);

	private native void putVariantLong(long in);

	private native void putVariantLongRef(long in);

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

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

	/**
	 * Set this Variant's type to VT_NULL (the VB equivalent of NULL)
	 */
	private native void putVariantNull();

	private native void putVariantSafeArray(SafeArray in);

	private native void putVariantSafeArrayRef(SafeArray in);

	/**
	 * 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|VT_BYREF)
	 * 
	 * @param in
	 */
	private native void putVariantShortRef(short in);

	private native void putVariantString(String in);

	/**
	 * set the content of this variant to a string (VT_BSTR|VT_BYREF)
	 * 
	 * @param in
	 */
	private native void putVariantStringRef(String in);

	/**
	 * All VariantVariant type variants are BYREF.
	 * 
	 * Set the content of this variant to a string (VT_VARIANT|VT_BYREF).
	 * 
	 * Added 1.12 pre 6 - VT_VARIANT support is at an alpha level
	 * 
	 * @param in
	 *            variant to be wrapped
	 * 
	 */
	private native void putVariantVariant(Variant in);

	/**
	 * now private so only this object can access was: call this to explicitly
	 * release the com object before gc
	 * 
	 */
	private native void release();

	/**
	 * 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.
	 * <p>
	 * 
	 * @see com.jacob.com.JacobObject#safeRelease()
	 */
	public void safeRelease() {
		// The well known constants should not be released.
		// Unfortunately this doesn't fix any other classes that are
		// keeping constants around in their static ivars.
		// those will still be busted.
		//
		// The only inconsistency here is that we leak
		// when this class is unloaded because we won't
		// free the memory even if the constants are being
		// finalized. this is not a big deal at all.
		// another way around this would be to create the constants
		// in their own thread so that they would never be released
		if (!objectIsAConstant(this)) {
			super.safeRelease();
			if (m_pVariant != 0) {
				release();
				m_pVariant = 0;
			} else {
				// looks like a double release
				// this should almost always happen due to gc
				// after someone has called ComThread.Release
				if (isDebugEnabled()) {
					debug("Variant: " + this.hashCode() + " double release");
					// Throwable x = new Throwable();
					// x.printStackTrace();
				}
			}
		} else {
			if (isDebugEnabled()) {
				debug("Variant: " + this.hashCode()
						+ " don't want to release a constant");
			}
		}
	}

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

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

	/**
	 * @deprecated should be replaced by changeType() followed by getBoolean()
	 * @return the value of this variant as boolean (after possible conversion)
	 */
	@Deprecated
	public boolean toBoolean() {
		changeType(Variant.VariantBoolean);
		return getBoolean();
	}

	/**
	 * 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();
	}

	/**
	 * @deprecated superseded by SafeArray
	 * @return nothing because this method is not implemented
	 * @throws com.jacob.com.NotImplementedException
	 */
	@Deprecated
	public Object toByteArray() {
		throw new NotImplementedException("Not implemented");
	}

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

	/**
	 * @deprecated should be replaced by changeType() followed by getCurrency
	 * @return the content of this variant as a long representing a monetary
	 *         amount
	 */
	@Deprecated
	public Currency toCurrency() {
		changeType(Variant.VariantCurrency);
		return getCurrency();
	}

	/**
	 * @deprecated should use changeType() followed by getDate()
	 * @return the value of this variant as a date (after possible conversion)
	 */
	@Deprecated
	public double toDate() {
		changeType(VariantDate);
		return getDate();
	}

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

	/**
	 * @deprecated should call changeType() then getDouble()
	 * @return the content of this variant as a double (after possible
	 *         conversion)
	 */
	@Deprecated
	public double toDouble() {
		changeType(Variant.VariantDouble);
		return getDouble();
	}

	/** @return the value of this variant as an enumeration (java style) */
	public native EnumVariant toEnumVariant();

	/**
	 * 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();
	}

	/**
	 * 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();
	}

	/**
	 * @deprecated should use changeType() followed by getInt()
	 * @return the value of this variant as an int (after possible conversion)
	 */
	@Deprecated
	public int toInt() {
		changeType(VariantInt);
		return getInt();
	}

	/**
	 * 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.
	 * <p>
	 * This method added 12/2005 for possible use by jacobgen instead of its
	 * conversion code
	 * <p>
	 * This does not convert the data
	 * 
	 * @deprecated callers should use getDate()
	 * @return java.util.Date version of this variant if it is a date, otherwise
	 *         null
	 * 
	 */
	@Deprecated
	public Date toJavaDate() {
		changeType(Variant.VariantDate);
		return getJavaDate();
	}

	/**
	 * Convert a JACOB Variant value to a Java object (type conversions).
	 * provided in Sourceforge feature request 959381. See
	 * JavaVariantConverter..convertVariantTJavaObject(Variant) for more
	 * information.
	 * 
	 * @return Corresponding Java object of the type matching the Variant type.
	 * @throws IllegalStateException
	 *             if no underlying windows data structure
	 * @throws NotImplementedException
	 *             if unsupported conversion is requested
	 * @throws JacobException
	 *             if the calculated result was a JacobObject usually as a
	 *             result of error
	 */
	public Object toJavaObject() throws JacobException {
		return VariantUtilities.variantToObject(this);
	}

	/**
	 * 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();
	}

	/**
	 * 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);
	}

	/**
	 * I don't know what this is. Is it some legacy (pre 1.8) thing?
	 * 
	 * @deprecated
	 * @return this object as a dispatch object by calling toDispatch()
	 */
	@Deprecated
	public Object toScriptObject() {
		return toDispatch();
	}

	/**
	 * attempts to return the contents of this Variant as a short (after
	 * possible conversion)
	 * 
	 * @deprecated callers should use changeType() followed by getShort()
	 * @return short
	 */
	@Deprecated
	public short toShort() {
		this.changeType(Variant.VariantShort);
		return getShort();
	}

	/**
	 * 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();
		}
	}

	/**
	 * Exists to support jacobgen. This would be deprecated if it weren't for
	 * jacobgen
	 * 
	 * @deprecated superseded by "this"
	 * @return this same object
	 */
	@Deprecated
	public Variant toVariant() {
		return this;
	}

	/**
	 * @deprecated superseded by SafeArray
	 * @return nothing because this method is not implemented
	 * @throws com.jacob.com.NotImplementedException
	 */
	@Deprecated
	public Variant[] toVariantArray() {
		throw new NotImplementedException("Not implemented");
	}

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

	private native SafeArray toVariantSafeArray(boolean deepCopy);

	/*
	 * =====================================================================
	 * 
	 * 
	 * =====================================================================
	 */

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

}