COM Pluggable Provider

Overview

Apache COM Pluggable Provider is a demonstration of accessing Window's component object model (COM) through SOAP services on Windows 2000 or Windows NT® servers. The COM Pluggable provider is an Apache SOAP pluggable provider that takes in coming requests to the SOAP server and delegates them to a COM object.

Installation

Enabling the COM Pluggable provider

Install your webserver and include the SOAP jar file in the classpath
If the Web application server is started from the command line update the PATH environment variable to include the full path of the Apache soap lib directory where Comprovider.dll is located. Or, you can update PATH environment variable for all programs on the system by going into the system's Control Panel->System->Advanced->System variables and update the path. This provides the Web Application Server and the COM Pluggable provider access to the COMProvider.dll file located in the lib directory.

Configuring the COM Pluggable Provider

The COM pluggable provider is configured by Apache SOAP deployment descriptors. The following is an example of the deployment descriptor provided with the adder demo in the Apache install directory java\samples\com\server\adder.xml:

1.   
2.   <isd:service xmlns:isd=http://xml.apache.org/xml-soap/deployment
3.      isd:serviceid="urn:adder-COM">
4.   <isd:provider type="org.apache.soap.providers.com.RPCProvider"
5.        scope="Application"
6.        methods="add">
7.    <isd:java class="required not needed for COMProvider"/>
8.    <isd:option key="progid" value="Apacheadder.adder" />
9.    <isd:option key="threadmodel" value="MULTITHREADED" />
10.    </isd:provider>
11.    <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
12.    </isd:service>

The following is a description of the lines in the above deployment descriptor that are relevant to deploying COM services:

In line 3 the value of the isd:serviceid attribute is the urn that the client requesting the SOAP service will use to identify the object associated with this deployment. It can be anything as long as it is unique in this SOAP server (i.e. it is not used in any other deployment descriptor).
Line 4 should always be the same for all services that are to use the COM pluggable provider support. This Java class file is located it soap.jar file.
In line 6 the methods attributes values are the names of the methods the client can invoke on object associated with this deployment . This is a list of valid methods each seperated by a space. To access COM object properties this should be the property name with either "set_" or "get_" prefixed on the property name. With regard to this prefix, case is significant to identify it as accessing a property as opposed to a method. For most COM object, methods or properties names are not case significant.
In line 8 the value of the value attribute is the ProgId or CLSID of the COM object that is to service SOAP deployment. If this is a CLSID it should be enclosed in braces("{<CLSID>})".
In line 9 the COM threading model is specified which can be MULTITHREADED, APARTMENTTHREADED, SINGLEAPARTMENTTHREADED. If not specified is set to MULTITHREADED.

Once the deployment descriptor is written it can be used to configure the Apache SOAP server as follows:

java org.apache.soap.server.ServiceManagerClient http://<hostname>:<port>/soap/servlet/rpcrouter deploy <Full path of the deployment descriptor file>

Demo

Overview

Two COM implemented SOAP services are provided. They are located in java\samples\com. In this directory there are two subdirectories: client and server. With the following files:

Files

client\Addit.class	The Java class file requesting the adder SOAP service.
client\Addit.java	The Java source code for the above file.
client\Sum.class	The Java class file requesting the totals SOAP service.
client\Sum.java	The Java source code for the above file.
server\adder.cls	The Visual Basic® class source code for the adder service. It can be viewed with a text editor, but should be updated only by Microsoft Visual Basic®.
server\adder.xml	Apache SOAP Deployment descriptor for the adder service.
server\rundemo.bat	A batch file making it easier to set up the server side of the demo.
server\APACHEADDER.dll	The COM object implementing the adder service.
server\APACHEADDER.vbp	The Visual Basic® project file for the adder service. Double clicking on this will bring up Microsoft Visual Basic® if installed to work on the adder service.
server\APACHEADDER.vbw	The Visual Basic® workspace file for the adder service.
server\APACHESUM.dll	The COM object implementing the totals service.
server\APACHESUM.vbp	The Visual Basic® project file for the totals service. Double clicking on this will bring up Microsoft Visual Basic® if installed to work on the totals service.
server\APACHESUM.vbw	The Visual Basic® workspace file for the totals service.
server\totals.cls	The Visual Basic® class source code for the totals service. It can be viewed with a text editor, but should be updated only by Microsoft Visual Basic®.
server\sum.xml	Apache SOAP Deployment descriptor for the totals service.

NOTE: For COM objects developed by Visual Basic® the ProgId is the project name and the class name separated by a period.

Running

Start the Web application server you previously configured. Remember the path must include Comprovider.dll
Create a new command line window.
Go to the server directory and run: rundemo deploy
This will issue for you the deploy commands for the deployment descriptors of the demo. Note it does one other thing: COM needs to know where the implementation of your objects are and this is the reason behind the lines REGSVR32 /s <com object's dll> name. This only needs to happen once unless you move or rename the dll. You should be now able to issue SOAP requests to the two SOAP services just deployed.
Change to the comprovider client directory.
Run for example: java samples.com.client.Addit 3 4
It takes any two integers as arguments and sends it over to the server to be added and returns the result.
For the second SOAP service run: java samples.com.client.Sum 4
This will send the integer over to be added to a total that's kept in a file. You can continue to issue this request to add to the total.
To set it to a specific value, run: java samples.com.client.Sum -set 9
To set it to 9 for example.
To stop the services go back to the server directory and run: rundemo undeploy.

Limitations

The following limitations are known at this time:

Only primitive types are supported as arguments and return types with the exception of Currency and Date primitives.
There is no framework provided to support statefull COM objects.
Only returned objects and IN parameters are supported.

Visual Basic® is a Trademark of Microsoft Corporation.
Windows NT® is a Registered Trademark of Microsoft Corporation.
Microsoft® and Windows® are registered trademarks of Microsoft Corporation.