COM Clients Accessing Java Objects Running on EPOC

Java/J2EE COM Interoperability Products Page


  1. Introduction
    1. What is EPOC
    2. What is DCOM
  2. Prerequisites
  3. Setting up the EPOC machine
  4. Setting up the Windows machine, and running the VB client
  5. Summary

1 Introduction

In this document I will briefly show you how you can easily access unmodified Java objects running on EPOC devices from COM clients running under Windows. This means that you can access your unmodified Java objects running on your Psion palmtop from COM clients such as Visual Basic, Visual C++ or any other COM environment.

This example makes use of the J-Integra® pure Java-COM bridge.

1.1 What is EPOC?

EPOC is an Operating System originally created by Psion, and now maintained and developed by Symbian, which is a consortium of companies including Ericsson, Motorola, Nokia, Panasonic and Psion.

The EPOC Operating System is used on a wide variety of hand-held and communications devices, such as the Psion Series 5mx, the Psion Revo, and the Ericsson R380.

Among the many cool features of EPOC is its support for the Java environment. This means that you can run standard Java programs on EPOC devices.

1.2 What is DCOM?

Microsoft have defined a standard binary interface for interaction between software components, called the Component Object Model (COM). They also defined a wire-level protocol for allowing distributed COM objects to interoperate, and they named this protocol Distributed COM (DCOM). DCOM can talk over various communications protocol, including TCP/IP.

J-Integra® incorporates a pure Java DCOM engine, allowing you to talk from Java objects to COM objects, and from COM objects to Java objects. It exposes COM objects to Java clients as though the COM objects were Java objects, and it exposes Java objects to COM clients as though they were COM objects.

This document takes you step-by-step through an example of accessing a standard Java object (an instance of a java.util.Hashtable) running on an EPOC device, from a Visual BASIC client running under Windows.

2 Prerequisites

In order to run this example you will need an EPOC device with Java installed on it, such as a Psion Series 5mx, or a Psion Revo (although Java is not officially supported on the Revo, if you have nothing else installed on a Revo, Java will run -- this example was created on a Revo).

You will need a Windows machine with Visual Basic installed on it. DCOM comes as part of Windows NT, and Windows 98, and for Windows 95 it can be downloaded from the MS Web Site.

3 Setting up the EPOC machine

Ensure that Java is installed on the EPOC machine.

  1. Download J-Integra®. Unzip the kit and copy the jintegra.jar runtime to the C:\System\Java\Ext subdirectory (you may need to create the Ext subdirectory) on the EPOC machine.

  2. Create a C:\Documents\DCOM subdirectory on the EPOC machine into which we will put the Java classes used to start the JVM hosting the Java objects to be accessed from the VB client.

  3. There is a bug in the EPOC Java implementation which means that attempts to get the local machine's IP address from Java don't get the current address. There is a fix here: Download the file from that web site, and copy EpocLocalHost.class to the C:\Documents\DCOM directory you created.

    Also copy the localhost.dll file from the Release\Arm directory in the ZIP file to the C:\System\LIBS directory on the EPOC machine.

  4. This is the Java classes which we will run on the EPOC machine. It initializes the J-Integra® runtime. You could simply add the relevant initialization code to an existing Java program which you run on EPOC machine.

    You will need to compile this Java code on a Windows machine first. To do so, make sure that your CLASSPATH includes the J-Integra® runtime (jintegra.jar).

    Copy EpocDCOM.class to C:\Documents\DCOM directory you created on the EPOC device.

    The line in bold is really what it is all about -- the rest is to work around the EPOC IP address bug, and to enable logging.

    // This program initializes the J-Integra® runtime so that COM clients can access Java
    // objects running on an EPOC machine.  You run this class on the EPOC machine.
    import java.awt.*;
    import java.awt.event.*;
    public class EpocDCOM
     implements ActionListener {
     public static void main(java.lang.String[] args)throws Exception {
       // Pop up a button to let the user know what is happening
       Frame frame = new Frame("Click to end");
       Button btn = new Button("Connecting to the internet ...");
       btn.addActionListener(new EpocDCOM());
       // Get the local IP address.  This section of code is not normally required
       // when using J-Integra®.  It is specific to EPOC because of an EPOC bug.
       String ipAddress = EpocLocalHost.localHost();
       java.util.Properties properties = System.getProperties();
       properties.put("com.linar.jintegra.server", ipAddress);
       // Big performance hit, so comment out the logImmediately() line when using
       // this for real.
       btn.setLabel("Enabling logging ...");
       com.linar.jintegra.Log.logImmediately(3, "jintegra.log");
       // Register the name of the JVM and the TCP/IP port the J-Integra® runtime
       // should listen on for DCOM requests.
       btn.setLabel("Registering JVM ...");
       com.linar.jintegra.Jvm.register("epocjvm", 1350);
       // Tell the user how they should register the JVM on the windows client.
       btn.setLabel("On Windows machine do: regjvmcmd epocjvm " + ipAddress + "[1350]");
       // Wait until the JVM is killed by the user clicking on the button
       while(true) Thread.sleep(100000);
     public void actionPerformed(ActionEvent e) {

You have now set up the EPOC device, and by double-clicking on EpocDCOM.class you can start up the JVM. When you do this you will see frame with a button, the text in the button changes as the JVM is initialized, and it eventually finishes with On Windows machine do: regjvmcmd epocjvm W.X.Y.Z[1350]. Where W.X.Y.Z is the TCP/IP address of the EPOC device.

In order to connect to the EPOC device from the VB client you will need to be able to talk to that device over TCP/IP from the Windows machine.

If the IP address is then the TCP/IP initialization failed. If your Windows Client is Windows NT then you can check that the EPOC device is reachable using the tracert command from a DOS console -- pass the EPOC device's IP address as the parameter.

4 Setting up the Windows machine, and running the VB client

Having started the JVM on the EPOC device, you will need to register its location on the Windows client machine.

  1. Do this using the J-Integra® 'regjvmcmd' command which is in the 'bin' directory of the J-Integra® kit. Assuming you unzipped the file to C:\jintegra, use this command from the DOS prompt:

    C:\jintegra\bin\regjvmcmd epocjvm W.X.Y.Z[1350]

    where W.X.Y.Z is the ip address displayed on the EPOC device when you ran EpocDCOM.class.

    If you had already registered the JVM you will need to unregister it using the regjvmcmd /unregister command prior to re-registering it (if its IP address had changed, for example).

  2. Next start up Visual BASIC, create a new Standard EXE project, double-click on the displayed form to edit the code that is run when the form is displayed, and enter the following Visual BASIC code:

    Private Sub Form_Load()
      Set ht = GetObject("epocjvm:java.util.Hashtable")
      ht.put "testing", "123"
      MsgBox ht
    End Sub

  3. Run the VB program ... you should see a message box containing the contents of the Hashtable (actually the result of doing Hashtable.toString()).

Although this example just creates a Hashtable, you can instantiate any public class on the EPOC device that has a public default constructor and invoke any public method or field. Any such class on the EPOC device is accessible.

A jintegra.log file will be created on the EPOC device. This is used for debugging, but its contents will show the DCOM requests emanating from the Windows client.

5 Summary

In this short paper you have seen how you can access pretty much any Java object running on an EPOC device from a COM client such as Visual Basic running on Windows. The reverse is also possible, and equally trivial to set up -- accessing Windows based COM objects from a Java client running on an EPOC device is also easy.