org.isis.jaut
Class Dispatch

java.lang.Object
  extended byorg.isis.jaut.ApartmentObject
      extended byorg.isis.jaut.Dispatch
Direct Known Subclasses:
MgaAddOn, MgaAddOns, MgaAttribute, MgaAttributes, MgaComponent, MgaComponents, MgaConnPoint, MgaConnPoints, MgaConstraint, MgaConstraints, MgaFCOs, MgaFilter, MgaFolders, MgaMetaAspects, MgaMetaAttributes, MgaMetaBase, MgaMetaConnJoint, MgaMetaConnJoints, MgaMetaEnumItem, MgaMetaEnumItems, MgaMetaFCOs, MgaMetaFolders, MgaMetaModels, MgaMetaParts, MgaMetaPointerItem, MgaMetaPointerItems, MgaMetaPointerSpec, MgaMetaPointerSpecs, MgaMetaProject, MgaMetaRegNode, MgaMetaRegNodes, MgaMetaRoles, MgaObject, MgaObjects, MgaPart, MgaParts, MgaProject, MgaRegNode, MgaRegNodes, MgaTerritories, MgaTerritory

public class Dispatch
extends ApartmentObject

The Dispatch class enables Java programs to invoke methods and access properties of an Automation object. Embedded in the class, there is an IDispatch interface pointer. The methods of this class should be called always from the same thread (or from the same Apartment).


Field Summary
static int CLSCTX_INPROC_HANDLER
          A class context allowing in-process handlers.
static int CLSCTX_INPROC_SERVER
          A class context allowing in-process servers.
static int CLSCTX_LOCAL_SERVER
          A class context allowing local servers.
static int DISPATCH_METHOD
          The member is invoked as a method.
static int DISPATCH_PROPERTYGET
          The member is retrived as a property or data member.
static int DISPATCH_PROPERTYPUT
          The member is changed as a property or data member.
static int DISPATCH_PROPERTYPUTREF
          The member is changed by a reference assignment.
static int DISPID_EVALUATE
          The dispatch ID of the standard "Evaluate" property.
static int DISPID_PROPERTYPUT
          The dispatch ID of the return value named argument.
static int DISPID_VALUE
          The dispatch ID of the standard "Value" property.
 int pDispatch
          This holds an IDispatch interface pointer.
 
Fields inherited from class org.isis.jaut.ApartmentObject
apartment
 
Constructor Summary
Dispatch()
          Creates a NULL Dispatch object.
Dispatch(int target)
          Creates a Dispatch object pointing to the given target interface pointer.
Dispatch(Variant target)
          Creates a Dispatch object from a Variant.
 
Method Summary
 void attach(Dispatch target)
          Sets the interface pointer of the Dispatch object to the interface pointer stored in target.
 void attach(int target)
          Sets the interface pointer of the given interface pointer stored in target.
 void attach(Variant target)
          Sets the interface pointer of the Dispatch object to the interface pointer stored in the Variant.
 void attachActiveObject(java.lang.String progID)
          Sets the interface pointer of the Dispatch object to a running object.
 void attachNewInstance(java.lang.String progID, int context)
          Creates an Automation object of a given program ID, and attaches this Dispatch object to it.
 java.lang.Object call(java.lang.String dispName)
          Invokes an Automation method with no argument.
 java.lang.Object call(java.lang.String dispName, java.lang.Object arg0)
          Invokes an Automation method with one argument.
 java.lang.Object call(java.lang.String dispName, java.lang.Object[] args)
          Invokes an Automation method with a list of arguments.
 java.lang.Object call(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1)
          Invokes an Automation method with two arguments.
 java.lang.Object call(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2)
          Invokes an Automation method with three arguments.
 java.lang.Object call(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3)
          Invokes an Automation method with four arguments.
 void callSub(java.lang.String dispName)
          Invokes an Automation subrutine with no argument.
 void callSub(java.lang.String dispName, java.lang.Object arg0)
          Invokes an Automation subrutine with one argument.
 void callSub(java.lang.String dispName, java.lang.Object[] args)
          Invokes an Automation subrutine with a list of arguments.
 void callSub(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1)
          Invokes an Automation subrutine with two arguments.
 void callSub(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2)
          Invokes an Automation subrutine with three arguments.
 void changeInterface(java.lang.String iID)
          Changes the embedded interface pointer to another interface pointer on the same Automation object.
 java.lang.Object clone()
          Returns a clone of this object.
