7
Web Services Assembly Tool

The Oracle9iAS Web Services assembly tool, WebServicesAssembler, assists in assembling Oracle9iAS Web Services. The Web Services assembly tool takes a configuration file which describes the location of the Java classes or J2EE/EJB Jar files and produces a J2EE EAR file that can be deployed under Oracle9iAS Web Services. The assembly tool assists with assembling the following types of Web Services:

Stateless Java (including PL/SQL Stored Procedures and Functions)
Stateful Java
Stateless Session EJB

This chapter contains the following topics:

Running the Web Services Assembly Tool

Run the Web Services assembly tool as follows:

java -jar WebServicesAssembler.jar -config [file]

Where file is a Web Services assembly tool configuration file.

See Also:

Web Services Assembly Tool Configuration File Specification

The input file for WebServicesAssembler is an XML file conforming to the Web Services Assembly Tool configuration file DTD. Example 7-1 shows the Web Services Assembly Tool Configuration file DTD.

Example 7-1 Assembly Tool Input File DTD

<?xml version="1.0" encoding="UTF-8"?> 
<!-- Specify the properties of the web services to be assembled. --> 
<!ELEMENT web-service (display-name?, description?, destination-path, 
temporary-directory, context, stateful-java-service*, stateless-java-service*, 
stateless-session-ejb-service*)> 
<!ELEMENT display-name (#PCDATA)> 
<!ELEMENT description (#PCDATA)> 
<!-- Specify the full path of the resulting EAR file. For example, 
"/home/demo/webservices.ear" --> 
<!ELEMENT destination-path (#PCDATA)> 
<!-- Specify a direcotry where the assembly tool can create temporary 
directories and files. --> 
<!ELEMENT temporary-directory (#PCDATA)> 
<!-- Specify the context root of the web services. For example, "/webservies". 
--> 
<!ELEMENT context (#PCDATA)> 
<!-- Specify the properties of a stateful Java service --> 
<!ELEMENT stateful-java-service (interface-name?, class-name, uri, 
java-resource*, ejb-resource*)> 
<!-- Specify the properties of a stateless Java service --> 
<!ELEMENT stateless-java-service (interface-name?, class-name, uri, 
database-jndi-name?, java-resource*, ejb-resource*)> 
<!-- Specify the properties of a stateless session ejb service --> 
<!ELEMENT stateless-session-ejb-service (path, uri, ejb-name, ejb-resoruce*)> 
<!-- Specify the java interface which defines the public methods to be exposed 
in the web service. 
     For example, "com.foo.myproject.helloWorld". --> 
<!ELEMENT interface-name (#PCDATA)> 
<!-- Specify the java class to be exposed as a web service. If interface-name is 
not specified, 
     all the public methods in this class will be exposed. For example, 
     "com.foo.myproject.helloWorldImpl". --> 
<!ELEMENT class-name (#PCDATA)> 
<!-- Specify the uri of this service. This uri is used in the URL to access the 
WSDL and client 
     jar, and invoke the web service. For example, "/myService". --> 
<!ELEMENT uri (#PCDATA)> 
<!-- 
Specify the java resources used in this service.
The value can be a directory or a file that implements the web services. If it 
is a directory, all the files and subdirectories under the directory are copied 
and packaged in the Enterprise ARchive. If the java resource should belong to a 
java package, you should either package it as a jar file and specify it as a 
java resource, or create the necessary directory and specify the directory which  
contains this directory structure as java resource. For example, you want to 
include  "com.mycompany.mypackage.foo" class as a java resource of the web 
services, you can either package this class file in foo.jar and specify 
<java-resource>c:/mydir/foo.jar</java-resource>, or place the class under 
d:/mydir/com/mycompany/mypackage/foo.class and specify the java resource as 
<java-resource>c:/mydir/</java-resource>. 
--> 
<!ELEMENT java-resource (#PCDATA)> 
<!-- Specify the ejb resources used in this service. ejb-resource should be a 
jar file 
     that implements a enterprise java bean. --> 
<!ELEMENT ejb-resource (#PCDATA)> 
<!-- Specify the database JNDI name for your stateless PL/SQL web service. --> 
<!ELEMENT database-jndi-name (#PCDATA)> 
<!-- Specifies the path of the EJB jar file to exposed as web services. --> 
<!ELEMENT path (#PCDATA)> 
<!-- Specify the ejb-name of the session bean to be exposed as web services. 
ejb-name 
     should match the <ejb-name> value in the META-INF/ejb-jar.xml of the bean. 
--> 
<!ELEMENT ejb-name (#PCDATA)>

Web Services Assembly Tool Configuration File Sample

The sample configuration file shown in Example 7-2 defines two services to be wrapped in an Enterprise ARchive file (EAR). Table 7-1 describes the sample configuration file tags.

Example 7-2 Sample Web Services Assembly Tool Configuration File

<?xml version="1.0"?> 
<!DOCTYPE application-server PUBLIC "Orion Application Server Config" 
"http://xmlns.oracle.com/ias/dtds/webservices-assembler.dtd"> 
<web-service> 
    <display-name>Web Services Demo</display-name> 
    <description>This is a demo.</description> 
    <destination-path>/tmp/work/ws_example.ear</destination-path> 
    <temporary-directory>/tmp</temporary-directory> 
    <context>/webservices</context> 
    <stateless-java-service> 
        <interface-name>StatelessExample</interface-name> 
        <class-name>StatelessExampleImpl</class-name> 
        <uri>/statelessTest</uri> 
        <java-resource>/tmp/work/java/</java-resource> 
        <java-resource>/home/oracle/mylib.jar</java-resource> 
    </stateless-java-service>

    <stateless-session-ejb-service> 
        <path>/tmp/work/ejb/MyCart.jar</path> 
        <uri>/statelessEjbTest</uri> 
        <ejb-name>Cart</ejb-name> 
        <ejb-resource-path>/tmp/work/ejb/ </ejb-resource-path> 
    </stateless-session-ejb-service> 
</web-service>

Table 7-1 Sample Web Services Configuration File Tag Components and Descriptions

Component	SubComponent	Description
web-services		Specifies the properties used to assemble the Web Service.
	display-name	Specifies the display name of the Web Services.
	description	A simple description of the Web Services.
	destination-path	Specifies that the resulting EAR will be stored as /tmp/work/ws_example.ear
	temporary-directory	Specifies a temporary directory that ws_assembler can store temporary files.
	context	Specifies the context root of the Web Service is called "/webservices".
stateful-java-service
stateless-java-service		Specifies the properties of the stateless Java Web Service.
	interface-name	(optional) Specifies the interface class that defines methods to be exposed on the Web Service.
	class-name	Specifies the Java class to be exposed on the Web Service.
	uri	Specifies the URI of the service is /statelessTest. This URI is used in the URL to access the WSDL and client jar, and invoke the Web Service.
	web-resource-path	Specifies "/tmp/work/java/" as the directory that contains all the Java classes and jar libraries that the Java class depends on.
stateless-session-ejb-service		Specifies the properties of the stateless session ejb service.
	path	Specifies the location of the ejb jar file to be exposed as a Web Service.
	uri	Specifies the URI of the service is /statelessEjbTest. This URI is used in the URL to access the WSDL and client jar, and invoke the Web Service.
	ejb-name	Specifies the name of the stateless session EJB.
	ejb-resource-path	(optional) Specifies "/tmp/work/ejb/" as the directory that contains all the EJB jars that the stateless session ejb depends on

Web Services Assembly Tool Configuration File Sample Output

After running the Web Services Assembly tool with the sample input file shown in Example 7-2, the generated output is an EAR file (/tmp/work/ws_example.ear) The generated EAR file, ws_example.ear, has the structure shown in Example 7-3.

Example 7-3 Structure of Web Services Assembly Tool Sample Ear File

+------ MyCart.jar 
+------ META-INF/ 
|       `------ application.xml 
`------ ws_example.war 
        +------ index.html 
        `------ WEB-INF/ 
                +------- web.xml 
                +------- lib/ 
                |        +------ mylib.jar 
                `------- classes/ 
                         +------ StatelessExample.class 
                         `------ StatelessExampleImpl.class

Example 7-4 shows the sample application.xml file.

Example 7-4 Web Services Assembly Tool Sample application.xml File

<?xml version="1.0"?> 
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 
1.2//EN" "http://java.sun.com/j2ee/dtds/application_1_2.dtd"> 
<application> 
    <display-name>Web Services - ws_example</display-name> 
    <module> 
        <web> 
            <web-uri>ws_example</web-uri> 
            <context-root>/webservices</context-root> 
        </web> 
    </module> 
    <module> 
        <ejb>MyCart.jar</ejb> 
    </module> 
</application> 



The web.xml looks as follows -- 
<?xml version="1.0"?> 
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 
2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> 
<servlet> 
    <servlet-name>stateless java web service - statelessTest</servlet-name> 
    <servlet-class>oracle.j2ee.ws.StatelessJavaRpcWebService</servlet-class> 
    <init-param> 
        <param-name>class-name</param-name> 
        <param-value>StatelessExampleImpl</param-value> 
    </init-param> 
    <init-param> 
        <param-name>interface-name</param-name> 
        <param-value>StatelessExample</param-value> 
    </init-param> 
</servlet> 
<servlet> 
    <servlet-name>stateless session bean web service - Cart</servlet-name> 
    <servlet-class>oracle.j2ee.ws.SessionBeanWebService</servlet-class> 
    <init-param> 
        <param-name>jndi-name</param-name> 
        <param-value>ejb/Cart</param-value> 
    </init-param> 
</servlet> 
<servlet-mapping> 
    <servlet-name>stateless java web service - statelessTest</servlet-name> 
    <url-pattern>/statelessTest</url-pattern> 
</servlet-mapping> 
<servlet-mapping> 
    <servlet-name>stateless session bean web service - Cart</servlet-name> 
    <url-pattern>/statelessEjbTest</url-pattern> 
</servlet-mapping> 
<welcome-file-list> 
    <welcome-file>index.html</welcome-file> 
</welcome-file-list> 
<ejb-ref> 
    <ejb-ref-name>ejb/Cart</ejb-ref-name> 
    <ejb-ref-type>Session</ejb-ref-type> 
    <home>CartHome</home> 
    <remote>Cart</remote> 
    <ejb-link>Cart</ejb-link> 
</ejb-ref>
</web-app>

Web Services Assembly Tool Limitations

The WebServicesAssembler tool has the following limitations:

Upload/download: this tool is designed for use as a server side tool. The Web Services Assembly tool does not upload Java classes from a client system to a server or download a generated EAR file back to a client system.
Does not support advanced configuration tasks: for example, the Web Services Assembly tool is not able to control the security options for a Web Services Servlet, cannot secure an EJB, or welcome files or perform other administrative tasks.
Does not modify an existing EAR file: the Web Services Assembly tool cannot take a EAR file as input, parse the contents and then return a new EAR file or modify the existing EAR file.

7 Web Services Assembly Tool