Borland Enterprise Server Web Services Preview

The Borland Enterprise Server now provides two web service solutions. In addition to the existing SOAP server provided in all Partitions, this release previews a new, more functionally rich, web services server. This new web services server is provided out-of-the-box in a "webservices" Partition. For information on the existing SOAP server found in all Partitions, see the Borland Enterprise Server Developer's Guide.

This document covers the following:

The Borland Webservices Partition
Web Service Providers
How the Borland Webservices Partition Works
Web Service Deployment Descriptors
Packaging Web Service Application Archives
Viewing/Modifying WSDD Properties Using the Console
Borland Web Services Examples

A separate document, Web Services Overview, provides a general introduction to Web Services for those not familiar with Web Services technologies.

The Borland Webservices Partition

The Borland Enterprise Server stand-alone webservices Partition is pre-configured to support our new web services server and can be used in conjunction with all other Partitions. You simply need to start the webservices Partition to begin using the new web services server and deploy WARs (or EARs containing WARs) containing web services.

The Borland web services server is based on the Apache Axis technology and supports:

Dispatch of incoming SOAP web services requests to "web service providers"
EJB providers
RPC/Java providers
VisiBroker providers (Java and/or C++)

Managing Webservice Partitions

Like the Borland standard Partition, you can clone a Borland webservices Partition. You can have multiple Borland webservices Partitions within your Borland Enterprise Server. If, for any reason the Borland webservices Partition is deleted, use the cloning operation to restore the partition.

NOTE: Because certain configuration options are required for web services support, you should only use the Borland webservices Partition (or a clone of this Partition) to clone new webservices Partitions.

For more information on cloning a partition, refer to the Borland Enterprise Server User's Guide.

If you have multiple Partitions on the same machine with web containers enabled, you need to change the HTTP port number for each of the containers. This prevents the Partitions from clashing on HTTP ports.

The standard Partition is configured by default to listen on HTTP port 8080, and the webservices Partition on HTTP port 8040.

To change the HTTP Port number:

Start the Borland Enterprise Server Console.
In the navigation pane, go to the Borland webservices Partition and expand Partition Services.
Right-click Web Container and choose configure.

The Edit Tomcat's Server .xml window appears.

Scroll down to:


<Define a non-SSL HTTP/1.1 Connector on port 8040

  Connector className="org.apache.catalina.connector.http.HttpConnector"

    port="8040" minProcessors="5" maxProcessors="75"

    enableLookups="true" redirectPort="8443"

    acceptCount="10" debug="0" connectionTimeout="60000"/>

Edit the port number.
Click OK.

Web Service Providers

The Borland Web Services engine includes a number of providers. A provider is the link that connects a client web service request to the user's class on the server side.

All providers do the following:

Create an instance of an object on which they can invoke methods.
Invoke the methods on that object and pass all the parameters that the XML client sent.
Pass the return value to the Axis Runtime engine, which then converts it to XML and sends it back to the client.

Specifying Web Service Information in a deploy.wsdd file

When installing a new web service, you must name the web service and specify which provider the service is going to use. Each provider takes different parameters. The following describes the service providers and the required parameters for each.

Java:RPC provider

This provider assumes that the class serving the web service is in the application archive (WAR). When a web service request arrives, the RPC provider:

Loads the Java class associated with the service.
Creates a new instance of the object.
Invokes the specified method using reflection.

The parameters are:

className - The name of the class that is loaded when a request arrives on this service.
allowedMethods - The methods that are allowed to be invoked on this class. The class can have more methods than listed here; the methods listed here are available for remote invocation.

Example:


<service name="Animal" provider="java:RPC">

 <parameter name="className" value="com.borland.examples.web services.java.Animal"/>

 <parameter name="allowedMethods" value="talk sleep"/>

</service>

Java:EJB provider

This provider assumes that the class serving the web service is an EJB.

When a web service request arrives:

