activexcomponent.java

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

/*
 * 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.activeX;

import com.jacob.com.Dispatch;
import com.jacob.com.JacobObject;
import com.jacob.com.Variant;

/**
 * This class provides a higher level, more object like, wrapper for top of the
 * Dispatch object. The Dispatch class's method essentially directly map to
 * Microsoft C API including the first parameter that is almost always the
 * target of the message. ActiveXComponent assumes the target of every message
 * is the MS COM object behind the ActiveXComponent. This removes the need to
 * pass the Dispatch object into every method.
 * <p>
 * It is really up to the developer as to whether they want to use the Dispatch
 * interface or the ActiveXComponent interface.
 * <p>
 * This class simulates com.ms.activeX.ActiveXComponent only in the senese that
 * it is used for creating Dispatch objects
 */
public class ActiveXComponent extends Dispatch {

	/**
	 * Normally used to create a new connection to a microsoft application. The
	 * passed in parameter is the name of the program as registred in the
	 * registry. It can also be the object name.
	 * <p>
	 * This constructor causes a new Windows object of the requested type to be
	 * created. The windows CoCreate() function gets called to create the
	 * underlying windows object.
	 * 
	 * <pre>
	 * new ActiveXComponent(&quot;ScriptControl&quot;);
	 * </pre>
	 * 
	 * @param programId
	 */
	public ActiveXComponent(String programId) {
		super(programId);
	}

	/**
	 * Creates an active X component that is built on top of the COM pointers
	 * held in the passed in dispatch. This widends the Dispatch object to pick
	 * up the ActiveXComponent API
	 * 
	 * @param dispatchToBeWrapped
	 */
	public ActiveXComponent(Dispatch dispatchToBeWrapped) {
		super(dispatchToBeWrapped);
	}

	/**
	 * only used by the factories
	 * 
	 */
	private ActiveXComponent() {
		super();
	}

	/**
	 * Probably was a cover for something else in the past. Should be
	 * deprecated.
	 * 
	 * @return Now it actually returns this exact same object.
	 */
	public Dispatch getObject() {
		return this;
	}

	/**
	 * Most code should use the standard ActiveXComponent(String) contructor and
	 * not this factory method. This method exists for applications that need
	 * special behavior. <B>Experimental in release 1.9.2.</B>
	 * <p>
	 * Factory that returns a Dispatch object wrapped around the result of a
	 * CoCreate() call. This differs from the standard constructor in that it
	 * throws no exceptions and returns null on failure.
	 * <p>
	 * This will fail for any prog id with a ":" in it.
	 * 
	 * @param pRequestedProgramId
	 * @return Dispatch pointer to the COM object or null if couldn't create
	 */
	public static ActiveXComponent createNewInstance(String pRequestedProgramId) {
		ActiveXComponent mCreatedDispatch = null;
		try {
			mCreatedDispatch = new ActiveXComponent();
			mCreatedDispatch.coCreateInstance(pRequestedProgramId);
		} catch (Exception e) {
			mCreatedDispatch = null;
			if (JacobObject.isDebugEnabled()) {
				JacobObject.debug("Unable to co-create instance of "
						+ pRequestedProgramId);
			}
		}
		return mCreatedDispatch;
	}

	/**
	 * Most code should use the standard ActiveXComponent(String) contructor and
	 * not this factory method. This method exists for applications that need
	 * special behavior. <B>Experimental in release 1.9.2.</B>
	 * <p>
	 * Factory that returns a Dispatch wrapped around the result of a
	 * getActiveObject() call. This differs from the standard constructor in
	 * that it throws no exceptions and returns null on failure.
	 * <p>
	 * This will fail for any prog id with a ":" in it
	 * 
	 * @param pRequestedProgramId
	 * @return Dispatch pointer to a COM object or null if wasn't already
	 *         running
	 */
	public static ActiveXComponent connectToActiveInstance(
			String pRequestedProgramId) {
		ActiveXComponent mCreatedDispatch = null;
		try {
			mCreatedDispatch = new ActiveXComponent();
			mCreatedDispatch.getActiveInstance(pRequestedProgramId);
		} catch (Exception e) {
			mCreatedDispatch = null;
			if (JacobObject.isDebugEnabled()) {
				JacobObject.debug("Unable to attach to running instance of "
						+ pRequestedProgramId);
			}
		}
		return mCreatedDispatch;
	}