static Dispatch createInstance(java.lang.String progID, int context)
          Creates an Automation object of a given program ID and returns the new Dispatch object.
 boolean equals(java.lang.Object target)
          Tests if target is a Dispatch object referring to the same Automation object as this object.
 void finalize()
          Clears and releases the Dispatch object, can be called from any Thread.
 java.lang.Object get(java.lang.String dispName)
          Retrives an Automation property.
 java.lang.Object get(java.lang.String dispName, java.lang.Object arg0)
          Retrives an Automation property with one argument.
 int getIDOfName(java.lang.String name)
          Maps a member name to a dispatch ID.
 int[] getIDsOfNames(java.lang.String[] names)
          Maps a single member and an optional set of argument names to the corresponding list of integer dispatch IDs.
 int hashCode()
          Returns a hash code value for the object.
 void invoke(int dispID, int dispFlags, Variant[] arguments, int[] namedArgDispIDs, Variant retval)
          Invokes a method, or sets or retrives a property of an Automation object.
 java.lang.Object invoke(java.lang.String dispName, int dispFlags, java.lang.Object[] arguments, int[] namedArgDispIDs)
          Invokes a method, or retrives a property of an Automation object.
 void invokeSub(java.lang.String dispName, int dispFlags, java.lang.Object[] arguments, int[] namedArgDispIDs)
          Invokes a subrutine, or sets a property of an Automation object.
 boolean isNull()
          Tests if the embedded IDispatch interface pointer is NULL.
 void put(java.lang.String dispName, java.lang.Object value)
          Sets an Automation property.
 void put(java.lang.String dispName, java.lang.Object arg0, java.lang.Object value)
          Sets an Automation property with one argument.
 void putRef(java.lang.String dispName, java.lang.Object value)
          Sets an Automation property by reference.
 void putRef(java.lang.String dispName, java.lang.Object arg0, java.lang.Object value)
          Sets an Automation property with one argument by reference.
 Dispatch queryInterface(java.lang.String iID)
          Returns a new Dispatch object with another interface pointer to the same Automation object.
 void release()
          Releases the interface pointer of the Dispatch object.
 
Methods inherited from class org.isis.jaut.ApartmentObject
finalizeInApartment, getApartment
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

pDispatch

public int pDispatch
This holds an IDispatch interface pointer.


CLSCTX_INPROC_SERVER

public static final int CLSCTX_INPROC_SERVER
A class context allowing in-process servers. The code that creates and manages objects of this class run in the same process as the caller.

See Also:
attachNewInstance(java.lang.String, int), Constant Field Values

CLSCTX_INPROC_HANDLER

public static final int CLSCTX_INPROC_HANDLER
A class context allowing in-process handlers. An in-process DLL is managing the remote access of objects of this class.

See Also:
attachNewInstance(java.lang.String, int), Constant Field Values

CLSCTX_LOCAL_SERVER

public static final int CLSCTX_LOCAL_SERVER
A class context allowing local servers. The code that creates and manages obejcts of this class is an executable EXE running in a separate process on the same machine.

See Also:
attachNewInstance(java.lang.String, int), Constant Field Values

DISPID_VALUE

public static final int DISPID_VALUE
The dispatch ID of the standard "Value" property.

See Also:
Constant Field Values

DISPID_PROPERTYPUT

public static final int DISPID_PROPERTYPUT
The dispatch ID of the return value named argument.

See Also:
Constant Field Values

DISPID_EVALUATE

public static final int DISPID_EVALUATE
The dispatch ID of the standard "Evaluate" property.

See Also:
Constant Field Values

DISPATCH_METHOD

public static final int DISPATCH_METHOD
The member is invoked as a method. If a property has the same name, both this and DISPATCH_PROPERTYGET flag may be set.

See Also:
invoke, Constant Field Values

DISPATCH_PROPERTYGET

public static final int DISPATCH_PROPERTYGET
The member is retrived as a property or data member. If a method has the same name, both this and DISPATCH_METHOD flag may be set.

See Also:
invoke, Constant Field Values

DISPATCH_PROPERTYPUT

public static final int DISPATCH_PROPERTYPUT
The member is changed as a property or data member.

See Also:
invoke, Constant Field Values

DISPATCH_PROPERTYPUTREF

public static final int DISPATCH_PROPERTYPUTREF
The member is changed by a reference assignment.

