Using Jactivex's JavaTLB Compatibility Support

The jactivex utility is used for hosting automation-enabled ActiveX controls in Java, and generating .java files for the classes and interfaces that are described by a type library. These .java files, once compiled into .class files, allow Java programs to use COM (Component Object Model) services. Although the default operation of the tool is ActiveX Control manipulation in Java, this documentation only covers tool usage for features originally supported by the javatlb and jcom tools (which this tool replaces).

Using the Jactivex 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 jactivex tool uses the COM type library information to create Java classes that represent COM interfaces.

A type library is a mechanism defined by COM to define type information. Each type library contains complete type information about one or more COM entities, including classes, interfaces, and dispinterfaces. For more information about type libraries, see the Microsoft Platform SDK. To find out how to use the interfaces that are available from a particular programmable control or automation server, see the documentation provided by that vendor.

Note The jactivex tool is virtually identical to the jcom tool, and similar to the javatlb tool. The jactivex tool generates Java source code (.java) rather than the .class files that javatlb generates. The generated Java source requires new functionality not present in older versions of the compiler in Microsoft® Visual J++™. To learn about upgrading from older versions of this tool, see Upgrading to Jactivex from JavaTLB.

To use the jactivex tool for low-level Java/COM integration (that is, enabling the JavaTLB behavior), use the /javatlb switch and provide the name of a type library as follows:

jactivex /javatlb <filename>

Filename is the filename of the type library (*.tlb, *.olb, *.ocx, *.dll or *.exe).

Note If you specify an .ocx file without the /javatlb switch, the jactivex tool will generate a JavaBean wrapper for the ActiveX control (its default operation).

For example, consider this command line, which first creates a \Widgets subdirectory underneath the trusted library directory (specified by the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\TrustedLibsDirectory):

jactivex /javatlb widgets.tlb

If the trusted library directory is \Windows\Java\Trustlib, the preceding command creates the directory \Windows\Java\Trustlib\Widgets, and fills it with .java files. A separate .java file is created for each class, structure, enumeration, and interface described by the widgets.tlb type library. The names of packages and directories created by jactivex contain only lowercase letters.

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

Upgrading to Jactivex from JavaTLB

Jactivex has been designed for backward compatibility with the javatlb tool. In most cases, upgrading to jactivex should require only three modifications to your makefiles or build scripts:

1. Replace references to javatlb with references to jactivex.
2. Add the appropriate command-line switch (/javatlb) in any scripts to access jactivex features.
3. Upgrade to a compiler for Java that recognizes the new @com directives generated by jactivex. If you are using the Visual J++ compiler (jvc.exe), you must use version 1.02.3920 or later to compile the output from jactivex. Earlier versions of jvc will not issue a compile-time error, but the class files they generate will not work. For more information about the @com directives, see @com Directives.

The following table shows the correspondence between jactivex and javatlb command-line options:

Javatlb	Jactivex	Notes
/d dir	/javatlb /d dir	Option works identically
/p package	/javatlb /p package	Option works identically
/p:b-	/javatlb /p:b-	Option works identically
/X:m-	/javatlb /X:m-	Option works identically
/U	N/A	Not supported in jactivex*
/U:T	N/A	Not supported in jactivex*
*Jactivex does not support the generation of summary.txt files as did javatlb because jactivex generates human-readable .java source.

@com Directives

Jactivex generates Java source files that use a new Microsoft extension called the @com directives. These directives must appear inside specially formatted comments that are similar to the javadoc documentation comments syntax. A typical @com directive generated by jactivex might look like the following example:

/** @com.method(vtoffset=4, dispid=100, type=METHOD, name="Hello")
    @com.parameters() */
    public void Hello();

The @com directives are important and are used to generate the extra information needed by the Java/COM integration subsystem in the Microsoft Win32 VM for Java. Therefore, the compiler used to compile jactivex's output must process these directives. If you are using the jvc.exe, you must use version 1.02.3920 or later to compile jactivex's output. Earlier versions of jvc will not issue an compile-time error, but the class files they generate will not work.

