Article ID: 179849 - View products that this article applies to.
This article was previously published under Q179849
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.
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.
ExampleNOTE: 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\. 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:
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:
In the constructor, create a ConnectionPointCookie. The constructor parameters should be based on the following:
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:
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.
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/javaFor 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:
(http://support.microsoft.com/kb/177165/EN-US/ )INFO: Use New Java 1.1 Language Features with Visual J++ 1.1
Article ID: 179849 - Last Review: November 14, 2005 - Revision: 2.5