Developing MTS Components with Java

You can develop Java MTS components using tools provided by MTS and Visual J++. It is also recommended that you install the latest version of the Microsoft SDK for Java, available at http://www.microsoft.com/java.

This section contains the following topics:

• Implementing a Component in Java
  
  
• Using an MTS Component from Java
  
  
• Using the Java Sample Bank Components

Implementing a Component in Java

To implement a component in Java, follow these steps

1. Run the ActiveX Component Wizard for Java (available with Visual J++) for each Java class file. Use the wizard to create new IDL files.
   
   
2. Modify the IDL files to add JAVACLASS and PROGID to the coclass attributes. See "Using IDL Files with Java Components."
   
   
3. Run the ActiveX Component Wizard for Java again. Use the IDL files that you created in Step 1 to create type libraries for your components.

   This will create a set of Java class files, typically under \%systemroot%\Java\Trustlib. It will create one class file for each custom interface, and one class file for each coclass in the library.

4. Run JAVAGUID against each class file generated in Step 3. See "Working with GUIDs in Java" for more information.
   
   
5. Recompile your Java implementation classes.
   
   
6. Run EXEGEN to convert the type libraries and class files into a DLL. See "Using EXEGEN to Create DLLs."
   
   
7. Use the MTS Explorer to install the DLL.

Using IDL Files with Java Components

To specify the custom attributes in a type library, add the following in your IDL or ODL file:

#include <JavaAttr.h>

Within the attributes section of a coclass, specify the JAVACLASS:

JAVACLASS("package.class")

You may optionally specify a PROGID:

PROGID("Progid")

For example:

	[
		uuid(a2cda060-2d38-11d0-b94b-0080c7394688),
		helpstring("Account Class"),
		JAVACLASS("Account.AccountObj"),
		PROGID("Bank.Account.VJ"),
		TRANSACTION_REQUIRED
	]
	coclass CAccount
	{
		[default] interface IAccount;
	};

Using EXEGEN to Create DLLs

EXEGEN is the Java executable file generator. To use this file, copy it to the appropriate destination folders (usually \JavaSDK\bin). This version of EXEGEN.EXE is capable of creating DLL files from Java classes, and can also include user-specified resources in its output files. This version of EXEGEN no longer supports the /base: directive. Class files are always included with the proper name. It supports a new /D directive that causes it to generate a DLL file instead of an EXE.

EXEGEN is now capable of reading five types of input files:

• Java class files
  
  
• RES files containg resources to be included
  
  
• Executable files containg resources to be included
  
  
• TLB files containing type libraries to be included
  
  
• Text files describing which classes should be registered (DLL only).

If you use EXEGEN to create a DLL, the DLL can self-register any included Java classes that implement COM objects. There are two ways to tell EXEGEN which classes should be registered:

• Include a type library that contains custom attributes for the classes. This is the preferred method.

  û or û

• Include a text file as input that gives EXEGEN the necessary directions. Each line of the text file describes one Java class, using the following keywords:
  • class:JavaClassName

    Required keyword.

  • clsid:{.....}

    Optional keyword that specifies the clsid GUID. If omitted, EXEGEN chooses a unique GUID.

  • progid:ProgId

    Optional keyword. If omitted, the class will be registered without a progid.

Working with GUIDs in Java

When an MTS method uses a GUID parameter, you must pass an instance of class com.ms.com._Guid. Do not use class Guid, CLSID or IID from package com.ms.com; they will not work and they are deprecated. The definition of class _Guid is:

package com.ms.com;
public final class _Guid {

	// Constructors
	public _Guid (String s);
	public _Guid (byte[] b);
	public _Guid (int a, short b, short c,
		byte b0, byte b1, byte b2, byte b3,
		byte b4, byte b5, byte b6, byte b7);
	public _Guid ();

	// methods
	public void set(byte[] b);
	public void set(String s);
	public void set(int a, short b, short c,
		byte b0, byte b1, byte b2, byte b3,
		byte b4, byte b5, byte b6, byte b7);

	public byte[] toByteArray();
	public String toString();
}

Instances of this class can be constructed from a String (in the form ô{00000000-0000-0000-0000-000000000000}ö), from an array of 16 bytes, or from the usual parts of a Guid. Once constructed, the value can also be changed. Method toByteArray will return an array of 16 bytes as stored in the Guid, and method toString will return a string in the same form used by the constructor.

JAVAGUID.EXE

Microsoft Transaction Server supplies a tool, JAVAGUID.EXE, that will post-process the output of JAVATLB. The following occurs for each class file:

• If any method takes a GUID as a parameter, the class of that parameter will be changed to com.ms.com._Guid.
  
  
• If the class file is an interface derived from a type library, a public static final member named iid will be added to the class. This member will contain the interface ID of the interface.
  
  
• If the class file represents a coclass derived from a type library, a public static final member named clsid will be added to the class. This member will contain the CLSID of the class.

The clsid and iid members that JAVAGUID adds are useful as parameters to IObjectContext.CreateInstance and ITransactionContextEx.CreateInstance.

JAVAGUID can only be executed from the command line. It takes one or more parameters which are names of class files to update.

JAVATLB will eventually be updated to make JAVAGUID unnecessary.

Using an MTS Component from Java

To use an MTS component from Java, run the Java Type Library Wizard against the type library for the component. This will create several Java class files, typically under \%systemroot%\Java\TrustLib. It will create one class file for each custom interface, and one class file for each coclass in the library.

Assume, for example, that the type library contained one interface named IMyInterface, and one coclass, named CMyClass.

From Java, you can create a new instance of the component by executing

new CMyClass()

If you want to control transaction boundaries in the class, you can execute

ITransactionContextEx.CreateInstance ( CMyClass.clsid, IMyInterface.iid )

You should never call JavaÆs new operator on the class that you implemented. Instead, use one of the following techniques:

• Use Java's new operator on the class created by the Java Type Library Wizard. This will cause the Java VM to call CoCreateInstance.
  
  
• Call MTx.GetObjectContext().CreateInstance (clsid, iid);
  This will create a new instance in the same activity as the current instance. This only works if the calling code is itself an MTS component.
  
  
• If you have a reference to an ITransactionContextEx object, call its CreateInstance method. This will create a new instance in the transaction owned by the ITransactionContextEx object.

All of these techinques will result in the creation of a new instance of the class that you implemented.

Using the Java Sample Bank Components

The Java Sample Bank components are automatically configured by MTS Setup and require no additional steps in order to run them.

If you want to recompile the Java Sample Bank components, follow these steps:

1. Run the SetJavaDev.bat file located in the \mts\Samples\Account.VJ folder. Javatlb.exe must be in your path for this batch file to run properly.
   
   
2. Recompile your Java component implementation classes.
   
   
3. After you recompile the component classes, use the mkdll.bat file located in the \mts\Samples\Account.VJ folder to generate and register vjacct.dll. Exegen.exe must be in your path for this batch file to run properly. You can also add running mkdll.bat as a build step to your Visual J++ project to simplify recompiling.
   
   
4. Using the MTS Explorer, import the new components into the Sample Bank package.