From a1d010482634d8ee575d043a2fa6b1c8dab2d277 Mon Sep 17 00:00:00 2001 From: clay_shooter Date: Tue, 14 Feb 2006 04:37:15 +0000 Subject: [PATCH] doc updates to support 1.10 pre3 and the different way we handle event callbacks with InvocationProxy --- docs/EventCallbacks.htm | 213 +++++++++++++++++++++++++--------------- docs/ReleaseNotes.html | 9 +- 2 files changed, 137 insertions(+), 85 deletions(-) diff --git a/docs/EventCallbacks.htm b/docs/EventCallbacks.htm index 078a589..1d4a23a 100644 --- a/docs/EventCallbacks.htm +++ b/docs/EventCallbacks.htm @@ -1,4 +1,5 @@ - @@ -16,8 +17,6 @@ xmlns="http://www.w3.org/TR/REC-html40"> + @@ -188,98 +203,116 @@ is:

 

1)        Application thread creates an instance of the event handler and registers it with Jacob

2)        The application continues on doing other work.

3)        Some time later, the MS application takes some action and initiates the event callback.

4)        The Java VM receives the event and spins up a new thread to handle it.

5)        -The Jacob EventProxy -in the dll is called by the VM.

+The Jacob jni EventProxy in the dll is called by +the VM.

6)        -The Jacob EventProxy -creates Variant objects to handle the parameters of the passed in event.

+The Jacob jni EventProxy creates Variant objects +to handle the parameters of the passed in event.

7)        -The Jacob EventProxy -uses reflection to map the event name to a method name with the exact same -name.

+The Jacob jni EventProxy sends the name of the +callback and the array of Variant objects to the Java  InvocationProxy that was registered to catch +events.

8)        -The Jacob EventProxy -sends the message to the registered event handler.

+The Java InvocationProxy uses reflection to map +the event name to a method name with the exact same name.

+ +

9)        +The Java InvocationProxy sends the message to +the registered event handler and returns if the event handler is of type void +(standard behavior). 

+ +

10)    The +Java InvocationProxy sends the message to the registered event handler and +returns the Variant that resulted from the call back to the Jacob jni +EventProxy that then returns it to the windows calling program.

 

Swing developers should note that this message comes in on a thread other than the event thread.  All objects receiving events that require user intervention or drawing -in the UI should use invokeLater() to post requests for actions onto the event queue.  Failure to do so will insure random failures -in the GUI.

+in the UI should use invokeLater() to post requests for actions onto the event +queue.  Failure to do so will insure random +failures in the GUI.

+ +

 

 

Java Web Start (JWS) and other launchers can have additional issues related to the class loader.  -The Jacob C++ library uses FindClass() to find the Variant class when building the parameter -list.  FindClass() uses the system -class loader which includes only the classes specified at run time or in the -CLASSPATH.  Most of the application -classes in this situation live in an alternate set of class loaders that were -created when the launcher located and ran the application classes.  This means that the search for Variant will -fail usually with the silent and immediate termination of the Java application.  The thread classloader +The Jacob C++ library uses FindClass() to find the Variant class when +building the parameter list.  FindClass() +uses the system class loader which includes only the classes specified at run +time or in the CLASSPATH.  Most of the +application classes in this situation live in an alternate set of class loaders +that were created when the launcher located and ran the application +classes.  This means that the search for +Variant will fail usually with the silent and immediate termination of the Java +application.  The thread classloader probably can’t be used to try and find the class because this new thread does -not have a classloader associated with it other than -the system class loader.  The end result -is that the Variant class needs to be located via other means and that the -thread classloader should be set to be the context -class loader of the event handler class.

+not have a classloader associated with it other than the system class +loader.  The end result is that the +Variant class needs to be located via other means and that the thread +classloader should be set to be the context class loader of the event handler +class.

 

-

The Jacob EventProxy class has -been modified (off of the 1.8 tree) so that it takes a two step approach to -towards fixing these problems.

+

<b>1.8 and 1.9 behavior</b>

+ +

The Jacob EventProxy class has been modified (off of the +1.8 tree) so that it takes a two step approach  towards fixing these problems.

           

@@ -287,28 +320,26 @@ towards fixing these problems.

l0 level1 lfo4;tab-stops:list 42.0pt'>1)        -The EventProxy -constructor now accepts an extra object, an instance of the Variant class.  This gives the EventProxy -a way to get to the Variant class and thus to its classloader. -All of the callers of the constructor have been modified to pass a Variant -object to the EventProxy without programmer -intervention.

+The EventProxy constructor now accepts an extra +object, an instance of the Variant class.  +This gives the EventProxy a way to get to the Variant class and thus to +its classloader. All of the callers of the constructor have been modified to +pass a Variant object to the EventProxy without programmer intervention.

2)        -EventProxy first -attempts to locate the Variant class using FindClass()

+EventProxy first attempts to locate the Variant +class using FindClass()

3)        Failing that, it looks to see if a variant -object had been passed in. If so, it calls class() and -goes from there. 

+object had been passed in. If so, it calls class() and goes from there. 

        If all that fails, it logs a message and then fails in the spectacular fashion of the previous versions.

+

<b>1.10 behavior</b>

+ +

The Jacob EventProxy class has been modified so that it +takes a different approach towards fixing this problem.

+ +

1.    All +objects that request event notification are now wrapped in a Java +InvocationProxy so that a standard interface is always presented to the JNI +EventProxy object.

+ +

2.    The +EventProxy constructor accepts an Java InvocationProxy as the object that will +receive any callbacks for this set of events.

+ +

3.    The +Java InvocationProxy has a method on it that will return the Variant class that +the EventProxy.

+

 

Developers can receive call back events in JWS other Java launching programs without implementing any additional code.  They should be aware that their callback -methods may need to set the class loader.:

+methods may need to set the class loader. If they expect to create any objects.:

-

      Public xxx someHandler(Variant[] -foo){

+

      Public xxx +someHandler(Variant[] foo){

-

            Thread.currentThread().setContextClassLoader(

+

            Thread.currentThread().setContextClassLoader(

-

                  this.getClass().getClassLoader());

+

                  this.getClass().getClassLoader());

            // do something

diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html index 570e408..eb449ed 100644 --- a/docs/ReleaseNotes.html +++ b/docs/ReleaseNotes.html @@ -30,11 +30,10 @@ has been added to the DispatchEvents constructors that lets a user provide the location of the OLB or EXE that contains the information required to retrieve the events. -
  • Event handlers can now return a value to calling MS Windows program. - The event handlers must return an objec of type Variant if they wish to return - a value. All - previous event handlers still work with a void return. (This change should be - backwards compatible) +
  • Event handlers can now return a Variant to calling MS Windows program. + Event handlers that do not return an object should still be defined + as being of type "void". This means that support for event handler's returning + values should be backwards compatible with previous releases.