Because the Java proxies generated by com2java tool are simply mapped from the original COM programming API, you need to refer to the original documentation of the COM API to understand what each corresponding Java proxy does. The comments in the Java proxies are based on the comments found from the COM IDL file. The easiest way to start programming Java source code (which uses J-Integra for COM to access a COM component) is to find a VB example first, and then map the VB code to Java. This article covers some basic principles to map VB code to its equivalent Java code.

1. Object
   1.1 Creating a New Object
   1.2 Retrieving an Existing Active Object
   1.3 Casting an Object into Another Object
   1.4 Embedding an ActiveX Control
   1.5 Getting an Object from Its Collection
2. Method
   2.1 Object Parameter
   2.2 Array Parameter
3. Property
   3.1 Basic Property
   3.2 Default Property
   3.3 Constant Property
4. Event

1. Object

Each COM object is mapped to a Java Class, and each COM interface is mapped to a Java Interface. Both the COM and Java object models will have the same object inheritance.

1.1 Creating a New Object

In the Excel Object Model (for example), you can create a new Application object, which is the basic object used to automate Excel. Each COM component has its own basic object, and you need to refer to the documentation of the COM component itself to find out its basic object.

VB

Dim app As Excel.Application
Set app = New Excel.Application
Set app = CreateObject("Excel.application", "localhost")
Set app = CreateObject("Excel.application", "123.45.6.78")

Java

Excel.Application app;
app = new Excel.Application();
app = new Excel.Application("localhost");
app = new Excel.Application("123.45.6.78");

1.2 Retrieving an Existing Active Object

VB

Set app = GetObject("", "Excel.application")

Java

Refer to the related KB article 30397 Connecting to a Running MS Office Application.

1.3 Casting an Object into Another Object

VB

Dim objA as ComObjectA
Set objA = New ComObjectB

Java

You CANNOT cast a COM object as a standard Java object:

ComObjectA objA = new ComObjectA();
ComObjectB objB = new ComObjectB();
objA = (ComObjectA) objB; // this will cause a java.lang.ClassCastException

Instead, you must cast the COM object this way:

ComObjectA objA = new ComObjectA();
ComObjectB objB = new ComObjectB();
objA = new ComObjectA(objB);

1.4 Embedding an ActiveX Control

Remember to always display the ActiveX Control before invoking its methods. Refer to KB article 30945 NullPointerException when Working with ActiveX Controls for more information.

For example, to embed an Acrobat Reader 6 ActiveX Control:

VB

Dim pdf As PdfLib.pdf
Set pdf = Controls.Add("PDF.PdfCtrl.6", "pdf")
pdf.Width = 4000
pdf.Height = 4000
pdf.Visible = True
Controls.Remove "pdf"

Java

PDF pdf = new Pdf();
pdf.setSize(250, 250);
pdfControl.setVisible(true);
JPanel panel = new JPanel();
panel.add(vControl, BorderLayout.CENTER);
JFrame frame = new JFrame();
frame.getContentPane().add(pdf, BorderLayout.CENTER);
panel.remove(pdf);

1.5 Getting an Object from Its Collection

The Java method which retrieves an object always has a prefix "get". In the Excel Object Model, an object Application contains an object Workbooks, and you will find a corresponding getWorkbooks method which returns a Workbooks object in the Application class. A Windows object is a collection of all the Window objects. An index number is required to get a Window object from its collection in VB. When getting the Window object in Java, you need to pass an Integer object as its index number.

VB

Dim App As Excel.Application
Set App = New Excel.Application
App.Workbooks.Add ' Add a new book
App.Windows.Item(1) ' Get the first Window

Java

Application app = new Application();
app.getWorkbooks().add(null); // Add a new book
app.getWindows().getItem(new Integer(1)); // Get the first Window

2. Method

Each method of a COM object is mapped to a method in its corresponding Java Class. The method names are identical among IDL, VB and Java. Refer to Supported COM Data Types for more information about how the object used in parameter is mapped from VB to Java.

2.1 Object Parameter

If a parameter is passed as a VB String or Int, but mapped to an object in Java, you will need to convert it into a Java object to use it.

VB

object.method("a string", 1)

Java

The method may contain this signature in Java:

public void method(Object x, Object y) {
   ...
}

To use it, pass the appropriate object type:

object.method(new String("a string"), new Integer(1));

