Skip Headers

Oracle® Application Server Web Services Developer's Guide 10g Release 3 (10.1.3) B14434-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 13 Assembling a J2EE Web Service Client

This chapter describes how to develop a Web service client from within a J2EE container. Any component of a J2EE 1.4-compliant container, such as a version 2.4 servlet, 2.1 EJB, or 2.0 JSP application can act as a J2EE Web service client.

This chapter contains the following sections:

- Understanding J2EE Web Service Clients

- Writing J2EE Web Service Client Code

- Packaging a J2EE Client

For information on assembling a Web service client that runs in the J2SE environment, see Chapter 14, "Assembling a J2SE Web Service Client".

## Understanding J2EE Web Service Clients

The J2EE platform provides an environment that allows client applications to access Web services. In a J2EE environment, the deployment descriptors define the client-side Web service access information. This access information can be changed at deployment time. In addition, the J2EE platform handles the underlying work of creating and initializing access to Web services.

J2EE Web service clients inherit the advantages of the J2EE platform, such as declarative security, transactions, and instance management. In addition to these platform characteristics, the OracleAS Web Services management framework makes it possible to configure SOAP logging and auditing, WS-Reliability, and WS-Security.

Unlike the J2SE Web service client, the J2EE client resides in and is managed by the OC4J container. It requires no proxy code generation or packaging. You get a portable client application with Web service access that is easy to embed in JSPs, servlets, and EJBs. EJB variants such as Container Managed Persistence (CMP), Bean Managed Persistence (BMP), and Message-Driven Beans (MDB) can call out to Web service endpoints.

### Prerequisites

Before you begin, supply the following files and information.

- The WSDL file or location from which the service endpoint interface and JAX-RPC mapping file will be generated.

- The location where the generated service endpoint interface and JAX-RPC mapping file will be stored.

### How to Assemble a J2EE Web Service Client

Use the WebServicesAssembler tool to assemble a service endpoint interface and the J2EE Web service client. Then, edit the deployment descriptor to add Web service access information. The following steps describe these tasks in more detail.

1. Provide the WSDL and the information described in the Prerequisites section as input to the WebServicesAssembler `genInterface` command. For example:

       java -jar wsa.jar
            -genInterface
            -wsdl HelloService.wsdl
            -output build -packageName oracle.demo.hello

   This command line uses `HelloService.wsdl` to generate `HelloInterface` in the `oracle.demo.hello` package.

2. Edit the deployment descriptor of the J2EE component to add a `<service-ref>` element. This element captures all of the Web service access information.

   See "Adding J2EE Web Service Client Information to Deployment Descriptors" for a sample of the `<service-ref>` element and its sub-elements.

   If the client also provides message processing in the form of JAX-RPC handlers, then these also must be added to the deployment descriptor. See "Adding JAX-RPC Handlers to Deployment Descriptors" for more information on adding handler information to the deployment descriptor.

3. Assemble the client deployment module into an EAR file:

   1. Compile all the client files.

   2. Copy deployment descriptor files to their appropriate locations. For example, for an EJB, copy the WSDL to `META-INF/wsdl/`, the JAX-RPC mapping file and the deployment files such as `ejb-jar.xml` and `orion-ejb-jar.xml` to `META-INF`, and so on. For a description of where files should reside for servlet, EJB, or JSP Web service clients, see "Packaging Structure for Web Service Applications".

   3. Package the client deployment module.

      Note: The current tool set cannot package J2EE Web service clients. You must package the client manually. "Packaging a J2EE Client" provides more information on how to package a J2EE Web service client.

4. Deploy the client deployment module.

   The following steps will deploy an EJB, JSP, or other J2EE client. If you are deploying an application client, skip these steps and continue with "Deploying and Running an Application Client Module".

   1. Start OC4J. The following is a sample command to start OC4J.

          java -jar oc4j.jar

   2. Deploy the client module into OC4J. The following is a sample deployment command.

          java -jar admin_client.jar deployer:oc4j:<oc4jHost>:<oc4jPort> <adminID> <adminPassword>
                   -deploy
                   -file .\client\myClient.ear
                   -deploymentName myClient
                   -bindWebApp default-web-site

      The `oc4jHost` and `oc4jPort` variables are the host name and port number of the OC4J server. The `adminID` and `adminPassword` are the OC4J server user name and password. The following are sub-switches of the `-deploy` switch.

   - `file`—path and filename of the EAR file to deploy.

   - `deploymentName`—user-defined application deployment name, used to identify the application within OC4J.

   - `bindWebApp`—specifies the Web site to which the web application should be bound. This is the Web site that will be used to access the application.

5. Run the EJB or JSP client.

   If you are running an application client, see "Deploying and Running an Application Client Module".

#### Deploying and Running an Application Client Module

The following steps describe how to deploy and run an application client module. Unlike EJB, JSP, or other J2EE clients, you must specify the directory where the generated `deployment-cache.jar` will be stored. You must also specify the location of the `deployment-cache.jar` in the run command.

1. Start OC4J. The following is a sample command to start OC4J.

       java -jar oc4j.jar

2. Deploy the application client module into OC4J. The following is a sample deployment command.

       java -jar admin_client.jar deployer:oc4j:<oc4jHost>:<oc4jPort> <adminID> <adminPassword>
                -deploy
                -file .\client\myAppClient.ear
                -deploymentName myAppClient
                -deploymentDirectory C:\home\myDir

   This command creates a `deployment-cache.jar` file and stores it in `C:\home\myDir`.

   The `oc4jHost`, `oc4jPort`, `adminID`, and `adminPassword` variables and the `file` and `deploymentName` sub-switches of `-deploy` are described in Step 4b of the previous section.

   The `deploymentDirectory` sub-switch indicates the location where OC4J deploys `deployment-cache.jar`. In this example, OC4J deploys it into `C:\home\myDir`. If you do not specify this sub-switch, OC4J deploys the application into the `OC4J_HOME``/application-deployments/` directory. If you supply the empty string (" "), OC4J will always read the deployment configurations from the EAR file each time the application is deployed.