	/**
	 * @see com.jacob.com.Dispatch#finalize()
	 */
	protected void finalize() {
		super.finalize();
	}

	/*
	 * ============================================================
	 * 
	 * start of instance based calls to the COM layer
	 * ===========================================================
	 */

	/**
	 * retrieves a property and returns it as a Variant
	 * 
	 * @param propertyName
	 * @return variant value of property
	 */
	public Variant getProperty(String propertyName) {
		return Dispatch.get(this, propertyName);
	}

	/**
	 * retrieves a property and returns it as an ActiveX component
	 * 
	 * @param propertyName
	 * @return Dispatch representing the object under the property name
	 */
	public ActiveXComponent getPropertyAsComponent(String propertyName) {
		return new ActiveXComponent(Dispatch.get(this, propertyName)
				.toDispatch());

	}

	/**
	 * retrieves a property and returns it as a Boolean
	 * 
	 * @param propertyName
	 *            property we are looking up
	 * @return boolean value of property
	 */
	public boolean getPropertyAsBoolean(String propertyName) {
		return Dispatch.get(this, propertyName).getBoolean();
	}

	/**
	 * retrieves a property and returns it as a byte
	 * 
	 * @param propertyName
	 *            property we are looking up
	 * @return byte value of property
	 */
	public byte getPropertyAsByte(String propertyName) {
		return Dispatch.get(this, propertyName).getByte();
	}

	/**
	 * retrieves a property and returns it as a String
	 * 
	 * @param propertyName
	 * @return String value of property
	 */
	public String getPropertyAsString(String propertyName) {
		return Dispatch.get(this, propertyName).getString();

	}

	/**
	 * retrieves a property and returns it as a int
	 * 
	 * @param propertyName
	 * @return the property value as an int
	 */
	public int getPropertyAsInt(String propertyName) {
		return Dispatch.get(this, propertyName).getInt();
	}

	/**
	 * sets a property on this object
	 * 
	 * @param propertyName
	 *            property name
	 * @param arg
	 *            variant value to be set
	 */
	public void setProperty(String propertyName, Variant arg) {
		Dispatch.put(this, propertyName, arg);
	}

	/**
	 * sets a property on this object
	 * 
	 * @param propertyName
	 *            property name
	 * @param arg
	 *            variant value to be set
	 */
	public void setProperty(String propertyName, Dispatch arg) {
		Dispatch.put(this, propertyName, arg);
	}

	/**
	 * sets a property to be the value of the string
	 * 
	 * @param propertyName
	 * @param propertyValue
	 */
	public void setProperty(String propertyName, String propertyValue) {
		this.setProperty(propertyName, new Variant(propertyValue));
	}

	/**
	 * sets a property as a boolean value
	 * 
	 * @param propertyName
	 * @param propValue
	 *            the boolean value we want the prop set to
	 */
	public void setProperty(String propertyName, boolean propValue) {
		this.setProperty(propertyName, new Variant(propValue));
	}

	/**
	 * sets a property as a boolean value
	 * 
	 * @param propertyName
	 * @param propValue
	 *            the boolean value we want the prop set to
	 */
	public void setProperty(String propertyName, byte propValue) {
		this.setProperty(propertyName, new Variant(propValue));
	}

	/**
	 * sets the property as an int value
	 * 
	 * @param propertyName
	 * @param propValue
	 *            the int value we want the prop to be set to.