Implementing Automation Objects in Java

There are two ways to implement automation objects in Java:

1. Use automatic IDispatch
2. Use the /javatlb /cj command-line option to generate a .impl file.

The following sections describe each of these methods.

Using Automatic IDispatch

The Microsoft VM now implements IDispatch automatically for almost all Java objects (previously, it did so only for applets). This means that tools such as jactivex are no longer necessary simply to script a Java object from an automation controller such as Microsoft® Visual Basic® or Microsoft ® Visual Basic® Scripting Edition (VBScript). To implement a simple automation object in Java:

1. Implement the Java object and compile it.
2. Register it using javareg (version 3.0 pre-release 2).
3. Ensure that the Java class is visible in the CLASSPATH environment variable.

Using the /javatlb /cj Option with Jactivex

The second approach uses jactivex to generate COM interfaces from type libraries. This approach requires more work but allows you to ensure that the exposed interface matches the typelib description exactly.

The /javatlb /cj approach requires an interface definition language (IDL) or object definition language (ODL) file describing your interface and a coclass, which uses the [default] attribute to define the default interface. The following example shows a simple IDL file for the IWidget interface:

[ 
	   object,
	   uuid(...),
	   helpstring("IWidget"),
	   pointer_default(unique)
           ]
           interface IWidget : IUnknown
           {
	    HRESULT add([in] long x, [in] long y, [out,retval] long*pz);
           };

	[
		uuid(...),
		helpstring("CWidget")
	]
	coclass CWidget
	{
		[default] interface IWidget;
	};

When you invoke jactivex on the typelib using the /javatlb /cj switches, Jactivex generates an extra file named CWidgetImpl.java, which looks as follows:

public class CWidgetImpl implements IWidgetDefault,com.ms.com.NoAutoScripting
	{
	    public int add(int x, int y) 
                {
	       throw new com.ms.com.ComFailException(0x80004001);  //E_NOTIMPL
                }
	}

To create a Java implementation of CWidget, you can either extend the class or use CWidgetImpl itself as a template for MyWidget (this is preferable as it eliminates a superclass). The following shows the superclass implementation:

public class MyWidget extends CWidgetImpl
	{
	    public int add(int x, int y) 
        {
	        return x+y;
	    }
    }

Jactivex Extended Command-Line Options

The jactivex tool replaces both javatlb and jcom. By default, the tool is used to host automation-enabled ActiveX controls in Java. To access typelib features, you must use the /javatlb command-line switch to activate the other switches described in the following section.

Translation

/javatlb

Specifies typelib translation. Use this switch combined with others to access typelib features of the jactivex tool.

/b

Uses the JavaBeans design pattern for properties. For example, by default, a read-write property named "a" becomes mapped to property accessor methods named "geta" and "puta". If the "/b" flag is specified, the names "getA" and "setA" will be used instead. In addition, the property is exposed to COM by the name "A" only. It is not possible to access the names "getA," or "setA" from COM (these names were exposed only for compatibility with javatlb).

/G3.1

Prevents use of features that are not supported by the VM in Microsoft® Internet Explorer version 3.1. Disabled by default.

/G4

Prevents the use of features that are not supported by the VM in Internet Explorer version 4.0. Disabled by default; this switch is reserved for future use.

/r

Causes jactivex to register all type libraries that are mentioned on the command line.

/w

Disables all warnings.

/WX

Treats warnings as errors. This prevents any output files from being generated if a warning is reported.

/x2

Maps VT_I2 and VT_UI2 to Java char rather than Java short. By default, these types are mapped to Java short for compatibility with javatlb.

/xc

This causes all coclasses in the type libraries to be ignored.

/xd-

Suppresses creation of default versions of the .java files. Jactivex normally creates two .java files for each dispinterface: one that is used when the interface is the default for a coclass, and one that is used when the interface is not the default. The default versions of the java files are needed only to implement the interface using Java. Suppressing the creation of default versions can speed up compilation considerably on large type libraries.

