Programming WebLogic jCOM

Overview of WebLogic jCOM

The following sections provide an overview of WebLogic jCOM:

What Is WebLogic jCOM?

WebLogic jCOM is a software bridge that allows bidirectional access between Java/J2EE objects deployed in WebLogic Server, and Microsoft ActiveX components available within Microsoft Office family of products, Visual Basic and C++ objects, and other Component Object Model/Distributed Component Object Model (COM/DCOM) environments.

In general, BEA Systems believes that Web services are the preferred way to communicate with Microsoft applications. We suggest that customers plan to migrate legacy COM applications to .NET in order to leverage this type of communication. jCOM is provided as a migration path for interim solutions that require Java-to-COM integration. It is suitable for small projects or bridge solutions.

Unlike other Java-to-COM bridges available on the market, jCOM is specifically designed to work with WebLogic Server on the Java side. You cannot use jCOM to make COM objects communicate with any arbitrary Java Virtual Machine (JVM). In addition, jCOM makes direct use of WebLogic Server threads, providing a very robust way to expose services to COM objects.

WebLogic jCOM makes the differences between the object types transparent: to a COM client, WebLogic Server objects appear to be COM objects and to a WebLogic Server application, COM components appear to be Java objects.

WebLogic jCOM is bidirectional because it allows:

Microsoft COM clients to access objects in WebLogic Server as though they were COM components.

and

Applications within WebLogic Server to access COM components as though they were Java objects.

An Important Note on Terminology

Throughout the remainder of this programming guide, we refer to the two types of applications by their directions of access. Thus:

An application in which a COM client accesses WebLogic Server objects is a "COM-to-WLS" application.
An application in which WebLogic Server accesses COM objects is a "WLS-to-COM" application.

jCOM Architecture

WebLogic jCOM provides a runtime component that implements both COM/DCOM over Distributed Computing Environment Remote Procedure Call, and Remote Method Invocation (RMI) over Java Remote Method protocol/Internet Inter-ORB Protocol distributed components infrastructures. This makes the objects on the other side look like native objects for each environment.

WebLogic jCOM also provides automated tools to convert between both types of interfaces: it automatically builds COM/DCOM proxies and RMI stubs necessary for each side to be able to communicate via the above mentioned protocols.

WebLogic jCOM does all the necessary translation between DCOM and RMI technologies, and connects to WebLogic Server as an RMI client. It then communicates requests to Enterprise Java Beans (EJBs) deployed in the WebLogic Server as if the request comes from a regular EJB client.

In a similar manner, when a component deployed in WebLogic Server requests services provided by a DCOM object, the request is translated by the jCOM component from a regular RMI client request issued by the WebLogic Server into DCOM compliant request, and communicated to the DCOM environment to the appropriate object.

Use dcomcnfg to configure DCOM in your machine to ensure that a COM object located in a remote machine is accessible over a distributed environment. For more information about DCOM Configuration, see "Configuring DCOM for Remote Access," which is available at the following URL: http://j-integra.intrinsyc.com/support/com/doc/index.htm

In addition to the runtime file, WebLogic jCOM also provides a number of tools and components which are used for configuring the client and server environments.

Why Use WebLogic jCOM?

The major reasons for using WebLogic jCOM are:

To gain interoperability among distributed applications that span diverse hardware and software platforms
To aid those with a significant investment in Microsoft development tools and trained development staff who don't want to write Java client software in order for their client applications to access business logic on WebLogic Server.
To address the needs of e-business application builders seeking to leverage the skills available for both COM/DCOM, and Java environments to build fully integrated applications and reuse existing components. The specifics of each environment can be completely hidden for developers used to another environment.

WebLogic jCOM follows a software industry trend of making heterogeneous environments and applications interoperate transparently.

WebLogic jCOM Features

The key features of the WebLogic jCOM subsystem are:

WebLogic jCOM hides the existence of the data types accessed by the client, dynamically mapping between the most appropriate Java objects and COM components.
WebLogic jCOM supports both late and early binding of object types.
No native code is required on the machine hosting the COM component. Internally, WebLogic jCOM uses the Windows DCOM network protocol to provide communication between both local and remote COM components and a pure Java environment.
WebLogic jCOM supports an optional "native mode" which maximizes performance when running on a Windows platform. See DCOM Versus Native Mode.
WebLogic jCOM supports event handling. For example, Java events are accessible from Visual Basic using the standard COM event mechanism and Java objects can subscribe to COM component events.

WebLogic jCOM Examples

WebLogic Server includes an example demonstrating how to access an EJB deployed on WebLogic Server from an Excel Visual Basic Application (VBA) client using the zero client installation.

In a zero client installation, no WebLogic jCOM software is needed on the Windows client machine. However, in order to achieve this, you must retrieve an "object reference moniker" from a servlet and place it in the COM client code.

For detailed instructions on how to build and run the examples, invoke the Web page WL_HOME\samples\server\examples\src\examples\jcom\package_summary.html.

Planning Your WebLogic jCOM Application

Before designing and building your jCOM application, you must make a few key decisions. Specifically, you must decide:

Whether to employ a zero-client architecture for your application (COM-to-WLS only)
Whether to employ an early or late binding model (COM-to-WLS only)
Whether to run your jCOM application in native or DCOM mode (both COM-to-WLS and WLS-to-COM)

This section provides information to help you make these decisions. For additional information about JCOM, see the COM documentation available at the J-Integra website, at the following URL http://j-integra.intrinsyc.com/support/com/doc/index.htm

Zero-Client Deployment

A jCOM zero client deployment is easy to implement. No WebLogic-jCOM-specific software is required on the client machine.

The WebLogic Server location is coded into the COM client using an object reference moniker (objref) moniker string. The objref moniker is generated by the user and it encodes the IP address and port of the WebLogic Server. You can obtain the moniker string for the COM client code programmatically—or by copying and pasting—from a WebLogic Server servlet. Once the server connection is established, the COM client can link a COM object to an interface in the Java component.

Advantages and Disadvantages of Zero-Client Deployment

The following table summarizes the advantages and disadvantages of a zero-client implementation.

Advantages	Disadvantages
No WebLogic-specific software need be loaded into the client machine registry.	A few jCOM-specific tools must be copied from the `WL_HOME\bin` directory on the WebLogic Server machine
Offers the benefits of the late binding model (see Early Versus Late Binding) and therefore provides the same flexibility in terms of changes made to the Java component.	Requires that the WebLogic Server location and port number be coded into the COM client, which means that if the server location is changed, this reference has to be regenerated and changed in the source code.
	Deprives your application of the advantages of early binding. (See Early Versus Late Binding)

The zero-client model programming model is probably a good choice if your WebLogic jCOM deployment requires a large number of COM client machines.

The Zero-Client Example

For an example of zero client implementation see WL_HOME\samples\server\examples\src\examples\jcom\zeroclient in your WebLogic Server installation.

Early Versus Late Binding

Binding substitutes the symbolic addresses of routines or modules with physical addresses. Early binding and late binding both provide access to another application's objects.

Early bound access gives you information about the object you are accessing while you are compiling your program; all objects accessed are evaluated at compile time. This requires that the server application provide a type library and that the client application identify the library for loading onto the client system.

In late bound access, no information about the object being accessed is available at compile time; the objects being accessed are dynamically evaluated at runtime. This means that it is not until you run the program that you find out if the methods and properties you are accessing actually exist.

Advantages and Disadvantages of Each Binding Model

The following tables summarize the pros and cons of the early binding model:

Early Binding Pros	Early Binding Cons
More reliable than late bound implementation. Compile-time type checking makes debugging easy The application's end user can browse the type library. Improved runtime transaction performance relative to a late bound implementation.	Complex to implement, as it requires the generation of a type library and wrappers. The type library is required on the client side; the wrappers are required on the server side. If the client and server are running on separate machines the type library and wrappers have to be generated on the same machine and then copied to the systems where they are required. Lacks the flexibility of late bound access, in that any changes made to the Java component require regeneration of the wrappers and the library. Slower initialization at runtime than a late bound implementation.

