HOWTO: Use Connectable Objects Including ActiveX Objects in Java

• Microsoft Visual J++, versions 1.0, 1.1
• SDK for Java, versions 2.0, 2.01

SUMMARY

Connectable objects are COM objects that use a standard COM mechanism for notifying clients that something has occurred or changed. ActiveX controls and Automation objects use this mechanism to fire "events." Developer environments such as Visual Basic and Visual C++ have built-in support for these events.

The Microsoft SDK 2.0 for Java gives Java client developers the ability to use these connectable objects and receive their events.

MORE INFORMATION

A connectable object is a COM object that implements the interface IConnectionPointContainer. A client application calls IConnectionPointContainer->FindConnectionPoint() to ask the object if it supports a specific type of connection which is defined by a unique COM interface and ID. If the object supports that connection type, the result is a pointer to an IConnectionPoint interface that represents that specific connection type.

Now that the client application has the object's IConnectionPoint interface for a specific type of connection, the client can instruct the object to add the client as a recipient for the connection's outgoing calls.

To do this, the client application has to create a "sink" object, which is just a COM object that implements the unique COM interface used by this connection. The client then calls IConnectionPoint->Advise() and passes its sink to the connectable object. The object gives the client a value called a "cookie" that represents this connection.

When the connectable object needs to notify the client application that some event has occurred, it makes a call to the interface that is implemented on the clients "sink" object.

Later, when the client wants to disconnect from the object, the client calls IConnectionPoint->Unadvise() and passes in the "cookie."

Fortunately for Java developers, the Microsoft SDK for Java 2.0 makes this process much simpler. To attach a client written in Java to a connectable object, you must first make the "sink" by creating a Java class that implements the COM interface defined in the objects type library. Once you have created an instance of this "sink" class, you will use the com.ms.com.ConnectionPointCookie class to make the "connection" between your sink and the connectable object. All calls to the sink occur in the methods defined on the COM interface.

Example

NOTE: In order to compile the following code, you MUST use the latest Java compiler included in SDK 2.0 or later (Jvc.exe version 1.02.4337 or above). The version of the compiler included with Visual J++ and SDK 1.5 will not work with the source produced by JActiveX.exe. For information on about using the new Java compiler with Visual J++, see the REFERENCES section of this document.

To demonstrate this, use the Internet Explorer 4.0 COM object. Internet Explorer fires "events," or calls to a "sink" object connected to it. Since Internet Explorer's type information includes the description of the interface Internet Explorer uses as a sink, you need to convert the type information into Java classes by using the JActiveX.exe tool.

Open a command prompt and set the current directory to C:\<WINDIR>\SYSTEM[32]\. Make sure that the SDK-JAVA.20\BIN directory is in the PATH, then type:

   JACTIVEX.EXE SHDOCVW.DLL

• InternetExplorer.java
• IWebBrowser2.java
• DWebBrowserEvents2.java

