Oracle9i Application Server Web Services Developer's Guide Release 2 (9.0.3) Part Number B10004-01 |
|
This chapter describes the procedures you use to write and deploy Oracle9iAS Web Services that handle document style messages and are implemented as Java classes.
This chapter covers the following topics:
This chapter describes Document Style Web Services that are implemented with Java classes and describes the difference between writing stateful and stateless Document Style Java Web Services. The sample code for Document Style Web Services is supplied with Oracle9iAS Web Services in the stateless
and stateful
directories in the directory $ORACLE_HOME/webservices/demo/basic/java_doc_services
on UNIX or in %ORACLE_HOME%\webservices\demo\basic\java_doc_services
on Windows.
Oracle9iAS supplies Servlets to access the Java classes which you write to implement a Web Service. The Servlets handle messages generated by Web Services clients and dispatch them to run the Java methods that implement Document Style Web Services. After a Web Service is deployed, when a client makes a service request (uses a service) the Oracle9iAS Web Services runtime, using an automatically generated Web Services Servlet invokes the methods that you implement to support the Document Style Web Service.
Writing Document Style Java Web Services involves building a Java class that includes one or more methods using supported method signatures; the java class includes methods that either handle an incoming message or return an outgoing message.
This section covers the following topics:
Table 6-1 shows the supported method signatures for Document Style Web Services. The Oracle9iAS Web Services runtime verifier rejects Document Style Web Services that do not conform to the method signatures listed in Table 6-1.
The Element
input parameter and Element
return value shown in the method signatures in Table 6-1 must conform to the Document Object Model (DOM) as specified by the W3C (org.w3c.dom.Element)
.
A null
could be passed as an input Element
or as the Element
that the Document Style Web Service returns.
Oracle9iAS Web Services does not support Element[]
(arrays of org.w3c.dom.Element
).
See Also:
|
Oracle9iAS Web Services supports stateful and stateless implementations for Document Style Java classes running as Web Services. For a stateful Java implementation, Oracle9iAS Web Services allows a single Java instance to serve the Web Service requests from an individual client.
For a stateless Java implementation, Oracle9iAS Web Services creates multiple instances of the Java class in a pool, any one of which may be used to service a request. After servicing the request, the object is returned to the pool for use by a subsequent request.
Note: It is the job of the Web Services developer to make the design decision to implement a stateful or stateless Web Service. When packaging Web Services, stateless and stateful Web Services are handled slightly differently. This chapter describes these differences in the section, "Preparing Document Style Web Services". |
Developing a Document Style Java Web Service consists of the following steps:
Create a Document Style Web Service by writing or supplying a Java class with methods that are deployed as a Document Style Web Service. The stateful
and stateless
sample directories contain sample stateless and stateful Document Style Web Services. In the src
directories, the file StatefulDocImpl.java
provides the implementation of the sample stateful Java service and StatelessDocImpl.java
provides the implementation of the stateless Document Style Web Service. These examples use interface classes; the use of interface classes is optional when implementing Document Style Web Services.
A Java class that implements a Document Style Web Service has the following limitations:
There are very few restrictions on what actions a Document Style Java class based web service can perform. At a minimum, the service performs some action to handle an incoming message (Element
) or to generate an outgoing message (Element
).
The StatelessDoc
Web Service sample is implemented with StatelessDocImpl
, a public class and the interface StatelessDoc
. The StatelessDocImpl
class defines two public methods: displayElement()
, that displays the incoming message on the server where the web service runs, and processElement()
, that takes an incoming message and returns a transformed message to the client. The private method applyXSLtoXML()
is a helper method that transforms the incoming message, as specified in the converter.xsl
file.
Example 6-1 shows the method signatures for the StatelessDocImpl
class (see the src
directory to view the complete source code for StatelessDocImpl
).
import org.w3c.dom.*; import oracle.xml.parser.v2.*; import java.io.*; public class StatelessDocImpl implements StatelessDoc { public StatelessDocImpl() { } // Display the Element that was sent public void displayElement(Element e) { } //method to process the input xml doc public Element processElement(Element e) { } /** * This Method Transforms an XML Document into another using the provided * Style Sheet: converter.xsl. Note : This Method makes use of XSL * Transformation capabilities of Oracle XML Parser Version 2.0 **/ private Element applyXSLtoXML(Element e) throws Exception {}
The StatfulDoc
Web Service sample is implemented with StatefulDocImpl
, a public class and the interface StatefulDoc
. The StatefulDocImpl
class defines two public methods: startShopping()
that initializes the state of the customer information and makePurchase()
, that modifies the state of the customer information and returns the updated information to the client. The private method processElement()
is a helper method that processes the customer's XML element representing a purchase and returns the updated XML element.
Example 6-2 shows the method signatures for the StatefulDoc
class (see the src
directory to view the complete source code for StatefulDocImpl
).
import org.w3c.dom.*; import oracle.xml.parser.v2.*; public class StatefulDocImpl implements StatefulDoc private Element e ; public void startShopping(Element e) { } public Element makePurchase() { } private void processElement(Element e) { }
Oracle9iAS Web Services allows you to limit the methods you expose as Document Style Web Services by supplying a public interface. To limit the methods exposed in a Web Service, include a public interface that lists the method signatures for the methods that you want to expose. Example 6-3 shows an interface for the methods in the class StatelessDocImpl
. Example 6-4 shows an interface for the methods in the class StatelefulDocImpl
.
When an interface is included with a Document Style Web Service, then only the public methods specified in the interface need to conform to the method signature restrictions shown in Table 6-1. If you do not include an interface, then all the public methods in the class must conform to the method signature restrictions. Using an interface, for example StatelessDoc
shown in Example 6-3, only the methods with the specified method signatures are exposed when the Java class is prepared and deployed as a Document Style Web Service.
Use a Document Style Web Service interface for the following purposes:
import org.w3c.dom.*; public interface StatelessDoc { //method to display the element public void displayElement(Element e) ; //method to process the input xml doc public Element processElement(Element e) ; }
import org.w3c.dom.Element; // Interface that implements getElement and setElement public interface StatefulDoc { // Set the Element public void startShopping(Element e); // Retrieve the element that was set public Element makePurchase(); }
It is entirely up to the Web Service developer to determine the processing that occurs for messages associated with a Document Style Web Service.
The message associated with a Document Style Web Service is specified in the Element
parameter or the Element
return value associated with the Document Style Web Service. It is the Document Style Web Service developer's job to process or generate messages. The only limitation on Document Style Web Service messages is that the Element
must conform to must conform to the Document Object Model (DOM) as specified by the W3C (org.w3c.dom.Element)
.
A Document Style Web Service implementation or the client that uses a service may need to supports null
values, since a null
could be passed as an input Element
or as the Element
that is returned.
For example, the following is valid for a Document Style Web Service implementation:
Element get_op () {
return null;
}
This section describes how to use the Oracle9iAS Web Services tool WebServicesAssembler
to prepare a J2EE .ear file for a stateless and stateful Document Style Web Service implemented as Java classes.
To deploy a Java class that implements a Document Style Web Service, you need to assemble a J2EE .ear file that includes the deployment descriptors for the Oracle9iAS Web Services Servlet and the Java classes that supply the Java implementation. A Web Service implemented with Java classes includes a .war file that provides configuration information for the Web Services Servlet running under Oracle9iAS Containers for J2EE (OC4J). This section describes the procedures you use to create a configuration file to use with the WebServicesAssembler
.
This section contains the following topics:
The Oracle9iAS Web Services assembly tool, WebServicesAssembler
, assists in assembling Oracle9iAS Web Services. This section describes how to create a configuration file to use to assemble a Document Style Web Service. The Web Services assembly tool uses an XML configuration file that describes the Document Style Web Service. The WebServicesAssembler
uses the configuration file to produce a J2EE .ear file that can be deployed under Oracle9iAS Web Services.
Create WebServicesAssembler
configuration file by adding the following:
Table 6-2 describes the top level WebServicesAssembler
configuration file tags. Add these tags to provide top level information describing the Document Style Web Service.
Example 6-5 shows a complete stateless sample configuration file. Example 6-6 shows a complete stateful sample configuration file. The stateless
and stateful
directories in the java_doc_services
demo
directory contain the sample config.xml
files.
WebServicesAssembler
Configuration Tags
Tag | Description |
---|---|
|
Specifies the context root of the Web Service. This tag is required. |
|
Specifies the datasource associated with the Web Service. |
|
Provides a simple description of the Web Service. This tag is optional. |
|
Specifies the name of the generated J2EE .ear file output. The dest_path specifies the complete path for the output file. This tag is required. |
|
Specifies the Web Service display name. This tag is optional. |
|
Includes a specified file in the output .ear file. The path specifies the path to the file to include. |
|
Use this tag to add a Document Style Web Services that defines a stateless service. See Table 6-3 for a description of valid sub-tags. |
|
Use this tag to add a Document Style Web Services that defines a stateful service. See Table 6-3 for a description of valid sub-tags. |
|
Specifies a directory where the assembler can store temporary files. This tag is optional. |
The Document Style Web Service developer determines if the service is stateful or stateless. The configuration file includes different tags depending on the type of the service. This section covers the tags for both cases, including:
WebServicesAssembler
Configuration Tags - Document Style
Table 6-3 describes the <stateful-java-service>
WebServicesAssembler
configuration file tags. Use these tags when creating a configuration file for a stateful Document Style Web Service.
Example 6-5 shows a complete config.xml
file, including the stateful Document Style Web Service tags.
Table 6-3 describes the <stateless-java-service>
WebServicesAssembler
configuration file tags to use when creating a stateful Document Style Web Service. The <stateless-java-service>
tag is included within a <web-service>
tag in the configuration file. Add this tag to provide information required for generating a stateless Document Style Web Service J2EE .ear file.
Example 6-6 shows a complete config.xml
file, including the stateless Document Style Web Service tags.
The WebServicesAssembler
configuration file supports the <wsdl-gen>
and <proxy-gen>
tags to allow a Web Service developer to generate Web Service description WSDL files and client-side proxy files. You can add these tags to control whether the WSDL file and the client-side proxy are generated. You can also specify that the WSDL file be assembled with the Document Style Web Service .ear. A client-side developer can then obtain the WSDL file from the deployed Web Service and use it to build an application.
<web-service> <display-name>Stateful Java Document Web Service</display-name> <description>Stateful Java Document Web Service Example</description> <!-- Specifies the resulting web service archive will be stored in ./docws.ear --> <destination-path>./docws.ear</destination-path> <!-- Specifies the temporary directory that web service assembly tool can create temporary files. --> <temporary-directory>./temp</temporary-directory> <!-- Specifies the web service will be accessed in the servlet context named "/docws". --> <context>/statefuldocws</context> <!-- Specifies the web service will be stateful --> <stateful-java-service> <interface-name>StatefulDoc</interface-name> <class-name>StatefulDocImpl</class-name> <!-- Specifies the web service will be accessed in the uri named "/docService" within the servlet context. --> <uri>/docservice</uri> <!-- Specifies the location of Java class files ./classes --> <java-resource>./classes</java-resource> <!-- Specifies that it uses document style SOAP messaging --> <message-style>doc</message-style> </stateful-java-service> <!-- generate the wsdl --> <wsdl-gen> <wsdl-dir>wsdl</wsdl-dir> <!-- over-write a pregenerated wsdl , turn it 'false' to use the pregenerated wsdl--> <option name="force">true</option> <option name="httpServerURL">http://localhost:8888</option> </wsdl-gen> <!-- generate the proxy --> <proxy-gen> <proxy-dir>proxy</proxy-dir> <option name="include-source">true</option> </proxy-gen> </web-service>
<web-service> <display-name>Stateless Java Document Web Service</display-name> <description>Stateless Java Document Web Service Example</description> <!-- Specifies the resulting web service archive will be stored in ./statelessdocws.ear --> <destination-path>./statelessdocws.ear</destination-path> <!-- Specifies the temporary directory that web service assembly tool can create temporary files. --> <temporary-directory>./temp</temporary-directory> <!-- Specifies the web service will be accessed in the servlet context named "/statelessdocws". --> <context>/statelessdocws</context> <!-- to package the stylesheet to format input xml --> <option name="source-path">converter.xsl</option> <!-- Specifies the web service will be stateless --> <stateless-java-service> <interface-name>StatelessDoc</interface-name> <class-name>StatelessDocImpl</class-name> <!-- Specifies the web service will be accessed in the uri named "/docService" within the servlet context. --> <uri>/docservice</uri> <!-- Specifies the location of Java class files ./classes --> <java-resource>./classes</java-resource> <!-- Specifies that it uses document style SOAP messaging --> <message-style>doc</message-style> </stateless-java-service> <!-- generate the wsdl --> <wsdl-gen> <wsdl-dir>wsdl</wsdl-dir> <!-- over-write a pregenerated wsdl , turn it 'false' to use the pregenerated wsdl--> <option name="force">true</option> <option name="httpServerURL">http://localhost:8888</option> </wsdl-gen> <!-- generate the proxy --> <proxy-gen> <proxy-dir>proxy</proxy-dir> <option name="include-source">true</option> </proxy-gen> </web-service>
After you create the WebServicesAssembler
configuration file, you can generate a J2EE .ear file for the Document Style Web Service. The J2EE EAR file includes Document Style Web Service servlet configuration information, including the generated file web.xml
, and the implementation classes.
Run the Oracle9iAS Web Services assembly tool, WebServicesAssembler
as follows:
java -jar WebServicesAssembler.jar -config my_service_config
Where: my_service_config is the configuration file that contains the <stateless-java-service>
or the <stateful-java-service>
tag.
After creating the .ear file containing Java classes and the Web Services Servlet deployment descriptors, you can deploy the Web Service as you would any standard J2EE application stored in an .ear file (to run under OC4J).
|
![]() Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|