3. Run the client deployment module. For an application client, the location of the `deployment-cache.jar` must be present in the classpath. The following is a sample run command:

       java -classpath .:C:\home\myDir\deployment-cache.jar:'oc4jclient.jar'
         :appclient.jar oracle.myappclient.classname

   In this sample, it is assumed that `appclient.jar` contains the class `oracle.myappclient.`classname.

#### Ant Task for Generating an Interface

The current release provides Ant tasks for Web service development. The following sample code shows how the `genInterface` command in the preceding example can be rewritten as an Ant task.

    <oracle:genInterface wsdl="${etc.web1.dir}/HelloService.wsdl"
            output="build"
            packageName="oracle.demo.hello"
    />

#### Adding J2EE Web Service Client Information to Deployment Descriptors

You must edit the J2EE component's deployment descriptor to add information that allows the component to access the Web service endpoint.

- For an EJB 2.1 Web service client, edit the `META-INF/ejb-jar.xml` deployment descriptor.

- For a JSP 2.0 or servlet Web service client, edit the `WEB-INF/web.xml` deployment descriptor.

- For an application client, edit the `META-INF/application-client.xml` deployment descriptor.

Edit the deployment descriptor to add a `<service-ref>` element. By adding this element, you can employ an EJB, JSP, or servlet as a Web service client that can invoke a remote Web service. The `<service-ref>` element and its subelements capture all the Web service access information, such as the location of the WSDL and mapping file, the service interface, the service ports, their related service endpoint interfaces, and so on. For a complete listing of all the information that can be included in the `<service-ref>` element, see the `service-ref` (J2EE client) schema.

`http://java.sun.com/xml/ns/j2ee/j2ee_web_services_client_1_1.xsd`

Example 13-1 illustrates a sample `<service-ref>` element that has been added to a `web.xml` deployment descriptor for the `MyHelloService` Web service. The `<service-ref>` subelements in this example are described in Table 13-1. Note that this sample `<service-ref>` uses only a subset of all of the Web service access information available in the schema.

Example 13-1 Contents of a Sample service-ref Element

    <service-ref>
        <service-ref-name>service/MyHelloServiceRef</service-ref-name>
        <service-interface>javax.xml.rpc.Service</service-interface>
        <wsdl-file>WEB-INF/wsdl/HelloService.wsdl</wsdl-file>
        <jaxrpc-mapping-file>WEB-INF/HelloService-java-wsdl-mapping.xml
        </jaxrpc-mapping-file>
        <service-qname xmlns:service-qname_ns__="http://hello.demo.oracle/">
        service-qname_ns__:HelloService</service-qname>
        <port-component-ref>
             <service-endpoint-interface>oracle.demo.hello.HelloInterface
             </service-endpoint-interface>
             <port-component-link></port-component-link>
        </port-component-ref>
    </service-ref>

Table 13-1 describes the `<service-ref>` sub-elements used in this sample.

Table 13-1 Sub-elements of the <service-ref> Element

service-ref Subelement | Description
--- | ---
<service-ref-name> | Specifies the JNDI path and service name assigned by the client.
<service-interface> | Specifies the fully-qualified class name of the JAX-RPC Service interface the client depends on. In most cases the value will be `javax.xml.rpc.Service`. A JAX-RPC generated Service Interface class may also be specified.
<wsdl-file> | Specifies the fully-qualified path to the WSDL file.
<jaxrpc-mapping-file> | Specifies the fully-qualified path to the JAX-RPC mapping file.
<service-qname> | Specifies the service `QName` for the service: `xmlns:ns`—maps to the `targetNamespace` value in the WSDL. `ns`—maps to the `service name` attribute in the WSDL.
<port-component-ref> | Declares a client dependency on the container for resolving a service endpoint interface to a WSDL port. It optionally associates the service endpoint interface with a particular port-component. The container uses this only for a `Service.getPort(Class)` method call.
<service-endpoint-interface> | Specifies the fully-qualified Java class that represents the service endpoint interface of a WSDL port.
<port-component-link> (optional) | If the Web service is implemented in the same module as the client, you can add this element to access the service. For more information on this element, see "Accessing a Web Service".

#### Accessing a Web Service

To enable the Oracle Application Server to access a Web service that resides in the same module as the client, add the `<port-component-link>` element to the `<service-ref>` clause of the client deployment descriptor and add the `PortComponentLinkResolver` property to the `system-application.xml` configuration. The following steps summarize these tasks.

1. Add the `<port-component-link>` element to the `<service-ref>` clause in the J2EE client deployment descriptor.

   "Adding a Port Component Link to a J2EE Client Deployment Descriptor" provides more information on this step.

2. Shut down the Oracle Application Server.

3. Add the `PortComponentLinkResolver` property to the `system-application.xml` server configuration file. This file resides in the directory `ORACLE_HOME``/j2ee/home/config`.

   Add the following lines to this file.

       <ejb-module id="PortComponentLinkResolver" path="../../../webservices/lib/wsserver.jar"/>

4. Re-start the Oracle Application Server.

##### Adding a Port Component Link to a J2EE Client Deployment Descriptor

If the Web service resides in the same container as the client, then you can access the service by adding the `<port-component-link>` element to the `<service-ref>` clause of the J2EE client deployment descriptor (`web.xml`, `ejb-jar.xml`, or `application-client.xml`).

