com.jacob.activeX

Class ActiveXComponent

java.lang.Object

com.jacob.com.JacobObject

com.jacob.com.Dispatch

com.jacob.activeX.ActiveXComponent

public class ActiveXComponent
extends Dispatch

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.

It is really up to the developer as to whether they want to use the Dispatch interface or the ActiveXComponent interface.

This class simulates com.ms.activeX.ActiveXComponent only in the sense that it is used for creating Dispatch objects

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	shouldLogEvents This boolean determines if callback events should be logged

Fields inherited from class com.jacob.com.Dispatch

fdexNameCaseSensitive, Get, LOCALE_SYSTEM_DEFAULT, m_pDispatch, Method, Put, PutRef

Constructor Summary

Constructors

Constructor and Description
ActiveXComponent(Dispatch dispatchToBeWrapped) Creates an active X component that is built on top of the COM pointers held in the passed in dispatch.
ActiveXComponent(java.lang.String programId) Normally used to create a new connection to a microsoft application.

Method Summary

Modifier and Type	Method and Description
static ActiveXComponent	connectToActiveInstance(java.lang.String pRequestedProgramId) Most code should use the standard ActiveXComponent(String) constructor and not this factory method.
static ActiveXComponent	createNewInstance(java.lang.String pRequestedProgramId) Most code should use the standard ActiveXComponent(String) contructor and not this factory method.
protected void	finalize()
Dispatch	getObject() Probably was a cover for something else in the past.
Variant	getProperty(java.lang.String propertyName) retrieves a property and returns it as a Variant
boolean	getPropertyAsBoolean(java.lang.String propertyName) retrieves a property and returns it as a Boolean
byte	getPropertyAsByte(java.lang.String propertyName) retrieves a property and returns it as a byte
ActiveXComponent	getPropertyAsComponent(java.lang.String propertyName) retrieves a property and returns it as an ActiveX component
int	getPropertyAsInt(java.lang.String propertyName) retrieves a property and returns it as a int
java.lang.String	getPropertyAsString(java.lang.String propertyName) retrieves a property and returns it as a String
Variant	invoke(java.lang.String callAction) makes a dispatch call for the passed in action and no parameter
Variant	invoke(java.lang.String actionCommand, boolean parameter) makes a dispatch call to the passed in action with a single boolean parameter
Variant	invoke(java.lang.String actionCommand, int parameter) makes a dispatch call to the passed in action with a single int parameter
Variant	invoke(java.lang.String actionCommand, int parameter1, int parameter2) makes a dispatch call to the passed in action with two integer parameters (this was put in for some application)
Variant	invoke(java.lang.String actionCommand, java.lang.String parameter) invokes a single parameter call on this dispatch that returns no value
Variant	invoke(java.lang.String actionCommand, java.lang.String parameter1, int parameter2) makes a dispatch call to the passed in action with a string and integer parameter (this was put in for some application)
Variant	invoke(java.lang.String name, Variant... args) This is really a cover for call(String,Variant[]) that should be eliminated call with a variable number of args mainly used for quit.
ActiveXComponent	invokeGetComponent(java.lang.String callAction) makes a dispatch call for the passed in action and no parameter
ActiveXComponent	invokeGetComponent(java.lang.String callAction, Variant... parameters) makes a dispatch call for the passed in action and single parameter
void	logCallbackEvent(java.lang.String description, Variant[] args) used by the doc and application listeners to get intelligent logging
void	setProperty(java.lang.String propertyName, boolean propValue) sets a property as a boolean value
void	setProperty(java.lang.String propertyName, byte propValue) sets a property as a boolean value
void	setProperty(java.lang.String propertyName, Dispatch arg) sets a property on this object
void	setProperty(java.lang.String propertyName, int propValue) sets the property as an int value
void	setProperty(java.lang.String propertyName, java.lang.String propertyValue) sets a property to be the value of the string
void	setProperty(java.lang.String propertyName, Variant arg) sets a property on this object

