How To Use Connectable Objects Including ActiveX Objects in Java

View products that this article applies to.

This article was previously published under Q179849

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 for Java 2.0 and later gives Java client developers the ability to use these connectable objects and receive their events.

Back to the top

MORE INFORMATION

A connectable object is a COM object that implements the interface IConnectionPointContainer. A client application calls IConnectionPointContainer and 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 and 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 and Unadvise() and passes in the "cookie."

Fortunately for Java developers, the Microsoft SDK for Java 2.0 and later versions make 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. After 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 that are defined on the COM interface.

Back to the top

Example

NOTE: In order to compile the following code, you must use the latest Java compiler that is included in SDK 2.0 or later (Jvc.exe version 1.02.4337 or later). 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 article.

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 This produces a directory and many files under C:\<WINDIR>\JAVA\TRUSTLIB\. The directory name is Shdocvw and the following list shows the files that you need to know about:

InternetExplorer.java
IWebBrowser2.java
DWebBrowserEvents2.java

These files are the wrapper classes for the Internet Explorer 4.0 COM object and its interfaces.

Notice the DWebBrowserEvents2.java file. This source file contains the interface definition for the sink required to connect to Internet Explorer 4.0. The methods on the interface represent the events that Internet Explorer "fires." This sink has many methods. The two that we are concerned with for this sample are StatusTextChange(String Text) and OnQuit(). In order for a program to receive Internet Explorer's events, you need to create a class that implements this interface.

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)
   {}
}

In the constructor, create a ConnectionPointCookie. The constructor parameters should be based on the following:

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

In this application's case, you called ConnectionPointCookie(browser, this, shdocvw.DWebBrowserEvents2.class).

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

One is a Java Frame that contains a TextField, a Button, and a TextArea. The other is the Internet Explorer windows. On the Java Frame, enter a URL in the TextField and click Navigate. You should notice the Internet Explorer window load the URL you specified. As Internet Explorer loads the Web page, the Status Bar at the bottom of the browser window changes to give the user an updated status. This text is also echoed to the Java application through the event mechanism. The applications StatusTextChange() method gets called each time. The StatusTextChange method appends the text to the bottom of the TextArea on the Frame.

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.

Back to the top

REFERENCES

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

For more information about ConnectionPointCookie, see the Microsoft SDK for Java at the following Microsoft Web site:

http://www.microsoft.com/mscorp/java (http://www.microsoft.com/mscorp/java)

For additional information about using the new Java compiler with Visual J++, click the following article number to view the article in the Microsoft Knowledge Base:

177165 (http://support.microsoft.com/kb/177165/EN-US/ ) INFO: Use New Java 1.1 Language Features with Visual J++ 1.1

Back to the top