See Also:
invoke, Constant Field Values
Constructor Detail

Dispatch

public Dispatch()
Creates a NULL Dispatch object. The interface pointer of the Dispatch object must be set to a non-NULL value before any other method can be invoked.

See Also:
attach(Variant), attach(Dispatch)

Dispatch

public Dispatch(int target)
Creates a Dispatch object pointing to the given target interface pointer.


Dispatch

public Dispatch(Variant target)
         throws ComException
Creates a Dispatch object from a Variant.

Parameters:
target - a Variant holding an interface pointer to an Automation object.
See Also:
Variant.getDispatch(), attach(Variant)
Method Detail

isNull

public boolean isNull()
Tests if the embedded IDispatch interface pointer is NULL.

Returns:
true if the embedded IDispatch interface pointer is NULL, false otherwise.
See Also:
attach(Variant), attach(Dispatch)

attach

public void attach(Variant target)
            throws ComException
Sets the interface pointer of the Dispatch object to the interface pointer stored in the Variant. If the target Variant holds an IUnknown interface pointer, the IUnknown::QueryInterface method is used to get the IDispatch pointer. COM object references are managed according to the COM rules using the IUnknown::AddRef and IUnknown::Release methods.

Parameters:
target - a Variant of type VT_DISPATCH, VT_DISPATCH|VT_BYREF, VT_UNKNOWN or VT_UNKNOWN|VT_BYREF holding the new interface pointer.
Throws:
ComException - is the IUnknown::QueryInterface method fails.
JAutException - if the target Variant does not have its underlying VARIANT created, or it is not of the porper type.

attach

public void attach(Dispatch target)
Sets the interface pointer of the Dispatch object to the interface pointer stored in target. COM object references are managed according to the COM rules using the IUnknown::AddRef and IUnknown::Release methods.

Parameters:
target - a Dispatch object holding the new interface pointer.

attach

public void attach(int target)
Sets the interface pointer of the given interface pointer stored in target. COM object references are managed according to the COM rules using the IUnknown::AddRef and IUnknown::Release methods.

Parameters:
target - an integer representation if the new interface pointer.

release

public void release()
Releases the interface pointer of the Dispatch object. If the interface pointer is not NULL, it is released using the IDispatch::Release method. Then the embedded interface pointer is set to NULL.

Specified by:
release in class ApartmentObject

finalize

public void finalize()
Clears and releases the Dispatch object, can be called from any Thread. Calls the #releaseInApartment method if the underlying interface pointer is not NULL.


clone

public java.lang.Object clone()
Returns a clone of this object. The copy will have the same IDispatch interface pointer, and the reference count is incremented using the IDispatch::AddRef method.

Returns:
the clone of this object, which is of type Dispatch.

hashCode

public int hashCode()
Returns a hash code value for the object. The actual returned value is the IUnknown interface pointer of this Dispatch object, obtained by using the IUnknow::QueryInterface method.

Returns:
a hash code value for this object.

equals

public boolean equals(java.lang.Object target)
Tests if target is a Dispatch object referring to the same Automation object as this object.

Returns:
true if target is a Dispatch object referring to the same Automation object as this object, false otherwise.

changeInterface

public void changeInterface(java.lang.String iID)
                     throws ComException
Changes the embedded interface pointer to another interface pointer on the same Automation object. This method uses the IIDFromString and IUnknown::QueryInterface Automation functions.

Parameters:
iID - the interface ID of the new interface, in the format of "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}". The retrived interface must be derived from IDispatch.
Throws:
JAutException - if the current interface pointer of this object is NULL.
ComException - if either IIDFromString or IUnknown::QueryInterface fails.

queryInterface

public Dispatch queryInterface(java.lang.String iID)
                        throws ComException
Returns a new Dispatch object with another interface pointer to the same Automation object.

Parameters:
iID - the interface ID of the new interface, in the format of "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}". The retrived interface must be derived from IDispatch.
Throws:
JAutException - if the current interface pointer of this object is NULL.
ComException - if either IIDFromString or IUnknown::QueryInterface fails.
See Also:
changeInterface(java.lang.String)

attachNewInstance

public void attachNewInstance(java.lang.String progID,
                              int context)
                       throws ComException
