JACOB Project mailing-list FAQ
Donated by Massimiliano Bigatti (http://www.bigatti.it, max@bigatti.it)

See “Credits” for the fundamental work of others.
Updated version at: http://danadler.com/jacob/jacobfaq.html
This is revision 0.2 - (20 Sept 2002)

Jacob related

What is Jacob?
The Jacob project is a generic COM bridge for Java pioneered by Dan Adler (http://danadler.com). It is licensed as open-source on sourceforge.net.

How do I do this/that in Word, Excel, Project, ... ?
Let’s clarify: Jacob is only a bridge, it is an ancronym for JAva COm Bridge. It only implements a generic bridge to call COM components from Java.
It is not the Java interface of Microsoft Office nor it supports directly its COM components. To know more on calling Office with Java, see the “Microsoft Office related” section of this FAQ.

Do I need to compile Jacob to use it?
No, you need only to install it. You can install it as an extension (see “What I should do if IIS/other crashed using Jacob?”) or as a part of your application. To do the latter:


I did not get jacob.dll when downloading jacob_xx.jar
Turn “Show hidden files” on in your Windows Explorer.

If I use Jacob in my application do I have to install jacob.dll on client side?
Yes, if Jacob is used in your client code.
No, if your code uses Jacob on the server side.
You only have to install Jacob on the computer where the process that makes direct use of Jacob is running.

I’m getting an “UnsatisfiedLinkException” on com.jacob.com... What should I do?
Check if jacob.jar is in your CLASSPATH. Try to move it at the beginning of the list, maybe your CLASSPATH is too long and Java is ignoring the latest jars.

What I should do if IIS/other crashed using Jacob?
Try to install Jacob as a JRE extension. To do this: put jacob.dll in jre/bin and jacob.jar in jre/lib/ext. The jre directory is under your jdk installation, or Programs/JavaSoft if you’re using only the runtime environment.
It might also be a threading issue, see (“What should I do if my program hangs after the code has called Jacob?”).

What should I do if my program hangs after the code has called Jacob?
Maybe you’re experiencing threading problems. Upgrade to Jacob 1.7 and use the ComThread class to implement COM threading manually. See COM Object Lifetime (http://danadler.com/jacob/JacobComLifetime.html) in Jacob.

Can I call COM component across machines or operating systems?
The answer to this question is No. The way jacob is implemented is using JNI
and a c++ DLL designed for the windows platform. COM is a binary standard
defined by Microsoft as it hasn’t been ported over (as far as I know) to any
other platforms yet. Jacob is only a java bridge for COM which defines how
components talk to each other when they are on the same machine. The DCOM
standard defines how components communicate accross networks, but Jacob has no support for DCOM.
Solutions:

When I downloaded Jacob I didn’t get javadocs, where can I find these?
There are not javadocs available for Jacob classes. However, Jacob is almost 1:1 compatible with Microsoft COM access for Java, you can check out the MS docs at http://www.microsoft.com/java/download/dl_sdk40.htm.

When should I call ComThread.release() in a JSP/Servlet environment?
Why not make a "worker thread" that do all the COM invocations for you? So
that you in a way marshal your requests to this thread or threads. You'd
need some way of "job control", but this could be very simple depending on
what you need.


I’m getting “An unexpected exception has been detected in native code outside the VM.” error, using Jacob in a Web Application running on Tomcat as a service. What should I do?
frode@coretrek.no says: “Are your COM component Apartment threaded?

The problem with this kind of set up is that when the thread responsible
for hosting your COM component goes down, the apartment goes down as well
and your COM component becomes invalid.

I have noticed that for the very first thread in Java, the "MAIN" thread,
there is a corresponding Win32 thread, and When the MAIN thread exists,
the Win32 thread is still alive, as you can see if you use the Windows
Task Manager and enable the "Threads#" column. The thread count does not
decrease after the MAIN exists. (When any other thread exits,
the thread count decrease).

When you run as an NT service, your entry point where you probably
create your object is _not_ the first (win32) thread that never really exits.
Does this make sense? Anyway, I solved this problem by making sure
that the thread in which you create the Dispatch object never exists.

Try adding the following code to the "end" of the thread where you
create your object to prevent the thread from exiting:

    Object o = new Object();

    synchronized(o) {

        while (true) {

            try {

                o.wait();   //  hang around forever

            } catch (InterruptedException e) {}

        }

    }

Hope this helps!”

COM related

How do I call a Visual Basic/COM component/DLL from Java?
You have to instantiate the COM component using either the ActiveX or Dispatch classes. When you have the object instantiated, you can call Dispatch.call() to invoke a single COM method passing the parameters the method needs. You can check out samples for this in the Jacob distribution (in the “samples” directory), the simplest (if you have MS Access installed) would probabily be Access.java

How do I setup a Jacob installation and make sure it works?
Try the following:
1) unzip jacobSrc.zip - the bundle downloaded from http://danadler.com/jacob.
2) cd to <jacob_unzipped>\samples\test
3) run prompt> set path=%path%;.\MathProj
4) run prompt> regsvr32 MathProj\MathTest.dll
5) run prompt> javac -classpath ..\..\jacob.jar math.java
6) run prompt> java -classpath ..\..\jacob.jar;. math

What is the correct way to pass optional parameters?
Use the variant.noParam(), that makes it as if that argument is skipped.