The `<port-component-link>` element links a `<port-component-ref>` to a specific port component in the server-side deployment descriptor. The `<port-component-name>` element resides in the server-side deployment descriptor, `webservices.xml`.

The following examples illustrate this relationship. The `webservices.xml` fragment in Example 13-2 illustrates the deployment configuration for the Web service that exposes the EJB `InterModuleEjb`. In this fragment, the port component is named `InterPC`. Example 13-3 illustrates a fragment of a client-side deployment descriptor where this name is referenced from the `<port-component-link>` element in the `<service-ref>` clause. The presence of this element allows the J2EE client to look up the Web service.

These examples assume that the Web service is running in the same container as the J2EE Web service client.

Example 13-2 webservices.xml Fragment, Identifying a Port Component Name

    <webservices>
      <webservice-description>
        <webservice-description-name>InterModuleEjb</webservice-description-name>
        <wsdl-file>META-INF/wsdl/InterModuleService.wsdl</wsdl-file>
        <jaxrpc-mapping-file>META-INF/InterModuleService.xml</jaxrpc-mapping-file>
        <port-component>
          <port-component-name>InterPC</port-component-name>
          <wsdl-port
            xmlns:wsdl1="http://PortCompLink.org/ejb/inter">wsdl1:InterModuleSeiPort
          </wsdl-port>
          <service-endpoint-interface>oracle.demo.InterModuleSei
          </service-endpoint-interface>
          <service-impl-bean>
            <ejb-link>InterModuleEjb</ejb-link>
          </service-impl-bean>
        </port-component>
    </webservices>

Example 13-3 illustrates a fragment of a client-side deployment descriptor where the value of the `<port-component-name>` element in the server-side deployment descriptor is referenced from the `<port-component-link>` element in the `<service-ref>` clause. The presence of this element allows the client to look up the Web service.

Note that the value of the port component name in the `<port-component-link>` is prefixed by `PortCompLinkEjb-ejb.jar#`. This value qualifies the name of the EJB with the JAR file where it resides.

Example 13-3 <port-component-link> Element in the Client-Side Deployment Descriptor

      <service-ref>
        <service-ref-name>service/portcomplink/inter</service-ref-name>
        <service-interface>javax.xml.rpc.Service</service-interface>
        <wsdl-file>META-INF/wsdl/InterModuleService.wsdl</wsdl-file>
        <jaxrpc-mapping-file>META-INF/InterModuleService.xml</jaxrpc-mapping-file>
        <port-component-ref>
           <service-endpoint-interface>oracle.demo.InterModuleSei
           </service-endpoint-interface>
           <port-component-link>PortCompLinkEjb-ejb.jar#InterPC</port-component-link>
        </port-component-ref>
      </service-ref>

#### Adding OC4J-Specific Platform Information

The `<service-ref-mapping>` element can appear as a subelement of the `<orion-web-app>` element in the `orion-web.xml`, `orion-ejb-jar.xml`, or `orion-application-client.xml` proprietary deployment descriptor files. It defines OC4J-specific runtime and deployment-time generated settings for a Web service reference. It also specifies security, logging, and auditing quality of service (QOS) features for the corresponding Web service.

The `<service-ref-mapping>` element is used in conjunction with the `<service-ref>` element that appears in the standard deployment descriptors. The `<service-ref>` element contains the information that lets you employ an EJB, JSP, or servlet as a Web service client that can invoke a remote Web service.

Note that whenever a `<service-ref>` element can appear in a `web.xml`, `ejb-jar.xml`, or `application-client.xml` file, a corresponding `<service-ref-mapping>` element can appear in an `orion-web.xml`, `orion-ejb-jar.xml`, or `orion-application-client.xml` file.

The `<service-ref-mapping>` element's supported features are described in the `service-ref-mapping-10_0.xsd` that is imported into the `orion-web`, `orion-ejb-jar`, and `orion-application-client` XSDs. Currently, there is no tool support, such as JDeveloper wizards, for providing values to `service-ref-mapping-10_0.xsd`. You must refer to the schema and edit the XML file by hand.

In its simplest case, the `<service-ref-mapping>` element contains only deployment information. Do not add run-time or quality of service elements if you do not want your client to be managed. A managed client is more expensive in terms of performance.

Example 13-4 contains a sample `<service-ref-mapping>` segment. So that you can see this element's hierarchy, all the subelements are displayed. The tables following the XML sample describe the sub-elements.

Example 13-4 Sample <service-ref-mapping> Segment

    <service-ref-mapping name="service/MyJAXRPCTime">
      <service-impl-class>oracle.demo.MyTime_Impl</service-impl-class>
      <wsdl-file final-location="file:/myhome/mytime/client-wsdl/MyJAXRPCTime.wsdl">
      <wsdl-location wsdl-override-last-modified=19NOV>
      <service-qname namespaceURI="urn:oracle-ws" localpart="MyService" />
      <stub-property>
       <name>...</name>
       <value>...</value>
      </stub-property>
      <call-property>
         <name>javax.xml.rpc.service.endpoint.address</name>
         <value>http://myhost:8888/time-ejb/timeport</value>
      </call-property>
      <port-info>
        <wsdl-port>
        <service-endpoint-interface>time.TimeService</service-endpoint-interface>
        <stub-property>
          <name>another.endpoint.address</name>
          <value>http://anotherhost:8888/time-ejb/timeport</value>
        </stub-property>
        <call-property>
          <name>...</name>
          <value>...</value>
        </call-property>
        <runtime>...</runtime>
        <operations>
          <operation name="echo">
             <runtime>
               <auditing request="true" response="false" fault="false"/>
               <reliability><reject-non-reliable-messages value="false"/></reliability>
               ...
             </runtime>
         </operation>
       </operations>
      </port-info>
    </service-ref-mapping>

