Javatlb Reference

Previous

About Tools

Next

Using the Javatlb Command-Line Tool

To use a COM class from Java, you must first import it; this means creating a Java class that represents the COM class in the context of Java.

The javatlb tool generates .class files for the classes and interfaces described by a type library. These .class files allow COM services to be used by Java programs.

A type library is a mechanism defined by COM to store type information; each type library contains complete type information about one or more COM entities, including classes, interfaces, dispinterfaces, and others. For more information about type libraries, see the Win32 SDK. To find out how to use the interfaces available from a particular programmable control or Automation server, consult the documentation provided by the vendor.

The typical usage is as follows:

javatlb filename

where filename is the name of the type library (.TLB, .OLB, .OCX, .DLL or .EXE).

For example:

javatlb widgets.tlb

This command first creates a \widgets subdirectory underneath the trusted library directory specified by the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\TrustedLibsDirectory. If the trusted library directory is \windows\java\trustlib, the preceding command creates the directory \windows\java\trustlib\widgets, and fills it with .class files, one for each class, structure, enumeration, and interface described by the widgets.tlb type library.

If the type library contains an importlib statement, javatlb creates a separate Java package in a separate directory for the imported type library.

Note The packages and directories created by javatlb always have all-lowercase names.

You can also use a response file to run javatlb on multiple type libraries at once. For example:

javatlb @list

The filename after the @ must specify a text file containing the name of the type library files.

Options

Javatlb also supports certain command-line options:

/U classname

This option causes javatlb to display the signatures for all the public methods in the .class file. For example:

javatlb /U IDooHickey.class

This command would produce output similar to the following:

public interface widgets/IDooHickey extends java.lang.Object
{
	public native short getThingie();
	public native void putThingie(short);
	public native void doWhatever();
}

This describes the methods you can call when using the IDooHickey interface. There are several things worth noting about the output:

• In the declaration of the class or interface, the name packagename/classname format is used strictly to provide information about what package the class or interface belongs to. An identifier like widgets/IDooHickey is not legal in Java.
• In general, all methods can throw an instance of com.ms.com.ComException.
• Only interfaces have methods; classes do not. When using the Java wrappers for COM classes, you must always call methods through an interface, not through the class itself.

/U:T

This option generates .class files and then writes the signature information to a text file. For example, running the command:

javatlb /U:T widgets.tlb

is the equivalent of first running the command "javatlb widgets.tlb" and then running the command "javatlb /U *.class > summary.txt" in the /widgets subdirectory.

/p package

This option lets you specify where javatlb will place the .class files it generates. For example:

javatlb /p gremlinsoft widgets.tlb

This places the .class files in the directory \windows\java\trustlib\gremlinsoft\widgets. This option allows you to define, for example, a company-specific directory tree that contains the .class files for all the COM objects produced by your company.

The package parameter can have multiple levels; for example, the command "javatlb /p gremlinsoft.toolworks widgets.tlb" would place the .class files in the directory \windows\java\trustlib\gremlinsoft\toolworks\widgets. To use these classes in your Java program, you would need to specify an import statement of the form "import gremlinsoft.toolworks.widgets.*;" in your source code.

/d

This option specifies the base directory where the package directory will be placed. For example, the following command will create the widgets package directory in the c:\mypackages directory and place all generated .class files in c:\mypackages\widgets.

 
javatlb /d c:\mypackages widgets.tlb 

/p:b[–]

Use this option to include (or exclude) the basename as the package for the converted class. For example, if you are converting widgets.tlb to Java classes, this option will create a package called widgets. Since the default is to use the basename as the package, this option is generally used with the dash (–) following it to disable the automatic creation of the package directory and place the created .class files in the default package directory (java\trustlib or the directory specified in the /d option).

For example, the following command places all class files in the c:\mypackages directory:

javatlb /p:b- /d c:\mypackages widgets.tlb 

/X:m[–] classname

Use this option to enable or disable (–) automatic marshaling of COM parameters. By default, the Microsoft VM must assume that COM objects are not thread safe and therefore performs special handling of all calls to and from the COM object. The /X:m– option alerts the VM that the COM object is thread safe and therefore can be called directly, reducing the overhead of the call.