doc updates to support 1.10 pre3 and the different way we handle event callbacks with InvocationProxy

This commit is contained in:
clay_shooter
2006-02-14 04:37:15 +00:00
parent 15c53120bc
commit a1d0104826
2 changed files with 137 additions and 85 deletions

View File

@@ -1,4 +1,5 @@
<html xmlns:o="urn:schemas-microsoft-com:office:office"
<html xmlns:v="urn:schemas-microsoft-com:vml"
xmlns:o="urn:schemas-microsoft-com:office:office"
xmlns:w="urn:schemas-microsoft-com:office:word"
xmlns="http://www.w3.org/TR/REC-html40">
@@ -16,8 +17,6 @@ xmlns="http://www.w3.org/TR/REC-html40">
</xml><![endif]--><!--[if gte mso 9]><xml>
<w:WordDocument>
<w:DisplayBackgroundShape/>
<w:SpellingState>Clean</w:SpellingState>
<w:GrammarState>Clean</w:GrammarState>
<w:ValidateAgainstSchemas/>
<w:SaveIfXMLInvalid>false</w:SaveIfXMLInvalid>
<w:IgnoreMixedContent>false</w:IgnoreMixedContent>
@@ -50,12 +49,6 @@ p.MsoPlainText, li.MsoPlainText, div.MsoPlainText
font-size:10.0pt;
font-family:"Courier New";
mso-fareast-font-family:"Times New Roman";}
span.SpellE
{mso-style-name:"";
mso-spl-e:yes;}
span.GramE
{mso-style-name:"";
mso-gram-e:yes;}
@page Section1
{size:8.5in 11.0in;
margin:1.0in 65.95pt 1.0in 65.95pt;
@@ -108,47 +101,64 @@ div.Section1
mso-level-number-position:left;
text-indent:-.25in;}
@list l1
{mso-list-id:638341914;
mso-list-type:hybrid;
mso-list-template-ids:-1620437462 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l1:level1
{mso-level-tab-stop:.75in;
mso-level-number-position:left;
margin-left:.75in;
text-indent:-.25in;}
@list l2
{mso-list-id:1316765558;
mso-list-type:hybrid;
mso-list-template-ids:860497186 -1920937264 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l1:level1
@list l2:level1
{mso-level-text:"%1\)";
mso-level-tab-stop:42.0pt;
mso-level-number-position:left;
margin-left:42.0pt;
text-indent:-24.0pt;}
@list l1:level2
@list l2:level2
{mso-level-tab-stop:1.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level3
@list l2:level3
{mso-level-tab-stop:1.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level4
@list l2:level4
{mso-level-tab-stop:2.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level5
@list l2:level5
{mso-level-tab-stop:2.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level6
@list l2:level6
{mso-level-tab-stop:3.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level7
@list l2:level7
{mso-level-tab-stop:3.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level8
@list l2:level8
{mso-level-tab-stop:4.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level9
@list l2:level9
{mso-level-tab-stop:4.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l3
{mso-list-id:1718122875;
mso-list-type:hybrid;
mso-list-template-ids:-1873125376 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l3:level1
{mso-level-tab-stop:.5in;
mso-level-number-position:left;
text-indent:-.25in;}
ol
{margin-bottom:0in;}
ul
@@ -174,7 +184,12 @@ ul
mso-fareast-language:#0400;
mso-bidi-language:#0400;}
</style>
<![endif]-->
<![endif]--><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="2050"/>
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1"/>
</o:shapelayout></xml><![endif]-->
</head>
<body lang=EN-US style='tab-interval:.5in'>
@@ -188,98 +203,116 @@ is:</p>
<p class=MsoPlainText><o:p>&nbsp;</o:p></p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l1 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>1)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>Application thread creates an instance of the
event handler and registers it with Jacob</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l1 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>2)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>The application continues on doing other work.</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l1 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>3)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>Some time later, the MS application takes some
action and initiates the event callback.</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l1 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>4)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>The Java VM receives the event and spins up a
new thread to handle it.</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l1 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>5)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>The Jacob <span class=SpellE>EventProxy</span>
in the <span class=SpellE>dll</span> is called by the VM.</p>
</span></span></span><![endif]>The Jacob jni EventProxy in the dll is called by
the VM.</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l1 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>6)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>The Jacob <span class=SpellE>EventProxy</span>
creates Variant objects to handle the parameters of the passed in event.</p>
</span></span></span><![endif]>The Jacob jni EventProxy creates Variant objects
to handle the parameters of the passed in event.</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l1 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>7)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>The Jacob <span class=SpellE>EventProxy</span>
uses reflection to map the event name to a method name with the exact same
name.</p>
</span></span></span><![endif]>The Jacob jni EventProxy sends the name of the
callback and the array of Variant objects to the Java<span
style='mso-spacerun:yes'><EFBFBD> </span>InvocationProxy that was registered to catch
events.</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l1 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>8)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>The Jacob <span class=SpellE>EventProxy</span>
sends the message to the registered event handler.</p>
</span></span></span><![endif]>The Java InvocationProxy uses reflection to map
the event name to a method name with the exact same name.</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>9)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>The Java InvocationProxy sends the message to
the registered event handler and returns if the event handler is of type void
(standard behavior).<span style='mso-spacerun:yes'><EFBFBD> </span></p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l2 level1 lfo2;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>10)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; </span></span></span><![endif]>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.</p>
<p class=MsoPlainText><o:p>&nbsp;</o:p></p>
<p class=MsoPlainText>Swing developers should note that this message comes in
on a thread other than the event thread.<span style='mso-spacerun:yes'><EFBFBD>
</span>All objects receiving events that require user intervention or drawing
in the UI should use <span class=SpellE><span class=GramE>invokeLater</span></span><span
class=GramE>(</span>) to post requests for actions onto the event queue.<span
style='mso-spacerun:yes'><EFBFBD> </span>Failure to do so will insure random failures
in the GUI.</p>
in the UI should use invokeLater() to post requests for actions onto the event
queue.<span style='mso-spacerun:yes'><EFBFBD> </span>Failure to do so will insure random
failures in the GUI.</p>
<p class=MsoPlainText><o:p>&nbsp;</o:p></p>
<p class=MsoPlainText><o:p>&nbsp;</o:p></p>
<p class=MsoPlainText>Java Web Start (JWS) and other launchers can have
additional issues related to the class loader.<span style='mso-spacerun:yes'><EFBFBD>
</span>The Jacob C++ library uses <span class=SpellE><span class=GramE>FindClass</span></span><span
class=GramE>(</span>) to find the Variant class when building the parameter
list.<span style='mso-spacerun:yes'><EFBFBD> </span><span class=SpellE><span
class=GramE>FindClass</span></span><span class=GramE>(</span>) uses the system
class loader which includes only the classes specified at run time or in the
CLASSPATH.<span style='mso-spacerun:yes'><EFBFBD> </span>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.<span
style='mso-spacerun:yes'><EFBFBD> </span>This means that the search for Variant will
fail usually with the silent and immediate termination of the Java application.<span
style='mso-spacerun:yes'><EFBFBD> </span>The thread <span class=SpellE>classloader</span>
</span>The Jacob C++ library uses FindClass() to find the Variant class when
building the parameter list.<span style='mso-spacerun:yes'><EFBFBD> </span>FindClass()
uses the system class loader which includes only the classes specified at run
time or in the CLASSPATH.<span style='mso-spacerun:yes'><EFBFBD> </span>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.<span style='mso-spacerun:yes'><EFBFBD> </span>This means that the search for
Variant will fail usually with the silent and immediate termination of the Java
application.<span style='mso-spacerun:yes'><EFBFBD> </span>The thread classloader
probably can<61>t be used to try and find the class because this new thread does
not have a <span class=SpellE>classloader</span> associated with it other than
the system class loader.<span style='mso-spacerun:yes'><EFBFBD> </span>The end result
is that the Variant class needs to be located via other means and that the
thread <span class=SpellE>classloader</span> should be set to be the context
class loader of the event handler class.</p>
not have a classloader associated with it other than the system class
loader.<span style='mso-spacerun:yes'><EFBFBD> </span>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.</p>
<p class=MsoPlainText><o:p>&nbsp;</o:p></p>
<p class=MsoPlainText>The Jacob <span class=SpellE>EventProxy</span> class has
been modified (off of the 1.8 tree) so that it takes a two step approach to
towards fixing these problems.</p>
<p class=MsoPlainText>&lt;b&gt;1.8 and 1.9 behavior&lt;/b&gt;</p>
<p class=MsoPlainText>The Jacob EventProxy class has been modified (off of the
1.8 tree) so that it takes a two step approach <span
style='mso-spacerun:yes'><EFBFBD></span>towards fixing these problems.</p>
<p class=MsoPlainText><span style='mso-tab-count:2'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span></p>
@@ -287,28 +320,26 @@ towards fixing these problems.</p>
l0 level1 lfo4;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>1)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>The <span class=SpellE>EventProxy</span>
constructor now accepts an extra object, an instance of the Variant class.<span
style='mso-spacerun:yes'><EFBFBD> </span>This gives the <span class=SpellE>EventProxy</span>
a way to get to the Variant class and thus to its <span class=SpellE>classloader</span>.
All of the callers of the constructor have been modified to pass a Variant
object to the <span class=SpellE>EventProxy</span> without programmer
intervention.</p>
</span></span></span><![endif]>The EventProxy constructor now accepts an extra
object, an instance of the Variant class.<span style='mso-spacerun:yes'><EFBFBD>
</span>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.</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l0 level1 lfo4;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>2)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]><span class=SpellE>EventProxy</span> first
attempts to locate the Variant class using <span class=SpellE>FindClass</span>()</p>
</span></span></span><![endif]>EventProxy first attempts to locate the Variant
class using FindClass()</p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l0 level1 lfo4;tab-stops:list 42.0pt'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>3)<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>Failing that, it looks to see if a variant
object had been passed in. If so, it calls <span class=GramE>class(</span>) and
goes from there.<span style='mso-spacerun:yes'><EFBFBD> </span></p>
object had been passed in. If so, it calls class() and goes from there.<span
style='mso-spacerun:yes'><EFBFBD> </span></p>
<p class=MsoPlainText style='margin-left:42.0pt;text-indent:-24.0pt;mso-list:
l0 level1 lfo4;tab-stops:list 42.0pt'><![if !supportLists]><span
@@ -317,24 +348,46 @@ style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span></span><![endif]>If all that fails, it logs a message and then
fails in the spectacular fashion of the previous versions.</p>
<p class=MsoPlainText>&lt;b&gt;1.10 behavior&lt;/b&gt;</p>
<p class=MsoPlainText>The Jacob EventProxy class has been modified so that it
takes a different approach towards fixing this problem.</p>
<p class=MsoPlainText style='margin-left:.75in;text-indent:-.25in;mso-list:
l1 level1 lfo6;tab-stops:list .75in'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>1.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; </span></span></span><![endif]>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.</p>
<p class=MsoPlainText style='margin-left:.75in;text-indent:-.25in;mso-list:
l1 level1 lfo6;tab-stops:list .75in'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>2.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; </span></span></span><![endif]>The
EventProxy constructor accepts an Java InvocationProxy as the object that will
receive any callbacks for this set of events.</p>
<p class=MsoPlainText style='margin-left:.75in;text-indent:-.25in;mso-list:
l1 level1 lfo6;tab-stops:list .75in'><![if !supportLists]><span
style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>3.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; </span></span></span><![endif]>The
Java InvocationProxy has a method on it that will return the Variant class that
the EventProxy.</p>
<p class=MsoPlainText><o:p>&nbsp;</o:p></p>
<p class=MsoPlainText>Developers can receive call back events in JWS other Java
launching programs without implementing any additional code.<span
style='mso-spacerun:yes'><EFBFBD> </span>They should be aware that their callback
methods may need to set the class <span class=GramE>loader.:</span></p>
methods may need to set the class loader. If they expect to create any objects.:</p>
<p class=MsoPlainText><span style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>Public xxx <span
class=SpellE><span class=GramE>someHandler</span></span><span class=GramE>(</span>Variant[]
<span class=SpellE>foo</span>){</p>
<p class=MsoPlainText><span style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>Public xxx
someHandler(Variant[] foo){</p>
<p class=MsoPlainText><span style='mso-tab-count:2'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span><span
class=SpellE><span class=GramE>Thread.currentThread</span></span><span
class=GramE>(</span>).<span class=SpellE>setContextClassLoader</span>(</p>
<p class=MsoPlainText><span style='mso-tab-count:2'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>Thread.currentThread().setContextClassLoader(</p>
<p class=MsoPlainText><span style='mso-tab-count:3'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span><span
class=SpellE><span class=GramE>this.getClass</span></span><span class=GramE>(</span>).<span
class=SpellE>getClassLoader</span>());</p>
<p class=MsoPlainText><span style='mso-tab-count:3'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>this.getClass().getClassLoader());</p>
<p class=MsoPlainText><span style='mso-tab-count:2'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>// do
something</p>

View File

@@ -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.
<li>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)
<li>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.
</ul>
</li>