Table 13-2 describes the subelements of `<service-ref-mapping>`.

Table 13-2 Subelements of the <service-ref-mapping> Element

Element Name | Description
--- | ---
<service-impl-class> | Defines a deployment-time generated name of a `Service` implementation.
<wsdl-file> | Defines a deployment-time generated name for the WSDL file. This element has this attribute: `final-location`—points to the copy of the WSDL document associated with the `service-ref` in the standard deployment descriptor.
<wsdl-location> | (Optional) Contains a valid URL pointing to a WSDL document. If a URL is specified, then the WSDL document at this URL will be used during deployment instead of the WSDL document associated with the `service-ref` in the standard deployment descriptor. Sample values for `<wsdl-location>` include: `http://hostname:port/myservice/myport?WSDL` and `file:/home/user1/myfinalwsdl.wsdl`. This element has this attribute: `wsdl-override-last-modified`—this optional string value is generated at deployment time and lists the time when the WSDL file was last modified.
<service-qname> | Derived at deployment-time, this element contains the `QName` of the Web service.
<stub-property> | Defines the stub property values applicable to all ports. This is a convenient way to specify a property without specifying the port name. The `name` and `value` subelements of `<stub-property>` are described in Table 13-6. Note that the `<port-info>` element also contains a `<stub-property>` element. If stub property values are specified for a particular port inside the `<port-info>` tag, then they will override the values set here.
<call-property> | Defines the call property values applicable to all ports. This is a convenient way to specify a property without specifying the port name. The `name` and `value` subelements of `<call-property>` are described in Table 13-6. Note that the `<port-info>` element also contains a `<call-property>` element. If call property values are specified for a particular port inside the `<port-info>` tag, then they will override the values set here.
<port-info> | Defines a port within a service-reference. See Table 13-3 for a description of the subelements of `<port-info>`.

Table 13-3 describes the sub-elements for the `<port-info>` element. This element provides all of the information for a port within a service reference. You can specify either `<service-endpoint-interface>` or `<wsdl-port>` to indicate the port that the container will use for container-managed port selection. If you specify both, then the container will use the `<wsdl-port>` value. If you do not specify `<wsdl-port>` or `<service-endpoint-interface>`, then the `<port-info>` property values will apply to all available ports.

The `<port-info>` element also contains subelements that let you specify quality of service features that are available for the port and its operations.

Table 13-3 Subelements of the <port-info> Element

Element Name | Description
--- | ---
<wsdl-port> | Specifies the name of a port in the WSDL that the container will use for container-managed port selection. In container-managed port selection, the container manages calls to the instance directly, and the client requests a generic port that might be used to access multiple different instances.
<service-endpoint-interface> | Specifies the fully-qualified path to the service endpoint interface of a WSDL port. The container uses this port for container-managed port selection.
<stub-property> | Defines the stub property values applicable to the port defined by the `<port-info>` element. The `name` and `value` subelements of `<stub-property>` are described in Table 13-6. Note that the `<service-ref-mapping>` element also contains a `<stub-property>` subelement (described in Table 13-2). If stub property values are specified for a particular port inside the `<port-info>` tag, then they override the `<stub-property>` element values set under `<service-ref-mapping>`.
<call-property> | Defines the call property values applicable to the port defined by the `<port-info>` element. The `name` and `value` sub-elements of `<call-property>` are described in Table 13-6. Note that the `<service-ref-mapping>` element also contains a `<call-property>` subelement (described in Table 13-2). If call property values are specified for a particular port inside the `<port-info>` tag, then they override the `<call-property>` element values set under `<service-ref-mapping>`.
<runtime> | Contains client-side quality of service runtime information (security and/or reliability) applicable to all the operations provided by the referenced Web service. Each child element contains configuration for a specific feature.
<operations> | Contains a sequence of elements, one for each operation. The `<operation>` subelement indicates an individual operation. Each of these subelements contain client-side quality of service configuration for a single operation provided by the referenced Web service. For a description of the `<operations>` subelement, see Table 13-4.

Table 13-4 describes the `<operation>` subelement of the `<operations>` element.

Table 13-4 Subelement of the <operations> Element

Element Name | Description
--- | ---
<operation> | Specifies client-side quality of service configuration for a particular operation provided by the referenced Web service. The configuration appears within this element's `<runtime>` subelement. The `<runtime>` subelement is described in Table 13-5. This `<operation>` element has these attributes: `name`—associates the contained quality of service configuration to a specific operation. The value of the attribute must match the operation name from the WSDL. `inputName`—contains the input name of the operation from the WSDL. It is required only if the `name` attribute cannot be used to uniquely identify the operation. `outputName`—contains the output name of the operation from the WSDL. It is required only if the `name` and `input` attributes cannot be used to uniquely identify the operation.

Table 13-5 describes the `<runtime>` subelement of the `<operation>` element.

Table 13-5 Subelement of the <operation> Element

Element Name | Description
--- | ---
<runtime> | Contains client-side quality of service configuration for individual operations within the port. Each child element contains configuration for one of the quality of services features (security, reliability, and/or auditing).

Table 13-6 describes the `name` and `value` subelements of the `<stub-property>` and `<call-property>` elements.

Table 13-6 Subelements of <stub-property> and <call-property> Elements

Element Name | Description
--- | ---
<name> | Defines the name of any property supported by the JAX-RPC `Call` or `Stub` implementation. See the output of the Javadoc tool for the valid properties for `javax.xml.rpc.Call` and `javax.xml.rpc.Stub`.
<value> | Defines a JAX-RPC property value that should be set on a `Call` object or a `Stub` object before it is returned to the Web service client.

