variant.java

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

/*
 * Copyright (c) 1999-2004 Sourceforge JACOB Project.
 * All rights reserved. Originator: Dan Adler (http://danadler.com).
 * Get more information about JACOB at http://sourceforge.net/projects/jacob-project
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
package com.jacob.com;

import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Date;

/**
 * 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.
 * <p>
 * Just loading this class creates 3 variants that get added to the ROT
 * <p>
 * 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
 * <p>
 * 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.
 */
public class Variant extends JacobObject {

	/**
	 * Use this constant for optional parameters
	 */
	public final static com.jacob.com.Variant DEFAULT;

	/**
	 * Same than {@link #DEFAULT}
	 */
	public final static com.jacob.com.Variant VT_MISSING;

	/**
	 * Use for true/false variant parameters
	 */
	public final static com.jacob.com.Variant VT_TRUE = new com.jacob.com.Variant(
			true);

	/**
	 * Use for true/false variant parameters
	 */
	public final static com.jacob.com.Variant VT_FALSE = new com.jacob.com.Variant(
			false);

	/** variant's type is empty : equivalent to VB Nothing and VT_EMPTY */
	public static final short VariantEmpty = 0;

	/** variant's type is null : equivalent to VB Null and VT_NULL */
	public static final short VariantNull = 1;

	/** variant's type is short VT_I2 */
	public static final short VariantShort = 2;

	/** variant's type is int VT_I4, a Long in VC */
	public static final short VariantInt = 3;

	/** variant's type is float VT_R4 */
	public static final short VariantFloat = 4;

	/** variant's type is double VT_R8 */
	public static final short VariantDouble = 5;

	/** variant's type is currency VT_CY */
	public static final short VariantCurrency = 6;

	/** variant's type is date VT_DATE */
	public static final short VariantDate = 7;

	/** variant's type is string also known as VT_BSTR */
	public static final short VariantString = 8;

	/** variant's type is dispatch VT_DISPATCH */
	public static final short VariantDispatch = 9;

	/** variant's type is error VT_ERROR */
	public static final short VariantError = 10;

	/** variant's type is boolean VT_BOOL */
	public static final short VariantBoolean = 11;

	/** variant's type is variant it encapsulate another variant VT_VARIANT */
	public static final short VariantVariant = 12;

	/** variant's type is object VT_UNKNOWN */
	public static final short VariantObject = 13;

	/** variant's type is object VT_DECIMAL */
	public static final short VariantDecimal = 14;

	// VT_I1 = 16

	/** variant's type is byte VT_UI1 */
	public static final short VariantByte = 17;

	// VT_UI2 = 18
	// VT_UI4 = 19

	/**
	 * 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.
	 */
	public static final short VariantLongInt = 20;

	// VT_UI8 = 21
	// VT_INT = 22
	// VT_UNIT = 23
	// VT_VOID = 24
	// VT_HRESULT = 25

	/**
	 * This value is for reference only and is not to be used by any callers
	 */
	public static final short VariantPointer = 26;

	// VT_SAFEARRAY = 27
	// VT_CARRARY = 28
	// VT_USERDEFINED = 29

	/** what is this? VT_TYPEMASK && VT_BSTR_BLOB */
	public static final short VariantTypeMask = 4095;

	/** variant's type is array VT_ARRAY */
	public static final short VariantArray = 8192;

	/** variant's type is a reference (to IDispatch?) VT_BYREF */
	public static final short VariantByref = 16384;

	/*
	 * Do the run time definition of DEFAULT and MISSING. Have to use static
	 * block because of the way the initialization is done via two calls instead
	 * of just a constructor for this type.
	 */
	static {
		com.jacob.com.Variant vtMissing = new com.jacob.com.Variant();
		vtMissing.putVariantNoParam();
		DEFAULT = vtMissing;
		VT_MISSING = vtMissing;
	}

	/**
	 * Pointer to MS struct.
	 */
	int m_pVariant = 0;

	/**
	 * 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(boolean in) {
		this(new Boolean(in));
	}

	/**
	 * Constructor that accepts a primitive rather than an object
	 * 
	 * @param in
	 */
	public Variant(byte in) {
		this(new Byte(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(float in) {
		this(new Float(in));
	}

	/**
	 * 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(long in) {
		this(new Long(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 information about whether
	 * this is by reference or not. It calls the JavaVariantConverter to
	 * actually push the data into the newly created Variant.
	 * 
	 * @param pValueObject
	 *            The value object that will pushed down into windows memory. A
	 *            null object sets this to "empty"
	 * @param fByRef
	 */
	public Variant(Object pValueObject, boolean fByRef) {
		init();
		VariantUtilities.populateVariant(this, pValueObject, fByRef);
	}

	/**
	 * Constructor that accepts a primitive rather than an object
	 * 
	 * @param in
	 */
	public Variant(short in) {
		this(new 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;
	}

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

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

	/**
	 * @deprecated No longer used
	 * @return null !
	 */
	@Deprecated
	public native Variant cloneIndirect();

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

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

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

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

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

	/**
	 * 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 Currency getCurrency() {
		if (this.getvt() == VariantCurrency) {
			return new Currency(getVariantCurrency());
		} else {
			throw new IllegalStateException(
					"getCurrency() only legal on Variants of type VariantCurrency, not "
							+ this.getvt());
		}
	}

	/**
	 * 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 Currency getCurrencyRef() {
		if ((this.getvt() & VariantCurrency) == VariantCurrency
				&& (this.getvt() & VariantByref) == VariantByref) {
			return new Currency(getVariantCurrencyRef());
		} else {
			throw new IllegalStateException(
					"getCurrencyRef() only legal on byRef Variants of type VariantCurrency, not "
							+ this.getvt());
		}
	}

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

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

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

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

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

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

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

	/**
	 * Pointless method that was put here so that putEmpty() has a get method.