The EJB provider looks up the bean name in JNDI initial context.
Locates the home class and creates a bean.
Invokes the specified method using reflection on the EJB stub.

The actual EJB itself must be deployed to any non-webservices Partition before a client can access it.

The essential parameters are:

beanJndiName - The name of the bean in JNDI.
homeInterfaceName - The fully specified class of the home interface. This class must be present in the WAR.
allowedMethods - The methods that are allowed to be invoked on this EJB, separated by spaces. The EJB can have more methods than listed here; the methods listed here are available for remote invocation.

Example:


  <service name="Animal" provider="java:EJB">

    <parameter name="beanJndiName" value="Animal"/>

    <parameter name="homeInterfaceName" value="com.borland.examples.webservices.ejb.AnimalHome"/>

    <parameter name="allowedMethods" value="talk sleep"/>

  </service>

Java:VISIBROKER provider

This provider assumes that the class serving the web service is a Visibroker Server. When a web service request arrives, this provider:

Initializes the ORB.
Binds on the name specified to obtain a CORBA object.
Invokes the specified method on the CORBA stub.

The Visibroker Server must be running on your LAN. In order for the web service to locate it, the VisiBroker Server must use the same user Smart Agent port as Borland Enterprise Server.

The parameters are:

className - The name of the class that is loaded when a request arrives on this service. Typically this is the name of the CORBA class generated and based on the IDL. The VisiBroker client stubs including this class, must be present in the WAR.
allowedMethods - The methods that are allowed to be invoked on this class. The CORBA object can have more methods than listed here; the methods listed here are available for remote invocation.
poaName - The name of the POA that hosts the CORBA object.
objectName - The name of the object within the POA.
cacheObject - When set to true, then any repeated invocations on the same service will use the same object. A bind( ) is used to locate the object for the initial request. The default is false.

If the poaName is not specified, then it is assumed that the object itself is directly available and the appropriate bind is used to locate the object.

Example:


  <service name="Animal" provider="java:VISIBROKER">

    <parameter name="className" value="com.borland.examples.web services.visibroker.AnimalModule.Animal"/>

    <parameter name="allowedMethods" value="talk sleep"/>

    <parameter name="objectName" value="BigAnimal"/>

    <parameter name="cacheObject" value="false"/>

  </service>

How the Borland Webservices Partition Works

The web services server receives an XML SOAP message from a client.
It then:
1. Interprets the SOAP message.
2. Extracts the SOAP service name.
3. Determines the appropriate provider who can respond to this service.
The mapping between the SOAP service and the type of provider is obtained from the Web Service Deployment Descriptor (WSDD) as part of WAR deployment.
If the provider is RPC (provider="java:RPC"), then that provider does the method invocation through reflection on a Java class that is present in the WAR.
If the provider is EJB (provider="java:EJB"), then that provider:
1. looks up the bean home in JNDI.
2. calls the create method on home (bean).
3. invokes the method on the bean stub that is part of the WAR. The Bean stub in turn invokes the method on the remote EJB hosted typically in the Borland standard Partition or some other server.
If the provider is VISIBROKER (provider="java:VISIBROKER"), then that provider:
1. looks up the Object/POA name in the Smart Agent and invokes the method on the CORBA stub that is part of the WAR.
2. The CORBA stub in turn invokes the method on the remote VisiBroker Server running anywhere in the LAN. This VisiBroker Server can be either Java or C++.

Web Service Deployment Descriptors

Web services are deployed as part of a WAR. A single WAR can contain multiple web services. You can also deploy multiple WARs with each containing many web services.

The difference between a normal WAR and a WAR containing web services is the presence of an extra descriptor named server-config.wsdd in the WEB-INF directory. The server-config.wsdd file provides configuration information (the name of the web service, the provider, any corresponding Java classes and allowed methods).

There is one WSDD file per WAR and it contains information about all available web services within that WAR.

The typical component structure of a WAR containing web services has the following elements:

WEB-INF/web.xml
WEB-INF/server-config.wsdd
WEB-INF/classes/<classes corresponding to your web services are located here>
WEB-INF/lib/<classes corresponding to your web services are located here in the packed JAR form>

The WEB-INF/lib also contains some standard JARs that are necessary for the Axis Runtime engine.

To publish your Java classes as a web service, use the WSDD format to define the items that you want to deploy to the webservices Partition. For example, an entry corresponding to a service named "BankService" can be:


  <service name="BankService" provider="java:RPC">

    <parameter name="allowedMethods" value="create_account query_account"/>

    <parameter name="className" value="com.fidelity.Bank"/>

  </service>

In this case, the com.fidelity.Bank Java class links to web service BankService. The class com.fidelity.Bank can have a number of public methods, but only the methods create_account and query_account are allowed.

NOTE: For more information on the web services deployment descriptor (WSDD), refer to the Axis User Guide located in <install_dir>/doc/axis/user-guide.html, where install_dir is the Borland Enterprise Server installation directory.

Creating a server-config.wsdd file

To create the server-config.wsdd:

Use JBuilder to generate the deployment descriptor as part of your WAR.

or

Use a text editor to write a deploy.wsdd file. Refer to the deploy.wsdd file in <install_dir>/examples/webservices/java/server.
Run the Axis Admin tool with the deploy.wsdd file by typing:

prompt>java org.apache.axis.utils.Admin server deploy.wsdd

The server-config.wsdd file is packaged as part of the WAR.

Editing a server-config.wsdd file

You can modify the server-config.wsdd file in your WAR using the Borland Deployment Descriptor Editor.

Packaging Web Service Application Archives

To Create a WAR that can be deployed to the web services archive:

Make sure your web service classes are in WEB-INF/classes or WEB-INF/lib.
Copy the Axis toolkit libraries to WEB-INF/lib. The Axis libraries can be found in: <install_dir>/lib/axis
Copy the web.xml necessary for the Axis tool kit to WEB-INF directory. The web.xml can be found in: <install_dir>/etc/axis
Create a deploy.wsdd that has deployment information about your web services.
Run the Axis Admin tool on this deploy.wsdd to generate the server-config.wsdd as follows:
```
   <java org.apache.axis.utils.Admin server deploy.wsdd>
```
Copy this server-config.wsdd to WEB-INF
JAR your web application into a WAR file.

Viewing/Modifying WSDD Properties Using the Console

Using the Borland Enterprise Server Console, you can view the properties of any web service deployment descriptor (WSDD) that is packaged in a WAR file.

To view the server-config.wsdd file from the Borland Enterprise Server Console:

In the Navigation Pane, expose the webservices Partition by expanding the Enterprise Servers tree.
Click the name of the WAR file you want to view.
At the bottom of the content Pane, click the Properties tab.

The property elements of the server-config.wsdd file are mapped into a read-only layout.

From the Elements drop-down list, choose the type of element you want to view.

When you select an element, any associated parameters are automatically displayed in the adjacent table. You can drill-down to view the Parameters of Element details.

For detailed information on these property elements, refer to the Axis User's Guide in:<install_dir>\doc\axis\user-guide.html, where install_dir is the Borland Enterprise Server installation directory.

To view or modify the server-config.wsdd file using DDEditor:

In the Console, choose Tools|Deployment Descriptor Editor.
The Borland Deployment Descriptor Editor appears.
Choose File|Open File.
The Open J2EE archive or descriptor window appears.
Navigate to the directory where the WAR file resides.
Select the WAR file and click OK.
At the top of the navigation tree, click the name of the archive.

On the bottom right of the contents pane, click the XML tab.
Click the Web Services tab.

The raw server-config.wsdd file displays.

Make your edits.
Click Apply Changes.
Choose File|Save.

Borland Web Services Examples

To help you get started with developing and deploying web services, we provide samples and examples for the Borland webservices engine. These examples are included in your Borland Enterprise Server 5.0.1 installation at:

<install_dir>/examples/webservices/