Below is an application that implements the DWebBrowserEvents2 interface:

   import java.awt.*;
   import java.awt.event.*;
   import com.ms.activeX.*;
   import com.ms.com.*;
   import shdocvw.*;  // Import the IE40 package created by JactiveX.

   public class JavaConnect extends Frame
      implements DWebBrowserEvents2, ActionListener
   {
      IWebBrowser2 browser; // Member to hold IE COM object
      TextField location; // Member on Frame for user to type in URL
      TextArea out; // TextArea on Frame that shows Browser status text
      ConnectionPointCookie cookie; // Cookie that connects your event
                                    // "sink" to the browser

      public static void main(String args[])
      {
         // Create an instance of this class. Resize and show.
         final JavaConnect jc = new JavaConnect();
         jc.addWindowListener(new WindowAdapter() {
           public void windowClosing(WindowEvent e)
           {
              if (jc.browser != null)
                 jc.browser.Quit();
           }
         });
         jc.setSize(400,400);
         jc.show();
      }

      public JavaConnect()
      {
         // Create an instance of IE and make it visible
         browser = (IWebBrowser2)new InternetExplorer();
         browser.setVisible(true);

         // Create a ConnectionPoint between the browser
         // and our DWebBrowserEvents2 interface
         cookie = new ConnectionPointCookie(browser, this,
                      shdocvw.DWebBrowserEvents2.class);

         // Create a Panel for the Button and TextField
         Panel northPanel = new Panel();
         northPanel.setLayout(new BorderLayout());

         // Create a Button, add yourself as its ActionListener
         // and add it to the Panel
         Button nav = new Button("Navigate");
         nav.addActionListener(this);
         northPanel.add("West", nav);

         // Create a TextField and add it to the Panel
         location = new TextField();
         northPanel.add("Center", location);

         // Add Panel to Frame
         add("North", northPanel);

         // Create a TextArea and add it to the Frame
         out = new TextArea();
         add("Center", out);
      }

      // ***********************************************************
      // These methods are declared in the ActionListener interface.
      // By implementing this interface, you can receive events
      // from the button on the Frame.

      public void actionPerformed(ActionEvent e)
      {
         // Create a variant for use with the optional
         // parameters of the Navigate2 method
         Variant optional = new Variant();
         optional.noParam();

         // Call Navigate2 on IE
         browser.Navigate2(new Variant(location.getText()),
                               optional, optional, optional, optional);
      }

      // ***************************************************************
      // These methods are declared in the DWebBrowserEvents2 interface.
      // By implementing this interface and using a ConnectionPointCookie,
      // you can receive events from Internet Explorer.
      // Each method represents a different event that can come from
      // Internet Explorer.

      public void StatusTextChange(String Text)
      {
         // The status bar information has changed.
         // Append this new status text to the TextArea.
         out.append(Text+"\n");
      }

      public void ProgressChange(int Progress, int ProgressMax)
      {}

      public void CommandStateChange(int Command, boolean Enable)
      {}

      public void DownloadBegin()
      {}

      public void DownloadComplete()
      {}

      public void TitleChange(String Text)
      {}

      public void PropertyChange(String szProperty)
      {}

      public void BeforeNavigate2(Object pDisp, Variant URL,
          Variant Flags, Variant TargetFrameName, Variant PostData,
          Variant Headers, boolean[] Cancel)
      {}

      public void NewWindow2(Object[] ppDisp, boolean[] Cancel)
      {}

      public void NavigateComplete2(Object pDisp, Variant URL)
      {}

      public void DocumentComplete(Object pDisp, Variant URL)
      {}

      public void OnQuit()
      {
         // The user closed IE.
         out.append("Quiting IE\n");
         cookie = null;

         // Manually release the browser COM object.
         // This is not necessary, but ensures that no extra
         // references to the COM object hang around after we
         // exit the Java application.
         ComLib.release(browser);

         browser = null;
         System.exit(0);
      }

      public void OnVisible(boolean Visible)
      {}

      public void OnToolBar(boolean ToolBar)
      {}

      public void OnMenuBar(boolean MenuBar)
      {}

      public void OnStatusBar(boolean StatusBar)
      {}

      public void OnFullScreen(boolean FullScreen)
      {}

      public void OnTheaterMode(boolean TheaterMode)
      {}
   }

• The COM object that is a connectable object
• A Java object that implements the sink interface
• The Class object that represents the sink interface

The ConnectionPointCookie handles all of the COM complexities of attaching the sink to the correct IConnectionPoint on the connectable object.

When this application is executed using the following you will see two windows:

   jview JavaConnect

By clicking on the window close button on the Browser, you can send an OnQuit event to the Java application. The application responds by releasing the Internet Explorer COM object and quitting.

REFERENCES

For more information on connectable objects and Automation events, see "Inside OLE" (Second Edition) by Kraig Brockschmidt, Microsoft Press.

For more information on ConnectionPointCookie, see the Microsoft SDK for Java 2.0 documentation available at http://www.microsoft.com/java/sdk/.

For information on about using the new Java compiler with Visual J++, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q177165
   TITLE     : INFO: Use New Java 1.1 Language Features with Visual J++ 1.1