154 lines
7.1 KiB
HTML
154 lines
7.1 KiB
HTML
<HTML>
|
|
<BODY>
|
|
Jacob is a Java library that lets Java applications communicate with Microsoft Windows
|
|
DLLs or COM libraries. It does this through the use of a custom DLL that the Jacob
|
|
Java classes communicate with via JNI. The library and dll isolate the Java developer
|
|
from the underlying windows libraries so that the Java developer does not have to write
|
|
custom JNI code.
|
|
<p>
|
|
Jacob is not used for creating ActiveX plugins or other moduless that
|
|
live inside of Microsoft Windows applications.
|
|
<hr>
|
|
|
|
<h2> The Jacob Packages </h2>
|
|
<p>
|
|
The JACOB jar contains two main packages: the <code>com.jacob.com.*</code>> package and
|
|
the <code>com.jacob.activeX</code> package. The <code>com.jacob.com.*</code> package contains classes
|
|
map very closely to the com dispatch model with the <code>com.jacob.com.Dispatch</code>
|
|
acting as the primary communication class. Dispatch operate as a function library with
|
|
a set of static methods that map very closely to the C++ Dispatch APIs provided
|
|
to the COM layer.
|
|
<p><code>com.jacob.activex.ActiveXComponent</code> can be used in place of Dispatch
|
|
to provide a more object like API.
|
|
The only exception to this guideline is that the <code>ActiveXComponent</code> class is always
|
|
used to make the initial connection to the target dll/COM component.
|
|
|
|
<hr>
|
|
<H2> Determining the API of the target application </h2>
|
|
<p>
|
|
Section not yet written.
|
|
<p>
|
|
<hr>
|
|
<h2> The Jacob DLL </h2>
|
|
<p>
|
|
Jacob.jar relies on a DLL file that it loads off of the library path or classpath.
|
|
This means that you must either copy jacob.dll into your path or use VM options to
|
|
add jacob.dll directory to the path.
|
|
<p>
|
|
The code is written so that the jacob.dll is only loaded one time per classloader.
|
|
This works fine in the standard application but can cause problems if jacob.jar
|
|
is loaded from more than one class loader. This can happen in the situation where multiple
|
|
jacob dependent web applications run in the same container like a web server or JWS runtime.
|
|
<p>
|
|
In the case of a web server, Jacob is normally put in the application specific WEB-INF/lib directory.
|
|
This is the "right" way to do it and works in most situations.
|
|
But, if Jacob is put in the WEB-INF/lib directory of each application's war file for more than
|
|
one application then a problem occurs.
|
|
In this situation, the web server uses a different classloader for each applicaiton.
|
|
This means that each application will attempt to load the jacob.dll and errors
|
|
are generated. The only way around this at this time (1.11) is to put the jacob.jar
|
|
in the common/lib because that classloader is inherited by all of the applicaitons
|
|
so the DLLs will only get loaded once. This problem is described in SF 1645463 and
|
|
should be fixed in some future release, fix method and time not yet determined.
|
|
<p>
|
|
<hr>
|
|
<h2>Microsoft Visual C++ library dependencies.</h2>
|
|
Jacob 1.13 is built with VC++ 2005 that creates a dependency on msvcr80.dll.
|
|
Windows XP and later seem to already include the necessary components.
|
|
NT/2000 and Server/2003 require that you download vcredist_x86.exe
|
|
from the microsoft web site.
|
|
Microsoft has a download available that supplies the necessary components.
|
|
It is distributed as a redistributable package.
|
|
See the following links.
|
|
<pre>
|
|
http://www.microsoft.com/downloads/details.aspx?familyid=32bc1bee-a3f9-4c13-9c99-220b62a191ee&displaylang=en
|
|
http://www.microsoft.com/downloads/details.aspx?FamilyID=200b2fd9-ae1a-4a14-984d-389c36f85647&displaylang=en
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h2>Jacob Command Line Settings</h2>
|
|
This library supports several different :
|
|
<h3>java.library.path</h3>
|
|
Used to add the location of the jacob dll to the JVM's library path.
|
|
<p>
|
|
Example: -Djava.library.path=d:/jacob/release/x86
|
|
|
|
<h3>com.jacob.autogc </h3>
|
|
Determines if automatic garbage collection is enabled. This is the
|
|
only way to free up objects created in event callbacks. Automatic garbage collection , based on Java gc rules, garbage collection can be enabled via the
|
|
<code>com.java.autogc</code> command line option.
|
|
<em>This feature was added in release 1.9 is not fully debugged. </em>
|
|
<p>
|
|
There are real reasons for managing the
|
|
lifetime of JacobObjects on a per thread basis.
|
|
Jacob normally manages the the com/Java object lifetime as described in the
|
|
<a href="JacobComLifetime.html">JacobComLifetime.html</a> document.
|
|
Some users have run into situations where they wish to try and let the Java
|
|
GC lifetime manage the lifetime of objects. This seems to usually be tied
|
|
to long running threads or to objects created as part of event callbacks.
|
|
Code was added to let users try and let the JVM manage the object life cycles
|
|
even though the <a href="JacobComLifetime.html">JacobComLifetime.html</a> document
|
|
says this is a bad idea.
|
|
<p>
|
|
<p>
|
|
This value is cached at startup and cannot be changed on-the-fly via <code>System.setProperty();</code>
|
|
<p>
|
|
The default value is <strong>false</strong>
|
|
<p>
|
|
Example: <code>-Dcom.jacob.autogc=false</code>
|
|
|
|
<h3><class_name>.PutInROT</h3>
|
|
Lets a program specify that instances of certain classes are to not be inserted
|
|
into the ROT. This experimental (1.13) feature provides a mechanism for freeing
|
|
VariantViaEvent objects that are created in Event threads. There is normally no
|
|
way to free those objects because the thread terminates outside of any normaly MTA/STA
|
|
Startup/Teardown code. Each event occures in a new thread and creates a new ROT entry
|
|
so they grow without bounds.
|
|
<p>
|
|
This option may cause VM crashes in certain situations where windows memory is freed
|
|
outside of the thread it was created in but emperical evidence shows there are
|
|
situations where this great reduces the long running memory footprint of applications
|
|
that process a lot of events. <em>This function is still experimental</em>.
|
|
The functionality of this overlaps the experimental <code>com.jacob.autogc</code> introduced
|
|
in 1.9.
|
|
See the ROT.java test program for an example of the effects of this option.
|
|
<p>
|
|
This value is checked every time and can be changed on-the-fly via <code>System.setProperty();</code>
|
|
<p>
|
|
|
|
Example: <code>System.setProperty("com.jacob.com.VariantViaVariant.PutInROT","false");</code>
|
|
<BR>
|
|
Example: <code>-Dcom.jacob.com.VariantViaVariant.PutInROT=false</code>
|
|
|
|
<h3>com.jacob.debug</h3>
|
|
Determines if debug output is enabled to standard out.
|
|
<p>
|
|
This value is cached at startup and cannot be changed on-the-fly via <code>System.setProperty();</code>
|
|
<p>
|
|
The default value is <strong>false</strong>
|
|
<p>
|
|
|
|
Example: <code>-Dcom.jacob.debug=false</code>
|
|
|
|
<h3>-XCheck:jni</h3>
|
|
This turns on additional JVM checking for JNI issues. This is
|
|
not an actual JACOB system property but a property used by the JVM.
|
|
<p>
|
|
The default is "no additional checking"
|
|
Example: -XCheck:jni
|
|
<p>
|
|
<hr>
|
|
<h2>Finding the DLL version using windows command line</h2>
|
|
The jacob.dll file includes the jacob release number in the version field.
|
|
Run the following from the command prompt <code>dumpbin /version jacob.dll</code> .
|
|
The dll version number is stored in the "image version" field of the
|
|
"OPTIONAL HEADER VALUES" section.
|
|
This information from <a href="http://msdn2.microsoft.com/en-gb/library/h88b7dc8(VS.71).aspx">
|
|
The Microsoft msdn web site</a>
|
|
|
|
<p>
|
|
Last Modified 7/2007
|
|
|
|
</BODY>
|
|
</HTML> |