An example application, "Animal," illustrates the use of the three web service providers: the Java Provider, the EJB Provider, and the VisiBroker Provider. Each is located in the webservices examples directory in the Java, EJB, or VisiBroker folder, respectively.

Your Borland Enterprise Server installation also includes several Apache Axis samples in:

<install_dir>/examples/webservices/axis/samples/

Using the Web Service Provider Examples

Borland Enterprise Server provides a web service, Animal, in three different forms that correspond to the three web service providers. The Animal application is a text-based "pet" that can speak (although its vocabulary is quite limited) and sleep. You are free to add your own methods to make your pet animal do other things, but sleeping and speaking should be adequate for most users.

Examples for the Borland Enterprise Server must be built before they are deployed and deployed before they are run. Building the examples involves generating the necessary WSDL files and packaging the application's code and descriptors into a deployable unit, in this case a WAR. This WAR can then be deployed to the Borland webservices Partition. The application is run by invoking its client from a command-line. Building and running the examples is automated through the use of the Apache Ant utility, while deployment is performed using tools provided with the Borland Enterprise Server.

Steps to build, deploy, and run the examples

Build. You can build all of the examples simultaneously or build each one individually. To build them all simultaneously, navigate to the /examples/webservices/ directory and execute the Ant command. For example:
C:\BorlandEnterpriseServer\examples\webservices>Ant

builds all the examples. To build an individual example, navigate to its specific directory and execute the Ant command. For example:

C:\BorlandEnterpriseServer\examples\webservices\java>Ant

builds only the Java Provider example.
Deploy. You deploy the examples to a running instance of the Borland Enterprise Server. The example WAR files must be deployed to a webservices partition. For the EJB provider example, there is also a JAR file which must be deployed to a separate Partition with an EJB container. You deploy the WAR and JAR files using the iastool command-line utility.
If security is disabled on your server instance, type the following from the command prompt:

prompt>iastool -deploy -jars ejb/build/animal_ejb.war java/build/animal_java.war visibroker/build/animal_vb.war -server <server_name> -partition webservices -mgmtport <port_number>

prompt>iastool -deploy -jars ejb/build/animal_ejb.jar -server <your_server's_name> -partition standard -mgmt_port <port_number>

If you have security enabled on your server, you must provide a username, password, and server realm as a part of the iastool command syntax:

prompt>iastool -deploy -jars ejb/build/animal_ejb.war java/build/animal_java.war visibroker/build/animal_vb.war-server <server_name> -partition webservices -mgmtport <port_number> -user <user_name> -pwd <password> -realm <realm_name>

prompt>iastool -deploy -jars ejb/build/animal_ejb.jar -server <server_name> -partition standard -mgmt_port <port_number> -user <user_name> -pwd <password> -realm <realm_name>

You must include your server's name in both commands. The default management port number is 42424, unless you have changed it.
Run. To run an example, navigate to its directory and use the ant run-client command. For example, to run the Java Provider client:
C:\BorlandEnterpriseServer\examples\webservices\java>Ant run-client

Or, to run the EJB Provider client:

C:\BorlandEnterpriseServer\examples\webservices\EJB>Ant run-client

To run the VisiBroker Provider client, two commands are needed, one to start the VisiBroker server, and one to run the client:

C:\BorlandEnterpriseServer\examples\webservices\visibroker>Ant run-server

C:\BorlandEnterpriseServer\examples\webservices\visibroker>Ant run-client

Apache Axis Web Service Samples

The Apache Axis web service samples are already deployed in the axis-samples.war file present in the Borland webservices Partition. Since these are already pre-deployed, you do not need to use the Apache Axis deploy commands suggested in the Apache Axis User's Guide.

The Apache Axis User's Guide is also provided with your Borland Enterprise Server installation and is located in:

<install_dir>\doc\axis\user-guide.html

These samples illustrate the capabilities of the Axis tool. They are unmodified from the original Apache Axis implementation and are not guaranteed to run.