Methods inherited from class com.jacob.com.Dispatch

call, call, call, call, callN_CaseSensitive, callN, callN, callSub, callSub, callSub, callSub, callSubN, callSubN, coCreateInstance, get_CaseSensitive, get, get, getActiveInstance, getIDOfName, getIDsOfNames, getIDsOfNames, getProgramId, hasExited, hasExited, invoke, invoke, invoke, invokeSub, invokeSub, invokeSub, invokeSubv, invokeSubv, invokeSubv, invokev, invokev, invokev, invokev, isAttached, put_Casesensitive, put, put, putRef, putRef, QueryInterface, safeRelease

Methods inherited from class com.jacob.com.JacobObject

debug, getBuildDate, getBuildVersion, isDebugEnabled

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

shouldLogEvents

public static boolean shouldLogEvents

This boolean determines if callback events should be logged

Constructor Detail

ActiveXComponent

public ActiveXComponent(java.lang.String programId)

Normally used to create a new connection to a microsoft application. The passed in parameter is the name of the program as registered in the registry. It can also be the object name.

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.

 new ActiveXComponent("ScriptControl");
 

Parameters:

programId - the registry identifer for the target

ActiveXComponent

public ActiveXComponent(Dispatch dispatchToBeWrapped)

Creates an active X component that is built on top of the COM pointers held in the passed in dispatch. This widens the Dispatch object to pick up the ActiveXComponent API

Parameters:

dispatchToBeWrapped - - can wrap an ActiveXComponent around a dispatch

Method Detail

getObject

public Dispatch getObject()

Probably was a cover for something else in the past. Should be deprecated.

Returns:

Now it actually returns this exact same object.

createNewInstance

public static ActiveXComponent createNewInstance(java.lang.String pRequestedProgramId)

Most code should use the standard ActiveXComponent(String) contructor and not this factory method. This method exists for applications that need special behavior. Experimental in release 1.9.2.

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.

This will fail for any prog id with a ":" in it.

Parameters:

pRequestedProgramId - the program id from the registry

Returns:

Dispatch pointer to the COM object or null if couldn't create

connectToActiveInstance

public static ActiveXComponent connectToActiveInstance(java.lang.String pRequestedProgramId)

Most code should use the standard ActiveXComponent(String) constructor and not this factory method. This method exists for applications that need special behavior. Experimental in release 1.9.2.

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.

This will fail for any prog id with a ":" in it

Parameters:

pRequestedProgramId - the regsistry program id

Returns:

Dispatch pointer to a COM object or null if wasn't already running

finalize

protected void finalize()

Overrides:

finalize in class Dispatch

See Also:

Dispatch.finalize()

getProperty

public Variant getProperty(java.lang.String propertyName)

retrieves a property and returns it as a Variant

Parameters:

propertyName - the property name

Returns:

variant value of property

getPropertyAsComponent

public ActiveXComponent getPropertyAsComponent(java.lang.String propertyName)

retrieves a property and returns it as an ActiveX component

Parameters:

propertyName - the property name

Returns:

Dispatch representing the object under the property name

getPropertyAsBoolean

public boolean getPropertyAsBoolean(java.lang.String propertyName)

retrieves a property and returns it as a Boolean

Parameters:

propertyName - the property name property we are looking up

Returns:

boolean value of property

getPropertyAsByte

public byte getPropertyAsByte(java.lang.String propertyName)

retrieves a property and returns it as a byte

Parameters:

propertyName - the property name property we are looking up

Returns:

byte value of property

getPropertyAsString

public java.lang.String getPropertyAsString(java.lang.String propertyName)

retrieves a property and returns it as a String

Parameters:

propertyName - the property name

Returns:

String value of property

getPropertyAsInt

public int getPropertyAsInt(java.lang.String propertyName)

retrieves a property and returns it as a int

Parameters:

