HOWTO: Using DllSurrogate Support for Java/DCOM Servers

ID: Q173790

The information in this article applies to:

Microsoft SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

This article explains how to use a Java COM object as a Distributed COM (DCOM) server using the system surrogate provided by DCOM in Windows 95 and Windows NT 4.0 with SP2 or SP3.

MORE INFORMATION

DCOM allows COM objects to be activated on remote machines. It allows clients to create and invoke the methods of objects on other machines. Java objects can be used remotely using DCOM. One way to remotely use a Java object is by using the system surrogate support (DllSurrogate) in DCOM for Windows 95 and Window NT 4.0 with SP2 or SP3 along with the Microsoft virtual machine (Microsoft VM). JAVAREG is a tool that supports remote access to a COM class implemented in Java. It is a command-line tool that is used for registering Java classes as COM components in the registry. In fact many of JAVAREG's options are intended for use only with DCOM.

The JAVAREG (version 1.0) that shipped with Microsoft Visual J++, versions 1.0 and 1.1 implemented a surrogate process itself, but it had some bugs making it difficult to set up Java DCOM servers and clients. There is also a Knowledge Base article listed in the REFERENCES Section below that addresses this problem. The DCOM support now in Windows 95 and Windows NT 4.0 with SP2 and SP3 supports a surrogate as part of the system, so the surrogate support with JAVAREG 1.0 has been dropped.

JAVAREG 2.0 and newer is a new tool that ships with SDK for Java 2.0 and newer. This tool fixes the bugs associated with JAVAREG 1.0 and supports remote access to a Java COM object using the system provided surrogate process. The following steps explain how to set up a Java/COM object as a DCOM server using the new JavaReg2.0 tool.

Server Side Steps

The following sample makes use of the AutoIDispatch mechanism where you do not need to create an IDL file for your Java COM object. This method does not require tools like JAVATLB or JACTIVEX that ship with the SDK for Java 2.0x. For more information on the use of the AutoIDispatch mechanism, see the REFERENCES section below.

Using Visual J++ 1.1, create the following Java class:


public class TestDCOM
{
   public String getString()
   {
      String str = "SSSS";
      return str;
   }
}

Build the class and move the .class file to the <windir>/Java/trustlib directory, where <windir> = WINNT or WIN95.

Run JAVAREG (version 2.0 and later):
```
javareg /register /class:TestDCOM /progid:TestDCOM.1 /surrogate 
```
This step generates a class ID (CLSID) for your class and automatically adds the DllSurrogate (which is the system surrogate)to the APPID portion of your Java Class in the registry. So if you run Regedit.exe, you can find this key under HKEY_CLASSES_ROOT\APPID\{yourclsid}.

If you want to use a CLSID that you have already allocated, you can use the /clsid: flag to specify it, and JavaReg2.0 and later will use the one you specify. In either case, you need to note your CLSID so that you can use it on your client machine.

Once you have registered the COM object successfully, run OLEVIEW, which is a tool that lets you view all the registered COM objects interfaces and Type_Libraries. Select View.ExpertMode and also set Object.CoCreateInstance flags to CLSCTX_LOCAL_SERVER and CLSCTX_REMOTE_SERVER. (Make sure that CLSCTX_INPROC_SERVER is not selected). Expand the Java classes node. Then expand the Java Class:TestDCOM node. This is the same as right-clicking and selecting CreateInstance on the class. If it expands showing all the interfaces, then your COM object has been created in a separate process on your machine. Getting your class to activate out-of-process on a single machine is the first step towards getting it to activate on another machine, so it is essential that you test this scenario first.

Configure your applications to run your Java COM object in a remote machine and provide both Launch and Access Permissions to the remote machine user. You can do this either using OLEVIEW or DCOMCNFG. DCOMCNFG is a utility included with DCOM for Windows 95 and Windows NT 4.0 with SP2 or SP3.

Client Side Steps

Run JAVAREG 2.0 or later:
```
javareg /register /class:TestDCOM /progid:TestDCOM.1
/clsid:{yourclsid}
/remote:servername 
```
Where /remote:servername is a new option that lets you specify the remote server machine name.

Use OLEVIEW to test that your class activates remotely. Run OLEVIEW on the client, find the Java Classes:TestDCOM class under the Java Classes component category, and double-click it. After a brief pause you will see the list of interfaces your class supports displayed by OLEVIEW. If you use the Task Manager on the server machine to look at the running processes, you will see Dllhost.exe running. This is the surrogate process under which your class is running on the server.

Now you can create a Visual Basic application (or any other client such as Visual C++ or VBScript) to create an instance of TestDCOM.1:
```
Dim X As Object
Dim str As String
Set X = CreateObject("TestDCOM.1")
str = X.getString()
MsgBox str 
```

Now you should be able to run this Vb.exe file from your client machine, which will remotely activate the TestDCOM object on the server machine.

NOTE: If the client application specifies both a CLSID (instead of relying on the ProgID) and a remote server name to CoCreateInstanceEx (or equivalent), then no client side registration steps are necessary.

Other Tips

Whenever you attempt to get a DCOM solution to work, it is useful to know when processes are starting and stopping on a machine. One very effective way to do this is to enable the "Process Start" and "Process Stop" sounds in the Sounds Control Panel applet. With these sounds enabled (and set to two distinguishable noises), you will be able to tell whenever a process starts or stops on your machine. This is useful in tracking down problems where DCOM's launch security has allowed a client to launch the server process, but access security is disallowing access (you'll hear the process start sound, but the client will get E_ACCESSDENIED from the activation request). Of course, this requires that your server machine have a sound card installed with appropriate drivers.

Use OLEVIEW to test that your components are installed and registered correctly. Always test new components first in-process (CLSCTX_INPROC_SERVER checked in OLEVIEW), then cross-process-same-machine (CSLCTX_LOCAL_SERVER), then remotely (CLSCTX_REMOTE_SERVER with no LocalServer32 key). By doing this you reduce the number of variables (things that can go wrong) as you do your testing.

REFERENCES

Download the new SDK for Java from http://www.microsoft.com/java/.

For additional information on downloading DCOM for Windows 95, please see http://msdn.microsoft.com/library/default.htm.

For additional information on the issues involved with JAVAREG 1.0's surrogate support please refer to the following Microsoft Knowledge Base article:

Q162164 BUG: Using Java Servers and DCOM

For additional information on the usage of AutoIDispatch mechanism, please refer to the following Knowledge Base article:

Q172202 INFO: Implementing Java Automation Objects Using AutoIDispatch

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/

http://support.microsoft.com/support/java/

Additional query words: Java DCOM surrogate

Keywords : kbCOMt kbSDKJava200 kbSDKJava201 kbSDKJava300 kbSDKJava310 kbSDKJava202 JCOM kbSDKJava320 kbSDKJavaFAQ kbJavaFAQ
Version : WINDOWS:2.0,2.01,2.02,3.0,3.1,3.2
Platform : WINDOWS
Issue type : kbhowto