Early Binding Pros

Early Binding Cons

More reliable than late bound implementation.

Compile-time type checking makes debugging easy

The application's end user can browse the type library.

Improved runtime transaction performance relative to a late bound implementation.

Complex to implement, as it requires the generation of a type library and wrappers.

The type library is required on the client side; the wrappers are required on the server side. If the client and server are running on separate machines the type library and wrappers have to be generated on the same machine and then copied to the systems where they are required.

Lacks the flexibility of late bound access, in that any changes made to the Java component require regeneration of the wrappers and the library.

Slower initialization at runtime than a late bound implementation.

The following tables summarize the pros and cons of the late binding model:

Late Binding Advantages	Late Binding Disadvantages
Easy to implement Flexible implementation, since objects referenced are only evaluated at runtime Faster runtime initialization than for an early bound implementation	Error prone, as no type checking can be done at compile time It is not until you run the program that you find out if the methods and properties you are accessing actually exist. Runtime transaction performance inferior to early bound implementation

Late Binding Advantages

Late Binding Disadvantages

Easy to implement

Flexible implementation, since objects referenced are only evaluated at runtime

Faster runtime initialization than for an early bound implementation

Error prone, as no type checking can be done at compile time

It is not until you run the program that you find out if the methods and properties you are accessing actually exist.

Runtime transaction performance inferior to early bound implementation

DCOM Versus Native Mode

The DCOM (Distributed Component Object Model) mode uses the Component Object Model (COM) to support communication among objects on different computers. In a WebLogic jCOM application running in DCOM mode, the COM client communicates with WebLogic Server in DCOM protocol.

In native mode, COM clients make native calls to WebLogic Servers (COM-to-WLS) and WebLogic Servers make native calls to COM applications.

For both COM-to-WLS and WLS-to-COM applications, because native mode uses native code dynamically loaded libraries (DLLs)—which are compiled and optimized specifically for the local operating system and CPU—using native mode results in better performance.

Moreover, COM-to-WLS applications operating in native mode use WebLogic's T3/Internet InterORB (IIOP) protocols for communication between the COM client and WebLogic Server. This brings the advantages of:

Superior performance as compared to using DCOM calls because it results in fewer network calls

For example, suppose your COM application creates a vector containing 100 data elements whose values are returned by a call to WebLogic Server. In DCOM mode, this would require 100 roundtrip network calls to the server. In native mode, this would require one roundtrip call.

Access to WebLogic Server's failover and load balancing features

However, for both types of applications, because native libraries have only been created for Windows, implementing native late bound access requires that the WebLogic Server be installed all COM client machines. However, this does not mean you need a distinct WebLogic Server license for each machine running a COM application.

Moreover, for WLS-to-COM applications, WebLogic Server must be running on a Windows machine to run in native mode.

Advantages and Disadvantages of Native Mode

The following table summarizes the pros and cons of a native mode implementation.

Advantages	Disadvantages
For COM-to-WLS applications, superior performance to that of DCOM mode, because calls aren't made over the network.	For both COM-to-WLS and WLS-to-COM applications, since native libraries have only been created for Windows, implementing native mode requires that the WebLogic Server be installed on all COM machines.
For COM-to-WLS applications, access to WebLogic Server's load balancing and failover features.	In the case of WLS-to-COM applications, WebLogic Server must be running on a Windows machine to run in native mode.
For WLS-to-COM applications, performance benefits because, if the COM object is installed on the same machine as WebLogic Server, WebLogic Server will not make network calls to it.

jCOM Features and Changes in this Release

WebLogic jCOM now supports passing—from COM to Java—two dimensional arrays of the following COM types:

Table 1-1 Two Dimensional Array Support in jCOM

COM Type	Visual Basic Type	Jave Type
I1, UI1	Byte	Byte
BOOL	Boolean	Boolean
I2, UI2	Integer	Short
CY, I8, UI8	Currency	Long
R8	Double	Double
DATE	Date	Date
I4, UI3, INT, UINT	Long	Int