com.jacob.com

## Class DispatchEvents

- java.lang.Object
- - com.jacob.com.JacobObject
  - - 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

    Constructors
    Constructor and Description
    `DispatchEvents(Dispatch sourceOfEvent, java.lang.Object eventSink)` This is the most commonly used constructor.
    `DispatchEvents(Dispatch sourceOfEvent, java.lang.Object eventSink, java.lang.String progId)` None of the samples use this constructor.
    `DispatchEvents(Dispatch sourceOfEvent, java.lang.Object eventSink, java.lang.String progId, java.lang.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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `finalize()`
    `protected InvocationProxy` | `getInvocationProxy(java.lang.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,
                                java.lang.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,
                                java.lang.Object eventSink,
                                java.lang.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,
                                java.lang.Object eventSink,
                                java.lang.String progId,
                                java.lang.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(java.lang.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 `java.lang.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