How do I display a Visual COM component?
You can’t. Under “Limitations” on the Jacob homepage you can read “This release does not provide any support for hostng graphical ActiveX controls inside of Java components”.
You need to refer to other (commercial) products, like: Linar/Intrinsyc’s JIntegra suite (http://www.intrinsyc.com/products/bridging/jintegra.asp), and GenSym (note GenSym (http://www.gensym.com) has dropped support for their product)
There is also a (http://www.nothome.com/IECanvas/) project to run Internet Explorer inside a Java application, although I don’t know how stable it is.

I’m getting a “co-create ComFailException”, what should I do?
Maybe you need to register your DLL on the system, or you mispelled the name in the Java source code. To register a DLL use “REGSVR32 <filename>”. REGSVR32 ships with every copy of Windows. It should pop-up a message box saying the component was registered successfully.

I’m getting a “ComFailException: Can’t map name to dispid”, what should I do?
If the exception says “com.jacob.com.ComFailException: Can't map name to dispid”: maybe you’re trying to call method that didn't exist in the library...

Are COM Dates compatible with Java Dates? How can I convert one to each other?
You can use this http://groups.yahoo.com/group/jacob-project/message/97code. Jacobgen wrappers should handle this conversion automatically.

On ComThread.release() I get javaw.exe Application Error, The istruction at xxx referenced memory at 0x00000. What should I do?
That sometimes happens when your java app attempts to exit before COM
is finished. Try adding a sleep of a couple of seconds before the
java application exits. That usually cures it.

How do I create a COM component that will be called from Jacob?
You have to implement more functions and export them, preferably using
a .def file.

Building COM objects with C++ is more involved than I can go into
here. I advice you to get a decent book on creating COM objects in
C++ like Inside DCOM from Microsoft Press if you want to travel that
road. Tools like ATL generate the boilerplate code for you.

I think it would be easier if you used some high level language to
create COM components. Python would be my choice, an easy to use open
source scripting language (http://www.python.org), VB is very popular
but also expensive and proprietary, but maybe the easiest way to make
COM components.

Microsoft Components/Office related

How do I call Office components using Jacob?
First, you have to know Office API. Not knowing it is like trying to programming in Java without knowing its core API and packages like java.lang and so on.
The Office documentation is included on the Office CD and on msdn (http://msdn.microsoft.com). Alternatively, you can pop-up Visual Basic for Applications from within Word or Excel using F11. Once in VBA you can use Object Inspector (F2) to check out the APIs. Using F1 should display detailed documentation.
To know more on Office, see “How do I get more information about Office?”

What is the best way to create a Jacob program to perform a (complex) function in Word/Excel?
Launch the program (Word, Excel and so on), and then record a macro to execute the function you require. You now have VBA code to accomplish the function, wihich you can inspect from within VBA (F11). Now it should be easy to translate VB code in Java.

I’m still having problems translating VB code to Java?
Check out the examples provided with Jacob. First of all, you should figure out how to call a specific method on a specific component using Dispatch.call(). You should also figure out how to use Variant class, since that is the parameter and return type for the Dispatch.call() method.

It is still to complex/Is there another way?
You can use wrappers. These are Java classes that expose an object model similar to the COM components (Dispatch base mechanism is almost procedural - not so friendly for Java developers). You can generate wrappers for COM components using Jacobgen (http://www.bigatti.it/projects/jacobgen). Warning: Jacobgen is not complete yet!
You can find a list of other wrapper generators on the Jacob homepage (http://danadler.com/jacob). IBM Bridge2Java also has a wrapper generator.

How can I do mail merge in Word?
See: http://groups.yahoo.com/group/jacob-project/message/1525

How can I manipulate graphs in Excel?
You can check out an example in the full distribution of Jacobgen (http://www.bigatti.it/projects/jacobgen). The example uses the Excel wizard to produce a graph based on data in the Sheet.

How can I co-create a MAPI.Session object?
First, you must use Jacob 1.7. Second, use the ComThread class to initialize and release the STA (see “What should I do if my program hangs after the code has called Jacob?”).

My MAPI program runs well in Visual Café during development but fails runtime on JRun. Where can I look for further information?
See http://groups.yahoo.com/group/jacob-project/message/281 for a little bit more background information. If this looks like it might be your problem, get a hold of the msdn library and look into the cdo and win32 api's.

How can I get the value of constants?
You can find the constant value with the Visual Basic object browser:
1. In Excel, Choose Tools/Macro/Visual Basic editor.
2. Choose "object browser".
3. Search for the constant.
Once you have the value of the constant, create a new Variant object to represent the value.
i.e.:
new Variant(-4121)

Hey, my Excel and/or Word process still remain, also after the Java program terminates!
Try calling ComThread.release() when you’re finished. See http://groups.yahoo.com/group/jacob-project/message/1425

How can I create appointments with Outlook?
See: http://groups.yahoo.com/group/jacob-project/message/1106

How can I convert a PowerPoint presentation to HTML?
See: http://groups.yahoo.com/group/jacob-project/message/1577

How can I send faxes using Microsoft FaxServer?
See: http://groups.yahoo.com/group/jacob-project/message/1101

Where can I get more information about Microsoft Office?
You can check out these MSDN pages:

General Office: http://msdn.microsoft.com/office

Office XP

Office 2000

Office 97
And these newsgroups:


Credits
Thanks to everyone on the jacob-project list (http:/groups.yahoo.com/group/jacob-project). Most of the information here come from the mailing-list. Without the time everyone put in answering questions, this FAQ would never have been written.

Special thanks to:
Adriaan Hough
Robert Biernat