HOWTO: Using DllSurrogate Support for Java/DCOM Servers

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

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 is included with Microsoft Visual J++ versions 1.0 and 1.1, implemented a surrogate process itself, but it had some bugs that make it difficult to set up Java DCOM servers and clients. For more information about this problem with DCOM in Windows 95, see the "References" section of this article. The DCOM support that is 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 later versions) is a new tool that ships with SDK for Java 2.0 and later versions. This tool fixes the bugs that are 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.

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

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

2. Build the class and move the .class file to the windir/Java/trustlib directory, where windir = WINNT or WIN95.
3. 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.
4. After 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.
5. 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 that is included with DCOM for Windows 95 and with Windows NT 4.0 with SP2 or SP3.

Client Side Steps

1. 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.
2. 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.
3. 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
   						

4. 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.

For more information about the new SDK for Java, visit the following Microsoft Web site:For more information about DCOM for Windows 95, visit the following Microsoft Web site: For additional information about the issues that are involved with JAVAREG 1.0's surrogate support, click the following article number to view the article in the Microsoft Knowledge Base: For additional information about the usage of AutoIDispatch mechanism, click the following article number to view the article in the Microsoft Knowledge Base: For support information about Visual J++ and the SDK for Java, visit the following Microsoft Web site: