Jacob is not used for creating ActiveX plugins or other moduless that live inside of Microsoft Windows applications.

The Jacob Packages

The JACOB jar contains two main packages: the com.jacob.com.*> package and the com.jacob.activeX package. The com.jacob.com.* package contains classes map very closely to the com dispatch model with the com.jacob.com.Dispatch 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.

com.jacob.activex.ActiveXComponent can be used in place of Dispatch to provide a more object like API. The only exception to this guideline is that the ActiveXComponent class is always used to make the initial connection to the target dll/COM component.

Determining the API of the target application

Section not yet written.

The Jacob DLL

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.

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.

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.

Microsoft Visual C++ library dependencies.

If you see the following message then you probably don't have the right C++ libraries.

Exception in thread "main" java.lang.UnsatisfiedLinkError: C:\apps\...\jacob.dll: This application has fa 
iled to start because the application configuration is incorrect. Reinstalling the application may fix this pr 
oblem 

Visual C redistributable installer SP1

Jacob Command Line Settings

java.library.path

Example: -Djava.library.path=d:/jacob/release/x86

com.jacob.autogc

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 JacobComLifetime.html 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 JacobComLifetime.html document says this is a bad idea.

This value is cached at startup and cannot be changed on-the-fly via System.setProperty();

The default value is false

Example: -Dcom.jacob.autogc=false

<class_name>.PutInROT

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. This function is still experimental. The functionality of this overlaps the experimental com.jacob.autogc introduced in 1.9. See the ROT.java test program for an example of the effects of this option.

This value is checked every time and can be changed on-the-fly via System.setProperty();

Example: System.setProperty("com.jacob.com.VariantViaVariant.PutInROT","false");
Example: -Dcom.jacob.com.VariantViaVariant.PutInROT=false

com.jacob.debug

This value is cached at startup and cannot be changed on-the-fly via System.setProperty();

The default value is false

Example: -Dcom.jacob.debug=false

-XCheck:jni

The default is "no additional checking" Example: -XCheck:jni

Finding the DLL version using windows command line

Last Modified 7/2007