Creates an Automation object of a given program ID, and attaches this Dispatch object to it. First, the existing interface pointer is released. Then the program ID is transformed to the class ID (CLSID) of the COM class that will create the Automation object using the CLSIDFromProgID Automation function. Finally, the CoCreateInstance Automation function is invoked.

Parameters:
progID - the program ID of the Automation object to be created.
context - the in which the code that manages the newly created object will run. Acceptable values are combined from the CLSCTX_XXX constants.
Throws:
ComException - if either CLSIDFromProgID or CoCreateInstance fails.
See Also:
createInstance(java.lang.String, int)

createInstance

public static Dispatch createInstance(java.lang.String progID,
                                      int context)
                               throws ComException
Creates an Automation object of a given program ID and returns the new Dispatch object.

Parameters:
progID - the program ID of the Automation object to be created.
context - the in which the code that manages the newly created object will run. Acceptable values are combined from the CLSCTX_XXX constants.
Throws:
ComException
See Also:
attachNewInstance(java.lang.String, int)

attachActiveObject

public void attachActiveObject(java.lang.String progID)
                        throws ComException
Sets the interface pointer of the Dispatch object to a running object. First, the existing interface pointer is release. Second, the program ID is transformed to a class ID using the CLSIDFromProgID Automation function. Then the GetActiveObject and IUnknown::QueryInterface methods are called to retrive the IDispatch interface pointer of the active object.

Parameters:
progID - the program ID of the active object that has been registered.
Throws:
ComException - if one of the Automation functions fails.

getIDsOfNames

public int[] getIDsOfNames(java.lang.String[] names)
Maps a single member and an optional set of argument names to the corresponding list of integer dispatch IDs. This method is a direct wrapper around the IDispatch::GetIDsOfNames Automation function.

Parameters:
names - a list of names, the first is the name of an interface member (property or method), and the rest are parameters names.
Returns:
a list of dispatch IDs, one for each of the names. The dispatch IDs of interface members are relative to the corresponding Dispatch object, while the dispatch IDs of parameters are relative to the interface member.
Throws:
JAutException - if the current interface pointer of this object is NULL.
ComException - if IDispatch::GetIDsOfNames fails.
See Also:
getIDOfName(java.lang.String)

getIDOfName

public int getIDOfName(java.lang.String name)
Maps a member name to a dispatch ID. This method is a direct wrapper around the IDispatch::GetIDsOfNames Automation function.

Parameters:
name - the name of an interface member (property or method).
Returns:
the dispatch ID of the interface member.
Throws:
JAutException - if the current interface pointer of this object is NULL.
ComException - if IDispatch::GetIDsOfNames fails.
See Also:
getIDsOfNames(java.lang.String[])

invoke

public void invoke(int dispID,
                   int dispFlags,
                   Variant[] arguments,
                   int[] namedArgDispIDs,
                   Variant retval)
Invokes a method, or sets or retrives a property of an Automation object. This method is a direct wrapper around the IDispatch::Invoke Automation function.

Parameters:
dispID - the dispatch ID of the method or property to be invoked.
dispFlags - flags selecting the type of access. Acceptable values are DISPATCH_METHOD, DISPATCH_PROPERTYGET, DISPATCH_PROPERTYPUT and DISPATCH_PROPERTYPUTREF.
arguments - the arguments of the method or property. This can be null if there are no arguments. If an element of the arguements list is null, or its underlying VARIANT is not created, then that parameter will be passed as an DISP_E_PARAMNOTFOUND value of type VT_ERROR.
namedArgDispIDs - a list of dispatch IDs for named arguments. This can be null indicating that there are no named arguments.
retval - the Variant where the result is to be stored. This can be null if there is no return value, or the caller is not interested in the return value.
Throws:
JAutException - if the current interface pointer of this object is NULL.
ComException - if IDispatch::Invoke fails. Note, that when the COM error code is DISP_E_PARAMNOTFOUND or DISP_E_TYPEMISMATCH, then the index of the illegal argument is not returned to the invoker.
See Also:
getIDsOfNames(java.lang.String[])

invoke

public java.lang.Object invoke(java.lang.String dispName,
                               int dispFlags,
                               java.lang.Object[] arguments,
                               int[] namedArgDispIDs)
                        throws ComException
Invokes a method, or retrives a property of an Automation object. First, the the non-null arguments are converted to Variants with the Variant.Variant(Object) constructor, then invoke(int, int, Variant[], int[], Variant) is called. Note, that if an argument is of type Variant, then the invoked method will receive a reference created by Variant.Variant(Variant).

