|
Oracle® Application Server Web Services Developer's Guide
10g Release 2 (10.1.2) Part No. B14027-01 |
|
 Previous |
 Next |
|
Oracle® Application Server Web Services Developer's Guide
10g Release 2 (10.1.2) Part No. B14027-01 |
|
|
Previous |
Next |
This chapter describes the procedures you use to write and deploy Oracle Application Server Web Services that are implemented as Java classes.
This chapter covers the following topics:
Using Oracle Application Server Web Services With Java Classes
Serializing and Encoding Parameters and Results for Web Services
This chapter shows sample code for writing Web Services implemented with Java classes and describes the difference between writing stateful and stateless Java Web Services.
Oracle Application Server supplies Servlets to access the Java classes which implement a Web Service. The Servlets handle requests generated by a Web Service client, run the Java method that implements the Web Service and returns results back to Web Services clients.
Writing Java class based Web Services involves building a Java class that includes one or more methods. When a Web Services client makes a service request, Oracle Application Server Web Services invokes a Web Services Servlet that runs the method that implements the service request. There are very few restrictions on what actions Web Services can perform. At a minimum, Web Services generate some data that is sent to a client or perform an action as specified by a Web Service request.
This section shows how to write a stateful and a stateless Java Web Service that returns a string, "Hello World". The stateful service also returns an integer running count of the number of method calls to the service. This Java Web Service receives a client request and generates a response that is returned to the Web Service client.
The sample code is supplied on the Oracle Technology Network Web site,
http://otn.oracle.com/tech/java/oc4j/demos/1012/index.html
After expanding the Web Services demo.zip file, the Java class based Web Service is in the directory under webservices/demo/basic/java_services on UNIX or in \webservices\demo\basic\java_services on Windows.
Oracle Application Server Web Services supports stateful and stateless implementations for Java classes running as Web Services, as follows:
For a stateful Java implementation, Oracle Application Server Web Services uses a single Java instance to serve the Web Service requests from an individual client.
For a stateless Java implementation, Oracle Application Server 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 and Deploying Java Class Based Web Services". |
Developing a Java Web Service consists of the following steps:
Create a Java Web Service by writing or supplying a Java class with methods that are deployed as a Web Service. In the sample supplied in the java_services sample directory, the .ear file, ws_example.ear contains the Web Service source, class, and configuration files. In the expanded .ear file, the class StatefulExampleImpl provides the stateful Java service and StatelessExampleImpl provides the stateless Java service.
When writing a Java Web Service, if you want to place the Java service in a package, use the Java package specification to name the package. The first line of StatefulExampleImpl.java specifies the package name, as follows:
package oracle.j2ee.ws_example;
The stateless sample Web Service is implemented with StatelessExampleImpl, a public class. The class defines a public method, helloWorld(). In general, a Java class for a Web Service defines one or more public methods.
Example 3-1 shows StatelessExampleImpl.
The stateful sample Web Service is implemented with StatefulExampleImpl, a public class. The class initializes the count and defines two public methods, count() and helloWorld().
Example 3-2 shows StatefulExampleImpl.
Example 3-1 Defining A Public Class with Java Methods for a Stateless Web Service
package oracle.j2ee.ws_example;
public class StatelessExampleImpl {
public StatelessExampleImpl() {
}
public String helloWorld(String param) {
return "Hello World, " + param;
}
}
Example 3-2 Defining a Public Class with Java Methods for a Stateful Web Service
package oracle.j2ee.ws_example;
public class StatefulExampleImpl {
int count = 0;
public StatefulExampleImpl() {
}
public int count() {
return count++;
}
public String helloWorld(String param) {
return "Hello World, " + param;
}
}
A Java class implementation for a Web Service must include a public constructor that takes no arguments. Example 3-1 shows the public constructor StatelessExampleImpl() and Example 3-2 shows StatefulExampleImpl().
When an error occurs while running a Web Service implemented as a Java class, the Java class should throw an exception. When an exception is thrown, the Web Services Servlet returns a Web Services (SOAP) fault. Use the standard J2EE and OC4J administration facilities to view the logs of Servlet errors for a Web Service that uses Java classes for its implementation.
When you create a Java class containing methods that implement a Web Service, the method's parameters and return values must use supported types, or you need to use an interface class to limit the methods exposed to those methods using only supported types. Table 3-1 lists the supported types for parameters and return values for Java methods that implement Web Services.
There are several additional steps required to implement a Java Web Service if you need to handle or process SOAP request header entries.
Oracle Application Server Web Services allows you to limit the methods you expose as 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 3-3 shows an interface to the method in the class StatelessExampleImpl. Example 3-4 shows an interface to the methods in the class StatefulExampleImpl.
Example 3-3 Using a Public Interface to Expose Stateless Web Services Methods
package oracle.j2ee.ws_example;
public interface StatelessExample {
String helloWorld(String param);
}
Example 3-4 Using a Public Interface to Expose Stateful Web Services Methods
package oracle.j2ee.ws_example;
public interface StatefulExample {
int count();
String helloWorld(String param);
}
When an interface class is not included with a Web Service, the Web Services deployment exposes all public methods defined in the Java class. Using an interface, for example StatelessExample shown in Example 3-3 or StatefulExample shown in Example 3-4, exposes only the methods listed in the interface.
|
Note: Using an interface, only the methods with the specified method signatures are exposed when the Java class is prepared and deployed as a Web Service. |
Use a Web Services interface for the following purposes:
To limit the exposure of methods to a subset of the public methods within a class.
To expand the set of methods that are exposed as Web Services to include methods within the superclass of a class.
To limit the exposure of methods to a subset of the public methods within a class, where the subset contains only the methods that use supported types for parameters or return values. Table 3-1 lists the supported types for parameters and return values for Java methods that implement Web Services.
The WebServicesAssembler supports the <wsdl-gen> and <proxy-gen> tags to allow a Web Service developer to generate WSDL files and client-side proxy files. You can use these tags to control whether the WSDL file and the client-side proxy are generated. Using these tags you can also specify that the generated WSDL file or a WSDL file that you write is packaged with the Web Service J2EE .ear.
A client-side developer either uses the WSDL file that is obtained from a deployed Web Service, or the client-side proxy that is generated from the WSDL to build an application that uses the Web Service.
Table 3-1 lists the supported data types for parameters and return values for Oracle Application Server Web Services.
Table 3-1 Web Services Supported Data Types
| Primitive Type | Object Type |
|---|---|
Boolean
|
java.lang.Boolean
|
byte
|
java.lang.Byte
|
double
|
java.lang.Double
|
float
|
java.lang.Float
|
int
|
java.lang.Integer
|
long
|
java.lang.Long
|
short
|
java.lang.Short
|
string
|
java.lang.String
|
|
|
java.util.Date
|
|
|
java.util.Map
|
|
|
org.w3c.dom.Element
|
|
|
org.w3c.dom.Document
|
|
|
org.w3c.dom.DocumentFragment
|
|
|
Java Beans (whose property types are listed in this table or are another supported Java Bean) |
|
|
Single-dimensional arrays of types listed in this table. |
Document Style Web Service implementations under Oracle Application Server Web Services restrict the signature of the Java methods that implement the Web Service. Only org.w3c.dom.Element can be passed to or sent from these Web Services.
|
Note: The preceding restriction means thatorg.w3c.dom.Element types cannot be mixed as a parameter with other types in methods that implement a Web Service.
|
A Bean, for purposes of Web Services, is any Java class which conforms to the following restrictions:
It must have a constructor taking no arguments.
It must expose all interesting state through properties.
It must not matter what order the accessors for the properties, for example, the setX or getX methods, are in.
Oracle Application Server Web Services allows Beans to be returned or passed in as arguments to J2EE Web Service methods, as long as the Bean only consists of property types that are listed in Table 3-1 or are another supported Java Bean.
When Java Beans are used as parameters to Oracle Application Server Web Services, the client-side code should use the generated Bean included with the downloaded client-side proxy. This is because the generated client-side proxy code translates SOAP structures to and from Java Beans by translating SOAP structure namespaces to and from fully qualified Bean class names. If a Bean with the specified name does not exist in the specified package, the generated client code will fail.
However, there is no special requirement for clients using Web Services Description Language (WSDL) to form calls to Oracle Application Server Web Services, rather than the client-side proxy. The generated WSDL document describes SOAP structures in a standard way. Application development environments, such as Oracle JDeveloper, which work directly from WSDL documents can correctly call Oracle Application Server Web Services with Java Beans as parameters.
|
Note: When Web Service proxy classes and WSDL are generated, all Java primitive types in the service implementation on the server-side are mapped to Object types in the proxy code or in the WSDL. For example, when the Web Service implementation includes parameters of primitive Java typeint, the equivalent parameter in the proxy is of type java.lang.Integer. This mapping occurs for all primitive types.
|
To deploy a Java class as a Web Service you need to assemble a J2EE .ear file that includes the deployment descriptors for the Oracle Application Server Web Services Servlet and includes the Java class that supplies the Java implementation. This section describes how to use the Oracle Application Server Web Services tool, WebServicesAssembler. WebServicesAssembler takes an XML configuration file that describes the Java Class Web Service and produces a J2EE .ear file that can be deployed under Oracle Application Server Web Services.
This section contains the following topics.
Creating a Configuration File to Assemble Java Class Web Services
Running WebServicesAssembler To Prepare Java Class Web Services
The Oracle Application Server Web Services assembly tool, WebServicesAssembler, assists in assembling Oracle Application Server Web Services. This section describes how to create a configuration file to use with Java Class Web Services.
Create a WebServicesAssembler configuration file by adding the following:
Table 3-2 describes the top level WebServicesAssembler configuration file tags. Add these tags to provide top level information describing the Java Stateless Web Service or a Java Stateful Web Service. These tags are included within a <web-service> tag in the configuration file.
Example 3-5 shows a complete config.xml file, including the top level tags.
Table 3-2 Top Level WebServicesAssembler Configuration Tags
| Tag | Description |
|---|---|
<context>context</context>
|
Specifies the context root of the Web Service.
This tag is required. |
<datasource-JNDI-name> </datasource-JNDI-name>
|
Specifies the datasource associated with the Web Service. |
<description> description</description>
|
Provides a simple description of the Web Service.
This tag is optional. |
<destination-path> dest_path</destination-path>
|
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. |
<display-name> disp_name</display-name>
|
Specifies the Web Service display name.
This tag is optional. |
<option name="source-path" [contextroot="path1"] > path2 <option>
|
Includes a specified file in the output .ear file. Use this option to specify java resources, or the name of an existing .war, .ear, or ejb-jar file that is used as a source file for the output J2EE .ear file.
When a .war file is supplied as input, the optional contextroot specifies the root-context for the .war file. path1 specifies the context-root for the .war. path2 specifies the path to the file to include. For example: <option name="source-path" contextroot="/test">/myTestArea/ws/src/statefull.war</option> |
<stateless-java-service> sub-tags</stateless-java-service>
|
Use this tag to add a Java Web Services that defines a stateless service. See Table 3-3 for a description of valid sub-tags. |
<stateful-java-service> sub-tags</stateful-java-service>
|
Use this tag to add a Java Web Services that defines a stateful service. See Table 3-3 for a description of valid sub-tags. |
<temporary-directory> temp_dir</temporary-directory>
|
Specifies a directory where the assembler can store temporary files.
This tag is optional. |
Prepare Java Stateless Web Services using the WebServicesAssembler <stateless-java-service> tag. This tag is included within a <web-service> tag in the configuration file. Add this tag to provide information required for generating a Stateless Java Web Service.
Table 3-3 shows the <stateless-java-service> sub-tags and the <stateful-java-service> sub-tags. As noted in Table 3-3, some of the sub-tags listed only apply when using a <stateful-java-service>.
Example 3-5 shows a complete config.xml file, including <stateless-java-service>.
|
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. |
Prepare Java Stateful Web Services using the WebServicesAssembler <stateful-java-service> tag. This tag is included within a <web-service> tag in the configuration file. Add this tag to provide information required for generating a Stateful Java Web Service.
To support a clustered environment, for stateful Java Web Services with serializable java classes, the WebServicesAssembler adds a <distributable> tag in the web.xml of the Web Service's generated J2EE.ear file.
Table 3-3 shows the <stateful-java-service> sub-tags.
Example 3-5 shows a complete config.xml file, including <stateful-java-service>.
Table 3-3 Stateless and Stateful Java Service Sub-Tags
| Tag | Description |
|---|---|
<accept-untyped-request> value</accept-untyped-request>
|
Setting value to true tells WebServicesAssembler to allow the Web Service to accept untyped requests. When the value is false, the Web Service does not accept untyped-request.
Valid values: (case is not significant; This tag is optional. Default value: |
<class-name> class</class-name>
|
Specifies the fully qualified class name for the class that supplies the Web Service implementation.
This tag is required |
<interface-name> interface</interface-name>
|
Specifies the fully qualified name of the interface that tells the Web Service Servlet generation code which methods should be exposed as Web Services.
This tag is optional |
<ejb-resource>ejb-resource</ejb-resource>
|
This is a backward compatibility tag.
See Also: the top level <option name="source-path"> tag in Table 3-2. This tag is optional |
<java-resource> resource</java-resource>
|
This is a backward compatibility tag.
See Also: the top level <option name="source-path"> tag in Table 3-2. This tag is optional |
<message-style> rpc</message-style>
|
Sets the message style. When defining a Java Web Service, if you include the <message-style> tag you must specify the value rpc.
Valid Values: This tag is optional Default value: |
<scope> scope</scope>
|
Sets the scope of the session for stateful services.
The This tag is optional Valid Values: Default Value: |
<session-timeout> value</session-timeout>
|
Sets the session timeout for a stateful session.
The Specify value with an integer that defines the timeout for the session in seconds. The default value for the session timeout for stateful Java sessions where no session timeout is specified is 60 seconds. This tag is optional |
<uri> URI</uri>
|
Specifies servlet mapping pattern for the Servlet that implements the Web Service. The path specified as the URI is appended to the <context> to specify the Web Service location.
This tag is required |
|
|
|
Example 3-5 Sample WebServicesAssembler Configuration File
<web-service>
<display-name>Web Services Example</display-name>
<description>Java Web Service Example</description>
<!-- Specifies the resulting web service archive will be stored in
./ws_example.ear -->
<destination-path>./ws_example.ear</destination-path>
<!-- Specifies the temporary directory that web service assembly
tool can create temporary files. -->
<temporary-directory>./tmp</temporary-directory>
<!-- Specifies the web service will be accessed in the servlet context
named "/webservices". -->
<context>/webservices</context>
<!-- Specifies the web service will be stateless -->
<stateless-java-service>
<interface-name>oracle.j2ee.ws_example.StatelessExample</interface-name>
<class-name>oracle.j2ee.ws_example.StatelessExampleImpl</class-name>
<!-- Specifies the web service will be accessed in the uri named
"statelessTest" within the servlet context. -->
<uri>/statelessTest</uri>
<!-- Specifies the location of Java class files are under
./src -->
<java-resource>./src</java-resource>
</stateless-java-service>
<stateful-java-service>
<interface-name>oracle.j2ee.ws_example.StatefulExample</interface-name>
<class-name>oracle.j2ee.ws_example.StatefulExampleImpl</class-name>
<!-- Specifies the web service will be accessed in the uri named
"statefullTest" within the servlet context. -->
<uri>/statefulTest</uri>
<!-- Specifies the location of Java class files are under
./src -->
<java-resource>./src</java-resource>
</stateful-java-service>
</web-service>
The WebServicesAssembler supports the <wsdl-gen> and <proxy-gen> tags to allow a Web Service developer to generate WSDL files and client-side proxy files. You can use these tags to control whether the WSDL file and the client-side proxy are generated. Using these tags you can also specify that the generated WSDL file or a WSDL file that you supply is packaged with the Web Service J2EE .ear.
A client-side developer can use the WSDL file that is obtained from a deployed Web Service, or the client-side proxy that is generated from the WSDL to build an application that uses the Web Service.
After you create the WebServicesAssembler configuration file, you can generate a J2EE .ear file for the Web Service. The J2EE .ear file includes the Java Web Service servlet configuration information, including the file web.xml, and the Java classes and interfaces that you supply.
Run the Oracle Application Server Web Services assembly tool, WebServicesAssembler as follows:
java -jar WebServicesAssembler.jar -config config_file
Where: config_file is the configuration file that contains the <stateless-java-service> or the <stateful-java-service> tags.
After creating the J2EE .ear file containing the 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).
|
See Also: Oracle Application Server Containers for J2EE User's Guide in the Oracle Application Server 10g Documentation Library |
Parameters and results sent between Web Service clients and a Web Service implementation go through the following steps:
Parameters are serialized and encoded in XML when sent from the Web Service client.
Parameters are deserialized and decoded from XML when the Web Service receives a request on the server side.
Parameters or results are serialized and encoded in XML when a request is returned from a Web Service to a Web Service client.
Parameters or results must be deserialized and decoded from XML when the Web Service client receives a reply.
Oracle Application Server Web Services supports a prepackaged implementation for handling these four steps for serialization and encoding, and deserialization and decoding. The prepackaged mechanism makes the four serialization and encoding steps transparent both for the Web Services client-side application, and for the Java service writer that is implementing a Web Service. Using the prepackaged mechanism, Oracle Application Server Web Services supports the following encoding mechanisms:
Standard SOAP v.1.1 encoding: Using standard SOAP v1.1 encoding, the server side Web Services Servlet that calls the Java class implementation handles serialization and encoding internally for the types supported by Oracle Application Server Web Services. Table 3-1 lists the supported Web Services parameter and return value types when using standard SOAP v.1.1 encoding.
Literal XML encoding. Using Literal XML encoding, a Web Service client can pass as a parameter, or a Java service can return as a result, a value that is encoded as a conforming W3C Document Object Model (DOM) org.w3c.dom.Element. When an Element passes as a parameter to a Web Service, the server side Java implementation processes the org.w3c.dom.Element. For return values sent from a Web Service, the Web Services client parses or processes the org.w3c.dom.Element.
|
Note: For parameters to a Web Service or results that the Web Service generates and returns to Web Services clients, the Oracle Application Server Web Services implementation supports either the Standard SOAP encoding or Literal XML encoding but not both, for any given Web Service (Java method). |