Do not use this switch with the /cj option.

/xh

Modifies translation of HRESULT types so that only HRESULT return types that have the high (FAIL) bit set cause Java exceptions. Non-failing HRESULTs (such as S_FALSE) are treated as if they were S_OK.

Warning This feature is not supported by versions of the Microsoft VM prior to Internet Explorer 4.0. Classes built with this option set will not load on versions prior to version 4.0. If your class must run on versions prior to version 4.0, do not use this switch. Callers of this method will need to catch ComSuccessException to avoid the exception.

/xi

Causes the method declarations and COM declarations to be duplicated in the coclass files. This simplifies using COM objects from Java because default interface methods can be called directly on the object without first casting to an interface pointer. That is, without the /xi option you would have to write code like this:

IBeeper b = (IBeeper)new Beeper();
b.beep();

Using the /xi option, this can be simplified as follows:

Beeper b = new Beeper();
b.beep();

In addition, this form speeds up method invocation. The trade-offs are that the coclass files are larger and any manual changes to the information generated by jactivex must be made in both the coclass and the interface.

/X:m-

Disables thread switching. By default, the Microsoft VM assumes that all COM objects passed as parameters are non—thread-safe and performs background thread-switching to ensure that such objects are called on the correct thread. Using this switch disables this extra thread-switching. Typically, you will use this switch when you have designed a new thread-safe COM library.

Output

/cj

Generates a template file for each coclass that can be edited to implement that coclass in Java. The file is named <coclass>Impl.java. This file includes all the required methods with simple implementations that just throw an E_NOTIMPL exception. To create a Java class that implements the coclass, replace the class name and fill in the method implementations.

/d directory

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 .java files in C:\MyPackages\Widgets.

jactivex /javatlb /d c:\mypackages widgets.tlb

By default, the base directory is the value specified in the registry HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\TrustedLibsDirectory. The installation of the Microsoft VM sets this to %WINDIR%\java\trustlib.

/e

Generate files only for type libraries explicitly listed on the command line. This switch allows you to set command-line switches on a per-typelib basis. This may cause generation of .java files that reference unresolved names or packages.

If the /e option is not specified, jactivex will recursively compile type libraries needed to resolve all references.

/j

Generates Java source files without the extended COM information. As a result, these source files can be browsed more easily and will compile. They will not, however, integrate with COM if they are loaded into the Microsoft VM.

/p package

Specifies the target directory for .java files generated by jactivex as shown in the following example.

jactivex /javatlb /p gremlinsoft widgets.tlb

This example command line places the .java files in \windows\java\trustlib\gremlinsoft\widgets directory. With this option, you can define, for example, a company-specific directory tree that contains the .java files for all the COM objects produced by your company. The package parameter can have multiple levels. For example, the following command would place the .class files in the directory \windows\java\trustlib\gremlinsoft\toolworks\widgets.

jactivex /javatlb /p gremlinsoft.toolworks widgets.tlb

To use these classes in your Java program, specify an import statement of the following form in your source code:

import gremlinsoft.toolworks.widgets.*;

/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; this places the created .java 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:

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

Miscellaneous Switches

/?

Prints a brief summary of command-line options.

/l lstfile

Generates a response file for jvc that lists every .java file created by jactivex. The response file is a text listing of Java files so it can also be used to find out where and what files jactivex created.

For example, the following command line creates a file called mylist.lst, which can then be used as an input file to jvc:

jactivex /javatlb /l myfiles.lst widget.tlb

JVC @myfiles.lst

If a relative path is given for the response file, it is placed in the current directory. Its location is not affected by the /d option.

/n jnffile

Specifies an optional .jnf file, which supplies extra information on how to convert the type library. The .jnf file is a text file that has the following format:

[Custom]
	<typename>=<javatype>,<javamarshalertype>
		...

The purpose of the .jnf file is to inform jactivex that certain types are to be marshaled using a COM Custom Marshaling hook class.

/nologo

Disables the startup banner.