com.jacob.com
Class DispatchEvents

java.lang.Object
  extended by com.jacob.com.JacobObject
      extended by com.jacob.com.DispatchEvents
Direct Known Subclasses:
ActiveXDispatchEvents

public class DispatchEvents
extends JacobObject

This class creates the scaffolding for event callbacks. Every instance of tis acts as a wrapper around some java object that wants callbacks from the microsoft side. It represents the connection between Java and COM for callbacks.

The callback mechanism will take any event that it receives and try and find a java method with the same name that accepts the Variant... as a parameter. It will then wrap the call back data in the Variant array and call the java method of the object that this DispatchEvents object was initialized with.

Instances of this class are created with "sink object" that will receive the event messages. The sink object is wrapped in an Invocation handler that actually receives the messages and then forwards them on to the "sink object". The constructors recognize when an instance of InvocationProxy is passed in and do not create a new InvocationProxy as a wrapper. They instead use the passed in InvocationProxy.


Constructor Summary
DispatchEvents(Dispatch sourceOfEvent, Object eventSink)
          This is the most commonly used constructor.
DispatchEvents(Dispatch sourceOfEvent, Object eventSink, String progId)
          None of the samples use this constructor.
DispatchEvents(Dispatch sourceOfEvent, Object eventSink, String progId, String typeLib)
          Creates the event callback linkage between the the MS program represented by the Dispatch object and the Java object that will receive the callback.
 
Method Summary
protected  void finalize()
           
protected  InvocationProxy getInvocationProxy(Object pTargetObject)
          Returns an instance of the proxy configured with pTargetObject as its target
 void safeRelease()
          Finalizers call this method.
 
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
 

Constructor Detail

DispatchEvents

public DispatchEvents(Dispatch sourceOfEvent,
                      Object eventSink)
This is the most commonly used constructor.

Creates the event callback linkage between the the MS program represented by the Dispatch object and the Java object that will receive the callback.

Can be used on any object that implements IProvideClassInfo.

Parameters:
sourceOfEvent - Dispatch object who's MS app will generate callbacks
eventSink - Java object that wants to receive the events

DispatchEvents

public DispatchEvents(Dispatch sourceOfEvent,
                      Object eventSink,
                      String progId)
None of the samples use this constructor.

Creates the event callback linkage between the the MS program represented by the Dispatch object and the Java object that will receive the callback.

Used when the program doesn't implement IProvideClassInfo. It provides a way to find the TypeLib in the registry based on the programId. The TypeLib is looked up in the registry on the path HKEY_LOCAL_MACHINE/SOFTWARE/Classes/CLSID/(CLID drived from progid)/ProgID/Typelib

Parameters:
sourceOfEvent - Dispatch object who's MS app will generate callbacks
eventSink - Java object that wants to receive the events
progId - program id in the registry that has a TypeLib subkey. The progrId is mapped to a CLSID that is they used to look up the key to the Typelib

DispatchEvents

public DispatchEvents(Dispatch sourceOfEvent,
                      Object eventSink,
                      String progId,
                      String typeLib)
Creates the event callback linkage between the the MS program represented by the Dispatch object and the Java object that will receive the callback.

This method was added because Excel doesn't implement IProvideClassInfo and the registry entry for Excel.Application doesn't include a typelib key.

 DispatchEvents de = new DispatchEvents(someDispatch, someEventHAndler,
                "Excel.Application",
                "C:\\Program Files\\Microsoft Office\\OFFICE11\\EXCEL.EXE");
 

Parameters:
sourceOfEvent - Dispatch object who's MS app will generate callbacks
eventSink - Java object that wants to receive the events
progId - , mandatory if the typelib is specified
typeLib - The location of the typelib to use
Method Detail

getInvocationProxy

protected InvocationProxy getInvocationProxy(Object pTargetObject)
Returns an instance of the proxy configured with pTargetObject as its target

Parameters:
pTargetObject -
Returns:
InvocationProxy an instance of the proxy this DispatchEvents will send to the COM layer

finalize

protected void finalize()
Overrides:
finalize in class Object

safeRelease

public void safeRelease()
Description copied from class: JacobObject
Finalizers call this method. This method should release any COM data structures in a way that it can be called multiple times. This can happen if someone manually calls this and then a finalizer calls it.

Overrides:
safeRelease in class JacobObject


http://jacob-project.sourceforge.net