Jcom Reference

Previous

About Tools

Index

Next

Introduction to Jcom

The jcom tool generates .java files for the classes and interfaces described by a type library. These .java files, once compiled into .class files, allow Java programs to use COM services.

Using the Jcom 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.

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.

Note Jcom is similar to the javatlb tool (which it replaces), except jcom generates java source code (.java) rather than .class files. The generated Java source requires new functionality not present in older versions of the Visual J++ compiler. See Upgrading to Jcom from JavaTLB

The typical usage is as follows:

jcom filename

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

For example:

jcom 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 .java files—one for each class, structure, enumeration, and interface described by the widgets.tlb type library.

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

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

Upgrading to Jcom from JavaTLB

Jcom has been designed for backward compatibility with the JavaTLB tool. In most cases, upgrading to jcom should require only two modifications to your makefiles or build scripts:

1. Replace references to javatlb with references to jcom.
2. Upgrade to a compiler for Java that recognizes the new "@com" directives emitted by jcom. If you are using the Microsoft Visual J++ compiler (jvc.exe), you must use version 1.02.3920 or later to compile the output from jcom. 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 jcom and javatlb command-line options:

Javatlb	Jcom	Notes
/d dir	/d dir	Option works identically
/p package	/p package	Option works identically
/p:b-	/p:b-	Option works identically
/X:m-	/X:m-	Option works identically
/U	N/A	Not supported in jcom*
/U:T	N/A	Not supported in jcom*
*There is no support for generating summary.txt files in jcom because jcom generates human-readable .java source.

@com Directives

Jcom generates Java source files that use a new Microsoft extension known as the "@com directives." These directives must appear inside specially formatted comments, similar to the existing documentation comments syntax. A typical @com directive emitted by jcom might look like this:

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

The directives are significant and used to generate the extra information needed by the Java/COM integration subsystem in the Microsoft Virtual Machine for Java. Therefore, the compiler used to compile jcom's output must process these directives. If you are using the Microsoft Visual J++ compiler (jvc.exe), you must use version 1.02.3920 or later to compile jcom's output. Earlier versions of JVC will not issue an compile-time error but the class files they generate will not work.

This is a Beta release of the @com directive syntax and the syntax is subject to change before final release. Therefore, detailed documentation on the @com directive syntax is not being provided with this release.

Implementing Automation Objects in Java

There are two ways to implement automation objects in Java.

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

The following sections describe each of these methods.

Using Automatic IDispatch.

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

1. Implement the Java object and compile it.
2. Register it using javareg
3. Ensure that the Java class is visible in the CLASSPATH environment variable.

Using the /cj Option with Jcom

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

This approach requires creating an IDL (or ODL) describing your interface and a coclass which uses the [default] attribute to define the default interface. For example,

[ 
	   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;
	};

Invoke jcom on the typelib using the /cj switch. This causes jcom to emit an extra file named CWidgetImpl.java. The CWidgetImpl.java for this typelib looks like this:

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 implemention of CWidget, you can either extend the class:

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

or use CWidgetImpl itself as a template for MyWidget (this is preferable as it eliminates a superclass).

Jcom command-line options

The following section describes the command-line options that jcom can use.

Translation

/b

Follow JavaBeans design pattern for properties. 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", "setFoo" or "putA" (these names were exposed for JavaTLB compatibility only).

/G3.1

Prevents use of features not supported by Version 3.1 of the VM. Disabled by default.

/G4

Prevents use of features not supported by Version 4.0 of the VM. Disabled by default. This switch is reserved for future use.

/r

Causes jcom to register all typelibs mentioned on the command line.

/w

Disables all warnings.

/WX

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

/x2

Map 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 typelibs to be ignored.

/xd-

Jcom normally creates two .java files for each dispinterface: one for use when the interface is the default for a coclass, and one for use when the interface is not the default. The default versions are needed only in order to implement the interface using Java. This switch causes jcom to avoid creating the default versions. This can speed up compilation considerably on large typelibs.

Do not use this switch in conjunction with the /cj option.

/xh

Modifies translation of HRESULTs so that only HRESULTs that have the high (FAIL) bit on 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 pre-4.0 versions of the VM and classes built with this option set will not load on versions prior to 4.0. If your class must run on versions prior to 4.0, you must not use this switch and 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 use of COM objects from Java since default interface methods can be called directly on the object without first casting to an interface pointer. That is, the /xi option allows the following code:

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

to be simplified to:

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

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

/X:m-

By default, the VM assumes that all COM objects passed as parameters are non-threadsafe and performs behind-the-scenes 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 COM library which is thread-safe.

Output

/cj

For each coclass, causes jcom to generate a skeleton file that can be edited to implement that coclass in Java. The file is named <coclass>Impl.java, and includes all of the required methods with dummy bodies that throw an E_NOTIMPL exception. By replacing the class name and filling in the method bodies, you will have a Java class that implements the coclass.

/d directory

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 .java files in c:\mypackages\widgets.

jcom /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 normal VM install sets this to %WINDIR%\java\trustlib.

/e

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

If the /e option is not specified, jcom will recursively compile typelibs needed to resolve all references.

/j

Generates Java source without the extended COM information. Such files can be browsed more easily and will compile; however, they will not integrate with COM if loaded into the VM.

/p package

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

jcom /p gremlinsoft widgets.tlb

This places the .java 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 .java files for all the COM objects produced by your company. The package parameter can have multiple levels; for example, the command

jcom /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.

/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 (&#-106;) following it to disable the automatic creation of the package directory and place 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:

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

Miscellaneous

/?

Prints a brief summary of command-line options.

/l lstfile

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

For example,

jcom -l myfiles.lst widget.tlb

creates a file called mylist.lst which can then be used as input to jvc:

JVC @myfiles.lst

If a relative pathname 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 typelib. The .JNF file is a text file that has the format:

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

Its purpose is to inform jcom that certain types are to be marshalled using a COM Custom Marshalling hook class.

/nologo

Disables the startup banner.