#### Adding JAX-RPC Handlers to Deployment Descriptors

J2EE Web service clients can support JAX-RPC handlers to provide additional message processing facilities for Web service endpoints. For example, you can use a handler to process a SOAP message.

You must enter the handler information as a subelement of `<service-ref>` in a J2EE Web service client's deployment descriptor. The `<handler>` element encapsulates this information. For more information on client-side handlers and registering them with the deployment descriptor, see "Client-Side JAX-RPC Handlers".

## Writing J2EE Web Service Client Code

This section describes some of the common code that allows a J2EE component to access a Web service. At runtime, all J2EE Web service clients use a standard JNDI lookup to find Web services. The following steps describe the general pattern for coding a JNDI lookup that could be used within a servlet, EJB, or a JSP.

1. Create the initial JNDI context.

       Context ic = new InitialContext();

   The OC4J container sets up the initial context properties.

2. Locate the service using the `lookup` method from the initial context. The `comp/env/service/MyHelloServiceRef` in Example 13-5 provides the service reference. The JNDI call returns a reference to a `service` object.

       Service service = (Service) ic.lookup("java:comp/env/service/MyHelloServiceRef");

   The client always accesses the service implementation by using a JNDI lookup. This lookup returns a container-managed service reference. This allows the container to intervene and provide the client with additional service functionality, such as logging, security, and management.