propertyName - the property name

Returns:

the property value as an int

setProperty

public void setProperty(java.lang.String propertyName,
                        Variant arg)

sets a property on this object

Parameters:

propertyName - property name

arg - variant value to be set

setProperty

public void setProperty(java.lang.String propertyName,
                        Dispatch arg)

sets a property on this object

Parameters:

propertyName - property name

arg - variant value to be set

setProperty

public void setProperty(java.lang.String propertyName,
                        java.lang.String propertyValue)

sets a property to be the value of the string

Parameters:

propertyName - the property name

propertyValue - the new value

setProperty

public void setProperty(java.lang.String propertyName,
                        boolean propValue)

sets a property as a boolean value

Parameters:

propertyName - the property name

propValue - the boolean value we want the prop set to

setProperty

public void setProperty(java.lang.String propertyName,
                        byte propValue)

sets a property as a boolean value

Parameters:

propertyName - the property value

propValue - the boolean value we want the prop set to

setProperty

public void setProperty(java.lang.String propertyName,
                        int propValue)

sets the property as an int value

Parameters:

propertyName - the property name

propValue - the int value we want the prop to be set to.

logCallbackEvent

public void logCallbackEvent(java.lang.String description,
                             Variant[] args)

used by the doc and application listeners to get intelligent logging

Parameters:

description - event description

args - args passed in (variants)

invokeGetComponent

public ActiveXComponent invokeGetComponent(java.lang.String callAction)

makes a dispatch call for the passed in action and no parameter

Parameters:

callAction - the action to be called

Returns:

ActiveXComponent representing the results of the call

invokeGetComponent

public ActiveXComponent invokeGetComponent(java.lang.String callAction,
                                           Variant... parameters)

makes a dispatch call for the passed in action and single parameter

Parameters:

callAction - the action to be passed in

parameters - this looks plural..

Returns:

ActiveXComponent representing the results of the call

invoke

public Variant invoke(java.lang.String actionCommand,
                      java.lang.String parameter)

invokes a single parameter call on this dispatch that returns no value

Parameters:

actionCommand - the call name

parameter - the String parameter

Returns:

a Variant but that may be null for some calls

invoke

public Variant invoke(java.lang.String actionCommand,
                      boolean parameter)

makes a dispatch call to the passed in action with a single boolean parameter

Parameters:

actionCommand - the call name

parameter - the boolean parameter

Returns:

Variant result

invoke

public Variant invoke(java.lang.String actionCommand,
                      int parameter)

makes a dispatch call to the passed in action with a single int parameter

Parameters:

actionCommand - the command

parameter - the int parameter

Returns:

Variant result of the invoke (Dispatch.call)

invoke

public Variant invoke(java.lang.String actionCommand,
                      java.lang.String parameter1,
                      int parameter2)

makes a dispatch call to the passed in action with a string and integer parameter (this was put in for some application)

Parameters:

actionCommand - command that requires a string and int vlaues

parameter1 - the string parameter

parameter2 - the int parameter

Returns:

Variant result

invoke

public Variant invoke(java.lang.String actionCommand,
                      int parameter1,
                      int parameter2)

makes a dispatch call to the passed in action with two integer parameters (this was put in for some application)

Parameters:

actionCommand - the action that accepts 2 int parmaeters

parameter1 - first of two int parameters

parameter2 - the second of two int parameters

Returns:

a Variant but that may be null for some calls

invoke

public Variant invoke(java.lang.String callAction)

makes a dispatch call for the passed in action and no parameter

Parameters:

callAction - action name that requires zero parameters

Returns:

a Variant but that may be null for some calls

invoke

public Variant invoke(java.lang.String name,
                      Variant... args)

This is really a cover for call(String,Variant[]) that should be eliminated call with a variable number of args mainly used for quit.

Parameters:

name - the name we are invoking

args - a single arg

Returns:

Variant returned by the invoke (Dispatch.callN)