2.2 Array Parameter

There are some specific ways to pass a 2D or multi-dimensional array as a parameter. Please refer to the related KB articles:

96334 : AutomationException: 0x800a0009 - Subscript out of range
78598 : Accessing Multidimensional Java Arrays From a COM Client
30430 : Using a SAFEARRAY with Java and Visual C++
89771 : Converting Excel Automation Date Type to java.util.Date

3. Property

3.1 Basic Property

If a property is read/write, the generated Java proxy class will contain get and set methods for it. If the property is read-only, the generated Java proxy class will only contain a get method. In the Excel Object Model, the object Window contains a property Caption, and you can use the get and set methods to manipulate this property in Java.

VB

Dim App As Excel.Application
Set App = New Excel.Application
App.Workbooks.Add ' Add a new book
App.Windows.Item(1).Caption = "Test Window"
MsgBox App.Windows.Item(1).Caption

Java

Application app = new Application();
app.getWorkbooks().add(null); // Add a new book
app.getWindows().getItem(new Integer(1)).setCaption("Test Window");
System.out.println( app.getWindows().getItem(new Integer(1)).getCaption() );

3.2 Default Property

In the Excel Object Model, you will find that some objects have a default property.

VB

According to Microsoft's documentation of the property Cells... "because the Item property is the default property for the Range object, you can specify the row and column index immediately after the Cells keyword."

workSheets("Sheet1").cells(n, 1).Value = "hello"

Java

Because workSheet.getCells() returns a Range object, you will find a getItem(Object index) method in Range.java:

Sheets sheets = workbook.getWorksheets();
WorkSheet workSheet = new WorkSheet(sheets.getItem("Sheet1"));
workSheet.getCells().getItem(new Integer(n), new Integer(1)).setValue("hello");

3.3 Constant Property

In the Excel COM object API, the property XlWindowView can be one of two constants: xlNormalView and xlPageBreakPreview. In Java, the property XlWindowView is mapped to the interface XlWindowView containing two constants: xlNormalView and xlPageBreakPreview.

VB

Dim App As Excel.Application
Set App = New Excel.Application
App.Workbooks.Add 'Add a new book
App.ActiveWindow.View = xlPageBreakPreview

range.Value(xlRangeValueDefault)

Java

Application app = new Application();
app.getWorkbooks().add(null); // Add a new book
app.getActiveWindow().setView(XlWindowView.xlPageBreakPreview);

If the method takes an Integer object (instead of an Int type) as its parameter, then you need to convert the int type into an Integer object. For example

range.setValue(new Integer(XlRangeValueDataType.xlRangeValueDefault), newValue);

4. Event

This example illustrates how to fire and catch the Internet Explorer event NavigateComplete2 which contains two properties pDisp and URL.

IDL

[
  uuid(34A715A0-6587-11D0-924A-0020AFC7AC4D),
  helpstring("Web Browser Control events interface"),
  hidden
]
dispinterface DWebBrowserEvents2 {
  properties:
  methods:
  ...
  [id(0x000000fc), helpstring("Fired when the document being navigated to becomes visible and enters the navigation stack.")]
  void NavigateComplete2(
    [in] IDispatch* pDisp,
    [in] VARIANT* URL);

VB

Dim WithEvents ie As SHDocVw.InternetExplorer

Private Sub Command1_Click()
  Set ie = New SHDocVw.InternetExplorer
  ie.Visible = True
  ie.Navigate2 "http://www.intrinsyc.com"
End Sub

Private Sub ie_NavigateComplete2(ByVal pDisp As Object, URL As Variant)
  MsgBox "NavigateComplete2 " + URL
End Sub

Java

InternetExplorer ie = new InternetExplorer();
ie.addDWebBrowserEvents2Listener(new DWebBrowserEvents2Adapter(){
  public void navigateComplete2(DWebBrowserEvents2NavigateComplete2Event theEvent)
    throws java.io.IOException, com.linar.jintegra.AutomationException {
    System.out.println("NavigateComplete2 " + theEvent.getURL());
  }
});
ie.setVisible(true);
ie.navigate2("http://www.intrinsyc.com", null, null, null, null);
synchronized (listener) {
  listener.wait();
}
ie.removeDWebBrowserEvents2Listener(listener);

Refer to the Internet Explorer example for the complete Java source code.