Oracle9i Application Server Web Services Developer's Guide Release 2 (9.0.2) Part Number A95453-01 |
|
This chapter describes the procedures you use to write and deploy Oracle9iAS Web Services that are implemented as Java classes.
This chapter covers the following topics:
Oracle9iAS Web Services can be implemented as any of the following:
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.
Oracle9iAS supplies Servlets to access the Java classes which implement a Web Service. The Servlets handle requests generated by Web Services clients, run the Java methods that implement the Web Services and return results back to Web Services clients.
Writing Java class based Web Services involves building a Java class that includes one or more methods that a Web Services Servlet running under Oracle9iAS Web Services invokes when a Web Services client makes a 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 with Oracle9iAS Web Services in the directory $ORACLE_HOME/j2ee/home/demo/web_services/java_services
on UNIX or in %ORACLE_HOME%\j2ee\home\demo\web_services\java_services
on Windows.
Oracle9iAS Web Services supports stateful and stateless implementations for 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 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. If you expand the .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 StatelessExampleImpl
.
public class StatelessExampleImpl { public StatelessExampleImpl() { } public String helloWorld(String param) { return "Hello World, " + param; } }
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. For example, Example 3-1 shows the public constructor StatelessExampleImpl()
.
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 for logging Servlet errors for the 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 4-1 lists the supported types for parameters and return values for Java methods that implement Web Services.
Note: See Table 4-1 for the list of supported types for parameters and return values. |
Oracle9iAS 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
.
public interface StatelessExample { String helloWorld(String param); }
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. 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:
When writing a Java class based Web Service, this step is optional. If you do not perform this step, the Oracle9iAS Web Services runtime generates a WSDL file and the client-side proxies for deployed Web Services. These files allow Oracle9iAS Web Services to supply a Web Service client with the WSDL or the client-side proxies that a client-side developer can use to build an application that uses a Web Service.
When you do not want to use the Oracle9iAS Web Services generated WSDL file or client-side proxies and you want to supply your own versions of these files, perform the following steps:
.wsdl
extension. The client-side proxy Jar must have an _proxy.jar
extension.The extension is placed after the service name.
For example,
simpleservice.wsdl simpleservice_proxy.jar
WEB-INF/classes
. For example, if simpleservice.wsdl
describes a service that is part of the demo package, place the file in the following directory:
WEB-INF/classes/demo/simpleservice.wsdl
WEB-INF/lib
component of the .war file that is added to the .ear file and deployed as a Web Service.
For example, the file simpeservice_proxy.jar
could be added to simpleservice.jar
and placed in WEB-INF/lib
, or added to namex.jar
in WEB-INF/lib
(
where namex is a file name).
Note:
The Jar file containing the proxy stubs and optionally the proxy source must be a Jar component of a Jar file in |
To deploy a Java class as a Web Service you need to assemble a J2EE .ear file that includes the deployment descriptors for the Oracle9iAS Web Services Servlet and the Java class that supplies the Java implementation. A Web Service implemented using a Java class 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 assemble the .ear file that contains a Java class to run as a Web Service.
This section covers the following topics:
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 class and interface files and produces a J2EE .ear file that can be deployed under Oracle9iAS Web Services. This section describes how to assemble Oracle9iAS Web Services implemented as Java classes manually, without using WebServicesAssembler
.
To use a Java class as a Web Service, you need to add a <servlet>
entry and a corresponding <servlet-mapping>
entry in the web.xml
file for each Java class that is deployed as a Web Service. The resulting web.xml
file is assembled as part of a J2EE .war file that is included in the .ear file that defines the Web Service.
To modify web.xml
to support Web Services implemented as Java classes, perform the following steps:
To add Web Services based on Java classes you need to modify the <servlet>
tag in the web.xml
file. This supports using the Oracle9iAS Web Services Servlet to access the Java implementation for the Web Service. Table 3-1 describes the <servlet>
tag and the values to include in the tag to add a Web Service based on a Java class.
Example 3-5 shows a sample <servlet>
entry for Web Services implemented as a Java class running as a stateless Web Service. Example 3-6 shows a sample <servlet>
entry for a Web Service implemented as a Java class running as a stateful Web Service.
<servlet> <servlet-name>stateless java web service example</servlet-name> <servlet-class>oracle.j2ee.ws.StatelessJavaRpcWebService</servlet-class> <init-param> <param-name>class-name</param-name> <param-value>oracle.j2ee.ws_example.StatelessExampleImpl</param-value> </init-param> <init-param> <param-name>interface-name</param-name> <param-value>oracle.j2ee.ws_example.StatelessExample</param-value> </init-param> </servlet>
<servlet> <servlet-name>stateful java web service example</servlet-name> <servlet-class>oracle.j2ee.ws.JavaRpcWebService</servlet-class> <init-param> <param-name>class-name</param-name> <param-value>oracle.j2ee.ws_example.StatefulExampleImpl</param-value> </init-param> <init-param> <param-name>interface-name</param-name> <param-value>oracle.j2ee.ws_example.StatefulExample</param-value> </init-param> </servlet>
To add Web Services based on Java classes, you need to modify the <servlet-mapping>
tag in the web.xml
file. This tag specifies the URL for the Servlet that implements a Web Service.
Example 3-7 shows sample <servlet-mapping>
entries corresponding to the servlet entries shown in Example 3-5 and Example 3-6.
<servlet-mapping> <servlet-name>stateful java web service example</servlet-name> <url-pattern>/statefulTest</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>stateless java web service example</servlet-name> <url-pattern>/statelessTest</url-pattern> </servlet-mapping>
Web Services implemented with Java classes use a standard .war file to define J2EE Servlet configuration and deployment information. After modifying the web.xml
file, add the implementation classes and any required support classes or Jar files either under WEB-INF/classes
, or under WEB-INF/lib
(or in a classpath location available to OC4J).
To add Web Services based on Java classes, you need to include an application.xml
file and package the application.xml
and .war file containing the Java classes into a J2EE .ear file.
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).
Parameters and results sent between Web Service clients and a Web Service implementation go through the following steps:
Oracle9iAS 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, Oracle9iAS Web Services supports the following encoding mechanisms:
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
.
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|