variant.java

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

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

	/**
	 * fills the Variant with a float and sets the type to float
	 * 
	 * @param in
	 */
	public void putFloat(float in) {
		// verify we haven't been released yet
		getvt();
		putVariantFloat(in);
	}

	/**
	 * Dispatch and dispatchRef are treated the same This is a cover for
	 * putVariantDispatch(). Dispatch and dispatchRef are treated the same
	 * 
	 * @param in
	 */
	public void putDispatchRef(Dispatch in) {
		putVariantDispatch(in);
	}

	/**
	 * Dispatch and dispatchRef are treated the same This is just a cover for
	 * toDispatch() with a flag check
	 * 
	 * @return the results of toDispatch()
	 * @throws IllegalStateException
	 *             if variant is not of the requested type
	 */
	public Dispatch getDispatchRef() {
		if ((this.getvt() & VariantDispatch) == VariantDispatch
				&& (this.getvt() & VariantByref) == VariantByref) {
			return toDispatch();
		} else {
			throw new IllegalStateException(
					"getDispatchRef() only legal on byRef Variants of type VariantDispatch, not "
							+ this.getvt());
		}
	}

	/**
	 * @param in
	 *            the thing that would be come an array if this method was
	 *            implemented
	 * @deprecated superseded by SafeArray
	 * @throws com.jacob.com.NotImplementedException
	 */
	@Deprecated
	public void putVariantArrayRef(Variant[] in) {
		throw new NotImplementedException("Not implemented");
	}

	/**
	 * @return the Variant Array that represents the data in the Variant
	 * @deprecated superseded by SafeArray
	 * @throws com.jacob.com.NotImplementedException
	 */
	@Deprecated
	public Variant[] getVariantArrayRef() {
		throw new NotImplementedException("Not implemented");
	}

	/**
	 * Converts variant to the passed in type by converting the underlying
	 * windows variant structure. private so folks use public java method
	 * 
	 * @param in the desired resulting type
	 */
	private native void changeVariantType(short in);

	/**
	 * Cover for native method so we can cover it.
	 * <p>
	 * This cannot convert an object to a byRef. It can convert from byref to
	 * not byref
	 * 
	 * @param in
	 *            type to convert this variant too
	 * @return Variant returns this same object so folks can change when
	 *         replacing calls toXXX() with changeType().getXXX()
	 */
	public Variant changeType(short in) {
		changeVariantType(in);
		return this;
	}

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

	/**
	 * public constructor, initializes and sets type to VariantEmpty
	 */
	public Variant() {
		this(null, false);
	}

	/**
	 * Constructor that accepts a primitive rather than an object
	 * 
	 * @param in
	 */
	public Variant(int in) {
		this(new Integer(in));
	}

	/**
	 * Constructor that accepts a primitive rather than an object
	 * 
	 * @param in
	 */
	public Variant(double in) {
		this(new Double(in));
	}

	/**
	 * Constructor that accepts a primitive rather than an object
	 * 
	 * @param in
	 */
	public Variant(boolean in) {
		this(new Boolean(in));
	}

	/**
	 * Convenience constructor that calls the main one with a byRef value of
	 * false
	 * 
	 * @param in
	 *            object to be made into variant
	 */
	public Variant(Object in) {
		this(in, false);
	}

	/**
	 * constructor that accepts the data object and informaton about whether
	 * this is by reference or not.
	 * 
	 * @param pValueObject
	 *            a null object sets this to "empty"
	 * @param fByRef
	 */
	public Variant(Object pValueObject, boolean fByRef) {
		init();
		if (pValueObject == null) {
			putEmpty();
		} else if (pValueObject instanceof Integer) {
			if (fByRef) {
				putIntRef(((Integer) pValueObject).intValue());
			} else {
				putInt(((Integer) pValueObject).intValue());
			}
		} else if (pValueObject instanceof Short) {
			if (fByRef) {
				putShortRef(((Short) pValueObject).shortValue());
			} else {
				putShort(((Short) pValueObject).shortValue());
			}
		} else if (pValueObject instanceof String) {
			if (fByRef) {
				putStringRef((String) pValueObject);
			} else {
				putString((String) pValueObject);
			}
		} else if (pValueObject instanceof Boolean) {
			if (fByRef) {
				putBooleanRef(((Boolean) pValueObject).booleanValue());
			} else {
				putBoolean(((Boolean) pValueObject).booleanValue());
			}
		} else if (pValueObject instanceof Double) {
			if (fByRef) {
				putDoubleRef(((Double) pValueObject).doubleValue());
			} else {
				putDouble(((Double) pValueObject).doubleValue());
			}
		} else if (pValueObject instanceof Float) {
			if (fByRef) {
				putFloatRef(((Float) pValueObject).floatValue());
			} else {
				putFloat(((Float) pValueObject).floatValue());
			}
		} else if (pValueObject instanceof BigDecimal) {
			if (fByRef) {
				putDecimalRef(((BigDecimal) pValueObject));
			} else {
				putDecimal(((BigDecimal) pValueObject));
			}
		} else if (pValueObject instanceof Byte) {
			if (fByRef) {
				putByteRef(((Byte) pValueObject).byteValue());
			} else {
				putByte(((Byte) pValueObject).byteValue());
			}
		} else if (pValueObject instanceof Date) {
			if (fByRef) {
				putDateRef((Date) pValueObject);
			} else {
				putDate((Date) pValueObject);
			}
		} else if (pValueObject instanceof SafeArray) {
			if (fByRef) {
				putSafeArrayRef((SafeArray) pValueObject);
			} else {
				putSafeArray((SafeArray) pValueObject);
			}
		} else if (pValueObject instanceof Dispatch) {
			if (fByRef) {
				putDispatchRef((Dispatch) pValueObject);
			} else {
				putDispatch((Dispatch) pValueObject);
			}
		} else if (pValueObject instanceof Variant) {
			// newly added 1.12-pre6
			putVariant(pValueObject);
		} else {
			// should really throw an illegal argument exception if its an
			// invalid type
			if (fByRef) {
				putObjectRef(pValueObject);
			} else {
				putObject(pValueObject);
			}
		}
	}

	/**
	 * Returns the variant type via a native method call
	 * 
	 * @return short one of the VT_xx types
	 */
	private native short getVariantType();

	/**
	 * Reports the type of the underlying Variant object
	 * 
	 * @return 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
	 */
	public short getvt() {
		if (m_pVariant != 0) {
			return getVariantType();
		} else {
			throw new IllegalStateException("uninitialized Variant");
		}
	}

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

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

	protected native void init();

	/*
	 * (non-Javadoc)
	 * 
	 * @see java.lang.Object#finalize()
	 */
	protected void finalize() {
		safeRelease();
	}

	/**
	 * returns true if the passed in Variant is a constant that should not be
	 * freed
	 * 
	 * @param pVariant
	 * @return boolian that is true if Variant is a type of constant, VT_FALSE,
	 *         VT_TRUE, VT_MISSING, DEFAULT
	 */
	protected boolean objectIsAConstant(Variant pVariant) {
		if (pVariant == VT_FALSE || pVariant == VT_TRUE
				|| pVariant == VT_MISSING || pVariant == DEFAULT) {
			return true;
		} else {
			return false;
		}

	}

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

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

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

	/**
	 * is the variant null or empty or error or null dispatch
	 * 
	 * @return true if it is null or false if not
	 */
	private native boolean isVariantConsideredNull();

	/**
	 * 
	 * @return returns true if the variant is considered null
	 * @throws IllegalStateException
	 *             if there is no underlying windows memory
	 */
	public boolean isNull() {
		getvt();
		return isVariantConsideredNull();
	}

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

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

	/*
	 * =====================================================================
	 * 
	 * 
	 * =====================================================================
	 */
	/**
	 * Convert a JACOB Variant value to a Java object (type conversions).
	 * provided in Sourceforge feature request 959381. A fix was done to handle
	 * byRef bug report 1607878.
	 * <p>
	 * Unlike other toXXX() methods, it does not do a type conversion except for
	 * special data types (it shouldn't do any!)
	 * <p>
	 * Converts Variant.VariantArray types to SafeArrays
	 * 
	 * @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 {
		Object result = null;

		short type = this.getvt(); // variant type

		if ((type & Variant.VariantArray) == VariantArray) { // array
			// returned?
			SafeArray array = null;
			type = (short) (type - Variant.VariantArray);
			array = this.toSafeArray(false);
			// result = toJava(array);
			result = array;
		} else { // non-array object returned
			switch (type) {
			case Variant.VariantEmpty: // 0
			case Variant.VariantNull: // 1
				break;
			case Variant.VariantShort: // 2
				result = new Short(this.getShort());
				break;
			case Variant.VariantShort | Variant.VariantByref: // 2
				result = new Short(this.getShortRef());
				break;
			case Variant.VariantInt: // 3
				result = new Integer(this.getInt());
				break;
			case Variant.VariantInt | Variant.VariantByref: // 3
				result = new Integer(this.getIntRef());
				break;
			case Variant.VariantFloat: // 4
				result = new Float(this.getFloat());
				break;
			case Variant.VariantFloat | Variant.VariantByref: // 4
				result = new Float(this.getFloatRef());
				break;
			case Variant.VariantDouble: // 5
				result = new Double(this.getDouble());
				break;
			case Variant.VariantDouble | Variant.VariantByref: // 5
				result = new Double(this.getDoubleRef());
				break;
			case Variant.VariantCurrency: // 6
				result = new Long(this.getCurrency());
				break;
			case Variant.VariantCurrency | Variant.VariantByref: // 6
				result = new Long(this.getCurrencyRef());
				break;
			case Variant.VariantDate: // 7
				result = this.getJavaDate();
				break;
			case Variant.VariantDate | Variant.VariantByref: // 7
				result = this.getJavaDateRef();
				break;
			case Variant.VariantString: // 8
				result = this.getString();
				break;
			case Variant.VariantString | Variant.VariantByref: // 8
				result = this.getStringRef();
				break;
			case Variant.VariantDispatch: // 9
				result = this.getDispatch();
				break;
			case Variant.VariantDispatch | Variant.VariantByref: // 9
				result = this.getDispatchRef(); // Can dispatches even be byRef?
				break;
			case Variant.VariantError: // 10
				result = new NotImplementedException(
						"toJavaObject() Not implemented for VariantError");
				break;
			case Variant.VariantBoolean: // 11
				result = new Boolean(this.getBoolean());
				break;
			case Variant.VariantBoolean | Variant.VariantByref: // 11
				result = new Boolean(this.getBooleanRef());
				break;
			case Variant.VariantVariant: // 12 they are always by ref
				result = new NotImplementedException(
						"toJavaObject() Not implemented for VariantVariant without ByRef");
				break;
			case Variant.VariantVariant | Variant.VariantByref: // 12
				result = getVariant();
				break;
			case Variant.VariantObject: // 13
				result = new NotImplementedException(
						"toJavaObject() Not implemented for VariantObject");
				break;
			case Variant.VariantDecimal: // 14
				result = getDecimal();
				break;
			case Variant.VariantDecimal | Variant.VariantByref: // 14
				result = getDecimalRef();
				break;
			case Variant.VariantByte: // 17
				result = new Byte(this.getByte());
				break;
			case Variant.VariantByte | Variant.VariantByref: // 17
				result = new Byte(this.getByteRef());
				break;
			case Variant.VariantTypeMask: // 4095
				result = new NotImplementedException(
						"toJavaObject() Not implemented for VariantTypeMask");
				break;
			case Variant.VariantArray: // 8192
				result = new NotImplementedException(
						"toJavaObject() Not implemented for VariantArray");
				break;
			case Variant.VariantByref: // 16384
				result = new NotImplementedException(
						"toJavaObject() Not implemented for VariantByref");
				break;
			default:
				result = new NotImplementedException("Unknown return type: "
						+ type);
				// there was a "return result" here that caused defect 1602118
				// so it was removed
				break;
			}// switch (type)

			if (result instanceof JacobException) {
				throw (JacobException) result;
			}
		}

		return result;
	}// toJava()
}