3. Get a handle to the service port using the `getPort` method on the container-managed service object. Cast the return value to the interface type.

       HelloInterface helloPort = (HelloInterface) service.getPort(portQName, oracle.demo.hello.HelloInterface.class);

   Note that this step assumes that a `QName` has already been defined. For example:

       QName portQName = new QName("http://hello.demo.oracle/", "HelloInterfacePort");

   Instead of `getPort`, the client can make a DII Web service call by using the `service` object to get a handle on the `Call` object.

       Call call = service.createCall(new QName("http://hello.demo.oracle/", "HelloInterfacePort");

4. Call a method on the remote object.

       resultFromService = helloPort.sayHello(name);

Example 13-5 illustrates code that a servlet or JSP Web service client can use to look up a Web service.

Example 13-5 Servlet or JSP Code to Look Up a Web Service

    public String consumeService (String name)
    {
       ......
       Context ic = new InitialContext();
       Service service = (Service)ic.lookup("java:comp/env/service/MyHelloServiceRef");
       // declare the qualified name of the port, as specified in the wsdl
       QName portQName= new QName("http://hello.demo.oracle/","HelloInterfacePort");
       //get a handle on that port : Service.getPort(portQName,SEI class)
       HelloInterface helloPort =
    (HelloInterface) service.getPort(portQName,oracle.demo.hello.HelloInterface.class);
       //invoke the operation : sayHello()
       resultFromService = helloPort.sayHello(name);
       .....
    }

### Configuring a J2EE Web Service Client for a Stateful Web Service

J2EE Web service clients can be configured, either by using configuration files or programmatically, to consume stateful Web services.

- Configuring a J2EE Client with Configuration Files

- Configuring a J2EE Client Programmatically

See "Exposing Java Classes as a Stateful Web Service" for more information on stateful Web services.

#### Configuring a J2EE Client with Configuration Files

A J2EE client can be configured to consume stateful Web services by editing the `<service-ref-mapping>` clause of the appropriate Oracle-proprietary deployment descriptor (either `orion-web.xml`, `orion-ejb-jar.xml`, or `orion-application-client.xml`).

Within the `<service-ref-mapping>` clause, add a `<stub-property>` element with its `<name>` sub-element set to the `javax.xml.rpc.session.maintain` property and its `<value>` sub-element set to `true`.

The value of the J2EE standard property `javax.xml.rpc.session.maintain` indicates to the client whether it wants to participate in a session with a service endpoint. If this property is set to `true`, the client indicates that it wants the session to be maintained.

Example 13-6 illustrates a Web service client configuration for a stateful Web service. The definition of the `<stub-property>` allows the client to participate in a session with the port identified by the `CycleCounterInterface` service endpoint. The `<stub-property>` element, with its setting for `javax.xml.rpc.session.maintain`, is highlighted in bold.

Example 13-6 Configuration for a Client Participating with a Stateful Web Service

         <service-ref-mapping name="service/CycleCounter">
             <port-info>
                    <service-endpoint-interface>test.oracle.stateful.CycleCounterInterface</service-endpoint-interface>
              <!-- set the javax.xml.rpc.session.maintain property to true for a stateful client -->
                    <stub-property>
                         <name>javax.xml.rpc.session.maintain</name>
                         <value>true</value>
                    </stub-property>
                    <stub-property>
                         <name>javax.xml.rpc.service.endpoint.address</name>
                         <value>http://%J2EE_HOST%:%HTTP_PORT%/testsfWS-session/testsfWS-session</value>
                     </stub-property>
              </port-info>
         </service-ref-mapping>

#### Configuring a J2EE Client Programmatically

A J2EE client can be configured programmatically to consume stateful Web services. To do this, ensure that the client participates in the session by setting the `SESSION_MAINTAIN_PROPERTY` runtime property (`javax.xml.rpc.session.maintain`) to `true` either on the stub, the DII call, or the endpoint client instance.

For example, you can set the value of this property inside the generated implementation `_port` of `javax.xml.rpc.Stub`:

    ((Stub)__port)._setProperty(Stub.SESSION_MAINTAIN_PROPERTY, Boolean.valueOf (maintainSession));

Instead of setting this property directly, OracleAS Web Services provides a helpful wrapper class with a `setMaintainSession(boolean)` method. When this method is set to `true` the session is maintained. The wrapper takes care of setting the property inside of the client. For example, in the client code, you can enter the following:

    HttpSoap11Client c = new HttpSoap11Client(); // client wrapper class
    c.setMaintainSession(true);

### Configuring a J2EE Web Service Client to Make JMS Transport Calls

You can statically configure the J2EE client to make JMS transport calls. To do this, add a `<service-ref-mapping>` clause to the appropriate Oracle-proprietary J2EE client deployment descriptor file for your Web service (`orion-web.xml`, `orion-ejb-jar.xml`, or `orion-application-client.xml`). Within the clause, configure a `<stub-property>` element with `name` and `value` attributes for each of these items.

- ReplyTo queue—Enter a `<stub-property>` element with the `name` attribute set to the `ReplyToQueueName` API (`oracle.webservices.transport.ReplyToQueueName`) and the `value` attribute set to the JNDI name of the ReplyTo queue.

- ReplyTo factory name—Enter a `<stub-property>` element with the `name` attribute set to the `ReplyToFactoryName` API (`oracle.webservices.transport.ReplyToFactoryName`) and the `value` attribute set to the JNDI name of the ReplyTo factory.

- service endpoint address—Enter a `<stub-property>` element with `name` attribute set to the service endpoint address API (`javax.xml.rpc.service.endpoint.address`) and the `value` attribute set to the service endpoint interface file.

Example 13-7 illustrates a sample configuration.

Example 13-7 J2EE Client Configuration for JMS Transport Calls

    <service-ref-mapping name="service/MyJMSService">
         <stub-property>
            <name>oracle.webservices.transport.ReplyToQueueName</name>
            <value>jms/receiverQueue</value>
         </stub-property>
         <stub-property>
            <name>oracle.webservices.transport.ReplyToFactoryName</name>
            <value>jms/receiverQueueConnectionFactory</value>
         </stub-property>
         <stub-property>
            <name>javax.xml.rpc.service.endpoint.address</name>
            <value>/bank/soap12bank</value>
         </stub-property>
    </service-ref-mapping>

### Enabling Chunked Data Transfer for HTTP 1.1

OracleAS Web Services permits the chunked transfer encoding of messages when the protocol is HTTP 1.1. Chunked data transfer can be invoked on J2SE stub, J2EE stub and DII Web service clients.

Chunking can increase performance by breaking the payload into smaller pieces. These pieces can be sent over the wire faster than one large payload. Chunked transfer encoding includes all of the information that the recipient needs to verify that it has received the entire message. Chunked transfer encoding happens at the transport level; it is not detected or handled by the invoker of a Web services call or the server.

The following properties in the `oracle.webservices.ClientConstants` class can be set on the `Stub` or `Call` object to enable chunking and set the chunk size.

- `DO_NOT_CHUNK`—if this property is not set, or set to `true`, then chunking is turned off by default. If this property is set to `false`, then chunking is enabled.

- `CHUNK_SIZE`—sets the chunk size in bytes. If this property is not set, then the default chunk size is 4096 bytes.

Example 13-8 illustrates setting the chunking and chunk size property in client proxy stub code.

Example 13-8 Stub Code to Set Data Chunk Size

    import oracle.webservices.ClientConstants
    ...
    ((OracleStub)port)._setProperty(ClientConstants.DO_NOT_CHUNK (true));
    ((OracleStub)port)._setProperty(ClientConstants.CHUNK_SIZE (1024));
    ...

Example 13-9 illustrates using the `DO_NOT_CHUNK` and `CHUNK_SIZE` properties in DII client code to set the chunk size to 1024 bytes.

Example 13-9 DII Client Code to Set Data Chunk Size

    import oracle.webservices.ClientConstants
    ...
    ServiceFactory factory = ServiceFactory.newInstance();
    Service service = factory.createService(new QName("http://whitemesa.net/wsdl/rpc-lit-test", "tns" ) );
    QName stringType = new QName( "http://www.w3.org/2001/XMLSchema", "string");
    Call call = service.createCall();
    ...
    call.setProperty(ClientConstants.DO_NOT_CHUNK (false));
    call.setProperty(ClientConstants.CHUNK_SIZE (1024));
    ...

### Setting a Character Encoding for a SOAP Message

By default, a J2EE client (either static stub or DII) assembled under OracleAS Web Services sends a request message with a SOAP envelope encoded with UTF-8 characters. To override this behavior, you can set the following Oracle proprietary property:

    oracle.webservices.ClientConstants.CHARACTER_SET_ENCODING

You can apply this property to the `javax.xml.rpc.Stub` or `javax.xml.rpc.Call` object with the `setProperty` method.

The value of the `CHARACTER_SET_ENCODING` property can be of type `java.lang.String` or `java.nio.charset.Charset`. The set of supported character encodings depends on the underlying Java Virtual Machine (JVM). Use the `Charset.availableCharsets` method to return the list of character encodings that are supported by your JVM. for more information on the `Charset.availableCharsets` method, see the output of the Javadoc tool for the `java.nio.charset.Charset` class.

This property can also be used for J2SE Web service clients.

Example 13-10 illustrates Stub client code that sets `Shift_JIS` as the character encoding that will be used by the SOAP envelope.

Example 13-10 Setting Shift_JIS Characters for a SOAP Envelope on a Stub Client

    include oracle.webservices.ClientConstants
    ...
    ((OracleStub)port)._setProperty(ClientConstants.CHARACTER_SET_ENCODING, "Shift_JIS");
    ...

Example 13-11 illustrates DII client code that sets `Shift_JIS` as the character encoding that will be used by the SOAP envelope.

Example 13-11 Setting Shift_JIS Characters for a SOAP Envelope on a DII Client

    include oracle.webservices.ClientConstants
    ...
    ServiceFactory factory = ServiceFactory.newInstance();
    Service service = factory.createService(new URL("path to wsdl"),
    new QName("service namespace", "service name" ) );
    Call call = service.createCall();
    call.setProperty(ClientConstants.CHARACTER_SET_ENCODING, Charset.forName("Shift_JIS"));
    ...

## Packaging a J2EE Client

JDeveloper creates a standard packaging for Web application and EJB client files. This section describes that packaging structure in case you need to customize the contents of the client EAR file.

- Packaging a Servlet or Web Application Client

- Packaging an EJB Client

### Packaging a Servlet or Web Application Client

This section describes the packaging of servlet or Web application clients. The values for a number of elements in the deployment descriptors reflect the names of the files and their storage position in the EAR file. If you change the content of the EAR file, you might need to change the content of the deployment descriptors.

- Packaging Structure for Servlet or Web Application Clients

- Relationship Between Deployment Descriptors and Servlet or Web Application Client EAR Files

#### Packaging Structure for Servlet or Web Application Clients

Servlet or Web application clients are packaged in an EAR file with the name <`ear_file_name`>`.ear`. At the top level, the EAR file contains a `META-INF` directory for the manifest file and the `application.xml` file and <`war_file_name`>`.war` file for the servlet or Web application files, the JAX-RPC mapping file, the WSDL file, and the deployment descriptors. Example 13-12 illustrates the standard package structure of the EAR file.

Example 13-12 Structure of a Servlet or Web Application Client EAR File

    ./META-INF
        ./MANIFEST.MF
        ./application.xml
    ./<war file>.war
        ./WEB-INF/
                /orion-web.xml
                /web.xml
                /wsdl/<wsdl file name>.wsdl
                /<mapping file>.xml
                /classes
                     /class files
                /lib
                     /.jar files
        ./*.jsp or html files

#### Relationship Between Deployment Descriptors and Servlet or Web Application Client EAR Files

This section identifies the relationships between the J2EE standard deployment descriptor `web.xml`, the OC4J deployment descriptor for servlets or Web applications `orion-web.xml`, and the packaging structure of the client EAR file. These relationships are important because if you edit the structure or contents of the client EAR file, you might have to edit the content of the deployment descriptors.

The client information is contained in the `<service-ref>` element in `web.xml`. This element contains information about the Web service that can be looked up and consumed from inside a servlet or JSP. For example, it contains the locations for the WSDL (`<wsdl-file>`), the JAX-RPC mapping file (`<jaxrpc-mapping-file>`), the service interface used for JNDI lookup (`<service-ref-name>`), the service interface class (`<service-interface>`), and the service endpoint interface (`<service-endpoint-interface>`). Note that the `<service-ref-name>` in `web.xml` also appears as an attribute in the `<service-ref-mapping>` element in `orion-web.xml`. If you change the names and locations of any of these items in the EAR, then you must make the corresponding changes in the deployment descriptors.

See "Adding J2EE Web Service Client Information to Deployment Descriptors" for more information on the `<service-ref>` and `<service-ref-mapping>` elements and their subelements.

Example 13-13 lists the contents of `web.xml` for a servlet or Web application client. The `<service-ref>` element is highlighted in bold.

Example 13-13 web.xml Contents for a Servlet or Web Application Client

    <web-app>
      <servlet>
        <servlet-name>consumer</servlet-name>
        <servlet-class>oracle.ServiceConsumerServlet</servlet-class>
      </servlet>
      <servlet-mapping>
        <servlet-name>consumer</servlet-name>
        <url-pattern>/consumer</url-pattern>
      </servlet-mapping>
      <service-ref>
        <service-ref-name>service/MyHelloServiceRef</service-ref-name>
        <service-interface>javax.xml.rpc.Service</service-interface>
        <wsdl-file>WEB-INF/wsdl/HelloService.wsdl</wsdl-file>
     <jaxrpc-mapping-file>WEB-INF/HelloService-java-wsdl-mapping.xml</jaxrpc-mapping-file>
        <service-qname
    xmlns:service-qname_ns__="http://hello.demo.oracle/">service-qname_ns__:HelloService</service-qname>
            <port-component-ref>

    <service-endpoint-interface>oracle.demo.hello.HelloInterface</service-endpoint-interface>
            </port-component-ref>
      </service-ref>
    </web-app>

Example 13-14 lists the contents of OC4J proprietary `orion-web.xml` deployment descriptor for Web applications and servlets. The `<service-ref-mapping>` element is highlighted in bold.

Example 13-14 orion-web.xml Contents for a Client-Side Servlet or Web Application

    <orion-web-app
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/orion-web-10_0.xsd">
            <service-ref-mapping name="service/MyHelloServiceRef">
                            <!-- stub proprty applicable across all ports -->
                            <stub-property>

    <name>javax.xml.rpc.service.endpoint.address</name>

    <value>http://localhost:8888/hello/HelloService</value>
                            </stub-property>
            </service-ref-mapping>
    </orion-web-app>

### Packaging an EJB Client

This section describes the packaging of EJB clients. The values for a number of elements in the deployment descriptors reflect the names of the files and their storage position in the EAR file. If you change the content of the EAR file, you might need to change the content of the deployment descriptors.

- Package Structure for EJB Application Clients

- Relationship Between Deployment Descriptors for EJB Application Clients

#### Package Structure for EJB Application Clients

EJB clients are packaged in an EAR file with the name <`ear_file_name`>`.ear`. At the top level, the EAR file contains a `META-INF` directory for the manifest file and the `application.xml` file, the EJB class files, and <`ejb_jar_file_name`>`.jar` file. The JAR file contains the JAR manifest file, the JAX-RPC mapping file, the WSDL file, and the deployment descriptors. Example 13-15 illustrates the packaging structure of an EJB client EAR file.

Example 13-15 Package Structure for a Client-Side EJB Application EAR File

    ./META-INF
         ./MANIFEST.MF
         ./application.xml
    ./<ejb jar file name>.jar
         ./class files
         ./META-INF/
              /MANIFEST.MF
              /ejb-jar.xml
              /orion-ejb-jar.xml
              /wsdl/<wsdl file name>.wsdl
              /<mapping file>.xml

#### Relationship Between Deployment Descriptors for EJB Application Clients

This section identifies the relationships between the J2EE standard deployment descriptor `ejb-jar.xml`, the OC4J deployment descriptor for servlets or Web applications `orion-ejb-jar.xml`, and the packaging structure of the EJB client EAR file. These relationships are important because if you edit the structure or contents of the client EAR file, you might have to edit the content of the deployment descriptors.

The client information is contained in the `<service-ref>` element in `ejb-jar.xml`. This element contains information about the servlet or Web application that can be used as a Web service client. For example, it contains the locations for the WSDL (`<wsdl-file>`), the JAX-RPC mapping file (`<jaxrpc-mapping-file>`), the service interface used for JNDI lookup (`<service-ref-name>`), the service interface class (`<service-interface>`), and the service endpoint interface (`<service-endpoint-interface>`). Note that the `<service-ref-name>` in `ejb-jar.xml` also appears as an attribute in the `<service-ref-mapping>` element in `orion-ejb-jar.xml`. If you change the names and locations of any of these items in the EAR, then you must make the corresponding changes in the deployment descriptors.

See "Adding J2EE Web Service Client Information to Deployment Descriptors" for more information on the `<service-ref>` and `<service-ref-mapping>` elements and their subelements.

Example 13-16 lists the contents of `ejb-jar.xml` for an EJB client. The `<service-ref>` element is highlighted in bold.

Example 13-16 ejb-jar.xml Contents for a Client-Side EJB Application

    <ejb-jar>
      <display-name>serviceConsumerEJB</display-name>
      <enterprise-beans>
        <session>
            <ejb-name>ServiceConsumer</ejb-name>
            <home>oracle.ServiceConsumerHome</home>
            <remote>oracle.ServiceConsumerRemote</remote>
            <ejb-class>oracle.ServiceConsumerBean</ejb-class>
            <session-type>Stateless</session-type>
            <transaction-type>Container</transaction-type>
            <service-ref>
                    <service-ref-name>service/MyHelloService</service-ref-name>
                    <service-interface>javax.xml.rpc.Service</service-interface>
                    <wsdl-file>META-INF/wsdl/HelloService.wsdl</wsdl-file>

    <jaxrpc-mapping-file>META-INF/HelloService-java-wsdl-mapping.xml</jaxrpc-mapping-file>
                    <service-qnamexmlns:ns="http://hello.demo.oracle/">ns:HelloService</service-qname>
                    <port-component-ref>

    <service-endpoint-interface>oracle.demo.hello.HelloInterface</service-endpoint-interface>
                    </port-component-ref>
            </service-ref>
        </session>
      </enterprise-beans>
    </ejb-jar>

Example 13-17 lists the contents of OC4J proprietary `orion-ejb-jar.xml` deployment descriptor for Web applications and servlets. The `<service-ref-mapping>` element is highlighted in bold.

Example 13-17 orion-ejb-jar.xml Contents for a Client-Side EJB Application

    <orion-ejb-jar>
        <enterprise-beans>
            <session-deployment name="ServiceConsumer">
                <service-ref-mapping name="service/MyHelloService">
                    <stub-property>
                        <name>javax.xml.rpc.service.endpoint.address</name>
                        <value>http://localhost:8888/hello/HelloService</value>
                    </stub-property>
                </service-ref-mapping>
            </session-deployment>
        </enterprise-beans>
    </orion-ejb-jar>

## Limitations

See "Assembling a J2EE Web Service Client".

## Additional Information

For more information on:

- assembling Web services from a WSDL, see Chapter 5, "Assembling a Web Service from a WSDL".

- assembling stateful Web services, see Chapter 6, "Assembling a Web Service with Java Classes".

- assembling Web services from EJBs, see Chapter 7, "Assembling a Web Service with EJBs".

- assembling Web services from a JMS queue or topic, see Chapter 8, "Assembling Web Services with JMS Destinations".

- assembling Web services from database resources, see Chapter 9, "Developing Database Web Services".

- assembling Web services with J2SE 5.0 Annotations, see Chapter 10, "Assembling Web Services with Annotations".

- building J2SE clients, see Chapter 14, "Assembling a J2SE Web Service Client".

- using the WebServicesAssembler tool to assemble Web services, see Chapter 17, "Using WebServicesAssembler".

- packaging and deploying Web services, see Chapter 18, "Packaging and Deploying Web Services"

- jar files that are needed to assemble a client, see Appendix A, "Web Service Client APIs and JARs".

- Web services interoperability, see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.

- using quality of service features in Web service clients, see "Managing Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.

- adding security to a Web service, see the Oracle Application Server Web Services Security Guide.

- how to write clients to access Web services secured on the transport level, see "Adding Transport-level Security for Web Services Based on EJBs" and "Accessing Web Services Secured on the Transport Level" in the Oracle Application Server Web Services Security Guide.

- adding reliability to a Web service, see "Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide.

- adding an auditing and logging configuration to a Web service, see "Auditing and Logging Messages" in the Oracle Application Server Advanced Web Services Developer's Guide.

- processing nonstandard data types, see "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide.

- the JAX-RPC mapping file, see "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide.

- data types supported by OracleAS Web Services, see "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide.

- JDeveloper tool support for Web service development, see the JDeveloper on-line help.