Parameters:
dispName - the name of the method or property.
dispFlags - the type of access.
arguments - the list of arguments.
namedArgDispIDs - a list of dispatch IDs for named arguments.
Returns:
the returned value converted to an Object.
Throws:
ComException

invokeSub

public void invokeSub(java.lang.String dispName,
                      int dispFlags,
                      java.lang.Object[] arguments,
                      int[] namedArgDispIDs)
Invokes a subrutine, or sets a property of an Automation object. First, the the non-null arguments are converted to Variants with the Variant.Variant(Object) constructor, then invoke(int, int, Variant[], int[], Variant) is called. Note, that if an argument is of type Variant, then the invoked method will receive a reference created by Variant.Variant(Variant).

Parameters:
dispName - the name of the method or property.
dispFlags - the type of access.
arguments - the list of arguments.
namedArgDispIDs - a list of dispatch IDs for named arguments.

call

public java.lang.Object call(java.lang.String dispName)
Invokes an Automation method with no argument.

See Also:
invoke(String, int, Object[], int[])

call

public java.lang.Object call(java.lang.String dispName,
                             java.lang.Object arg0)
Invokes an Automation method with one argument.

See Also:
invoke(String, int, Object[], int[])

call

public java.lang.Object call(java.lang.String dispName,
                             java.lang.Object arg0,
                             java.lang.Object arg1)
Invokes an Automation method with two arguments.

See Also:
invoke(String, int, Object[], int[])

call

public java.lang.Object call(java.lang.String dispName,
                             java.lang.Object arg0,
                             java.lang.Object arg1,
                             java.lang.Object arg2)
Invokes an Automation method with three arguments.

See Also:
invoke(String, int, Object[], int[])

call

public java.lang.Object call(java.lang.String dispName,
                             java.lang.Object arg0,
                             java.lang.Object arg1,
                             java.lang.Object arg2,
                             java.lang.Object arg3)
Invokes an Automation method with four arguments.

See Also:
invoke(String, int, Object[], int[])

call

public java.lang.Object call(java.lang.String dispName,
                             java.lang.Object[] args)
Invokes an Automation method with a list of arguments.

See Also:
invoke(String, int, Object[], int[])

callSub

public void callSub(java.lang.String dispName)
Invokes an Automation subrutine with no argument.

See Also:
invokeSub(String, int, Object[], int[])

callSub

public void callSub(java.lang.String dispName,
                    java.lang.Object arg0)
Invokes an Automation subrutine with one argument.

See Also:
invokeSub(String, int, Object[], int[])

callSub

public void callSub(java.lang.String dispName,
                    java.lang.Object arg0,
                    java.lang.Object arg1)
Invokes an Automation subrutine with two arguments.

See Also:
invokeSub(String, int, Object[], int[])

callSub

public void callSub(java.lang.String dispName,
                    java.lang.Object arg0,
                    java.lang.Object arg1,
                    java.lang.Object arg2)
Invokes an Automation subrutine with three arguments.

See Also:
invokeSub(String, int, Object[], int[])

callSub

public void callSub(java.lang.String dispName,
                    java.lang.Object[] args)
Invokes an Automation subrutine with a list of arguments.

See Also:
invokeSub(String, int, Object[], int[])

get

public java.lang.Object get(java.lang.String dispName)
Retrives an Automation property.

See Also:
invoke(String, int, Object[], int[])

get

public java.lang.Object get(java.lang.String dispName,
                            java.lang.Object arg0)
Retrives an Automation property with one argument.

See Also:
invoke(String, int, Object[], int[])

put

public void put(java.lang.String dispName,
                java.lang.Object value)
Sets an Automation property.

See Also:
invokeSub(String, int, Object[], int[])

put

public void put(java.lang.String dispName,
                java.lang.Object arg0,
                java.lang.Object value)
Sets an Automation property with one argument.

See Also:
invokeSub(String, int, Object[], int[])

putRef

public void putRef(java.lang.String dispName,
                   java.lang.Object value)
Sets an Automation property by reference.

See Also:
invokeSub(String, int, Object[], int[])

putRef

public void putRef(java.lang.String dispName,
                   java.lang.Object arg0,
                   java.lang.Object value)
Sets an Automation property with one argument by reference.

See Also:
invokeSub(String, int, Object[], int[])