Oracle® Fusion Middleware

Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server

11g Release 1 (10.3.6)

E13735-06

March 2013

Documentation for software developers that describes how to program advanced features for WebLogic JAX-RPC Web services.

Oracle Fusion Middleware Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server, 11g Release 1 (10.3.6)

E13735-06

Copyright © 2007, 2013, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Contents

Preface

- Documentation Accessibility

- Conventions

1 Introduction

2 Invoking a Web Service Using Asynchronous Request-Response

- Overview of the Asynchronous Request-Response Feature

- Using Asynchronous Request-Response: Main Steps

- Configuring the Host WebLogic Server Instance for the Asynchronous Web Service

- Writing the Asynchronous JWS File

- Coding Guidelines for Invoking a Web Service Asynchronously

- Using Asynchronous Pre- and Post-call Contexts

- Example of a Synchronous Invoke

- Updating the build.xml File When Using Asynchronous Request-Response

- Disabling The Internal Asynchronous Service

- Using Asynchronous Request Response With a Proxy Server

3 Using Web Services Reliable Messaging

- Overview of Web Service Reliable Messaging

- Using WS-Policy to Specify Reliable Messaging Policy Assertions

- Managing the Life Cycle of the Reliable Message Sequence

- Using Web Service Reliable Messaging: Main Steps

- Prerequisites

- Configuring the Destination WebLogic Server Instance

- Configuring the Source WebLogic Server Instance

- Creating the Web Service Reliable Messaging WS-Policy File

- Creating a Custom WS-Policy File Using WS-ReliableMessaging Policy Assertions Version 1.1

- Creating a Custom WS-Policy File Using WS-ReliableMessaging Policy Assertions Version 1.0 (Deprecated)

- Using Multiple Policy Alternatives

- Programming Guidelines for the Reliable JWS File

- Using the @Policy Annotation

- Using the @Oneway Annotation

- Using the @BufferQueue Annotation

- Using the @ReliabilityBuffer Annotation

- Configuring Reliable Messaging for a Reliable Web Service

- Using the Administration Console

- Using WLST

- Programming Guidelines for the JWS File That Invokes a Reliable Web Service

- Updating the build.xml File for a Client of a Reliable Web Service

- Using Reliable Messaging With MTOM

- Client Considerations When Redeploying a Reliable Web Service

- Using Reliable Messaging With a Proxy Server

4 Creating Conversational Web Services

- Overview of Conversational Web Services

- Creating a Conversational Web Service: Main Steps

- Programming Guidelines for the Conversational JWS File

- Programming Guidelines for the JWS File That Invokes a Conversational Web Service

- ConversationUtils Utility Class

- Updating the build.xml File for a Client of a Conversational Web Service

- Updating a Stand-Alone Java Client to Invoke a Conversational Web Service

- Example Conversational Web Service .NET Client

- ConversationService.java File

- Service.cs File

- build.xml File

- Client Considerations When Redeploying a Conversational Web Service

5 Creating Buffered Web Services

- Overview of Buffered Web Services

- Creating a Buffered Web Service: Main Steps

- Configuring the Host WebLogic Server Instance for the Buffered Web Service

- Programming Guidelines for the Buffered JWS File

- Programming the JWS File That Invokes the Buffered Web Service

- Updating the build.xml File for a Client of the Buffered Web Service

6 Using the Asynchronous Features Together

- Using the Asynchronous Features Together

- Example of a JWS File That Implements a Reliable Conversational Web Service

- Example of Client Web Service That Asynchronously Invokes a Reliable Conversational Web Service

7 Using Callbacks to Notify Clients of Events

- Overview of Callbacks

- Callback Implementation Overview and Terminology

- Programming Callbacks: Main Steps

- Programming Guidelines for Target Web Service

- Programming Guidelines for the Callback Client Web Service

- Programming Guidelines for the Callback Interface

- Updating the build.xml File for the Client Web Service

8 Using JMS Transport as the Connection Protocol

- Overview of Using JMS Transport

- Using JMS Transport Starting From Java: Main Steps

- Using JMS Transport Starting From WSDL: Main Steps

- Configuring the Host WebLogic Server Instance for the JMS Transport Web Service

- Using the @WLJmsTransport JWS Annotation

- Using the <WLJmsTransport> Child Element of the jwsc Ant Task

- Updating the WSDL to Use JMS Transport

- Invoking a WebLogic Web Service Using JMS Transport

- Overriding the Default Service Address URL

- Using JMS BytesMessage Rather Than the Default TextMessage

- Disabling HTTP Access to the WSDL File

9 Creating and Using SOAP Message Handlers

- Overview of SOAP Message Handlers

- Adding SOAP Message Handlers to a Web Service: Main Steps

- Designing the SOAP Message Handlers and Handler Chains

- Creating the GenericHandler Class

- Implementing the Handler.init() Method

- Implementing the Handler.destroy() Method

- Implementing the Handler.getHeaders() Method

- Implementing the Handler.handleRequest() Method

- Implementing the Handler.handleResponse() Method

- Implementing the Handler.handleFault() Method

- Directly Manipulating the SOAP Request and Response Message Using SAAJ

- The SOAPPart Object

- The AttachmentPart Object

- Manipulating Image Attachments in a SOAP Message Handler

- Configuring Handlers in the JWS File

- @javax.jws.HandlerChain

- @javax.jws.soap.SOAPMessageHandlers

- Creating the Handler Chain Configuration File

- Compiling and Rebuilding the Web Service

- Creating and Using Client-Side SOAP Message Handlers

- Using Client-Side SOAP Message Handlers: Main Steps

- Example of a Client-Side Handler Class

- Creating the Client-Side SOAP Handler Configuration File

- XML Schema for the Client-Side Handler Configuration File

- Specifying the Client-Side SOAP Handler Configuration File to clientgen

10 Using Database Web Services

- Overview of Database Web Services

- Database Call-in

- Database Call-out

- Type Mapping Between SQL and XML

- SQL to XML Type Mappings for Web Service Call-Ins

- XML-to-SQL Type Mapping for Web Service Call-outs

- Developing Database Web Services Using Oracle JDeveloper

11 Publishing and Finding Web Services Using UDDI

- Overview of UDDI

- UDDI and Web Services

- UDDI and Business Registry

- UDDI Data Structure

- WebLogic Server UDDI Features

- UDDI 2.0 Server

- Configuring the UDDI 2.0 Server

- Configuring an External LDAP Server

- 51acumen.ldif File Contents

- Description of Properties in the uddi.properties File

- UDDI Directory Explorer

- UDDI Client API

- Pluggable tModel

- XML Elements and Permissible Values

- XML Schema for Pluggable tModels

- Sample XML for a Pluggable tModel

A Pre-Packaged WS-Policy Files for Reliable Messaging

- DefaultReliability1.1.xml (WS-Policy File)

- Reliability1.1_SequenceTransportSecurity.xml (WS-Policy File)

- Reliability1.1_SequenceSTR.xml (WS-Policy File)

- Reliability1.0_1.1.xml (WS-Policy.xml File)

- DefaultReliability.xml (WS-Policy File) [Deprecated]

- LongRunningReliability.xml (WS-Policy File) [Deprecated]

Preface

This preface describes the document accessibility features and conventions used in this guide—Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

1 Introduction

This chapter summarizes the advanced WebLogic Java API for XML-based RPC (JAX-RPC) features that are described in this document. This document is a resource for software developers who program advanced features for JAX-RPC.

Table 1-1 Programming Advanced Features Using JAX-RPC

Advanced Feature

Description

Chapter 2, "Invoking a Web Service Using Asynchronous Request-Response"

Invoke a Web service asynchronously.

Chapter 3, "Using Web Services Reliable Messaging"

Create a reliable Web service, as specified by the WS-ReliableMessaging specification, and then create a client Web services that invokes the reliable Web service.

Chapter 4, "Creating Conversational Web Services"

Create a conversational Web service which communicates with a client.

Chapter 6, "Using the Asynchronous Features Together"

Use the asynchronous features, such as reliable messaging, asynchronous request-response, and conversations, together in a single Web service.

Chapter 7, "Using Callbacks to Notify Clients of Events"

Notify a client of a Web service that an event has happened by programming a callback.

Chapter 5, "Creating Buffered Web Services"

Create a buffered Web service, which is a simpler type of reliable Web service that one specified by the WS-ReliableMessaging specification.

Chapter 8, "Using JMS Transport as the Connection Protocol"

Specify that JMS, rather than the default HTTP/S, is the connection protocol when invoking a Web service.

Chapter 9, "Creating and Using SOAP Message Handlers"

Create and configure SOAP message handlers for a Web service.

Chapter 10, "Using Database Web Services"

Create a database Web service using JDeveloper.

Chapter 11, "Publishing and Finding Web Services Using UDDI"

Use the UDDI features of WebLogic Web service.

For an overview of WebLogic Web services, standards, samples, and related documentation, see Introducing WebLogic Web Services for Oracle WebLogic Server.

For information about WebLogic Web service security, see Securing WebLogic Web Services for Oracle WebLogic Server.

2 Invoking a Web Service Using Asynchronous Request-Response

This chapter describes how to invoke a WebLogic Java API for XML-based RPC (JAX-RPC) Web service using asynchronous request-response.

This chapter includes the following topics:

- Overview of the Asynchronous Request-Response Feature

- Using Asynchronous Request-Response: Main Steps

- Configuring the Host WebLogic Server Instance for the Asynchronous Web Service

- Writing the Asynchronous JWS File

- Updating the build.xml File When Using Asynchronous Request-Response

- Disabling The Internal Asynchronous Service

- Using Asynchronous Request Response With a Proxy Server

Overview of the Asynchronous Request-Response Feature

When you invoke a Web service synchronously, the invoking client application waits for the response to return before it can continue with its work. In cases where the response returns immediately, this method of invoking the Web service might be adequate. However, because request processing can be delayed, it is often useful for the client application to continue its work and handle the response later on, or in other words, use the asynchronous request-response feature of WebLogic Web services.

You invoke a Web service asynchronously only from a client running in a WebLogic Web service, never from a stand-alone client application. The invoked Web service does not change in any way, thus you can invoke any deployed Web service (both WebLogic and non-WebLogic) asynchronously as long as the application server that hosts the Web service supports the WS-Addressing specification at http://www.w3.org/Submission/2004/SUBM-ws-addressing-20040810/.

When implementing asynchronous request-response in your client, rather than invoking the operation directly, you invoke an asynchronous flavor of the same operation. (This asynchronous flavor of the operation is automatically generated by the jwsc Ant task.) For example, rather than invoking an operation called getQuote directly, you would invoke getQuoteAsync instead. The asynchronous flavor of the operation always returns void, even if the original operation returns a value. You then include methods in your client that handle the asynchronous response or failures when it returns later on. You put any business logic that processes the return value of the Web service operation invoke or a potential failure in these methods. You use both naming conventions and JWS annotations to specify these methods to the JWS compiler. For example, if the asynchronous operation is called getQuoteAsync, then these methods might be called onGetQuoteAsyncResponse and onGetQuoteAsyncFailure.

Note:

For information about using asynchronous request-response with other asynchronous features, such as Web service reliable messaging or buffering, see Chapter 6, "Using the Asynchronous Features Together." This section describes how to use the asynchronous request-response feature on its own.

The asynchronous request-response feature works only with HTTP; you cannot use it with the HTTPS or JMS transport.

Using Asynchronous Request-Response: Main Steps

The following procedure describes how to create a client Web service that asynchronously invokes an operation in a different Web service. The procedure shows how to create the JWS file that implements the client Web service from scratch; if you want to update an existing JWS file, use this procedure as a guide.

For clarity, it is assumed in the procedure that:

- The client Web service is called StockQuoteClientService.

- The StockQuoteClientService service is going to invoke the getQuote(String) operation of the already-deployed StockQuoteService service whose WSDL is found at the following URL:

http://localhost:7001/async/StockQuote?WSDL

It is further assumed that you have set up an Ant-based development environment and that you have a working build.xml file to which you can add targets for running the jwsc Ant task and deploying the generated service. For more information, see the following sections in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server:

- "Use Cases and Examples"

- "Developing WebLogic Web Services"

- "Programming the JWS File"

- "Invoking Web Services"

Table 2-1 Steps to Use Asynchronous Request-Response

#

Step

Description

1

Configure the WebLogic Server instances.

Configure the asynchronous response service, as described in Configuring the Host WebLogic Server Instance for the Asynchronous Web Service.

2

Create a new JWS file, or update an existing one, that implements the StockQuoteClientService Web service.

Use your favorite IDE or text editor. See Writing the Asynchronous JWS File.

3

Update your build.xml file to compile the JWS file that implements the StockQuoteClientService.

You will add a <clientgen> child element to the jwsc Ant task so as to automatically generate the asynchronous flavor of the Web service operations you are invoking.

See Updating the build.xml File When Using Asynchronous Request-Response.

4

Run the Ant target to build the StockQuoteClientService.

For example:

prompt> ant build-clientService

5

Deploy the StockQuoteClientService Web service as usual.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

When you invoke the StockQuoteClientService Web service, which in turn invokes the StockQuoteService Web service, the second invoke will be asynchronous rather than synchronous.

Configuring the Host WebLogic Server Instance for the Asynchronous Web Service

Configuring the WebLogic Server instance on which the asynchronous Web service is deployed involves configuring JMS resources, such as JMS servers and modules, that are used internally by the Web services runtime.

You can configure these resources manually or you can use the Configuration Wizard to extend the WebLogic Server domain using a Web services-specific extension template. Using the Configuration Wizard greatly simplifies the required configuration steps; for details, see "Configuring Your Domain For Web Services Features" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Notes:

Alternatively, you can use WLST to configure the resources. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.

A domain that does not contain Web Services resources will still boot and operate correctly for non-Web services scenarios, and any Web Services scenario that does not involve asynchronous request and response. You will, however, see INFO messages in the server log indicating that asynchronous resources have not been configured and that the asynchronous response service for Web services has not been completely deployed.

If you prefer to configure the resources manually, perform the following steps.

Table 2-2 Steps to Configure Host WebLogic Server Instance Manually for the Asynchronous Web Service

#

Step

Description

1

Invoke the Administration Console for the domain that contains the host WebLogic Server instance.

To invoke the Administration Console in your browser, enter the following URL:

http://host:port/console

where

- host refers to the computer on which the Administration Server is running.

- port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.

See "Invoking the Administration Console" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

2

Create a JMS Server.

Create a JMS Server. If a JMS server already exists, you can use it if you do not want to create a new one.

See "Create JMS servers" in Oracle WebLogic Server Administration Console Help.

3

Create JMS module and define queue.

Create a JMS module, and then define a JMS queue in the module. If a JMS module already exists, you can use it if you do not want to create a new one. Target the JMS queue to the JMS server you created in the preceding step. Be sure you specify that this JMS queue is local, typically by setting the local JNDI name. See "Create JMS system modules" and "Create queues in a system module" in Oracle WebLogic Server Administration Console Help.

If you want the asynchronous Web service to use the default Web services queue, set the JNDI name of the JMS queue to weblogic.wsee.DefaultQueue.

Clustering Considerations:

If you are using the Web service asynchronous feature in a cluster, you must:

- Create a local JMS queue, rather than a distributed queue, when creating the JMS queue.

- Explicitly target this JMS queue to each server in the cluster.

4

Create a Work Manager.

Define a Work Manager named weblogic.wsee.mdb.DispatchPolicy, which is used by the asynchronous request-response feature, by default.

See "Create global Work Managers" in Oracle WebLogic Server Administration Console Help.

5

Tune your domain environment, as required. (Optional)

Review "Tuning Heavily Loaded Systems to Improve Web Service Performance" in Performance and Tuning for Oracle WebLogic Server.

Writing the Asynchronous JWS File

The following example shows a simple JWS file that implements a Web service called StockQuoteClient that has a single method, asyncOperation, that in turn asynchronously invokes the getQuote method of the StockQuote service. The Java code in bold is described Coding Guidelines for Invoking a Web Service Asynchronously. See Example of a Synchronous Invoke to see how the asynchronous invoke differs from a synchronous invoke of the same operation.

package examples.webservices.async_req_res;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.AsyncResponse;
import weblogic.jws.AsyncFailure;

import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPostCallContext;

import javax.jws.WebService;
import javax.jws.WebMethod;

import examples.webservices.async_req_res.StockQuotePortType;

import java.rmi.RemoteException;

@WebService(name="StockQuoteClientPortType",
serviceName="StockQuoteClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="asyncClient",
serviceUri="StockQuoteClient",
portName="StockQuoteClientServicePort")

/**
*  Client Web Service that invokes the StockQuote Service asynchronously.
*/

public class StockQuoteClientImpl {

@ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
serviceName="StockQuoteService", portName="StockQuote")

private StockQuotePortType port;

@WebMethod
public void asyncOperation (String symbol, String userName)
throws RemoteException {

AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
apc.setProperty("userName", userName);

try {
port.getQuoteAsync(apc, symbol );
System.out.println("in getQuote method of StockQuoteClient WS");

} catch (RemoteException re) {

System.out.println("RemoteException thrown");
throw new RuntimeException(re);
}

}

@AsyncResponse(target="port", operation="getQuote")
public void onGetQuoteAsyncResponse(AsyncPostCallContext apc, int quote) {
// Get the userName property we set on AsyncPreCallContext
String userName = (String)apc.getProperty("userName");
System.out.println("-------------------");
System.out.println(username + " Got quote " + quote );
System.out.println("-------------------");
}

@AsyncFailure(target="port", operation="getQuote")
public void onGetQuoteAsyncFailure(AsyncPostCallContext apc, Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}

}

Coding Guidelines for Invoking a Web Service Asynchronously

The following guidelines for invoking an operation asynchronously correspond to the Java code shown in bold in the example described in Writing the Asynchronous JWS File. These guidelines are in addition to the standard ones for creating JWS files. See Example of a Synchronous Invoke to see how the asynchronous invoke differs from a synchronous invoke of the same operation.

To invoke an operation asynchronously in your JWS file:

- Import the following WebLogic-specific JWS annotations related to the asynchronous request-response feature:

import weblogic.jws.ServiceClient;
import weblogic.jws.AsyncResponse;
import weblogic.jws.AsyncFailure;

- Import the JAX-RPC stub, created later by the jwsc Ant task, of the port type of the Web service you want to invoke. The stub package is specified by the packageName attribute of the <clientgen> child element of jwsc, and the name of the stub is determined by the WSDL of the invoked Web service.

import examples.webservices.async_req_res.StockQuotePortType;

- Import the asynchronous pre- and post-call context WebLogic APIs:

import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncPostCallContext;

For more information about asynchronous pre- and post-call context, see Using Asynchronous Pre- and Post-call Contexts. See the "weblogic.wsee.async" package in Oracle WebLogic Server API Reference for additional reference information about these APIs.

- In the body of the JWS file, use the required @ServiceClient JWS annotation to specify the WSDL, name, and port of the Web service you will be invoking asynchronously. You specify this annotation at the field-level on a variable, whose data type is the JAX-RPC port type of the Web service you are invoking.

@ServiceClient(
wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
serviceName="StockQuoteService",
portName="StockQuote")

private StockQuotePortType port;

When you annotate a variable (in this case, port) with the @ServiceClient annotation, the Web services runtime automatically initializes and instantiates the variable, preparing it so that it can be used to invoke another Web service asynchronously.

- In the method of the JWS file which is going to invoke the getQuote operation asynchronously, get a pre-call asynchronous context using the context factory:

AsyncPreCallContext apc =
AsyncCallContextFactory.getAsyncPreCallContext();

For more information about asynchronous pre- and post-call context, see Using Asynchronous Pre- and Post-call Contexts.

- Use the setProperty method of the pre-call context to create a property to store the username:

apc.setProperty("userName", userName);

- Using the stub you annotated with the @ServiceClient annotation, invoke the operation (in this case, getQuote). Instead of invoking it directly, however, invoke the asynchronous flavor of the operation, which has Async added on to the end of its name. The asynchronous flavor always returns void. Pass the asynchronous context as the first parameter:

port.getQuoteAsync(apc, symbol);

- For each operation you will be invoking asynchronously, create a method called onOperationnameAsyncResponse, where Operationname refers to the name of the operation, with initial letter always capitalized. The method must return void, and have two parameters: the post-call asynchronous context and the return value of the operation you are invoking. Annotate the method with the @AsyncResponse JWS annotation; use the target attribute to specify the variable whose datatype is the JAX-RPC stub and the operation attribute to specify the name of the operation you are invoking asynchronously. Inside the body of the method, put the business logic that processes the value returned by the operation. Use the getProperty method of the post-call context to get the property that was set by pre-call context before invoking the asynchronous method:

@AsyncResponse(target="port", operation="getQuote")
public void onGetQuoteAsyncResponse(AsyncPostCallContext apc,
int quote) {
// Get the userName property we set on AsyncPreCallContext
String userName = (String)apc.getProperty("userName");
System.out.println("-------------------");
System.out.println("Got quote " + quote );
System.out.println("-------------------");
}

For more information about asynchronous pre- and post-call context, see Using Asynchronous Pre- and Post-call Contexts.

- For each operation you will be invoking asynchronously, create a method called onOperationnameAsyncFailure, where Operationname refers to the name of the operation, with initial letter capitalized. The method must return void, and have two parameters: the post-call asynchronous context and a Throwable object, the superclass of all exceptions to handle any type of exception thrown by the invoked operation. Annotate the method with the @AsyncFailure JWS annotation; use the target attribute to specify the variable whose datatype is the JAX-RPC stub and the operation attribute to specify the name of the operation you are invoking asynchronously. Inside the method, you can determine the exact nature of the exception and write appropriate Java code.

@AsyncFailure(target="port", operation="getQuote")
public void onGetQuoteAsyncFailure(AsyncPostCallContext apc,
Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}

Note:

You are not required to use the @AsyncResponse and @AsyncFailure annotations, although it is a good practice because it clears up any ambiguity and makes your JWS file clean and understandable. However, in the rare use case where you want one of the onXXX methods to handle the asynchronous response or failure from two (or more) stubs that are invoking operations from two different Web services that have the same name, then you should explicitly NOT use these annotations. Be sure that the name of the onXXX methods follow the correct naming conventions exactly, as described above.

Using Asynchronous Pre- and Post-call Contexts

The AsyncPreCallContext and AsyncPostCallContext APIs describe asynchronous contexts that you can use in your Web service for a variety of reasons. For example:

- Set a property in the pre-context so that the method that handles the asynchronous response can distinguish between different asynchronous calls.

- Get and set contextual variables, such as the name of the user invoking the operation, their password, and so on.

- Get the name of the JAX-RPC stub that invoked a method asynchronously; and to set a time-out interval on the context.

To use asynchronous pre- and post-call contexts:

1. Import the asynchronous pre- and post-call context WebLogic APIs:

import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncPostCallContext;

2. In the method of the JWS file that is going to invoke the asynchronous operation, get a pre-call asynchronous context using the context factory. For example:

AsyncPreCallContext apc =
AsyncCallContextFactory.getAsyncPreCallContext();

3. Use the pre-call context methods to operate on the asynchronous context before the asynchronous method is called. The following example uses the setProperty method of the pre-call context to create a property that stores the username:

apc.setProperty("userName", userName);

4. Use the post-call context methods to operate on the asynchronous context after the asynchronous method is called. The following example uses the getProperty method of the post-call context to get the property that was set by pre-call context before invoking the asynchronous method:

String userName = (String)apc.getProperty("userName");

Example of a Synchronous Invoke

The following example shows a JWS file that invokes the getQuote operation of the StockQuote Web service synchronously. The example is shown only so you can compare it with the corresponding asynchronous invoke shown in Writing the Asynchronous JWS File.

package examples.webservices.async_req_res;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;

import javax.jws.WebService;
import javax.jws.WebMethod;

import java.rmi.RemoteException;

@WebService(name="SyncClientPortType",
serviceName="SyncClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="syncClient",
serviceUri="SyncClient",
portName="SyncClientPort")

/**
*  Normal service-to-service client that invokes StockQuote service
*  synchronously.
*/

public class SyncClientImpl {

@ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
serviceName="StockQuoteService", portName="StockQuote")
private StockQuotePortType port;

@WebMethod
public void nonAsyncOperation(String symbol) throws RemoteException {

int quote = port.getQuote(symbol);

System.out.println("-------------------");
System.out.println("Got quote " + quote );
System.out.println("-------------------");

}

}

Updating the build.xml File When Using Asynchronous Request-Response

To update a build.xml file to generate the JWS file that invokes a Web service operation asynchronously, add taskdefs and a build-clientService target that looks something like the following; see the description after the example for details:

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

<jwsc
enableAsyncService="true"
srcdir="src"
destdir="${clientService-ear-dir}" >

<jws file="examples/webservices/async_req_res/StockQuoteClientImpl.java" >

<clientgen
wsdl="http://${wls.hostname}:${wls.port}/async/StockQuote?WSDL"
packageName="examples.webservices.async_req_res"/>

</jws>

</jwsc>

</target>

Use the taskdef Ant task to define the full classname of the jwsc Ant tasks.

Update the jwsc Ant task that compiles the client Web service to include a <clientgen> child element of the <jws> element so as to generate and compile the JAX-RPC stubs for the deployed StockQuote Web service. The jwsc Ant task automatically packages them in the generated WAR file so that the client Web service can immediately access the stubs. By default, the jwsc Ant task in this case generates both synchronous and asynchronous flavors of the Web service operations in the JAX-RPC stubs. You do this because the StockQuoteClientImpl JWS file imports and uses one of the generated classes.

Disabling The Internal Asynchronous Service

By default, every WebLogic Server instance deploys an internal asynchronous Web service that handles the asynchronous request-response feature. To specify that you do not want to deploy this internal service, start the WebLogic Server instance using the -Dweblogic.wsee.skip.async.response=true Java system property.

One reason for disabling the asynchronous service is if you use a WebLogic Server instance as a Web proxy to a WebLogic cluster. In this case, asynchronous messages will never get to the cluster, as required, because the asynchronous service on the proxy server consumes them instead. For this reason, you must disable the asynchronous service on the proxy server using the system property.

For details on specifying Java system properties to configure WebLogic Server, see "Specifying Java Options for a WebLogic Server Instance" in Managing Server Startup and Shutdown for Oracle WebLogic Server.

Using Asynchronous Request Response With a Proxy Server

Client applications that use the asynchronous request-response feature might not invoke the operation directly, but rather, use a proxy server. Reasons for using a proxy include the presence of a firewall or the deployment of the invoked Web service to a cluster.

In this case, the WebLogic Server instance that hosts the invoked Web service must be configured with the address and port of the proxy server. If your Web service is deployed to a cluster, you must configure every server in the cluster.

This procedure describes how to create a network channel, the primary configurable WebLogic Server resource for managing network connection. Network channels enable you to provide a consistent way to access the front-end address of a cluster. For more information about network channels, see "Understanding Network Channels" in Configuring Server Environments for Oracle WebLogic Server.

For each server instance:

1. Create a network channel for the protocol you use to invoke the Web service. You must name the network channel weblogic-wsee-proxy-channel-XXX, where XXX refers to the protocol. For example, to create a network channel for HTTPS, call it weblogic-wsee-proxy-channel-https.
See "Configure custom network channels" in Oracle WebLogic Server Administration Console Help for general information about creating a network channel.

2. Configure the network channel, updating the External Listen Address and External Listen Port fields with the address and port of the proxy server, respectively.

3 Using Web Services Reliable Messaging

This chapter describes Web services reliable messaging for WebLogic Java API for XML-based RPC (JAX-RPC) Web services.

This chapter includes the following topics:

- Overview of Web Service Reliable Messaging

- Using Web Service Reliable Messaging: Main Steps

- Configuring the Destination WebLogic Server Instance

- Configuring the Source WebLogic Server Instance

- Creating the Web Service Reliable Messaging WS-Policy File

- Programming Guidelines for the Reliable JWS File

- Configuring Reliable Messaging for a Reliable Web Service

- Programming Guidelines for the JWS File That Invokes a Reliable Web Service

- Updating the build.xml File for a Client of a Reliable Web Service

- Using Reliable Messaging With MTOM

- Client Considerations When Redeploying a Reliable Web Service

- Using Reliable Messaging With a Proxy Server

Note:

Web service reliable messaging requires the use of asynchronous request-response feature of WebLogic Web services. Before proceeding, you should familiarize yourself with the concepts described in Chapter 2, "Invoking a Web Service Using Asynchronous Request-Response."

Overview of Web Service Reliable Messaging

Web service reliable messaging is a framework that enables an application running on one application server to reliably invoke a Web service running on another application server, assuming that both servers implement the WS-ReliableMessaging specification. Reliable is defined as the ability to guarantee message delivery between the two Web Services in the presence of software component, system, or network failures.

Note:

Web services reliable messaging works between any two application servers that implement the WS-ReliableMessaging specification at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf. In this document, however, it is assumed that the two application servers are WebLogic Server instances.

Web services reliable messaging is not supported with the JMS transport feature.

WebLogic Web services conform to the WS-ReliableMessaging specification (June 2007) at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf, which describes how two Web services running on different application servers can communicate reliably. In particular, the specification describes an interoperable protocol in which a message sent from a source endpoint (or client Web service) to a destination endpoint (or Web service whose operations can be invoked reliably) is guaranteed either to be delivered, according to one or more delivery assurances, or to raise an error.

A reliable WebLogic Web service provides the following delivery assurances.

Table 3-1 Delivery Assurances for Reliable Messaging

Delivery Assurance

Description

At Most Once

Messages are delivered at most once, without duplication. It is possible that some messages may not be delivered at all.

At Least Once

Every message is delivered at least once. It is possible that some messages are delivered more than once.

Exactly Once

Every message is delivered exactly once, without duplication.

In Order

Messages are delivered in the order that they were sent. This delivery assurance can be combined with one of the preceding three assurances.

Note:

Web services reliable messaging requires the use of asynchronous messages. Clients cannot invoke a reliable service synchronously. When invoking a reliable stub method, you must use the async signature—for example, xyzAsync() instead of xyz(). For clients that create SOAP messages directly, the request message is created with non-anonymous ReplyTo address.

You cannot set ReplyTo to the anonymous URI. Any attempt to invoke an operation on a JAX-RPC-based reliable service (either by invoking the sync stub signature or sending a request with anonymous ReplyTo) will result in a runtime exception.

This document describes how to create the reliable and client Web services and how to configure the two WebLogic Server instances to which the Web services are deployed. See the WS-ReliableMessaging specification for detailed documentation about the architecture of Web service reliable messaging (see http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf).

Using WS-Policy to Specify Reliable Messaging Policy Assertions

WebLogic Web services use WS-Policy files to enable a destination endpoint to describe and advertise its Web service reliable messaging capabilities and requirements. The WS-Policy files are XML files that describe features such as the version of the supported WS-ReliableMessaging specification and quality of service requirements. The WS-Policy specification (http://www.w3.org/TR/ws-policy/) provides a general purpose model and syntax to describe and communicate the policies of a Web service.

WebLogic Server includes pre-packaged WS-Policy files that contain typical reliable messaging assertions, as described in Appendix A, "Pre-Packaged WS-Policy Files for Reliable Messaging." If the pre-packaged WS-Policy files do not suit your needs, you must create your own WS-Policy file. See Creating the Web Service Reliable Messaging WS-Policy File for details. See "Web Service Reliable Messaging Policy Assertion Reference" in the WebLogic Web Services Reference for Oracle WebLogic Server for reference information about the reliable messaging policy assertions.

Managing the Life Cycle of the Reliable Message Sequence

The following figure shows a one-way reliable message exchange.

Figure 3-1 Web Service Reliable Message Exchange

A reliable message sequence is used to track the progress of a set of messages that are exchanged reliably between an RM source and RM destination. A sequence can be used to send zero or more messages, and is identified by a string identifier. This identifier is used to reference the sequence when using reliable messaging.

The Web service client application sends a message for reliable delivery which is transmitted by the RM source to the RM destination. The RM destination acknowledges that the reliable message has been received and delivers it to the Web service application. The message may be retransmitted by the RM source until the acknowledgement is received.

A Web service client sends messages to a target Web service by invoking methods on a JAX-RPC stub. The stub is associated with the port type of the reliable Web service and represents a programmatic interface to that service. WebLogic stores the identifier for the reliable message sequence within this stub. This causes the reliable message sequence to be connected to a single JAX-RPC stub. All messages that are sent using a given stub will use the same reliable messaging sequence, regardless of the number of messages that are sent using the stub. The JAX-RPC stub is created by the <clientgen> child element of the "jwsc" Ant task.

Because WebLogic Server retains resources associated with the reliable sequence, it is recommended that you take steps to release these resources in a timely fashion. WebLogic Server provides a utility class, weblogic.wsee.reliability.WsrmUtils, for use with the Web service reliable messaging. Use this class to perform common tasks such as set configuration options, get the sequence id, and terminate a reliable sequence.

Under normal circumstances, a reliable sequence should be retained until all messages have been sent and acknowledged by the RM destination. To facilitate the timely and proper termination of a sequence, it is recommended that you identify the final message in a reliable message sequence. Doing so indicates you are done sending messages to the RM destination and that WebLogic Server can begin looking for the final acknowledgement before automatically terminating the reliable sequence. Indicate the final message using the weblogic.wsee.reliability.WsrmUtils.setFinalMessage() method, passing the JAX-RPC stub being used to send messages to the RM destination.

When you identify a final message, after all messages up to and including the final message are acknowledged, the reliable message sequence is terminated, and all resources are released. Otherwise, the sequence is terminated automatically after the configured sequence expiration period is reached.

Although not recommended, you can terminate the sequence reliable message sequence regardless of whether all messages have been acknowledged using the terminateSequence() method. Once issued, no further reliable messages can be sent on this stub.

Note:

The JAX-RPC stub is not fully initialized until shortly after the first method is invoked on the reliable Web service. When the first method is invoked, the RM source sends a CreateSequence message to the RM destination requesting that the RM destination create and register the reliable sequence. The RM destination, at some later time, responds with the ID for the newly created sequence. Until this response ID is received, the RM source cannot have any further communication with the RM destination and the JAX-RPC stub representing the target service at the RM destination cannot be used.

You cannot perform operations on the reliable message sequence until it is fully initialized; otherwise an error is returned. Use the weblogic.wsee.reliability.WsrmUtils.waitForSequenceInitialization() method to monitor whether or not the reliable message sequence has been initialized. Once the reliable sequence is initialized, this method returns the ID of the sequence.

For more information about the WsrmUtils utility class, see "weblogic.wsee.reliability.WsrmUtils" in Oracle WebLogic Server API Reference.

Using Web Service Reliable Messaging: Main Steps

Configuring reliable messaging for a WebLogic Web service requires standard JMS tasks such as creating JMS servers and Store and Forward (SAF) agents, as well as Web service-specific tasks, such as adding additional JWS annotations to your JWS file. Optionally, you create WS-Policy files that describe the reliable messaging capabilities of the reliable Web service if you do not use the pre-packaged ones.

If you are using the WebLogic client APIs to invoke a reliable Web service, the client application must run on WebLogic Server. Thus, configuration tasks must be performed on both the source WebLogic Server instance on which the Web service that includes client code to invoke the reliable Web service reliably is deployed, as well as the destination WebLogic Server instance on which the reliable Web service itself is deployed.

The following table summarizes the steps to create a reliable Web service, as well as a client Web service that invokes an operation of the reliable Web service. The procedure describes how to create the JWS files that implement the two Web services from scratch; if you want to update existing JWS files, use this procedure as a guide. The procedure also describes how to configure the source and destination WebLogic Server instances.

Table 3-2 Steps to Create and Invoke a Reliable Web Service

#

Step

Description

1

Configure the destination and source WebLogic Server instances.

You will deploy the reliable Web service to the destination WebLogic Server instance. For information about configuring the destination WebLogic Server instance, see Configuring the Destination WebLogic Server Instance.

You will deploy the client Web service that invokes the reliable Web service to the source WebLogic Server instance. For information about configuring the source WebLogic Server instance, see Configuring the Source WebLogic Server Instance.

2

Create the WS-Policy file. (Optional)

Using your favorite XML or plain text editor, optionally create a WS-Policy file that describes the reliable messaging capabilities of the Web service running on the destination WebLogic Server. For details about creating your own WS-Policy file, see Creating the Web Service Reliable Messaging WS-Policy File.

This step is not required if you plan to use one of the WS-Policy files that are included in WebLogic Server; see Appendix A, "Pre-Packaged WS-Policy Files for Reliable Messaging," for more information.

3

Create or update the JWS file that implements the reliable Web service.

This Web service will be deployed to the destination WebLogic Server instance. See Programming Guidelines for the Reliable JWS File.

4

Update the build.xml file that is used to compile the reliable Web services.

Update your build.xml file to include a call to the jwsc Ant task which will compile the reliable JWS file into a Web service.

See "Running the jwsc WebLogic Web Services Ant Task" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server for general information about using the jwsc task.

5

Compile and deploy the reliable JWS file.

Compile the reliable JWS file by calling the appropriate target and deploy to the destination WebLogic Server. For example:

prompt> ant build-mainService deploy-mainService

6

Configure the reliable Web service.

Configure the reliable messaging options for the reliable Web service using the Administration Console. See Configuring Reliable Messaging for a Reliable Web Service.

7

Create or update the JWS file that implements the client Web service.

This service invokes the reliable Web service and will be deployed to the source WebLogic Server. See Programming Guidelines for the JWS File That Invokes a Reliable Web Service.

8

Update the build.xml file that is used to compile the client Web service.

See Updating the build.xml File for a Client of a Reliable Web Service.

9

Compile and deploy the client JWS file.

Compile your client JWS file by calling the appropriate target and deploy to the source WebLogic Server. For example:

prompt> ant build-clientService deploy-clientService

Each of these steps is described in more detail in the following sections.

In addition, the following advanced topics are discussed:

- Using Reliable Messaging With MTOM—Develop a reliable Web service that uses MTOM/XOP to optimize the transmission of XML data of type xs:base64Binary in SOAP messages

- Client Considerations When Redeploying a Reliable Web Service—Describes client considerations for when you deploy a new version of an updated reliable WebLogic Web service alongside an older version of the same Web service.

- Using Reliable Messaging With a Proxy Server—Describes considerations when invoking a reliable Web services operations using a proxy server.

Prerequisites

It is assumed that you have completed the following tasks:

- You have created the destination and source WebLogic Server instances.

- You have set up an Ant-based development environment for each environment.

- You have working build.xml files that you can edit, for example, to add targets for running the jwsc Ant task and deploying the generated reliable Web service.

For more information, see "Developing WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Configuring the Destination WebLogic Server Instance

To configure the WebLogic Server instance on which the reliable Web service is deployed, configure the JMS and store and forward (SAF) resources.

You can configure these resources manually or you can use the Configuration Wizard to extend the WebLogic Server domain using a Web services-specific extension template. Using the Configuration Wizard greatly simplifies the required configuration steps; for details, see "Configuring Your Domain For Web Services Features" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Note:

Alternatively, you can use WLST to configure the resources. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.

A domain that does not contain Web Services resources will still boot and operate correctly for non-Web services scenarios, and any Web Services scenario that does not involve asynchronous request and response. You will, however, see INFO messages in the server log indicating that asynchronous resources have not been configured and that the asynchronous response service for Web services has not been completely deployed.

If you prefer to configure the resources manually, perform the following steps.

Table 3-3 Steps to Configure the Destination WebLogic Server Instance Manually

#

Step

Description

1

Invoke the Administration Console for the domain that contains the destination WebLogic Server.

To invoke the Administration Console in your browser, enter the following URL:

http://host:port/console

where

- host refers to the computer on which the Administration Server is running.

- port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.

See "Invoking the Administration Console" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

2

Create persistent file store. (Optional)

Optionally create a persistent store (file or JDBC) that will be used by the destination WebLogic Server to store internal Web service reliable messaging information. You can use an existing one, or the default store that always exists, if you do not want to create a new one.

See "Create file stores" in Oracle WebLogic Server Administration Console Help.

3

Create a JMS Server.

Create a JMS Server. If a JMS server already exists, you can use it if you do not want to create a new one.

See "Create JMS servers" in Oracle WebLogic Server Administration Console Help.

4

Create JMS module and define queue.

Create a JMS module, and then define a JMS queue in the module. If a JMS module already exists, you can use it if you do not want to create a new one. Target the JMS queue to the JMS server you created in the preceding step. Be sure you specify that this JMS queue is local, typically by setting the local JNDI name.

Take note of the JNDI name you define for the JMS queue because you will later use it when you program the JWS file that implements your reliable Web service.

See "Create JMS system modules" and "Create queues in a system module" in Oracle WebLogic Server Administration Console Help.

Clustering Considerations:

If you are using the Web service reliable messaging feature in a cluster, you must:

- Create a local JMS queue, rather than a distributed queue, when creating the JMS queue.

- Explicitly target this JMS queue to each server in the cluster.

5

Create a store and forward (SAF) agent.

You can use an existing one if you do not want to create a new one.

When you create the SAF agent:

- Set the Agent Type field to Both to enable both sending and receiving agents.

- Be sure to target the SAF agent by clicking Next on the first assistant page to view the Select targets page (rather than clicking Finish).

Clustering Considerations:

- If you are using reliable messaging within a cluster, you must target the SAF agent to the cluster.

See "Create Store-and-Forward agents" in Oracle WebLogic Server Administration Console Help.

6

Tune your domain environment, as required. (Optional)

Review "Tuning Heavily Loaded Systems to Improve Web service Performance" in Performance and Tuning for Oracle WebLogic Server.

7

Restart the server.

In order for the configuration changes to take effect, you must restart the server, as described in "Starting and Stopping Servers" in Managing Server Startup and Shutdown for Oracle WebLogic Server.

Configuring the Source WebLogic Server Instance

Configuring the WebLogic Server instance on which the client Web service is deployed involves configuring JMS and store and forward (SAF) resources.

You can configure these resources manually or you can use the Configuration Wizard to extend the WebLogic Server domain using a Web services-specific extension template. Using the Configuration Wizard greatly simplifies the required configuration steps; for details, see "Configuring Your Domain For Web Services Features" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Notes:

Alternatively, you can use WLST to configure the resources. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.

A domain that does not contain Web Services resources will still boot and operate correctly for non-Web services scenarios, and any Web Services scenario that does not involve asynchronous request and response. You will, however, see INFO messages in the server log indicating that asynchronous resources have not been configured and that the asynchronous response service for Web services has not been completely deployed.

If you prefer to configure the resources manually, perform the following steps.

Table 3-4 Steps to Configure the Source WebLogic Server Instance

#

Step

Description

1

Invoke the Administration Console for the domain that contains the source WebLogic Server.

To invoke the Administration Console in your browser, enter the following URL:

http://host:port/console

where

- host refers to the computer on which the Administration Server is running.

- port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.

See "Invoking the Administration Console" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

2

Create persistent file store. (Optional)

Optionally create a persistent store (file or JDBC) that will be used by the source WebLogic Server to store internal Web service reliable messaging information. You can use an existing one, or the default store that always exists, if you do not want to create a new one.

See "Create file stores" in Oracle WebLogic Server Administration Console Help.

3

Create as store and forward (SAF) agent.

You can use an existing one if you do not want to create a new one.

When you create the SAF agent, set the Agent Type field to Both to enable both sending and receiving agents.

See "Create Store-and-Forward agents" in Oracle WebLogic Server Administration Console Help.

6

Tune your domain environment, as required. (Optional)

Review "Tuning Heavily Loaded Systems to Improve Web service Performance" in Performance and Tuning for Oracle WebLogic Server.

7

Restart the server.

In order for the configuration changes to take effect, you must restart the server, as described in "Starting and Stopping Servers" in Managing Server Startup and Shutdown for Oracle WebLogic Server.

Creating the Web Service Reliable Messaging WS-Policy File

A WS-Policy file is an XML file that contains policy assertions that comply with the WS-Policy specification. In this case, the WS-Policy file contains Web service reliable messaging policy assertions.

WebLogic Server includes pre-packaged WS-Policy files that contain typical reliable messaging assertions that you can use if you do not want to create your own WS-Policy file. The pre-packaged WS-Policy files are listed in the following table.

Note:

The DefaultReliability.xml and LongRunningReliability.xml files are deprecated in this release. Use of the DefaultReliability1.1.xml, Reliability1.1_SequenceTransportSecurity, or Reliability1.0_1.1.xml file is recommended and required to comply with the 1.1 version of the WS-ReliableMessaging specification at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf.

Table 3-5 Pre-packaged WS-Policy Files

Pre-packaged WS-Policy File

Description

DefaultReliability1.1.xml

Specifies policy assertions related to quality of service. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.1 at http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf. See DefaultReliability1.1.xml (WS-Policy File).

Reliability1.1_SequenceTransportSecurity

Specifies policy assertions related to transport-level security and quality of service. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.1 at http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf. See Reliability1.1_SequenceTransportSecurity.xml (WS-Policy File).

Reliability1.0_1.1.xml

Combines 1.1 and 1.0 WS Reliable Messaging policy assertions. This sample relies on smart policy selection to determine the policy assertion that is applied at runtime. See Reliability1.0_1.1.xml (WS-Policy.xml File)

DefaultRelibility.xml

Deprecated. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion Version 1.0 at http://schemas.xmlsoap.org/ws/2005/02/rm/WS-RMPolicy.pdf. In this release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

Specifies typical values for the reliable messaging policy assertions, such as inactivity timeout of 10 minutes, acknowledgement interval of 200 milliseconds, and base retransmission interval of 3 seconds. See DefaultReliability.xml (WS-Policy File) [Deprecated].

LongRunningReliability.xml

Deprecated. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion Version 1.0 for long running processes. In this release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

Similar to the preceding default reliable messaging WS-Policy file, except that it specifies a much longer activity timeout interval (24 hours.) See LongRunningReliability.xml (WS-Policy File) [Deprecated].

You can use one of the pre-packaged reliable messaging WS-Policy files included in WebLogic Server; these files are adequate for most use cases. You cannot modify the pre-packaged files. If the values do not suit your needs, you must create a custom WS-Policy file. The following sections describe how to create a custom WS-Policy file.

- Creating a Custom WS-Policy File Using WS-ReliableMessaging Policy Assertions Version 1.1

- Creating a Custom WS-Policy File Using WS-ReliableMessaging Policy Assertions Version 1.0 (Deprecated)

- Using Multiple Policy Alternatives

Creating a Custom WS-Policy File Using WS-ReliableMessaging Policy Assertions Version 1.1

This section describes how to create a custom WS-Policy file that contains Web service reliable messaging assertions that are based on WS Reliable Messaging Policy Assertion Version 1.1 at http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf. In the current release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

The root element of the WS-Policy file is <Policy> and it should include the following namespace declaration:

<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">

You wrap all Web service reliable messaging policy assertions inside of a <wsrmp:RMAssertion> element. This element should include the following namespace declaration for using Web service reliable messaging policy assertions:

<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">

The following table lists the Web service reliable messaging assertions that you can specify in the WS-Policy file. The order in which the assertions appear is important. You can specify the following assertions; the order they appear in the following list is the order in which they should appear in your WS-Policy file:

Table 3-6 Web Service Reliable Messaging Assertions (Version 1.1)

Assertion

Description

<wsrmp:SequenceSTR>

To secure messages in a reliable sequence, the runtime will use the wsse:SecurityTokenReference that is referenced in the CreateSequence message. You can only specify one security assertion; that is, you can specify wsrmp:SequenceSTR or wsrmp:SequenceTransportSecurity, but not both.

<wsrmp:SequenceTransportSecurity>

To secure messages in a reliable sequence, the runtime will use the SSL transport session that is used to send the CreateSequence message. This assertion must be used in conjunction with the sp:TransportBinding assertion that requires the use of some transport-level security mechanism (for example, sp:HttpsToken). You can only specify one security assertion; that is, you can specify wsrmp:SequenceSTR or wsrmp:SequenceTransportSecurity, but not both.

<wsrm:DeliveryAssurance>

Delivery assurance (or quality of service) of the Web service. Valid values are AtMostOnce, AtLeastOnce, ExactlyOnce, and InOrder. You can set one of the delivery assurances defined in the following table. If not set, the delivery assurance defaults to ExactlyOnce.

The following example shows a simple Web service reliable messaging WS-Policy file:

<?xml version="1.0"?>

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceTransportSecurity/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:Policy>

For more information about Reliable Messaging policy assertions in the WS-Policy file, see "Web Service Reliable Messaging Policy Assertion Reference" in WebLogic Web Services Reference for Oracle WebLogic Server.

Creating a Custom WS-Policy File Using WS-ReliableMessaging Policy Assertions Version 1.0 (Deprecated)

This section describes how to create a custom WS-Policy file that contains Web service reliable messaging assertions that are based on WS Reliable Messaging Policy Assertion Version 1.0 at http://schemas.xmlsoap.org/ws/2005/02/rm/WS-RMPolicy.pdf.

Note:

In the current release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

The root element of the WS-Policy file is <Policy> and it should include the following namespace declarations for using Web service reliable messaging policy assertions:

<wsp:Policy
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:beapolicy="http://www.bea.com/wsrm/policy">

You wrap all Web service reliable messaging policy assertions inside of a <wsrm:RMAssertion> element. The assertions that use the wsrm: namespace are standard ones defined by the WS-ReliableMessaging specification at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf. The assertions that use the beapolicy: namespace are WebLogic-specific. See "Web Service Reliable Messaging Policy Assertion Reference" in the WebLogic Web Services Reference for Oracle WebLogic Server for details.

The following table lists the Web service reliable messaging assertions that you can specify in the WS-Policy file. All Web service reliable messaging assertions are optional, so only set those whose default values are not adequate. The order in which the assertions appear is important. You can specify the following assertions; the order they appear in the following list is the order in which they should appear in your WS-Policy file,

Table 3-7 Web Service Reliable Messaging Assertions (Version 1.0)

Assertion

Description

<wsrm:InactivityTimeout>

Number of milliseconds, specified with the Milliseconds attribute, which defines an inactivity interval. After this amount of time, if the destination endpoint has not received a message from the source endpoint, the destination endpoint may consider the sequence to have terminated due to inactivity. The same is true for the source endpoint. By default, sequences never timeout.

<wsrm:BaseRetransmissionInterval>

Interval, in milliseconds, that the source endpoint waits after transmitting a message and before it retransmits the message if it receives no acknowledgment for that message. Default value is set by the SAF agent on the source endpoint's WebLogic Server instance.

<wsrm:ExponentialBackoff>

Specifies that the retransmission interval will be adjusted using the exponential backoff algorithm. This element has no attributes.

<wsrm:AcknowledgmentInterval>

Maximum interval, in milliseconds, in which the destination endpoint must transmit a stand-alone acknowledgement. The default value is set by the SAF agent on the destination endpoint's WebLogic Server instance.

<beapolicy:Expires>

Amount of time after which the reliable Web service expires and does not accept any new sequence messages. The default value is to never expire. This element has a single attribute, Expires, whose data type is an XML Schema duration type (see http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#duration). For example, if you want to set the expiration time to one day, use the following: <beapolicy:Expires Expires="P1D" />.

<beapolicy:QOS>

Delivery assurance level, as described in Table 3-9. The element has one attribute, QOS, which you set to one of the following values: AtMostOnce, AtLeastOnce, or ExactlyOnce. You can also include the InOrder string to specify that the messages be in order. The default value is ExactlyOnce InOrder. This element is typically not set.

The following example shows a simple Web service reliable messaging WS-Policy file:

<?xml version="1.0"?>

<wsp:Policy
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:beapolicy="http://www.bea.com/wsrm/policy"
>

<wsrm:RMAssertion>

<wsrm:InactivityTimeout
Milliseconds="600000" />
<wsrm:BaseRetransmissionInterval
Milliseconds="500" />
<wsrm:ExponentialBackoff />
<wsrm:AcknowledgementInterval
Milliseconds="2000" />

</wsrm:RMAssertion>

</wsp:Policy>

For more information about Reliable Messaging policy assertions in the WS-Policy file, see "Web Service Reliable Messaging Policy Assertion Reference" in WebLogic Web Services Reference for Oracle WebLogic Server.

Using Multiple Policy Alternatives

You can configure multiple policy alternatives—also referred to as smart policy alternatives—for a single Web service by creating a custom policy file. At runtime, WebLogic Server selects which of the configured policies to apply. It excludes policies that are not supported or have conflicting assertions and selects the appropriate policy, based on your configured preferences, to verify incoming messages and build the response messages.

The following example provides an example of a security policy that supports both 1.1and 1.0 WS-Reliable Messaging. Each policy alternative is enclosed in a <wsp:All> element.

Note:

The 1.0 Web service reliable messaging assertions are prefixed by wsrmp10.

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:ExactlyOne>
<wsp:All>
<wsrmp10:RMAssertion
xmlns:wsrmp10="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
<wsrmp10:InactivityTimeout Milliseconds="1200000"/>
<wsrmp10:BaseRetransmissionInterval Milliseconds="60000"/>
<wsrmp10:ExponentialBackoff/>
<wsrmp10:AcknowledgementInterval Milliseconds="800"/>
</wsrmp10:RMAssertion>
</wsp:All>
<wsp:All>
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceSTR/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:AtMostOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

For more information about multiple policy alternatives, see "Smart Policy Selection" in "Configuring Message-Level Security" in Securing WebLogic Web Services for Oracle WebLogic Server.

Programming Guidelines for the Reliable JWS File

This section describes how to create the JWS file that implements the reliable Web service.

The following JWS annotations are used in the JWS file that implements a reliable Web service.

Table 3-8 JWS Annotations for Reliable Messaging

Annotation

Description

@weblogic.jws.Policy

Required. Specifies that the Web service has a WS-Policy file attached to it that contains reliable messaging assertions. See Using the @Policy Annotation.

@javax.jws.Oneway

Required only if you invoke the reliable Web service operation synchronously (that is, you are not using the asynchronous request-response feature). See Using the @Oneway Annotation.

@weblogic.jws.BufferQueue

Optional. Specifies the JNDI name of the JMS queue which WebLogic Server uses to store reliable messages internally. See Using the @BufferQueue Annotation.

@weblogic.jws.ReliabilityBuffer

Optional. Specifies the number of times WebLogic Server should attempt to deliver the message from the JMS queue to the Web service implementation and the amount of time that the server should wait in between retries. See Using the @ReliabilityBuffer Annotation

The following example shows a simple JWS file that implements a reliable Web service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.reliable;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;

import weblogic.jws.WLHttpTransport;

import weblogic.jws.ReliabilityBuffer;
import weblogic.jws.BufferQueue;
import weblogic.jws.Policy;

/**
* Simple reliable Web Service.
*/

@WebService(name="ReliableHelloWorldPortType",
serviceName="ReliableHelloWorldService")

@WLHttpTransport(contextPath="ReliableHelloWorld",
serviceUri="ReliableHelloWorld",
portName="ReliableHelloWorldServicePort")

@Policy(uri="ReliableHelloWorldPolicy.xml",
direction=Policy.Direction.both,
attachToWsdl=true)
@BufferQueue(name="webservices.reliable.queue")

public class ReliableHelloWorldImpl {

private static String onewaySavedInput = null;

/**
* A one-way helloWorld method that saves the given string for later
* concatenation to the end of the message passed into helloWorldReturn.
*/
@WebMethod()
@Oneway()
@ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")

public void helloWorld(String input) {
System.out.println(" Hello World " + input);
onewaySavedInput = input;
}

/**
* This echo method concatenates the saved message from helloWorld
* onto the end of the provided message, and returns it.
*/
@WebMethod()
@ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")

public String echo(String input2) {
System.out.println(" Hello World " + input2 + onewaySavedInput);
return input + onewaySavedInput;
}
}

In the example, the custom ReliableHelloWorldPolicy.xml policy file is attached to the Web service at the class level, which means that the policy file is applied to all public operations of the Web service. The policy file is applied only to the request Web service message (as required by the reliable messaging feature) and it is attached to the WSDL file. For information about the pre-packaged policies available and creating a custom policy, see Creating the Web Service Reliable Messaging WS-Policy File.

The JMS queue that WebLogic Server uses internally to enable the Web service reliable messaging has a JNDI name of webservices.reliable.queue, as specified by the @BufferQueue annotation.

The helloWorld() method has been marked with both the @WebMethod and @Oneway JWS annotations, which means it is a public operation called helloWorld. Because of the @Policy annotation, the operation can be invoked reliably. The Web services runtime attempts to deliver reliable messages to the service a maximum of 10 times, at 10-second intervals, as described by the @ReliabilityBuffer annotation. The message may require re-delivery if, for example, the transaction is rolled back or otherwise does not commit.

The echo() method has been marked with the @WebMethod and JWS annotation, which means it is a public operation called echo. Because of the @Policy annotation, the operation can be invoked reliably. It uses the same reliability buffer configuration as the helloWorld() method.

Using the @Policy Annotation

Use the @Policy annotation in your JWS file to specify that the Web service has a WS-Policy file attached to it that contains reliable messaging assertions. WebLogic Server delivers a set of pre-packaged WS-Policy files, as described in Appendix A, "Pre-Packaged WS-Policy Files for Reliable Messaging."

Follow the following guidelines when using the @Policy annotation for Web service reliable messaging:

- Use the uri attribute to specify the build-time location of the policy file, as follows:

- If you have created your own WS-Policy file, specify its location relative to the JWS file. For example:

@Policy(uri="ReliableHelloWorldPolicy.xml",
direction=Policy.Direction.both,
attachToWsdl=true)

In this example, the ReliableHelloWorldPolicy.xml file is located in the same directory as the JWS file.

- To specify one of the pre-packaged WS-Policy files or a WS-Policy file that is packaged in a shared Java EE library, use the policy: prefix along with the name and path of the policy file. This syntax tells the jwsc Ant task at build-time not to look for an actual file on the file system, but rather, that the Web service will retrieve the WS-Policy file from WebLogic Server at the time the service is deployed.

Note:

Shared Java EE libraries are useful when you want to share a WS-Policy file with multiple Web services that are packaged in different Enterprise applications. As long as the WS-Policy file is located in the META-INF/policies or WEB-INF/policies directory of the shared Java EE library, you can specify the policy file in the same way as if it were packaged in the same archive at the Web service. See "Creating Shared Java EE Libraries and Optional Packages" in Developing Applications for Oracle WebLogic Server for information about creating libraries and setting up your environment so the Web service can locate the policy files.

- To specify that the policy file is published on the Web, use the http: prefix along with the URL, as shown in the following example:

@Policy(uri="http://someSite.com/policies/mypolicy.xml"
direction=Policy.Direction.both,
attachToWsdl=true)

- By default, WS-Policy files are applied to both the request (inbound) and response (outbound) SOAP messages. You can change this default behavior with the direction attribute by setting the attribute to Policy.Direction.inbound or Policy.Direction.outbound.

- You can specify whether the Web service requires the operations to be invoked reliably and have the responses delivered reliably using the wsp:optional attribute within the policy file specified by uri.
If the optional attribute is set to false for outbound on any operation, then:

- The client must provide an offer sequence (<wsrm: Offer...> as described in the WS-ReliableMessaging specification at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf) for use when sending reliable responses.

- Responses will be sent reliably for all operations requiring a response.

If the optional attribute is set to true for outbound on all operations, then:

- The client is not required to provide an offer sequence.

- Responses will be sent reliably if the client provides an offer sequence; otherwise, responses will be sent non-reliably.

- Set the attachToWsdl attribute of the @Policy annotation to specify whether the policy file should be attached to the WSDL file that describes the public contract of the Web service. Typically, you want to publicly publish the policy so that client applications know the reliable messaging capabilities of the Web service. For this reason, the default value of this attribute is true.

For more information about the @Policy annotation, see "weblogic.jws.Policy" in WebLogic Web Services Reference for Oracle WebLogic Server.

Using the @Oneway Annotation

If you plan on invoking the reliable Web service operation synchronously (or in other words, not using the asynchronous request-response feature), then you must annotate the implementing method with the @Oneway annotation to specify that the method is one-way. This means that the method cannot return a value, but rather, must explicitly return void.

Conversely, if the method is not annotated with the @Oneway annotation, then you must invoke it using the asynchronous request-response feature. If you are unsure how the operation is going to be invoked, consider creating two flavors of the operation: synchronous and asynchronous.

See Chapter 2, "Invoking a Web Service Using Asynchronous Request-Response," and Chapter 6, "Using the Asynchronous Features Together."

Using the @BufferQueue Annotation

Use the @BufferQueue annotation to specify the JNDI name of the JMS queue which WebLogic Server uses to store reliable messages internally. The JNDI name is the one you configured when creating a JMS queue in step 4 in Configuring the Destination WebLogic Server Instance.

The @BufferQueue annotation is optional; if you do not specify it in your JWS file then WebLogic Server uses a queue with a JNDI name of weblogic.wsee.DefaultQueue. You must, however, still explicitly create a JMS queue with this JNDI name using the Administration Console.

For more information about the @BufferQueue annotation, see "weblogic.jws.BufferQueue" in WebLogic Web Services Reference for Oracle WebLogic Server.

Using the @ReliabilityBuffer Annotation

Use the @ReliabilityBuffer annotation to specify the number of times WebLogic Server should attempt to deliver the message from the JMS queue to the Web service implementation and the amount of time that the server should wait in between retries.

Use the retryCount attribute to specify the number of retries and the retryDelay attribute to specify the wait time. The format of the retryDelay attribute is a number and then one of the following strings:

- seconds

- minutes

- hours

- days

- years

For example, to specify a retry count of 20 and a retry delay of two days, use the following syntax:

@ReliabilityBuffer(retryCount=20, retryDelay="2 days")

The retry count and delay default to 3 and 5 seconds, respectively.

For more information about the @ReliabilityBuffer annotation, see "weblogic.jws.ReliabilityBuffer" in WebLogic Web Services Reference for Oracle WebLogic Server.

Configuring Reliable Messaging for a Reliable Web Service

If necessary, you can edit the reliable message configuration options for a reliable Web service that are stored in the weblogic-webservices.xml descriptor by updating the application deployment plan. The deployment plan associates new values with specific locations in the descriptors for your application. At deployment time, a deployment plan is merged with the descriptors in the application by applying the values in its variable assignments to the locations in the application descriptors to which the variables are linked.

The following table summarizes the reliable messaging options that can be configured for the reliable Web service.

Table 3-9 Configuration Options for Reliable Messaging

Configuration Option

Description

Customize Reliable Message Configuration

Flag that specifies whether you want to customize the reliable message configuration defined in the Web service descriptor or deployment plan at the Web service endpoint level. This flag is available only when configuring reliable messaging at the Web service endpoint level If not checked, the reliable message configuration specified for the WebLogic Server is used.

Note: This flag does not reflect the configuration of Reliable Messaging in other forms, such as, WS-RM policy directly specified in the WSDL.

Base Retransmission Interval

Interval of time that must pass before a message is retransmitted to the RM destination.

If the source endpoint does not receive an acknowledgement for a given message within the specified interval, the source endpoint retransmits the message. The source endpoint can modify this retransmission interval at any point during the lifetime of the sequence of messages.

This element can be used in conjunction with the Retransmission Exponential Backoff element to specify the algorithm that is used to adjust the retransmission interval.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P0DT3S (3 seconds).

Enable Retransmission Exponential Backoff

Flag that specifies whether the message retransmission interval will be adjusted using the exponential backoff algorithm.

This element is used in conjunction with the Base Retransmission Interval element. If a destination endpoint does not acknowledge a sequence of messages for the time interval specified by the Base Retransmission Interval, the exponential backoff algorithm is used for timing successive retransmissions by the source endpoint, should the message continue to go unacknowledged.

The exponential backoff algorithm specifies that successive retransmission intervals should increase exponentially, based on the base retransmission interval. For example, if the base retransmission interval is 2 seconds, and the exponential backoff element is set, successive retransmission intervals if messages continue to go unacknowledged are 2, 4, 8, 16, 32, and so on.

This value defaults to false, the same retransmission interval is used in successive retries; the interval does not increase exponentially.

Acknowledgement Interval

Maximum interval during which the destination endpoint must transmit a stand-alone acknowledgement.

A destination endpoint can send an acknowledgement on the return message immediately after it has received a message from a source endpoint, or it can send one separately as a stand-alone acknowledgement. If a return message is not available to send an acknowledgement, a destination endpoint may wait for up to the acknowledgement interval before sending a stand-alone acknowledgement. If there are no unacknowledged messages, the destination endpoint may choose not to send an acknowledgement.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P0DT0.2S (200 milliseconds).

Inactivity Timeout

Inactivity interval. If, during the inactivity timeout interval, an endpoint (the RM source or destination) has not received messages application or control messages, the endpoint may consider the RM sequence to have been terminated due to inactivity.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P0DT600S (600 seconds).

Sequence Expiration

Expiration time for a sequence regardless of activity.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P1D (1 day).

Buffer Retry Count

Number of times to retry a reliable request. This value defaults to 3.

Buffer Retry Delay

Amount of time to wait before retrying a reliable request.

The retry attempts are between the client's request message on the JMS queue and delivery of the message to the Web service implementation.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P0DT5S (5 seconds).

You can set the reliable messaging configuration options using the Administration Console or WLST, as described in the following sections.

- Using the Administration Console

- Using WLST

Using the Administration Console

To configure reliable messaging for the Web service endpoint using the Administration Console:

1. Invoke the Administration Console, as described in "Invoking the Administration Console" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

2. In the left navigation pane, select Deployments.

3. Click the name of the Web service in the Deployments table.

4. Select the Configuration tab, then the Ports tab.

5. Click the name of the Web service endpoint in the Ports table.

6. Select the Reliable Message tab.

7. Click Customize Reliable Message Configuration and follow the instructions to save the deployment plan, if required.

8. Set the reliable messaging properties, as required.

9. Click Save.

Using WLST

For a complete description and example of using WLST to update an application's deployment plan to configure reliable messaging, see "Updating the Deployment Plan" in Oracle WebLogic Scripting Tool.

For your reference, the following table summarizes the XPath values for the WS-RM configuration options.

Table 3-10 WS_RM Configuration Variable Names and XPath Values

Configuration Option

Example Variable Name

XPath Value

Inactivity Timeout

ReliabilityConfig_
InactivityTimeout

/weblogic-webservices/webservice-description/
[webservice-description-name="
service_name"]/port-component/
[port-component-name="port_name"]
/reliability-config/inactivity-timeout

Base Retransmission Interval

ReliabilityConfig_
BaseRetransmission
Interval

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/base-retransmission-interval

Retransmission Exponential Backoff

ReliabilityConfig_
Retransmission
ExponentialBackoff

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]/reliability-
config/retransmission-exponential-backoff

Acknowledgement Interval

ReliabilityConfig_
AcknowledgementInterval

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/acknowledgement-interval

Sequence Expiration

ReliabilityConfig_
SequenceExpiration

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/sequence-expiration

Buffer Retry Count

ReliabilityConfig_
BufferRetryCount

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/buffer-retry-count

Buffer Retry Delay

ReliabilityConfig_
BufferRetryDelay

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/buffer-retry-delay

Programming Guidelines for the JWS File That Invokes a Reliable Web Service

If you are using the WebLogic client APIs, you must invoke a reliable Web service from within a Web service; you cannot invoke a reliable Web service from a stand-alone client application.

The following example shows a simple JWS file for a Web service that invokes a reliable operation from the service described in Programming Guidelines for the Reliable JWS File.

package examples.webservices.reliable;

import java.rmi.RemoteException;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.rpc.Stub;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.ReliabilityErrorHandler;

import weblogic.jws.AsyncFailure;
import weblogic.jws.AsyncResponse;

import examples.webservices.reliable.ReliableHelloWorldPortType;

import weblogic.wsee.reliability.ReliabilityErrorContext;
import weblogic.wsee.reliability.ReliableDeliveryException;
import weblogic.wsee.reliability.WsrmUtils;

@WebService(name="ReliableClientPortType",
serviceName="ReliableClientService")

@WLHttpTransport(contextPath="ReliableClient",
serviceUri="ReliableClient",
portName="ReliableClientServicePort")

public class ReliableClientImpl
{
private static String responseMessage = null;

@ServiceClient(
serviceName="ReliableHelloWorldService",
portName="ReliableHelloWorldServicePort")

private ReliableHelloWorldPortType port;

@WebMethod
public void callHelloWorld(String input, String input2, String serviceUrl)
throws RemoteException {

((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, serviceUrl);

port.helloWorld(input);

System.out.println(" Invoked the ReliableHelloWorld.helloWorld operation reliably." );
WsrmUtils.setFinalMessage((Stub)port);
port.echo(input2);
System.out.println(" Invoked the ReliableHelloWorld.echo operation reliably." );
}

@AsyncResponse(target = "port", operation = "echo")
public void onEchoAsyncResponse(String msg) {

System.out.println("ClientService: Got async response for request : " + msg);
responseMessage = msg;
}

@AsyncFailure(target = "port", operation = "echo")
public void onEchoAsyncFailure(Throwable t) {
System.out.println("ClientService: Got async FAILURE for request : " + t);
t.printStackTrace();
}

@ReliabilityErrorHandler(target="port")
public void onReliableMessageDeliveryError(ReliabilityErrorContext ctx) {

ReliableDeliveryException fault = ctx.getFault();
String message = null;
if (fault != null) {
message = ctx.getFault().getMessage();
}
String operation = ctx.getOperationName();
System.out.println("Reliable operation " + operation + " may have not invoked. The error message is " + message);
}

}

As illustrated in the previous examples (in bold text), follow these guidelines when programming the JWS file that invokes a reliable Web service:

- Import the @ServiceClient and @ReliabilityErrorHandler JWS annotations:

import weblogic.jws.ServiceClient;
import weblogic.jws.ReliabilityErrorHandler;

- Import the WebLogic APIs that you will use in the method that handles the error that results when the client Web service does not receive an acknowledgement of message receipt from the reliable Web service:

import weblogic.wsee.reliability.ReliabilityErrorContext;
import weblogic.wsee.reliability.ReliableDeliveryException;

- Import the APIs used for asynchronous response and failure.

import weblogic.jws.AsyncFailure;
import weblogic.jws.AsyncResponse;

- Import the JAX-RPC stub, created later by the <clientgen> child element of the jwsc Ant task, of the port type of the reliable Web service you want to invoke. The stub package is specified by the packageName attribute of <clientgen>, and the name of the stub is determined by the WSDL of the invoked Web service.

import examples.webservices.reliable.ReliableHelloWorldPortType;

- Import the APIs used for life cycle management (to set properties and specify the final message later).

import javax.xml.rpc.Stub;
import weblogic.wsee.reliability.WsrmUtils;

- In the body of the JWS file, use the @ServiceClient JWS annotation to specify the name and port of the reliable Web service you want to invoke. You specify this annotation at the field-level on a private variable, whose data type is the JAX-RPC port type of the Web service you are invoking.

@ServiceClient(
serviceName="ReliableHelloWorldService",
portName="ReliableHelloWorldServicePort")

private ReliableHelloWorldPortType port;

- Use the port._setProperty method to dynamically specify the target service endpoint address within the Web service client. For more information, see "Accessing Runtime Information About a Web service" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, serviceUrl);

- Using the stub you annotated with the @ServiceClient annotation, invoke the helloWorld reliable operation:

port.helloWorld(input);

Because the operation has been marked one-way, it does not return a value.

- Create a method that handles the error when the client Web service does not receive an acknowledgement from the reliable Web service that the latter has received a message and annotate this method with the @weblogic.jws.ReliabilityErrorHandler annotation:

@ReliabilityErrorHandler(target="port")
public void onReliableMessageDeliveryError(ReliabilityErrorContext ctx) {
ReliableDeliveryException fault = ctx.getFault();
String message = null;
if (fault != null) {
message = ctx.getFault().getMessage();
}
String operation = ctx.getOperationName();
System.out.println("Reliable operation " + operation + " may have not invoked. The error message is " + message);
}

This method takes ReliabilityErrorContext as its single parameter and returns void.

See "weblogic.jws.ReliabilityErrorHandler" in WebLogic Web Services Reference for Oracle WebLogic Server for details about programming this error-handling method.

- Because the service is not conversational, any state kept in the port field will be lost when this method returns. In the case of reliable messaging, this state includes the ID of the reliable sequence being used to send messages. The setFinalMessage method specifies that this is the final message to be sent on this sequence. This will allow the reliable messaging subsystem to proactively clean up the reliable sequence instead of timing out.

WsrmUtils.setFinalMessage((Stub)port);

- Using the stub you annotated with the @ServiceClient annotation, invoke the echo reliable operation:

port.echo(input2);

- Create methods to handle the asynchronous response or failure. Use the @weblogic.jws.AsyncResponse and @weblogic.jws.AsyncFailure annotations:

@AsyncResponse(target = "port", operation = "echo")
public void onEchoAsyncResponse(String msg) {
System.out.println("ClientService: Got async response for request : " + msg);
responseMessage = msg;
}

@AsyncFailure(target = "port", operation = "echo")
public void onEchoAsyncFailure(Throwable t) {
System.out.println("ClientService: Got async FAILURE for request : " + t);
t.printStackTrace();
}

For more information about generating asynchronous response and failure methods, see Writing the Asynchronous JWS File.

When programming the client Web service:

- Do not specify any reliable messaging annotations (other than @ReliabilityErrorHandler) or use any reliable messaging assertions in the associated WS-Policy files.

- Do not specify the wsdlLocation attribute of the @ServiceClient annotation. This is because the runtime retrieval of the specified WSDL might not succeed; therefore, it is better for WebLogic Server to use a local WSDL file instead.

Updating the build.xml File for a Client of a Reliable Web Service

To update a build.xml file to generate the JWS file that invokes the operation of a reliable Web service, add taskdef and a build-reliable-client targets similar to the following:

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-reliable-client">

<jwsc
enableAsyncService="true"
srcdir="src"
destdir="${client-ear-dir}" >

<jws file="examples/webservices/reliable/ReliableClientImpl.java">

<clientgen
wsdl="http://${wls.destination.host}:${wls.destination.port}/ReliableHelloWorld/ReliableHelloWorld?WSDL"
packageName="examples.webservices.reliable"/>

</jws>

</jwsc>

</target>

Use the taskdef Ant task to define the full classname of the jwsc Ant tasks.

Update the jwsc Ant task that compiles the client Web service to include a <clientgen> child element of the <jws> element so as to generate and compile the JAX-RPC stubs for the deployed ReliableHelloWorld Web service. The jwsc Ant task automatically packages them in the generated WAR file so that the client Web service can immediately access the stubs. You do this because the ReliableClientImpl JWS file imports and uses one of the generated classes.

Using Reliable Messaging With MTOM

The following example shows a simple JWS file that implements a reliable Web service and uses MTOM/XOP to optimize the transmission of XML data of type xs:base64Binary in SOAP messages; see the explanation after the example for coding guidelines that correspond to the Java code in bold. This example builds on the example provided in Programming Guidelines for the JWS File That Invokes a Reliable Web Service.

package examples.webservices.reliable;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;
import weblogic.jws.WLHttpTransport;

import weblogic.jws.ReliabilityBuffer;
import weblogic.jws.BufferQueue;
import weblogic.jws.Policy;
import weblogic.jws.Policies;

/**
* Simple reliable Web Service.
*/

@WebService(name="ReliableHelloWorldPortType",
serviceName="ReliableHelloWorldService")

@WLHttpTransport(contextPath="ReliableHelloWorld",
serviceUri="ReliableHelloWorld",
portName="ReliableHelloWorldServicePort")

@Policies({@Policy(uri="ReliableHelloWorldPolicy.xml",
direction=Policy.Direction.both,
attachToWsdl=true),
@Policy(uri = "policy:Mtom.xml")})

@BufferQueue(name="webservices.reliable.queue")

public class ReliableHelloWorldImpl {

@WebMethod()
@Oneway()
@ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")

public void helloWorld(String input) {
System.out.println(" Hello World " + input);

}

@WebMethod

public byte[] echoBinary(byte[] bytes) {
return bytes;
}
}

As illustrated in the previous example (in bold text), follow these guidelines when programming the JWS file that invokes a reliable Web service with MTOM:

- Use the "@weblogic.jws.Policy" annotation to specify that the pre-packaged Mtom.xml file should be applied to your Web service. Use the "@weblogic.jws.Policies" annotation to group multiple WS-Policy files, including the reliable messaging policy file and the MTOM policy file.

@Policies({@Policy(uri="ReliableHelloWorldPolicy.xml",
direction=Policy.Direction.both,
attachToWsdl=true),
@Policy(uri = "policy:Mtom.xml")})

- Use the Java byte[] data type in your Web service operations as either a return value or input parameter whenever you want the resulting SOAP message to use MTOM/XOP to send or receive the binary data.

public byte[] echoBinary(byte[] bytes) {
return bytes;
}

Note:

In this release of WebLogic Server, the only supported Java data type when using MTOM/XOP is byte[]; other binary data types, such as image, are not supported.

Client Considerations When Redeploying a Reliable Web Service

WebLogic Server supports production redeployment, which means that you can deploy a new version of an updated reliable WebLogic Web service alongside an older version of the same Web service.

WebLogic Server automatically manages client connections so that only new client requests are directed to the new version. Clients already connected to the Web service during the redeployment continue to use the older version of the service until they complete their work, at which point WebLogic Server automatically retires the older Web service. If the client is connected to a reliable Web service, its work is considered complete when the existing reliable message sequence is explicitly ended by the client or as a result of a timeout.

For additional information about production redeployment and Web service clients, see "Client Considerations When Redeploying a Web service" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Using Reliable Messaging With a Proxy Server

Client applications that invoke reliable Web services might not invoke the operation directly, but rather, use a proxy server. Reasons for using a proxy include the presence of a firewall or the deployment of the invoked Web service to a cluster.

In this case, the WebLogic Server instance that hosts the invoked Web service must be configured with the address and port of the proxy server. If your Web service is deployed to a cluster, you must configure every server in the cluster.

This procedure describes how to create a network channel, the primary configurable WebLogic Server resource for managing network connection. Network channels enable you to provide a consistent way to access the front-end address of a cluster. For more information about network channels, see "Understanding Network Channels" in Configuring Server Environments for Oracle WebLogic Server.

For each server instance:

1. Create a network channel for the protocol you use to invoke the Web service. You must name the network channel weblogic-wsee-proxy-channel-XXX, where XXX refers to the protocol. For example, to create a network channel for HTTPS, call it weblogic-wsee-proxy-channel-https.
See "Configure custom network channels" in Oracle WebLogic Server Administration Console Help for general information about creating a network channel.

2. Configure the network channel, updating the External Listen Address and External Listen Port fields with the address and port of the proxy server, respectively.

3. Disable the asynchronous response service on the WebLogic Server proxy server by starting the WebLogic Server instance using the -Dweblogic.wsee.skip.async.response=true Java system property.
By default, every WebLogic Server instance deploys an internal asynchronous Web service that handles the asynchronous request-response feature. If you do not specify this system property, asynchronous messages will never get to the cluster, as required, because the asynchronous service on the proxy server will consume them instead.

4 Creating Conversational Web Services

This chapter describes how to create conversational WebLogic Java API for XML-based RPC (JAX-RPC) Web services.

This chapter includes the following topics:

- Overview of Conversational Web Services

- Creating a Conversational Web Service: Main Steps

- Programming Guidelines for the Conversational JWS File

- Programming Guidelines for the JWS File That Invokes a Conversational Web Service

- ConversationUtils Utility Class

- Updating the build.xml File for a Client of a Conversational Web Service

- Updating a Stand-Alone Java Client to Invoke a Conversational Web Service

- Example Conversational Web Service .NET Client

- Client Considerations When Redeploying a Conversational Web Service

Overview of Conversational Web Services

A Web service and the client application that invokes it may communicate multiple times to complete a single task. Also, multiple client applications might communicate with the same Web service at the same time. Conversations provide a straightforward way to keep track of data between calls and to ensure that the Web service always responds to the correct client.

Conversations meet two challenges inherent in persisting data across multiple communications:

- Conversations uniquely identify a two-way communication between one client application and one Web service so that messages are always returned to the correct client. For example, in a shopping cart application, a conversational Web service keeps track of which shopping cart belongs to which customer. A conversational Web service implements this by creating a unique conversation ID each time a new conversation is started with a client application.

- Conversations maintain state between calls to the Web service; that is, they keep track of the data associated with a particular client application between its calls to the service. Conversations ensure that the data associated with a particular client is saved until it is no longer needed or the operation is complete. For example, in a shopping cart application, a conversational Web service remembers which items are in the shopping cart while the customer continues shopping. Maintaining state is also needed to handle failure of the computer hosting the Web service in the middle of a conversation; all state-related data is persisted to disk so that when the computer comes up it can continue the conversation with the client application.

WebLogic Server manages this unique ID and state by creating a conversation context each time a client application initiates a new conversation. The Web service then uses the context to correlate calls to and from the service and to persist its state-related data.

Conversations between a client application and a Web service have three distinct phases:

- Start—A client application initiates a conversation by invoking the start operation of the conversational Web service. The Web service in turn creates a new conversation context and an accompanying unique ID, and starts an internal timer to measure the idle time and the age of the conversation.

- Continue—After the client application has started the conversation, it invokes one or more continue operations to continue the conversation. The conversational Web service uses the ID associated with the invoke to determine which client application it is conversing with, what state to persist, and which idle timer to reset. A typical continue operation would be one that requests more information from the client application, requests status, and so on.

- Finish—A client application explicitly invokes the finish operation when it has finished its conversation; the Web service then marks any data or resources associated with the conversation as deleted.

Conversations typically occur between two WebLogic Web services: one is marked conversational and defines the start, continue, and finish operations and the other Web service uses the @ServiceClient annotation to specify that it is a client of the conversational Web service. You can also invoke a conversational Web service from a stand-alone Java client, although there are restrictions.

As with other WebLogic Web service features, you use JWS annotations to specify that a Web service is conversational.

Note:

The client Web service that invokes a conversational Web service is not required to also be conversational. However, if the client is not conversational, there is a danger of multiple instances of this client accessing the same conversational Web service stub and possibly corrupting the saved conversational state. If you believe this might true in your case, then specify that the client Web service also be conversational. In this case you cannot use a stand-alone Java client, because there is no way to mark it as conversational using the WebLogic APIs.

A conversational Web service on its own does not guarantee message delivery or that the messages are delivered in order, exactly once. If you require this kind of message delivery guarantee, you must also specify that the Web service be reliable. See Using Web Service Reliable Messaging: Main Steps and Using the Asynchronous Features Together.

Creating a Conversational Web Service: Main Steps

The following procedure describes how to create a conversational Web service, as well as a client Web service and stand-alone Java client application, both of which initiate and conduct a conversation. The procedure shows how to create the JWS files that implement the two Web services from scratch. If you want to update existing JWS files, you can also use this procedure as a guide.

It is assumed that you have set up an Ant-based development environment and that you have a working build.xml file to which you can add targets for running the jwsc Ant task and deploying the generated conversational Web service. It is further assumed that you have a similar setup for the WebLogic Server instance that hosts the client Web service that initiates the conversation. For more information, see the following sections in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server:

- "Use Cases and Examples"

- "Developing WebLogic Web Services"

- "Programming the JWS File"

- "Invoking Web Services"

Table 4-1 Steps to Create a Conversational Web Service

#

Step

Description

1

Create a new JWS file, or update an existing one, that implements the conversational Web service.

Use your favorite IDE or text editor. See Programming Guidelines for the Conversational JWS File.

2

Update your build.xml file to include a call to the jwsc Ant task to compile the conversational JWS file into a Web service.

See "Running the jwsc WebLogic Web Services Ant Task" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

3

Run the Ant target to build the conversational Web service.

For example:

prompt> ant build-mainService

4

Deploy the target Web service as usual.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

5

Create a new JWS file, or update an existing one, that implements the client Web service.

If the client application is a stand-alone Java client, see Updating a Stand-Alone Java Client to Invoke a Conversational Web Service. Skip Steps 6-9.

If the client application is itself a Web service, follow Steps 6-9.

6

Create a new JWS file, or update an existing one, that initiates and conducts the conversation with the conversational Web service.

Use your favorite IDE or text editor. It is assumed that the client Web service is deployed to a different WebLogic Server instance form the one that hosts the conversational Web service. See Programming Guidelines for the JWS File That Invokes a Conversational Web Service.

7

Update the build.xml file that builds the client Web service.

See Updating the build.xml File for a Client of a Conversational Web Service.

8

Run the Ant target to build the client Web services.

For example:

prompt> ant build-clientService

9

Deploy the client Web service as usual.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Programming Guidelines for the Conversational JWS File

The following example shows a simple JWS file that implements a conversational Web service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.conversation;

import java.io.Serializable;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Conversation;
import weblogic.jws.Conversational;
import weblogic.jws.Context;
import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.ServiceHandle;

import javax.jws.WebService;
import javax.jws.WebMethod;
@Conversational(maxIdleTime="10 minutes",
maxAge="1 day",
runAsStartUser=false,
singlePrincipal=false )
@WebService(name="ConversationalPortType",
serviceName="ConversationalService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="conv",
serviceUri="ConversationalService",
portName="ConversationalServicePort")

/**
* Conversational Web service.
*/

public class ConversationalServiceImpl implements Serializable {

@Context
private JwsContext ctx;
public String status = "undefined";

@WebMethod
@Conversation (Conversation.Phase.START)
public String start() {

ServiceHandle handle = ctx.getService();
String convID = handle.getConversationID();

status = "start";
return "Starting conversation, with ID " + convID + " and status equal to " + status;

}

@WebMethod
@Conversation (Conversation.Phase.CONTINUE)
public String middle(String message) {

status = "middle";
return "Middle of conversation; the message is: " + message + " and status is " + status;

}

@WebMethod
@Conversation (Conversation.Phase.FINISH)
public String finish(String message ) {

status = "finish";
return "End of conversation; the message is: " + message + " and status is " + status;

}

}

Follow these guidelines when programming the JWS file that implements a conversational Web service. Code snippets of the guidelines are shown in bold in the preceding example.

- Conversational Web services must implement java.io.Serializable, so you must first import the class into your JWS file:

import java.io.Serializable;

- Import the conversational JWS annotations:

import weblogic.jws.Conversation;
import weblogic.jws.Conversational;

- If you want to access runtime information about the conversational Web service, import the @Context annotation and context APIs:

import weblogic.jws.Context;

import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.ServiceHandle;

See "Accessing Runtime Information about a Web service" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server for more information about the runtime Web service context.

- Use the class-level @Conversational annotation to specify that the Web service is conversational. Although this annotation is optional (assuming you are specifying the @Conversation method-level annotation), it is a best practice to always use it in your JWS file to clearly specify that your Web service is conversational.
Specify any of the following optional attributes: maxIdleTime is the maximum amount of time that the Web service can be idle before WebLogic Server finishes the conversation; maxAge is the maximum age of the conversation; runAsStartUser indicates whether the continue and finish phases of an existing conversation are run as the user who started the conversation; and singlePrincipal indicates whether users other than the one who started a conversation are allowed to execute the continue and finish phases of the conversation.

@Conversational(maxIdleTime="10 minutes",
maxAge="1 day",
runAsStartUser=false,
singlePrincipal=false )

If a JWS file includes the @Conversational annotation, all operations of the Web service are conversational. The default phase of an operation, if it does not have an explicit @Conversation annotation, is continue. However, because a conversational Web service is required to include at least one start and one finish operation, you must use the method-level @Conversation annotation to specify which methods implement these operations.

See "weblogic.jws.Conversational" in WebLogic Web Services Reference for Oracle WebLogic Server for additional information and default values for the attributes.

- Your JWS file must implement java.io.Serializable:

public class ConversationalServiceImpl implements Serializable {

- To access runtime information about the Web service, annotate a private class variable, of data type weblogic.wsee.jws.JwsContext, with the field-level @Context JWS annotation:

@Context
private JwsContext ctx;

- Use the @Conversation annotation to specify the methods that implement the start, continue, and finish phases of your conversation. A conversation is required to have at least one start and one finish operation; the continue operation is optional. Use the following parameters to the annotation to specify the phase: Conversation.Phase.START, Conversation.Phase.CONTINUE, or Conversation.Phase.FINISH. The following example shows how to specify the start operation:

@WebMethod
@Conversation (Conversation.Phase.START)
public String start() {...

If you mark just one method of the JWS file with the @Conversation annotation, then the entire Web service becomes conversational and each operation is considered part of the conversation; this is true even if you have not used the optional class-level @Conversational annotation in your JWS file. Any methods not explicitly annotated with @Conversation are, by default, continue operations. This means that, for example, if a client application invokes one of these continue methods without having previously invoked a start operation, the Web service returns a runtime error.

Finally, if you plan to invoke the conversational Web service from a stand-alone Java client, the start operation is required to be request-response, or in other words, it cannot be annotated with the @Oneway JWS annotation. The operation can return void. If you are going to invoke the Web service only from client applications that run in WebLogic Server, then this requirement does not apply.

See "weblogic.jws.Conversation" in WebLogic Web Services Reference for Oracle WebLogic Server for additional information.

- Use the JwsContext instance to get runtime information about the Web service.
For example, the following code in the start operation gets the ID that WebLogic Server assigns to the new conversation:

ServiceHandle handle = ctx.getService();
String convID = handle.getConversationID();

See "Accessing Runtime Information about a Web service" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server for detailed information on using the context-related APIs.

Programming Guidelines for the JWS File That Invokes a Conversational Web Service

The following example shows a simple JWS file for a Web service that invokes the conversational Web service described in Programming Guidelines for the Conversational JWS File; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.conversation;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;

import weblogic.wsee.conversation.ConversationUtils;

import javax.jws.WebService;
import javax.jws.WebMethod;

import javax.xml.rpc.Stub;

import examples.webservices.conversation.ConversationalPortType;

import java.rmi.RemoteException;

@WebService(name="ConversationalClientPortType",
serviceName="ConversationalClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="convClient",
serviceUri="ConversationalClient",
portName="ConversationalClientPort")

/**
*  client that has a conversation with the ConversationalService.
*/

public class ConversationalClientImpl {

@ServiceClient(
wsdlLocation="http://localhost:7001/conv/ConversationalService?WSDL",
serviceName="ConversationalService",
portName="ConversationalServicePort")

private ConversationalPortType port;

@WebMethod
public void runConversation(String message) {

try {

// Invoke start operation
String result = port.start();
System.out.println("start method executed.");
System.out.println("The message is: " + result);

// Invoke continue operation
result = port.middle(message );
System.out.println("middle method executed.");
System.out.println("The message is: " + result);

// Invoke finish operation
result = port.finish(message );
System.out.println("finish method executed.");
System.out.println("The message is: " + result);
ConversationUtils.renewStub((Stub)port);

}
catch (RemoteException e) {
e.printStackTrace();
}

}

}

Follow these guidelines when programming the JWS file that invokes a conversational Web service; code snippets of the guidelines are shown in bold in the preceding example:

- Import the @ServiceClient JWS annotation:

import weblogic.jws.ServiceClient;

- Optionally import the WebLogic utility class for further configuring a conversation:

import weblogic.wsee.conversation.ConversationUtils;

- Import the JAX-RPC stub of the port type of the conversational Web service you want to invoke. The actual stub itself will be created later by the jwsc Ant task. The stub package is specified by the packageName attribute of the <clientgen> child element of <jws>, and the name of the stub is determined by the WSDL of the invoked Web service.

import examples.webservices.conversation.ConversationalPortType;

- In the body of the JWS file, use the @ServiceClient JWS annotation to specify the WSDL, name, and port of the conversational Web service you want to invoke. You specify this annotation at the field-level on a private variable, whose data type is the JAX-RPC port type of the Web service you are invoking.

@ServiceClient(
wsdlLocation="http://localhost:7001/conv/ConversationalService?WSDL",
serviceName="ConversationalService",
portName="ConversationalServicePort")

private ConversationalPortType port;

- Using the stub you annotated with the @ServiceClient annotation, invoke the start operation of the conversational Web service to start the conversation. You can invoke the start method from any location in the JWS file (constructor, method, and so on):

String result = port.start();

- Optionally invoke the continue methods to continue the conversation. Be sure you use the same stub instance so that you continue the same conversation you started:

result = port.middle(message );

- Once the conversation is completed, invoke the finish operation so that the conversational Web service can free up the resources it used for the current conversation:

result = port.finish(message );

- If you want to reuse the Web service conversation stub to start a new conversation, you must explicitly renew the stub using the renewStub() method of the weblogic.wsee.conversation.ConversationUtils utility class:

ConversationUtils.renewStub((Stub)port);

Note:

The client Web service that invokes a conversational Web service is not required to also be conversational. However, if the client is not conversational, there is a danger of multiple instances of this client accessing the same conversational Web service stub and possibly corrupting the saved conversational state. If you believe this might true in your case, then specify that the client Web service also be conversational.

ConversationUtils Utility Class

WebLogic Server provides a utility class for use with the conversation feature. Use this class to perform common tasks such as getting and setting the conversation ID and setting configuration options. Some of these tasks are performed in the conversational Web service, some are performed in the client that invokes the conversational Web service. See Programming Guidelines for the JWS File That Invokes a Conversational Web Service for an example of using this class.

See "weblogic.wsee.conversation.ConversationUtils" in Oracle WebLogic Server API Reference for details.

Updating the build.xml File for a Client of a Conversational Web Service

You update a build.xml file to generate the JWS file that invokes a conversational Web service by adding taskdefs and a build-clientService target that looks something like the following example. See the description after the example for details.

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

<jwsc
enableAsyncService="true"
srcdir="src"
destdir="${clientService-ear-dir}" >

<jws file="examples/webservices/conversation/ConversationalClientImpl.java" >
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/conv/ConversationalService?WSDL"
packageName="examples.webservices.conversation"/>

</jws>

</jwsc>

</target>

Use the taskdef Ant task to define the full classname of the jwsc Ant tasks.

Update the jwsc Ant task that compiles the client Web service to include a <clientgen> child element of the <jws> element so as to generate and compile the JAX-RPC stubs for the deployed ConversationalService Web service. The jwsc Ant task automatically packages them in the generated WAR file so that the client Web service can immediately access the stubs. You do this because the ConversationalClientImpl JWS file imports and uses one of the generated classes.

Updating a Stand-Alone Java Client to Invoke a Conversational Web Service

The following example shows a simple stand-alone Java client that invokes the conversational Web service described in Programming Guidelines for the Conversational JWS File. See the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.conv_standalone.client;

import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import weblogic.wsee.jaxrpc.WLStub;

/**
* stand-alone client that invokes and converses with ConversationlService.
*/

public class Main {

public static void main(String[] args)
throws ServiceException, RemoteException{

ConversationalService service = new ConversationalService_Impl(args[0] + "?WSDL");
ConversationalPortType port = service.getConversationalServicePort();

// Set property on stub to specify that client is invoking a Web service
// that uses advanced features; this property is automatically set if
// the client runs in a WebLogic Server instance.

Stub stub = (Stub)port;
stub._setProperty(WLStub.COMPLEX,  "true");

// Invoke start operation to begin the conversation
String result = port.start();
System.out.println("start method executed.");
System.out.println("The message is: " + result);

// Invoke continue operation
result = port.middle("middle" );
System.out.println("middle method executed.");
System.out.println("The message is: " + result);

// Invoke finish operation
result = port.finish("finish" );
System.out.println("finish method executed.");
System.out.println("The message is: " + result);

}

}

Follow these guidelines when programming the stand-alone Java client that invokes a conversational Web service. Code snippets of the guidelines are shown in bold in the preceding example.

- Import the weblogic.wsee.jaxrpc.WLStub class:

import weblogic.wsee.jaxrpc.WLStub;

- Set the WLStub.Complex property on the JAX-RPC stub of the ConversationalService using the _setProperty method:

Stub stub = (Stub)port;
stub._setProperty(WLStub.COMPLEX,  "true");

This property specifies to the Web services runtime that the client is going to invoke an advanced Web service, in this case a conversational one. This property is automatically set when invoking a conversational Web service from another WebLogic Web service.

- Invoke the start operation of the conversational Web service to start the conversation:

String result = port.start();

- Optionally invoke the continue methods to continue the conversation:

result = port.middle(message );

- Once the conversation is completed, invoke the finish operation so that the conversational Web service can free up the resources it used for the current conversation:

result = port.finish(message );

Example Conversational Web Service .NET Client

This section demonstrates how to create a .NET WSE3.0 client for a WebLogic conversational Web service. The example includes the following files:

- ConversationService.java -- JWS file that uses the @Conversation and @Callback annotations to implement a conversational Web service. ConversationService.java can optionally communicate results to its client via a callback.

- Service.cs -- The C# source file of the ConversationClient .NET Web service that acts as a client to the ConversationService Web service.
The sample .NET client can participate in conversations with ConversationService, as well as receiving results via callback.

- build.xml -- Ant build file that contains targets for building and deploying the Conversational Web service.

These files are described in detail in the sections that follow.

ConversationService.java File

The example ConversationService.java file is shown in Example 4-1. The example includes extensive comments that describe its function.

Example 4-1 ConversationService.java File

package conv;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;

import weblogic.jws.Conversation;
import weblogic.jws.Callback;
import weblogic.jws.CallbackService;

import java.io.Serializable;

/**
* Demonstrates use of the @Conversation annotation to manage the lifetime of the service
* and provide data persistence and message correlation.
*
* Remember that multiple clients might invoke a web service simultaneously.  When the
* web service stores data relevant to the client or calls additional services
* in order to process a client's request, the service must be able to process returned
* data from the external services in the context of the specific client it relates
* to.  This is all automatic when conversations are used.
*
* Remember that not all clients are capable of accepting callbacks.  Specifically,
* clients operating from behind firewalls may not be able to receive asynchronous
* callbacks.  You may wish to provide a synchronous interface, like this one,
* for such clients.  If a client can accept callbacks, it must send a callback endpoint refrence
* as part of any "start conversation" method invocation.
*
* To see the behavior in the Test View, invoke startRequest and then getRequestStatus
* several times quickly.
*/
@WebService(serviceName = "ConversationService", portName = "conversation", targetNamespace = "http://www.openuri.org/")
public class ConversationService implements Serializable {

@Callback
public CallbackInterface callback;
private boolean useCallbacks;
private int num;

/**
* Starts the conversation
*/
@Conversation(Conversation.Phase.START)
@WebMethod
public void startRequest(boolean useCallbacks) {
this.useCallbacks = useCallbacks;
}

@WebMethod
@Conversation(Conversation.Phase.CONTINUE)
public String getRequestStatus() {

num++;
if (num == 1)
return "This is the first time you call getRequestStatus method.";
if (num == 2 && useCallbacks) {
callback.onResultReady("finished");
return "This is the second time you call  getRequestStatus method, the conversation has been terminated automtically when the onResultReady callback method is invoked.";
} else
return "You have called getRequestStatus method " + num + " times";

}

/**
* Used to tell Conversation.jws that the current conversation is
* no longer needed.
*/
@WebMethod
@Conversation(Conversation.Phase.FINISH)
public void terminateRequest() {

}

@CallbackService(serviceName = "ConversationCallbackService")
public interface CallbackInterface {

/**
* Callback to invoke on the client when the external service
* returns its result. Will only be called it the client can
* accept callbacks and told us where to send them.
* <p/>
* If this callback is used, it implicitly terminates the
* conversation with no action required on the part of the
* client.
*/
@WebMethod
@Oneway
@Conversation(Conversation.Phase.FINISH)
public void onResultReady(String result);
}

}

Service.cs File

The example Service.cs file is shown in Example 4-2.

This conversation proxy file was created using the Microsoft WSDL to Proxy Class tool WseWsdl3.exe (see http://msdn.microsoft.com/en-us/library/aa529578.aspx) and the ConversationService Web service's WSDL file.

The example includes extensive comments that describe its function.

Example 4-2 Service.cs File

using System;
using System.Web;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Diagnostics;
using System.IO;
using System.Xml;
using Microsoft.Web.Services3.Addressing;
using Microsoft.Web.Services3;
using System.Collections.Generic;
using Microsoft.Web.Services3.Design;

[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class Service : System.Web.Services.WebService
{

public Service () {

//Uncomment the following line if using designed components
//InitializeComponent();
}

/*
* start invokes the Conversation web service's startRequest
* operation.
*
* Since the Conversation web service is conversational,
* we must also persist the ReplyTo endpoint reference SOAP header
* for subsequent calls.
*
* Since the Conversation web service can optionally communicate
* the result of it's work via a callback, we must prepare a
* second SOAP header CallbackTo SOAP header, which is the endpoint reference
* of the recipient to which callbacks should be sent.
*/
[WebMethod(EnableSession = true)]
public void start(Boolean useCallbacks, Boolean useIPAddress)
{
/*
* The Conversation proxy was created using .NET WSE3.0's WseWsdl3.exe
* application and the Conversation.jws's WSDL file.  The WSDL
* file for any WLS web service may be obtained
* by hitting the web service's URL with "?WSDL" appended to
* the end.  For example:
*
* http://somehost:7001/samples/async/Conversation.jws?WSDL
*
* WseWsdl3.exe produces a C# proxy class.  Place the resulting
* ConversationService.cs file in your .NET project, then use Visual
* Studio's Project->Add Existing Item menu action to "import"
* the class into the project.
*/
ConversationServiceSoapBinding conv;
String callbackLocation;
int asmxIndex;

/*
* Construct the callback URL from various pieces of
* server and HttpRequest info.
*/
Uri requestUrl = Context.Request.Url;

if (useIPAddress)
{
/*
* if useIPAddress is true, construct the callback address
* with the IP address of this host.
*/
callbackLocation = requestUrl.Scheme + "://" + System.Net.Dns.GetHostByName(requestUrl.Host).AddressList[0] +
":" + requestUrl.Port + requestUrl.AbsolutePath;
}
else
{
/*
* if useIPAddress is false, construct the callback address
* with the hostname of this host.
*/
callbackLocation = requestUrl.Scheme + "://" + requestUrl.Host +
":" + requestUrl.Port + requestUrl.AbsolutePath;
}

// Remove everything after ".asmx"
asmxIndex = callbackLocation.IndexOf(".asmx") + 5;
callbackLocation = callbackLocation.Remove(asmxIndex,
callbackLocation.Length - asmxIndex);

/*
* Create an instance of the proxy for the Conversation
* web service.
*
*/
conv = new ConversationServiceSoapBinding();

/*
* When callback is enabled, a custom callback header should be added into
* the outbound soap message.
*
*/
if (useCallbacks)
enableSoapFilterToAddCallbackHeader(conv, callbackLocation);

/*
* Invoke the startRequest method of the web service. The
* single boolean parameter determines whether the Conversation
* web service will use callbacks to communicate the result
* back to this client.
*
* If the argument is true, an onResultReady callback will
* be sent when the result is ready.  This client must implement
* a method with that name that expects the message shape defined
* by the target web service (returns void and accepts a single
* string argument).  See the onResultReady method below.
*
* If the argument to startRequest is false, callbacks will not
* be used and this client must use the getRequestStatus method
* to poll the Conversation web service for the result.
*/
conv.startRequest(useCallbacks);
/*
* Persist the ReplyTo header  in session state so that it can
* be used in other methods that take part in the conversation.
*
* This is not safe since one session could start multiple
* conversations, but there is no other apparent way to persist
* this information.  Member variables of WebService classes
* are not persisted across method invocations.
*/
Session["ConversationReplyTo"] = conv.ResponseSoapContext.Addressing.ReplyTo;

}

/* the CallbackTo header defintion isn't exposed by WLS9x/WLS10x callback service.
* So we need to use SOAPFilter to add the CallbackTo header.
*
*/
private static void enableSoapFilterToAddCallbackHeader(ConversationServiceSoapBinding conv, String callbackLocation)
{
//Create a custom policy.
Policy myPolicy = new Policy();
// Create a new policy assertion
MyPolicyAssertion myAssertion = new MyPolicyAssertion(callbackLocation);
// Add the assertion to the policy
myPolicy.Assertions.Add(myAssertion);
//Set the custom policy you have created on the client proxy
conv.SetPolicy(myPolicy);
}

/*
* getStatus invokes Conversation's getRequestStatus method.
* getRequestStatus is a polling method that is an alternative
* for web services that cannot recieve callbacks.
*
* Note that a conversation must be started with startRequest before
* this method may be invoked.  If not, or if this method is invoked
* outside of a conversation for any reason, it will get back a SOAP
* fault indicating that the conversation does not exist.
*/
[WebMethod(EnableSession = true)]
public String getStatus()
{
String result;

/*
* Create an instance of the proxy for the Conversation
* web service.  We could probably persist the proxy instance
* in session state, but chose not to.
*/
ConversationServiceSoapBinding conv = new ConversationServiceSoapBinding();

/*
* change the destination to the ReplyTo endpoint reference we cached on session state in
* the start method.
*/
conv.RequestSoapContext.Addressing.Destination = (EndpointReference)Session["ConversationReplyTo"];
/*
* Invoke the getRequestStatus method of the web service.
*/
result = conv.getRequestStatus();
return result;
}

/*
* finish invokes Conversation's terminateRequest method, which
* terminates the current conversation.
*
* Note that a conversation must be started with startRequest before
* this method may be invoked.  If not, or if this method is invoked
* outside of a conversation for any reason, it will get back a SOAP
* fault indicating that the conversation does not exist.
*/
[WebMethod(EnableSession = true)]
public void finish()
{
/*
* Create an instance of the proxy for the Conversation
* web service.  We could probably persist the proxy instance
* in session state, but chose not to.
*/
ConversationServiceSoapBinding conv = new ConversationServiceSoapBinding();

/*
* change the destination to the ReplyTo endpoint reference we cached on session state in
* the start method. Both "continue" and "finish" methods use the same destination.
*/
conv.RequestSoapContext.Addressing.Destination = (EndpointReference)Session["ConversationReplyTo"];
/*
* Invoke the terminateRequest method of the web service.
*/
conv.terminateRequest();
}

/*
* onResultReady is a callback handler for the onResultReady
* callback that Conversation.jws can optionally use to return
* its results.
*
* .NET WSE3.0 does not support callbacks directly, but a callback is just
* a method invocation message.  So if you construct a WebMethod with
* the same signature as the callback and set the XML namespace
* properly, it serves as a callback handler.
*
*/
[WebMethod]
[SoapDocumentMethod(OneWay = true,
Action = "http://www.openuri.org/ConversationService_CallbackInterface/onResultReady",
RequestElementName = "http://www.openuri.org/",
ResponseNamespace = "http://www.openuri.org/"
)]
public void onResultReady(String result)
{
/*
* When the callback is invoked, log a message to the
* hardcoded file c:\temp\ConversationClient.log.
*
* Note: if c:\temp does not exist on this server, an
* Exception will be raised.  Since it is not handled here,
* it will be returned as a SOAP fault to the Conversation
* web service.
*/
TextWriter output;
output = File.AppendText("c:\\temp\\ConversationClient.log");
String msg = "[" + DateTime.Now.ToString() + "] callback received";
output.WriteLine(msg);
output.Flush();
output.Close();
}

}

public class MyFilter : Microsoft.Web.Services3.SoapFilter
{
private String callbackLocation;

public MyFilter(String callbackLocation)
{
this.callbackLocation = callbackLocation;
}

public override SoapFilterResult ProcessMessage(SoapEnvelope envelope)
{

//create the CallbackTo soap element.
XmlDocument xmldoc = new XmlDocument();
XmlElement xmlEle = xmldoc.CreateElement("callback", "CallbackTo", "http://www.openuri.org/2006/03/callback");

//create the CallbackTo endpoint reference.
Address callbacto = new Address(new Uri(callbackLocation));
XmlElement xmlEle2 =new EndpointReference(callbacto).GetXml(xmldoc);
//add the CallbackTo endpoint reference into CallbackTo SOAP element.
xmlEle.AppendChild(xmlEle2.FirstChild);
//add the whole CallbackTo SOAP element into SOAP header.
XmlNode callbackheader = envelope.ImportNode(xmlEle, true);
envelope.DocumentElement.FirstChild.AppendChild(callbackheader);
return SoapFilterResult.Continue;

}
}

public class MyPolicyAssertion : Microsoft.Web.Services3.Design.PolicyAssertion
{
private String callbackLocation;

public MyPolicyAssertion(String callbackLocation)
{
this.callbackLocation = callbackLocation;
}

public override  SoapFilter CreateClientInputFilter(FilterCreationContext context)
{
return null;
}

public override  SoapFilter CreateClientOutputFilter(FilterCreationContext context)
{
//use MyFilter to add the CallbackTo header in the outbound soap message.
return new MyFilter(callbackLocation);
}

public override  SoapFilter CreateServiceInputFilter(FilterCreationContext context)
{
return null;
}

public override  SoapFilter CreateServiceOutputFilter(FilterCreationContext context)
{
return null;
}

}

build.xml File

The example build.xml file is shown in Example 4-3.

build.xml assumes that you copy the example source files to a new directory WL_HOME\samples\server\examples\src\examples\webservices\conv, where WL_HOME is the directory containing your WebLogic Server installation.

build.xml also requires that you first set your examples environment correctly via WL_HOME\samples\domains\wl_server>setExamplesEnv.cmd(sh and that the examples server is already started.

The example includes comments that describe the build file function and targets.

Example 4-3 build.xml File

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="webservices.conversation" default="all" basedir=".">

<!-- set global properties for this build -->
<property file="../../../examples.properties"/>

<property name="client.dir" value="${client.classes.dir}/webservices_conversation" />
<property name="package.dir" value="examples/webservices/conv"/>
<property name="package" value="examples.webservices.conv"/>
<property name="ear.dir" value="${examples.build.dir}/webservicesConversationEar" />

<path id="client.class.path">
<pathelement path="${java.class.path}"/>
</path>

<!-- Web service WLS Ant task definitions -->
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />

<target name="all" depends="build, deploy"/>

<target name="clean">
<delete dir="${ear.dir}"/>
</target>

<!-- Target that builds the conversational  Web service -->
<target name="build" description="Target that builds the MTOM Web service">
<jwsc
srcdir="${examples.src.dir}/${package.dir}"
sourcepath="${examples.src.dir}"
destdir="${ear.dir}"
classpath="${java.class.path}"
keepGenerated="true"
deprecation="${deprecation}"
debug="${debug}">
<jws file="ConversationService.java">
<WLHttpTransport contextPath="/samples/async" serviceURI="conversation.jws"/>
</jws>
</jwsc>
</target>

<!-- Target that deploys the conversational Web service -->
<target name="deploy" description="Target that deploys the conversational Web service">
<wldeploy
action="deploy"
source="${ear.dir}"
user="${wls.username}"
password="${wls.password}"
verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}"
failonerror="${failondeploy}"/>
</target>

<!-- Target that undeploys the conversational Web service -->
<target name="undeploy" description="Target that deploys the conversational Web service">
<wldeploy
action="undeploy"
name="webservicesConversationEar"
user="${wls.username}"
password="${wls.password}"
verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}"
failonerror="${failondeploy}"/>
</target>

</project>

Client Considerations When Redeploying a Conversational Web Service

WebLogic Server supports production redeployment, which means that you can deploy a new version of an updated conversational WebLogic Web service alongside an older version of the same Web service.

WebLogic Server automatically manages client connections so that only new client requests are directed to the new version. Clients already connected to the Web service during the redeployment continue to use the older version of the service until they complete their work, at which point WebLogic Server automatically retires the older Web service. If the client is connected to a conversational Web service, its work is considered complete when the existing conversation is explicitly ended by the client or because of a timeout.

For additional information about production redployment and Web service clients, see "Client Considerations When Redeploying a Web service" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

5 Creating Buffered Web Services

This chapter describes how to create buffered WebLogic Java API for XML-based RPC (JAX-RPC) Web services.

This chapter includes the following topics:

- Overview of Buffered Web Services

- Creating a Buffered Web Service: Main Steps

- Configuring the Host WebLogic Server Instance for the Buffered Web Service

- Programming Guidelines for the Buffered JWS File

- Programming the JWS File That Invokes the Buffered Web Service

- Updating the build.xml File for a Client of the Buffered Web Service

Overview of Buffered Web Services

When a buffered operation is invoked by a client, the method operation goes on a JMS queue and WebLogic Server deals with it asynchronously. As with Web service reliable messaging, if WebLogic Server goes down while the method invocation is still in the queue, it will be dealt with as soon as WebLogic Server is restarted. When a client invokes the buffered Web service, the client does not wait for a response from the invoke, and the execution of the client can continue.

Creating a Buffered Web Service: Main Steps

The following procedure describes how to create a buffered Web service and a client Web service that invokes an operation of the buffered Web service. The procedure shows how to create the JWS files that implement the two Web services from scratch. If you want to update existing JWS files, use this procedure as a guide. The procedure also shows how to configure the WebLogic Server instance that hosts the buffered Web service.

Note:

Unless you are also using the asynchronous request-response feature, you do not need to invoke a buffered Web service from another Web service, you can also invoke it from a stand-alone Java application.

It is assumed that you have set up an Ant-based development environment and that you have a working build.xml file to which you can add targets for running the jwsc Ant task and deploying the generated buffered Web service. It is further assumed that you have a similar setup for the WebLogic Server instance that hosts the client Web service that invokes the buffered Web service. For more information, see in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server:

- "Use Cases and Examples"

- "Developing WebLogic Web Services"

- "Programming the JWS File"

- "Invoking Web Services"

Table 5-1 Steps to Create a Buffered Web Service

#

Step

Description

1

Configure the WebLogic Server instance that hosts the buffered Web service.

See Configuring the Host WebLogic Server Instance for the Buffered Web Service.

2

Create a new JWS file, or update an existing one, that implements the buffered Web service.

Use your favorite IDE or text editor. See Programming Guidelines for the Buffered JWS File.

3

Update your build.xml file to include a call to the jwsc Ant task to compile the JWS file into a buffered Web service.

For example:

<jwsc
srcdir="src"
destdir="${service-ear-dir}" >
<jws
file="examples/webservices/async_buffered/AsyncBufferedImpl.java"
/>
</jwsc>

See "Running the jwsc WebLogic Web Services Ant Task" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server for general information about using the jwsc Ant task.

4

Recompile your JWS file by calling the appropriate target, then redeploy the Web service to the WebLogic Server.

For example:

prompt> ant build-clientService deploy-clientService

For more information about deployment, see See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

5

Create a new JWS file, or update an existing one, that implements the client Web service that invokes the buffered Web service.

See Programming the JWS File That Invokes the Buffered Web Service.

6

Update the build.xml file that builds the client Web service.

See Updating the build.xml File for a Client of the Buffered Web Service.

7

Recompile your client JWS file by calling the appropriate target, then redeploy the Web service to the client WebLogic Server.

For example:

prompt> ant build-clientService deploy-clientService

For more information about deployment, see See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Configuring the Host WebLogic Server Instance for the Buffered Web Service

Configuring the WebLogic Server instance on which the buffered Web service is deployed involves configuring JMS resources, such as JMS servers and modules, that are used internally by the Web services runtime.

You can configure these resources manually or you can use the Configuration Wizard to extend the WebLogic Server domain using a Web services-specific extension template. Using the Configuration Wizard greatly simplifies the required configuration steps; for details, see "Configuring Your Domain For Web Services Features" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Notes:

Alternatively, you can use WLST to configure the resources. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.

A domain that does not contain Web Services resources will still boot and operate correctly for non-Web services scenarios, and any Web Services scenario that does not involve asynchronous request and response. You will, however, see INFO messages in the server log indicating that asynchronous resources have not been configured and that the asynchronous response service for Web services has not been completely deployed.

If you prefer to configure the resources manually, perform the following steps.

Table 5-2 Steps to Configure Host WebLogic Server Instance Manually for the Buffered Web Service

#

Step

Description

1

Invoke the Administration Console for the domain that contains the host WebLogic Server instance.

To invoke the Administration Console in your browser, enter the following URL:

http://host:port/console

where

- host refers to the computer on which the Administration Server is running.

- port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.

See "Invoking the Administration Console" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

3

Create a JMS Server.

Create a JMS Server. If a JMS server already exists, you can use it if you do not want to create a new one.

See "Create JMS servers" in Oracle WebLogic Server Administration Console Help.

4

Create JMS module and define queue.

Create a JMS module, and then define a JMS queue in the module. If a JMS module already exists, you can use it if you do not want to create a new one. Target the JMS queue to the JMS server you created in the preceding step. Be sure you specify that this JMS queue is local, typically by setting the local JNDI name. See "Create JMS system modules" and "Create queues in a system module" in Oracle WebLogic Server Administration Console Help.

If you want the buffered Web service to use the default Web services queue, set the JNDI name of the JMS queue to weblogic.wsee.DefaultCallbackQueue. Otherwise, if you use a different JNDI name, be sure to use the @BufferQueue annotation in the JWS file to specify this JNDI name to the reliable Web service. See Programming Guidelines for the Buffered JWS File.

Clustering Considerations:

If you are using the Web service buffering feature in a cluster, you must:

- Create a local JMS queue, rather than a distributed queue, when creating the JMS queue.

- Explicitly target this JMS queue to each server in the cluster.

4

Tune your domain environment, as required. (Optional)

Review "Tuning Heavily Loaded Systems to Improve Web Service Performance" in WebLogic Server Performance and Tuning.

Programming Guidelines for the Buffered JWS File

The following example shows a simple JWS file that implements a buffered Web service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.buffered;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.MessageBuffer;
import weblogic.jws.BufferQueue;

@WebService(name="BufferedPortType",
serviceName="BufferedService",
targetNamespace="http://example.org")

@WLHttpTransport(contextPath="buffered",
serviceUri="BufferedService",
portName="BufferedPort")

// Annotation to specify a specific JMS queue rather than the default
@BufferQueue(name="my.jms.queue")

/**
* Simple buffered Web Service.
*/

public class BufferedImpl {

@WebMethod()
@MessageBuffer(retryCount=10, retryDelay="10 seconds")
@Oneway()
public void sayHelloNoReturn(String message) {
System.out.println("sayHelloNoReturn: " + message);

}
}

Follow these guidelines when programming the JWS file that implements a buffered Web service. Code snippets of the guidelines are shown in bold in the preceding example.

- Import the JWS annotations used for buffered Web services:

import javax.jws.Oneway;
import weblogic.jws.MessageBuffer;
import weblogic.jws.BufferQueue;

See the following bullets for guidelines on which JWS annotations are required.

- Optionally use the class-level @BufferQueue JWS annotation to specify the JNDI name of the JMS queue used internally by WebLogic Server when it processes a buffered invoke; for example:

@BufferQueue(name="my.jms.queue")

If you do not specify this JWS annotation, then WebLogic Server uses the default Web services JMS queue (weblogic.wsee.DefaultQueue).

You must create both the default JMS queue and any queues specified with this annotation before you can successfully invoke a buffered operation. See Configuring the Host WebLogic Server Instance for the Buffered Web Service for details.

- Use the @MessageBuffer JWS annotation to specify the operations of the Web service that are buffered. The annotation has two optional attributes:

- retryCount: The number of times WebLogic Server should attempt to deliver the message from the JMS queue to the Web service implementation (default 3).

- retryDelay: The amount of time that the server should wait in between retries (default 5 minutes).

For example:

@MessageBuffer(retryCount=10, retryDelay="10 seconds")

You can use this annotation at the class-level to specify that all operations are buffered, or at the method-level to choose which operations are buffered.

- If you plan on invoking the buffered Web service operation synchronously (or in other words, not using the asynchronous request-response feature), then the implementing method is required to be annotated with the @Oneway annotation to specify that the method is one-way. This means that the method cannot return a value, but rather, must explicitly return void. For example:

@Oneway()
public void sayHelloNoReturn(String message) {

Conversely, if the method is not annotated with the @Oneway annotation, then you must invoke it using the asynchronous request-response feature. If you are unsure how the operation is going to be invoked, consider creating two flavors of the operation: synchronous and asynchronous.

See Chapter 2, "Invoking a Web Service Using Asynchronous Request-Response," and Chapter 6, "Using the Asynchronous Features Together."

Programming the JWS File That Invokes the Buffered Web Service

You can invoke a buffered Web service from both a stand-alone Java application (if not using asynchronous request-response) and from another Web service. Unlike other WebLogic Web services asynchronous features, however, you do not use the @ServiceClient JWS annotation in the client Web service, but rather, you invoke the service as you would any other. For details, see "Invoking a Web Service from Another Web Service" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

The following sample JWS file shows how to invoke the sayHelloNoReturn operation of the BufferedService Web service:

package examples.webservices.buffered;

import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;

import javax.jws.WebService;
import javax.jws.WebMethod;

import weblogic.jws.WLHttpTransport;

import examples.webservices.buffered.BufferedPortType;
import examples.webservices.buffered.BufferedService_Impl;
import examples.webservices.buffered.BufferedService;

@WebService(name="BufferedClientPortType",
serviceName="BufferedClientService",
targetNamespace="http://examples.org")

@WLHttpTransport(contextPath="bufferedClient",
serviceUri="BufferedClientService",
portName="BufferedClientPort")

public class BufferedClientImpl {

@WebMethod()
public String callBufferedService(String input, String serviceUrl)
throws RemoteException {

try {

BufferedService service = new BufferedService_Impl(serviceUrl + "?WSDL");
BufferedPortType port = service.getBufferedPort();

// Invoke the sayHelloNoReturn() operation of BufferedService

port.sayHelloNoReturn(input);

return "Invoke went okay!";

} catch (ServiceException se) {

System.out.println("ServiceExcpetion thrown");
throw new RuntimeException(se);

}
}
}

Updating the build.xml File for a Client of the Buffered Web Service

To update a build.xml file to generate the JWS file that invokes a buffered Web service operation, add taskdefs and a build-clientService targets that look something like the following example. See the description after the example for details.

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

<jwsc
enableAsyncService="true"
srcdir="src"
destdir="${clientService-ear-dir}" >

<jws file="examples/webservices/buffered/BufferedClientImpl.java">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/buffered/BufferedService?WSDL"
packageName="examples.webservices.buffered"/>

</jws>

</jwsc>

</target>

Use the taskdef Ant task to define the full classname of the jwsc Ant tasks.

Update the jwsc Ant task that compiles the client Web service to include a <clientgen> child element of the <jws> element so as to generate and compile the JAX-RPC stubs for the deployed BufferedService Web service. The jwsc Ant task automatically packages them in the generated WAR file so that the client Web service can immediately access the stubs. You do this because the BufferedClientImpl JWS file imports and uses one of the generated classes.

6 Using the Asynchronous Features Together

This chapter describes how to use the asynchronous features together with WebLogic Java API for XML-based RPC (JAX-RPC) Web services.

This chapter includes the following topics:

- Using the Asynchronous Features Together

- Example of a JWS File That Implements a Reliable Conversational Web Service

- Example of Client Web Service That Asynchronously Invokes a Reliable Conversational Web Service

Using the Asynchronous Features Together

The preceding sections describe how to use the WebLogic Web service asynchronous features (Web service reliable messaging, conversations, asynchronous request-response, and buffering) on their own. Typically, however, Web services use the features together; see Example of a JWS File That Implements a Reliable Conversational Web Service and Example of Client Web Service That Asynchronously Invokes a Reliable Conversational Web Service for examples.

When used together, some restrictions described in the individual feature sections do not apply, and sometimes additional restrictions apply. The following table summarizes considerations for various feature combinations.

Table 6-1 Considerations When Using Asynchronous Features Together

Feature Combination

Consideration

Asynchronous request-response with Web service reliable messaging or buffering

- The asynchronous response from the reliable Web service is also reliable. This means that you must also configure a JMS server, module, and queue on the source WebLogic Server instance, in a similar way you configured the destination WebLogic Server instance, to handle the response.
When you create the JMS queue on the source WebLogic Server instance, you are required to specify a JNDI name of weblogic.wsee.DefaultQueue; you can name the queue anything you want. You must also ensure that you specify that this JMS queue is local, typically by setting the local JNDI name.

- The reliable or buffered operation cannot be one-way; in other words, you cannot annotate the implementing method with the @Oneway annotation.

Asynchronous request-response with Web service reliable messaging

If you set a property in one of the asynchronous contexts (AsyncPreCallContext or AsyncPostCallContext), then the property must implement java.io.Serializable.

Asynchronous request-response with buffering

You must use the @ServiceClient JWS annotation in the client Web service that invokes the buffered Web service operation.

Conversations with Web service reliable messaging

- JWS conversations are not the same as reliable sequences, and are not linked in any way. You must consider the management of reliable sequences separately from the life cycle of a conversation. For example, when using reliable messaging to send messages between a client service and a reliable and conversational service, finishing the conversation does not terminate the reliable sequence. You must explicitly cause the reliable sequence to be terminated (using WsrmUtils.setFinalMessage() or other acceptable method) or allows the reliable sequence to remain active until it expires when the sequence lifetime is exceeded). For more information about reliable message sequence life cycle, see Managing the Life Cycle of the Reliable Message Sequence.

- If you set the property WLStub.CONVERSATIONAL_METHOD_BLOCK_TIMEOUT on the stub of the client Web service, the property is ignored because the client does not block.

- At least one method of the reliable conversational Web service must not be marked with the @Oneway annotation.

Conversations with asynchronous request-response

Asynchronous responses between a client conversational Web service and any other Web service also participate in the conversation. For example, assume WebServiceA is conversational, and it invokes WebServiceB using asynchronous request-response. Because WebServiceA is conversational the asynchronous responses from WebServiceB also participates in the same conversation.

Example of a JWS File That Implements a Reliable Conversational Web Service

The following sample JWS file implements a Web service that is both reliable and conversational:

package examples.webservices.async_mega;

import java.io.Serializable;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Conversation;
import weblogic.jws.Policy;

import javax.jws.WebService;
import javax.jws.WebMethod;

@WebService(name="AsyncMegaPortType",
serviceName="AsyncMegaService",
targetNamespace="http://examples.org/")

@Policy(uri="AsyncReliableConversationPolicy.xml",
attachToWsdl=true)

@WLHttpTransport(contextPath="asyncMega",
serviceUri="AsyncMegaService",
portName="AsyncMegaServicePort")

/**
* Web Service that is both reliable and conversational.
*/

public class AsyncMegaServiceImpl implements Serializable {

@WebMethod
@Conversation (Conversation.Phase.START)
public String start() {
return "Starting conversation";
}

@WebMethod
@Conversation (Conversation.Phase.CONTINUE)
public String middle(String message) {
return "Middle of conversation; the message is: " + message;
}

@WebMethod
@Conversation (Conversation.Phase.FINISH)
public String finish(String message ) {
return "End of conversation; the message is: " + message;
}

}

Example of Client Web Service That Asynchronously Invokes a Reliable Conversational Web Service

The following JWS file shows how to implement a client Web service that reliably invokes the various conversational methods of the Web service described in Example of a JWS File That Implements a Reliable Conversational Web Service; the client JWS file uses the asynchronous request-response feature as well.

package examples.webservices.async_mega;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.AsyncResponse;
import weblogic.jws.AsyncFailure;

import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.xml.rpc.Stub;

import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPostCallContext;
import weblogic.wsee.reliability.WsrmUtils;

import examples.webservices.async_mega.AsyncMegaPortType;
import examples.webservices.async_mega.AsyncMegaService;
import examples.webservices.async_mega.AsyncMegaService_Impl;

import java.rmi.RemoteException;

@WebService(name="AsyncMegaClientPortType",
serviceName="AsyncMegaClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="asyncMegaClient",
serviceUri="AsyncMegaClient",
portName="AsyncMegaClientServicePort")

/**
* Client Web Service that has a conversation with the AsyncMegaService
* reliably and asynchronously.
*/

public class AsyncMegaClientImpl {

@ServiceClient(
wsdlLocation="http://localhost:7001/asyncMega/AsyncMegaService?WSDL",
serviceName="AsyncMegaService",
portName="AsyncMegaServicePort")

private AsyncMegaPortType port;

@WebMethod
public void runAsyncReliableConversation(String message) {

AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
apc.setProperty("message", message);

try {
port.startAsync(apc);
System.out.println("start method executed.");

port.middleAsync(apc, message );
System.out.println("middle method executed.");

// Since this service is not conversational, any state kept in the port
// field will be lost when this method returns. In the case of reliable
// messaging, this state includes the ID of the reliable sequence being
// used to send messages. The setFinalMessage method specifies
// that this is the final message to be sent on this sequence. This
// will allow the reliable messaging subsystem to proactively clean up
// the reliable sequence instead of timing out.
WsrmUtils.setFinalMessage((Stub)port);
port.finishAsync(apc, message );
System.out.println("finish method executed.");

}
catch (RemoteException e) {
e.printStackTrace();
}

}

@AsyncResponse(target="port", operation="start")
public void onStartAsyncResponse(AsyncPostCallContext apc, String message) {
System.out.println("-------------------");
System.out.println("Got message " + message );
System.out.println("-------------------");
}

@AsyncResponse(target="port", operation="middle")
public void onMiddleAsyncResponse(AsyncPostCallContext apc, String message) {
System.out.println("-------------------");
System.out.println("Got message " + message );
System.out.println("-------------------");
}

@AsyncResponse(target="port", operation="finish")
public void onFinishAsyncResponse(AsyncPostCallContext apc, String message) {
System.out.println("-------------------");
System.out.println("Got message " + message );
System.out.println("-------------------");
}

@AsyncFailure(target="port", operation="start")
public void onStartAsyncFailure(AsyncPostCallContext apc, Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}

@AsyncFailure(target="port", operation="middle")
public void onMiddleAsyncFailure(AsyncPostCallContext apc, Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}

@AsyncFailure(target="port", operation="finish")
public void onFinishAsyncFailure(AsyncPostCallContext apc, Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}
}

7 Using Callbacks to Notify Clients of Events

This chapter describes how to callbacks with WebLogic Java API for XML-based RPC (JAX-RPC) Web services to notify clients of events.

This chapter includes the following topics:

- Overview of Callbacks

- Callback Implementation Overview and Terminology

- Programming Callbacks: Main Steps

- Programming Guidelines for Target Web Service

- Programming Guidelines for the Callback Client Web Service

- Programming Guidelines for the Callback Interface

- Updating the build.xml File for the Client Web Service

Overview of Callbacks

Callbacks notify a client of your Web service that some event has occurred. For example, you can notify a client when the results of that client's request are ready, or when the client's request cannot be fulfilled.

When you expose a method as a standard public operation in your JWS file (by using the @WebMethod annotation), the client sends a SOAP message to the Web service to invoke the operation. When you add a callback to a Web service, however, you define a message that the Web service sends back to the client Web service, notifying the client of an event that has occurred. So exposing a method as a public operation and defining a callback are completely symmetrical processes, with opposite recipients.

WebLogic Server automatically routes the SOAP message from client invoke to the target Web service. In order to receive callbacks, however, the client must be operating in an environment that provides the same services. This typically means the client is a Web service running on a Web server. If the client does not meet these requirements, it is likely not capable of receiving callbacks from your Web service.

The protocol and message format used for callbacks is always the same as the protocol and message format used by the conversation start method that initiated the current conversation. If you attempt to override the protocol or message format of a callback, an error is thrown.

Callback Implementation Overview and Terminology

To implement callbacks, you must create or update the following three Java files:

- Callback interface: Java interface file that defines the callback methods. You do not explicitly implement this file yourself; rather, the jwsc Ant task automatically generates an implementation of the interface. The implementation simply passes a message from the target Web service back to the client Web service. The generated Web service is deployed to the same WebLogic Server that hosts the client Web service.
In the example in this section, the callback interface is called CallbackInterface. The interface defines a single callback method called callbackOperation().

- JWS file that implements the target Web service: The target Web service includes one or more standard operations that invoke a method defined in the callback interface; this method in turn sends a message back to the client Web service that originally invoked the operation of the target Web service.
In the example, this Web service is called TargetService and it defines a single standard method called targetOperation().

- JWS file that implements the client Web service: The client Web service invokes an operation of the target Web service. This Web service includes one or more methods that specify what the client should do when it receives a callback message back from the target Web service via a callback method.
In the example, this Web service is called CallbackClient and the method that is automatically invoked when it receives a callback is called callbackHandler(). The method that invokes TargetService in the standard way is called clientOperation().

The following graphic shows the flow of messages:

1. The clientOperation() method of the CallbackClient Web service, running in one WebLogic Server instance, explicitly invokes the targetOperation() operation of the TargetService. The TargetService service might be running in a separate WebLogic Server instance.

2. The implementation of the TargetService.targetOperation() method explicitly invokes the callbackOperation() operation of the CallbackInterface, which implements the callback service. The callback service is deployed to the WebLogic Server which hosts the client Web service.

3. The jwsc-generated implementation of the CallbackInterface.callbackOperation() method simply sends a message back to the CallbackClient Web service. The client Web service includes a method callbackHandler() that handles this message.

Programming Callbacks: Main Steps

The procedure in this section describes how to program and compile the three JWS files that are required to implement callbacks: the target Web service, the client Web service, and the callback interface. The procedure shows how to create the JWS files from scratch; if you want to update existing JWS files, you can also use this procedure as a guide.

It is assumed that you have set up an Ant-based development environment and that you have a working build.xml file to which you can add targets for running the jwsc Ant task and deploying the Web services. For more information, see Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Table 7-1 Steps to Program Callbacks

#

Step

Description

1

Create a new JWS file, or update an existing one, that implements the target Web service.

Use your favorite IDE or text editor. See Programming Guidelines for Target Web Service.

Note: The JWS file that implements the target Web service invokes one or more callback methods of the callback interface. However, the step that describes how to program the callback interface comes later in this procedure. For this reason, programmers typically program the three JWS files at the same time, rather than linearly as implied by this procedure. The steps are listed in this order for clarity only.

2

Update your build.xml file to include a call to the jwsc Ant task to compile the target JWS file into a Web service.

See "Running the jwsc WebLogic Web Services Ant Task" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

3

Run the Ant target to build the target Web service.

For example:

prompt> ant build-mainService

4

Deploy the target Web service as usual.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

5

Create a new JWS file, or update an existing one, that implements the client Web service.

It is assumed that the client Web service is deployed to a different WebLogic Server instance from the one that hosts the target Web service. See Programming Guidelines for the Callback Client Web Service.

6

Create the callback JWS interface that implements the callback Web service.

See Programming Guidelines for the Callback Interface.

7

Update the build.xml file that builds the client Web service.

The jwsc Ant task that builds the client Web service also implicitly generates the callback Web service from the callback interface file. See Updating the build.xml File for the Client Web Service.

8

Run the Ant target to build the client and callback Web services.

For example:

prompt> ant build-clientService

9

Deploy the client Web service as usual.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Programming Guidelines for Target Web Service

The following example shows a simple JWS file that implements the target Web service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.callback;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Callback;

import javax.jws.WebService;
import javax.jws.WebMethod;

@WebService(name="CallbackPortType",
serviceName="TargetService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="callback",
serviceUri="TargetService",
portName="TargetServicePort")

/**
* callback service
*/

public class TargetServiceImpl {

@Callback
CallbackInterface callback;

@WebMethod
public void targetOperation (String message) {

callback.callbackOperation (message);
}

}

Follow these guidelines when programming the JWS file that implements the target Web service. Code snippets of the guidelines are shown in bold in the preceding example.

- Import the required JWS annotations:

import weblogic.jws.Callback;

- Use the @weblogic.jws.Callback JWS annotation to specify that a variable is a callback, which means that you can use the annotated variable to send callback events back to a client Web service that invokes an operation of the TargetService Web service. The data type of the variable is the callback interface, which in this case is called CallbackInterface.

@Callback
CallbackInterface callback;

- In a method that implements an operation of the TargetService, use the annotated variable to invoke one of the callback methods of the callback interface, which in this case is called callbackOperation():

callback.callbackOperation (message);

See "JWS Annotation Reference" in WebLogic Web Services Reference for Oracle WebLogic Server for additional information about the WebLogic-specific JWS annotations discussed in this section.

Programming Guidelines for the Callback Client Web Service

The following example shows a simple JWS file for a client Web service that invokes the target Web service described in Programming Guidelines for Target Web Service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.callback;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.CallbackMethod;
import weblogic.jws.security.CallbackRolesAllowed;
import weblogic.jws.security.SecurityRole;

import javax.jws.WebService;
import javax.jws.WebMethod;

import examples.webservices.callback.CallbackPortType;

import java.rmi.RemoteException;

@WebService(name="CallbackClientPortType",
serviceName="CallbackClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="callbackClient",
serviceUri="CallbackClient",
portName="CallbackClientPort")

public class CallbackClientImpl {

@ServiceClient(
wsdlLocation="http://localhost:7001/callback/TargetService?WSDL",
serviceName="TargetService",
portName="TargetServicePort")
@CallbackRolesAllowed(@SecurityRole(role="mgr", mapToPrincipals="joe"))
private CallbackPortType port;

@WebMethod
public void clientOperation (String message) {

try {

port.targetOperation(message);
}
catch (RemoteException e) {
e.printStackTrace();
}

}
@CallbackMethod(target="port", operation="callbackOperation")
@CallbackRolesAllowed(@SecurityRole(role="engineer",  mapToPrincipals="shackell"))
public void callbackHandler(String msg) {

System.out.println (msg);
}

}

Follow these guidelines when programming the JWS file that invokes the target Web service; code snippets of the guidelines are shown in bold in the preceding example:

- Import the required JWS annotations:

import weblogic.jws.ServiceClient;
import weblogic.jws.CallbackMethod;

- Optionally import the security-related annotations if you want to specify the roles that are allowed to invoke the callback methods:

import weblogic.jws.security.CallbackRolesAllowed;
import weblogic.jws.security.SecurityRole;

- Import the JAX-RPC stub of the port type of the target Web service you want to invoke. The actual stub itself will be created later by the jwsc Ant task. The stub package is specified by the packageName attribute of the <clientgen> child element of <jws>, and the name of the stub is determined by the WSDL of the invoked Web service.

import examples.webservices.callback.CallbackPortType;

- In the body of the JWS file, use the @ServiceClient JWS annotation to specify the WSDL, name, and port of the target Web service you want to invoke. You specify this annotation at the field-level on a private variable, whose data type is the JAX-RPC port type of the Web service you are invoking.

@ServiceClient(
wsdlLocation="http://localhost:7001/callback/TargetService?WSDL",
serviceName="TargetService",
portName="TargetServicePort")
@CallbackRolesAllowed(@SecurityRole(role="mgr", mapToPrincipals="joe"))
private CallbackPortType port;

The preceding code also shows how to use the optional @CallbackRolesAllowed annotation to specify the list of @SecurityRoles that are allowed to invoke the callback methods.

- Using the variable you annotated with the @ServiceClient annotation, invoke an operation of the target Web service. This operation in turn will invoke a callback method of the callback interface:

port.targetOperation(message);

- Create a method that will handle the callback message received from the callback service. You can name this method anything you want. However, its signature should exactly match the signature of the corresponding method in the callback interface.
Annotate the method with the @CallbackMethod annotation to specify that this method handles callback messages. Use the target attribute to specify the name of the JAX-RPC port for which you want to receive callbacks (in other words, the variable you previously annotated with @ServiceClient). Use the operation attribute to specify the name of the callback method in the callback interface from which this method will handle callback messages.

@CallbackMethod(target="port", operation="callbackOperation")
@CallbackRolesAllowed(@SecurityRole(role="engineer",  mapToPrincipals="shackell"))
public void callbackHandler(String msg) {
System.out.println (msg);
}

The preceding code also shows how to use the optional @CallbackRolesAllowed annotation to further restrict the security roles that are allowed to invoke this particular callback method.

See "JWS Annotation Reference" in WebLogic Web Services Reference for Oracle WebLogic Server for additional information about the WebLogic-specific JWS annotations discussed in this section.

Programming Guidelines for the Callback Interface

The callback interface is also a JWS file that implements a Web service, except for one big difference: instead of using the standard @javax.jws.WebService annotation to specify that it is a standard Web service, you use the WebLogic-specific @weblogic.jws.CallbackService to specify that it is a callback service. The attributes of @CallbackService are a restricted subset of the attributes of @WebService.

Follow these restrictions on the allowed data types and JWS annotations when programming the JWS file that implements a callback service:

- You cannot use any WebLogic-specific JWS annotations other than @weblogic.jws.CallbackService.

- You can use all standard JWS annotations except for the following:

- javax.jws.HandlerChain

- javax.jws.soap.SOAPMessageHandler

- javax.jws.soap.SOAPMessageHandlers

- You can use all supported data types as parameters or return values except Holder classes (user-defined data types that implement the javax.xml.rpc.holders.Holder interface).

The following example shows a simple callback interface file that implements a callback Web service. The target Web service, described in Programming Guidelines for Target Web Service, explicitly invokes a method in this interface. The jwsc-generated implementation of the callback interface then automatically sends a message back to the client Web service that originally invoked the target Web service; the client service is described in Programming Guidelines for the Callback Client Web Service. See the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.callback;

import weblogic.jws.CallbackService;

import javax.jws.Oneway;
import javax.jws.WebMethod;

@CallbackService
public interface CallbackInterface {

@WebMethod
@Oneway
public void callbackOperation (String msg);

}

Follow these guidelines when programming the JWS interface file that implements the callback Web service. Code snippets of the guidelines are shown in bold in the preceding example.

- Import the required JWS annotation:

import weblogic.jws.CallbackService;

- Annotate the interface declaration with the @CallbackService annotation to specify that the JWS file implements a callback service:

@CallbackService
public interface CallbackInterface {

- Create a method that the target Web service explicitly invokes; this is the method that automatically sends a message back to the client service that originally invoked the target Web service. Because this is a Java interface file, you do not provide an implementation of this method. Rather, the WebLogic Web services runtime generates an implementation of the method via the jwsc Ant task.

public void callbackOperation (String msg);

Note:

Although the example shows the callback method returning void and annotated with the @Oneway annotation, this is not a requirement.

See "JWS Annotation Reference" in WebLogic Web Services Reference for Oracle WebLogic Server for additional information about the WebLogic-specific JWS annotations discussed in this section.

Updating the build.xml File for the Client Web Service

When you run the jwsc Ant task against the JWS file that implements the client Web service, the task implicitly also generates the callback Web service, as described in this section.

You update a build.xml file to generate a client Web service that invokes the target Web service by adding taskdefs and a build-clientService target that looks something like the following example. See the description after the example for details.

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

<jwsc
srcdir="src"
destdir="${clientService-ear-dir}" >

<jws file="examples/webservices/callback/CallbackClientImpl.java" >

<clientgen
wsdl="http://${wls.hostname}:${wls.port}/callback/TargetService?WSDL"
packageName="examples.webservices.callback"
serviceName="TargetService" />

</jws>

</jwsc>

</target>

Use the taskdef Ant task to define the full classname of the jwsc Ant tasks.

Update the jwsc Ant task that compiles the client Web service to include a <clientgen> child element of the <jws> element so as to generate and compile the JAX-RPC stubs for the deployed TargetService Web service. The jwsc Ant task automatically packages them in the generated WAR file so that the client Web service can immediately access the stubs. You do this because the CallbackClientImpl JWS file imports and uses one of the generated classes.

Because the WSDL of the target Web service includes an additional <service> element that describes the callback Web service (which the target Web service invokes), the <clientgen> child element of the jwsc Ant task also generates and compiles the callback Web service and packages it in the same EAR file as the client Web service.

8 Using JMS Transport as the Connection Protocol

This chapter describes how to use JMS transport as the connection protocol with WebLogic Java API for XML-based RPC (JAX-RPC) Web service using asynchronous request-response.

This chapter includes the following topics:

- Overview of Using JMS Transport

- Using JMS Transport Starting From Java: Main Steps

- Using JMS Transport Starting From WSDL: Main Steps

- Configuring the Host WebLogic Server Instance for the JMS Transport Web Service

- Using the @WLJmsTransport JWS Annotation

- Using the <WLJmsTransport> Child Element of the jwsc Ant Task

- Invoking a WebLogic Web Service Using JMS Transport

Overview of Using JMS Transport

Typically, client applications use HTTP/S as the connection protocol when invoking a WebLogic Web service. You can, however, configure a WebLogic Web service so that client applications use JMS as the transport instead.

Using JMS transport offers the following benefits: reliability, scalability, and quality of service. As with Web service reliable messaging, if WebLogic Server goes down while the method invocation is still in the queue, it will be dealt with as soon as WebLogic Server is restarted. When a client invokes a Web service, the client does not wait for a response from the invoke, and the execution of the client can continue. Using JMS transport does require slightly more overhead and programming complexity than HTTP/S.

You configure transports using either JWS annotations or child elements of the jwsc Ant task, as described in later sections. When a WebLogic Web service is configured to use JMS as the connection transport, the endpoint address specified for the corresponding port in the generated WSDL of the Web service uses jms:// in its URL rather than http://. An example of a JMS endpoint address is as follows:

jms://myHost:7001/transports/JMSTransport?URI=JMSTransportQueue

The URI=JMSTransportQueue section of the URL specifies the JMS queue that has been configured for the JMS transport feature. Although you cannot invoke the Web service using HTTP, you can view its WSDL using HTTP, which is how the clientgen is still able to generate JAX-RPC stubs for the Web service.

For each transport that you specify, WebLogic Server generates an additional port in the WSDL. For this reason, if you want to give client applications a choice of transports they can use when they invoke the Web service (JMS, HTTP, or HTTPS), you should explicitly add the transports using the appropriate JWS annotations or child elements of jwsc.

Note:

Using JMS transport is an added-value WebLogic feature; non-WebLogic client applications, such as a .NET client, may not be able to invoke the Web service using the JMS port.

Using JMS Transport Starting From Java: Main Steps

To use JMS transport when starting from Java, you must perform at least one of the following tasks:

- Add the @WLJmsTransport annotation to your JWS file.

- Add a <WLJmsTransport> child element to the jwsc Ant task. This setting overrides the transports defined in the JWS file.

Note:

Because you might not know at the time that you are coding the JWS file which transport best suits your needs, it is often better to specify the transport at build-time using the <WLJmsTransport> child element.

The following procedure describes the complete set of steps required so that your Web service can be invoked using the JMS transport when starting from Java.

Note:

It is assumed that you have created a basic JWS file that implements a Web service and that you want to configure the Web service to be invoked using JMS. It is also assumed that you have set up an Ant-based development environment and that you have a working build.xml file that includes targets for running the jwsc Ant task and deploying the service. For more information, see Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Table 8-1 Steps to Use JMS Transport Starting From Java

#

Step

Description

1

Configure the WebLogic Server domain for the required JMS components.

See Configuring the Host WebLogic Server Instance for the JMS Transport Web Service.

2

Add the @WLJmsTransport annotation to your JWS file. (Optional)

This step is optional. If you do not add the @WLJmsTransport annotation to your JWS file, then you must add a <WLJmsTransport> child element to the jwsc Ant task, as described in Step 3.

See Using the @WLJmsTransport JWS Annotation.

3

Add a <WLJmsTransport> child element to the jwsc Ant task. (Optional)

Use the <WLJmsTransport> child element to override the transports defined in the JWS file. This step is required if you did not add the @WLJmsTransport annotation to your JWS file in Step 2. Otherwise, this step is optional.

See Using the <WLJmsTransport> Child Element of the jwsc Ant Task for details.

4

Build your Web service by running the target in the build.xml Ant file that calls the jwsc task.

For example, if the target that calls the jwsc Ant task is called build-service, then you would run:

prompt> ant build-service

See "Running the jwsc WebLogic Web Services Ant Task" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

5

Deploy your Web service to WebLogic Server.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

See Invoking a WebLogic Web Service Using JMS Transport for information about updating your client application to invoke the Web service using JMS transport.

Using JMS Transport Starting From WSDL: Main Steps

To use JMS transport when starting from WSDL, you must perform at least one of the following tasks:

- Update the WSDL to use JMS transport before running the wsdlc Ant task.

- Update the stubbed-out JWS implementation file generated by the wsdlc Ant task to add the @WLJmsTransport annotation.

- Add a <WLJmsTransport> child element to the jwsc Ant task used to build the JWS implementation file. This setting overrides the transports defined in the JWS file.

Note:

Because you might not know at the time that you are coding the JWS file which transport best suits your needs, it is often better to specify the transport at build-time using the <WLJmsTransport> child element.

The following procedure describes the complete set of steps required so that your Web service can be invoked using the JMS transport when starting from WSDL.

Note:

It is assumed in this procedure that you have an existing WSDL file.

Table 8-2 Steps to Use JMS Transport Starting From WSDL

#

Step

Description

1

Configure the WebLogic Server domain for the required JMS components.

See Configuring the Host WebLogic Server Instance for the JMS Transport Web Service.

2

Update the WSDL to use JMS transport. (Optional)

This step is optional. If you do not update the WSDL to use JMS transport, then you must do at least one of the following:

- Edit the stubbed out JWS file to add the @WLJmsTransport annotation to your JWS file, as described in Step 4.

- Add a <WLJmsTransport> child element to the jwsc Ant task, as described in Step 5.

See Updating the WSDL to Use JMS Transport.

3

Run the wsdlc Ant task against the WSDL file.

For example, if the target that calls the wsdlc Ant task is called generate-from-wsdl, then you would run:

prompt> ant generate-from-wsdl

See "Running the wsdlc WebLogic Web Services Ant Task" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

4

Update the stubbed-out JWS file.

The wsdlc Ant task generates a stubbed-out JWS file.You need to add your business code to the Web service so it behaves as you want. See "Updating the Stubbed-out JWS Implementation Class File Generated by wsdlc" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

If you updated the WSDL to use the JMS transport in Step 2, the JWS file includes the @WLJmsTransport annotation that defines the JMS transport. If the @WLJmsTransport annotation is not included in the JWS file, you must do at least one of the following:

- Edit the JWS file to add the @WLJmsTransport annotation to your JWS file, as described in Using the @WLJmsTransport JWS Annotation.

- Add a <WLJmsTransport> child element to the jwsc Ant task, as described in Step 5.

5

Add a <WLJmsTransport> child element to the jwsc Ant task. (Optional)

Use the <WLJmsTransport> child element to override the transports defined in the JWS file. This step is required if the JWS file does not include the @WLJmsTransport annotation, as noted in Step 4. Otherwise, this step is optional.

See Using the <WLJmsTransport> Child Element of the jwsc Ant Task for details.

6

Run the jwsc Ant task against the JWS file to build the Web service.

Specify the artifacts generated by the wsdlc Ant task as well as your updated JWS implementation file, to generate an Enterprise Application that implements the Web service. See "Running the jwsc WebLogic Web Services Ant Task" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

7

Deploy the Web service to WebLogic Server.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

See Invoking a WebLogic Web Service Using JMS Transport for information about updating your client application to invoke the Web service using JMS transport.

Configuring the Host WebLogic Server Instance for the JMS Transport Web Service

Configuring the WebLogic Server instance on which the JMS transport Web service is deployed involves configuring JMS resources, such as JMS servers and modules, that are used internally by the Web services runtime.

You can configure these resources manually or you can use the Configuration Wizard to extend the WebLogic Server domain using a Web services-specific extension template. Using the Configuration Wizard greatly simplifies the required configuration steps; for details, see "Configuring Your Domain For Web Services Features" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Notes:

Alternatively, you can use WLST to configure the resources. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.

A domain that does not contain Web Services resources will still boot and operate correctly for non-Web services scenarios, and any Web Services scenario that does not involve asynchronous request and response. You will, however, see INFO messages in the server log indicating that asynchronous resources have not been configured and that the asynchronous response service for Web services has not been completely deployed.

If you prefer to configure the resources manually, perform the following steps.

Table 8-3 Steps to Configure Host WebLogic Server Instance Manually for the JMS Transport Web Service

#

Step

Description

1

Invoke the Administration Console for the domain that contains the host WebLogic Server instance.

To invoke the Administration Console in your browser, enter the following URL:

http://host:port/console

where

- host refers to the computer on which the Administration Server is running.

- port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.

See "Invoking the Administration Console" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

3

Create a JMS Server.

Create a JMS Server. If a JMS server already exists, you can use it if you do not want to create a new one.

See "Create JMS servers" in Oracle WebLogic Server Administration Console Help.

4

Create JMS module and define queue.

Create a JMS module, and then define a JMS queue in the module. If a JMS module already exists, you can use it if you do not want to create a new one. Target the JMS queue to the JMS server you created in the preceding step. Be sure you specify that this JMS queue is local, typically by setting the local JNDI name. See "Create JMS system modules" and "Create queues in a system module" in Oracle WebLogic Server Administration Console Help.

If you want the JMS transport Web service to use the default Web services queue, set the JNDI name of the JMS queue to weblogic.wsee.DefaultQueue. Otherwise, if you use a different JNDI name, be sure to specify the queue name when specifying the @WLJmsTransport annotation or <WLJmsTransport> child element of the jwsc Ant task.

Clustering Considerations:

If you are using the Web service JMS transport feature in a cluster, you must:

- Create a local JMS queue, rather than a distributed queue, when creating the JMS queue.

- Explicitly target this JMS queue to each server in the cluster.

Using the @WLJmsTransport JWS Annotation

If you know at the time that you program the JWS file that you want client applications to use JMS transport (instead of HTTP/S) to invoke the Web service, you can use the @WLJmsTransport to specify the details of the invocation. Later, at build-time, you can override the invocation defined in the JWS file and add additional JMS transport specifications, by specifying the <WLJmsTransport> child element of the jwsc Ant task, as described in Using the <WLJmsTransport> Child Element of the jwsc Ant Task.

Follow these guidelines when using the @WLJmsTranport annotation:

- You can include only one @WLJmsTransport annotation in a JWS file.

- Use the queue attribute to specify the JNDI name of the JMS queue you configured earlier in the section. If you want to use the default Web services queue (weblogic.wsee.DefaultQueue) then you do not have to specify the queue attribute.

- Use the connectionFactory attribute to specify the JNDI name of the connection factory. The default value of this attribute is the default JMS connection factory for your WebLogic Server instance.

The following example shows a simple JWS file that uses the @WLJmsTransport annotation, with the relevant code in bold:

package examples.webservices.jmstransport;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

import weblogic.jws.WLJmsTransport;

@WebService(name="JMSTransportPortType",
serviceName="JMSTransportService",
targetNamespace="http://example.org")

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

// WebLogic-specific JWS annotation that specifies the context path and
// service URI used to build the URI of the Web Service is
// "transports/JMSTransport"

@WLJmsTransport(contextPath="transports", serviceUri="JMSTransport",
queue="JMSTransportQueue", portName="JMSTransportServicePort",
connectionFactory="JMSTransportConnectionFactory")

/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHello
*/

public class JMSTransportImpl {

@WebMethod()
public String sayHello(String message) {
System.out.println("sayHello:" + message);
return "Here is the message: '" + message + "'";
}
}

Using the <WLJmsTransport> Child Element of the jwsc Ant Task

You can also specify the JMS transport at build-time by using the <WLJmsTransport> child element of the <jws> element of the jwsc Ant task. Reasons for specifying the transport at build-time include:

- You need to override the attribute values specified in the JWS file.

- The JWS file specifies a different transport, and at build-time you decide that JMS should be the transport.

- The JWS file does not include a @WLXXXTransport annotation; thus by default the HTTP transport is used, but at build-time you decide you want to clients to use the JMS transport to invoke the Web service.

If you specify a transport to the jwsc Ant task, it takes precedence over any transport annotation in the JWS file.

The following example shows how to specify a transport to the jwsc Ant task:

<target name="build-service">

<jwsc
srcdir="src"
destdir="${ear-dir}">
<jws file="examples/webservices/jmstransport/JMSTransportImpl.java">

<WLJmsTransport
contextPath="transports"
serviceUri="JMSTransport"
portName="JMSTransportServicePort"
queue="JMSTransportQueue"
connectionFactory="JMSTransportConnectionFactory"/>

</jws>

</jwsc>

</target>

The preceding example shows how to specify the same values for the URL and JMS queue as were specified in the JWS file shown in Using the @WLJmsTransport JWS Annotation.

For more information about using the jwsc Ant task, see "jwsc" in WebLogic Web Services Reference for Oracle WebLogic Server.

Updating the WSDL to Use JMS Transport

To update the WSDL to use JMS transport, you need to add <wsdl:binding> and <wsdl:service> definitions that define JMS transport information. You can add the definitions in one of the following ways:

- Edit the existing HTTP <wsdl:binding> and <wsdl:service> definitions.

- To specify multiple transport options in the WSDL, copy the existing HTTP <wsdl:binding> and <wsdl:service> definitions and edit them to use JMS transport.

In either case, you must modify the <wsdl:binding> and <wsdl:service> definitions to use JMS transport as follows:

- Set the transport attribute of the <soapwsdl:binding> child element of the <wsdl:binding> element to http://www.openuri.org/2002/04/soap/jms/. For example:

<binding name="JmsTransportServiceSoapBindingjms" type="tns:JmsTransportPortType">
<soap:binding style="document" transport="http://www.openuri.org/2002/04/soap/jms/"/>

- Specify a JMS-style endpoint URL for the location attribute of the <soapwsdl:address> child element of the <wsdl:service>. For example:

<s0:service name="JmsTransportService">
<s0:port binding="s1:JmsTransportServiceSoapBindingjms" name="JmsTransportServicePort">
<s2:address location="jms://localhost:7001/transports/JmsTransport?URI=JMSTransportQueue"/>
</s0:port>
</s0:service>

Invoking a WebLogic Web Service Using JMS Transport

You write a client application to invoke a Web service using JMS transport in the same way as you write one using the HTTP transport; the only difference is that you must ensure that the JMS queue (specified by the @WLJmsTransport annotation or <WLJmsTransport> child element of the jwsc Ant task) and other JMS objects have been created. See Using JMS Transport Starting From Java: Main Steps or Using JMS Transport Starting From WSDL: Main Steps for more information.

Although you cannot invoke a JMS-transport-configured Web service using HTTP, you can view its WSDL using HTTP, which is how the clientgen Ant task is still able to create the JAX-RPC stubs for the Web service. For example, the URL for the WSDL of the Web service shown in this section would be:

http://host:port/transports/JMSTransport?WSDL

However, because the endpoint address in the WSDL of the deployed Web service uses jms:// instead of http://, and the address includes the qualifier ?URI=JMS_QUEUE, the clientgen Ant task automatically creates the stubs needed to use the JMS transport when invoking the Web service, and your client application need not do anything different than normal. An example of a JMS endpoint address is as follows:

jms://host:port/transports/JMSTransport?URI=JMSTransportQueue

Note:

If you have specified that the Web service you invoke using JMS transport also runs within the context of a transaction (in other words, the JWS file includes the @weblogic.jws.Transactional annotation), you must use asynchronous request-response when invoking the service. If you do not, a deadlock will occur and the invocation will fail.

For general information about invoking a Web service, see "Invoking Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Overriding the Default Service Address URL

When you write a client application that uses the clientgen-generated JAX-RPC stubs to invoke a Web service, the default service address URL of the Web service is the one specified in the <address> element of the WSDL file argument of the Service constructor.

Sometimes, however, you might need to override this address, in particular when invoking a WebLogic Web service that is deployed to a cluster and you want to specify the cluster address or a list of addresses of the managed servers in the cluster. You might also want to use the t3 protocol to invoke the Web service. To override this service endpoint URL when using JMS transport, use the weblogic.wsee.jaxrpc.WLStub.JMS_TRANSPORT_JNDI_URL stub property as shown in the following example:

package examples.webservices.jmstransport.client;

import weblogic.wsee.jaxrpc.WLStub;

import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;

/**
* This is a simple standalone client application that invokes the
* the <code>sayHello</code> operation of the JMSTransport Web service.
*/

public class Main {

public static void main(String[] args)
throws ServiceException, RemoteException{

JMSTransportService service = new JMSTransportService_Impl(args[0] + "?WSDL" );
JMSTransportPortType port = service.getJMSTransportServicePort();

Stub stub = (Stub) port;

stub._setProperty(WLStub.JMS_TRANSPORT_JNDI_URL,
"t3://shackell01.amer.com:7001");
try {
String result = null;

result = port.sayHello("Hi there! ");

System.out.println( "Got JMS result: " + result );

} catch (RemoteException e) {
throw e;
}
}
}

See "WLStub" in Oracle WebLogic Server API Reference for additional stub properties.

Using JMS BytesMessage Rather Than the Default TextMessage

When you use JMS transport, the Web services runtime uses, by default, the javax.jms.TextMessage object to send the message. This is usually adequate for most client applications, but sometimes you might need to send binary data rather than ordinary text; in this case you must request that the Web services runtime use javax.jms.BytesMessage instead. To do this, use the WLStub.JMS_TRANSPORT_MESSAGE_TYPE stub property in your client application and set it to the value WLStub.JMS_BYTESMESSAGE, as shown in the following example:

stub._setProperty(WLStub.JMS_TRANSPORT_MESSAGE_TYPE,
WLStub.JMS_BYTESMESSAGE);

The Web services runtime sends back the response using the same message data type as the request.

See Overriding the Default Service Address URL for a full example of a client application in which you can set this property. See "WLStub" in Oracle WebLogic Server API Reference for additional stub properties.

Disabling HTTP Access to the WSDL File

As described in Invoking a WebLogic Web Service Using JMS Transport, the WSDL of the deployed Web service is, by default, still accessible using HTTP. If you want to disable access to the WSDL file, in particular if your Web service can be accessed outside of a firewall, then you can do one of the following:

- Use the weblogic.jws.WSDL annotation in your JWS file to programmatically disable access. For details, see "weblogic.jws.WSDL" in WebLogic Web Services Reference for Oracle WebLogic Server.

- Use the Administration Console to disable access to the WSDL file after the Web service has been deployed. In this case, the configuration information will be stored in the deployment plan rather than through the annotation.
To use the Administration Console to perform this task, go to the Configuration -> General page of the deployed Web service and uncheck the View Dynamic WSDL Enabled check box. After saving the configuration to the deployment plan, you must redeploy (update) the Web service, or Enterprise Application which contains it, for the change to take effect.

9 Creating and Using SOAP Message Handlers

This chapter describes how to create and use SOAP message handlers with WebLogic Java API for XML-based RPC (JAX-RPC) Web services.

This chapter includes the following topics:

- Overview of SOAP Message Handlers

- Adding SOAP Message Handlers to a Web Service: Main Steps

- Designing the SOAP Message Handlers and Handler Chains

- Creating the GenericHandler Class

- Configuring Handlers in the JWS File

- Creating the Handler Chain Configuration File

- Compiling and Rebuilding the Web Service

- Creating and Using Client-Side SOAP Message Handlers

Overview of SOAP Message Handlers

Some Web services need access to the SOAP message, for which you can create SOAP message handlers.

A SOAP message handler provides a mechanism for intercepting the SOAP message in both the request and response of the Web service. You can create handlers in both the Web service itself and the client applications that invoke the Web service.

A simple example of using handlers is to access information in the header part of the SOAP message. You can use the SOAP header to store Web service specific information and then use handlers to manipulate it.

You can also use SOAP message handlers to improve the performance of your Web service. After your Web service has been deployed for a while, you might discover that many consumers invoke it with the same parameters. You could improve the performance of your Web service by caching the results of popular invokes of the Web service (assuming the results are static) and immediately returning these results when appropriate, without ever invoking the back-end components that implement the Web service. You implement this performance improvement by using handlers to check the request SOAP message to see if it contains the popular parameters.

The following table lists the standard JWS annotations that you can use in your JWS file to specify that a Web service has a handler chain configured; later sections discuss how to use the annotations in more detail. For additional information, see the Web services MetaData for the Java Platform (JSR-181) specification at http://www.jcp.org/en/jsr/detail?id=181.

Table 9-1 JWS Annotations Used To Configure SOAP Message Handler Chains

JWS Annotation

Description

javax.jws.HandlerChain

Associates the Web service with an externally defined handler chain. Use this annotation when multiple Web services need to share the same handler configuration, or if the handler chain consists of handlers for multiple transports.

javax.jws.soap.SOAPMessageHandlers

Specifies a list of SOAP handlers that run before and after the invocation of each Web service operation. Use this annotation (rather than @HandlerChain) if embedding handler configuration information in the JWS file itself is preferred, rather than having an external configuration file.

The @SOAPMessageHandler annotation is an array of @SOAPMessageHandlers. The handlers are executed in the order they are listed in this array.

Note; This annotation works with JAX-RPC Web services only.

javax.jws.soap.SOAPMessageHandler

Specifies a single SOAP message handler in the @SOAPMessageHandlers array.

The following table describes the main classes and interfaces of the javax.xml.rpc.handler API, some of which you use when creating the handler itself. These APIs are discussed in detail in a later section. For additional information about these APIs, see the JAX-RPC 1.1 specification at http://java.net/projects/jax-rpc/.

Table 9-2 JAX-RPC Handler Interfaces and Classes

javax.xml.rpc.handler Classes and Interfaces

Description

Handler

Main interface that is implemented when creating a handler. Contains methods to handle the SOAP request, response, and faults.

GenericHandler

Abstract class that implements the Handler interface. User should extend this class when creating a handler, rather than implement Handler directly.

The GenericHandler class is a convenience abstract class that makes writing handlers easy. This class provides default implementations of the life cycle methods init and destroy and also different handle methods. A handler developer should only override methods that it needs to specialize as part of the derived handler implementation class.

HandlerChain

Interface that represents a list of handlers. An implementation class for the HandlerChain interface abstracts the policy and mechanism for the invocation of the registered handlers.

HandlerRegistry

Interface that provides support for the programmatic configuration of handlers in a HandlerRegistry.

HandlerInfo

Class that contains information about the handler in a handler chain. A HandlerInfo instance is passed in the Handler.init method to initialize a Handler instance.

MessageContext

Abstracts the message context processed by the handler. The MessageContext properties allow the handlers in a handler chain to share processing state.

soap.SOAPMessageContext

Sub-interface of the MessageContext interface used to get at or update the SOAP message.

javax.xml.soap.SOAPMessage

Object that contains the actual request or response SOAP message, including its header, body, and attachment.

Adding SOAP Message Handlers to a Web Service: Main Steps

The following procedure describes the high-level steps to add SOAP message handlers to your Web service.

It is assumed that you have created a basic JWS file that implements a Web service and that you want to update the Web service by adding SOAP message handlers and handler chains. It is also assumed that you have set up an Ant-based development environment and that you have a working build.xml file that includes a target for running the jwsc Ant task. For more information, see in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server:

- "Use Cases and Examples"

- "Developing WebLogic Web Services"

- "Programming the JWS File"

- "Invoking Web Services"

Table 9-3 Steps to Add SOAP Message Handlers to a Web Service

#

Step

Description

1

Design the handlers and handler chains.

See Designing the SOAP Message Handlers and Handler Chains.

2

For each handler in the handler chain, create a Java class that extends the javax.xml.rpc.handler.GenericHandler abstract class.

See Creating the GenericHandler Class.

3

Update your JWS file, adding annotations to configure the SOAP message handlers.

See Configuring Handlers in the JWS File.

4

If you are using the @HandlerChain standard annotation in your JWS file, create the handler chain configuration file.

See Creating the Handler Chain Configuration File.

5

Compile all handler classes in the handler chain and rebuild your Web service.

See Compiling and Rebuilding the Web Service.

For information about creating client-side SOAP message handlers and handler chains, see Creating and Using Client-Side SOAP Message Handlers.

Designing the SOAP Message Handlers and Handler Chains

When designing your SOAP message handlers and handler chains, you must decide:

- The number of handlers needed to perform all the work

- The sequence of execution

Each handler in a handler chain has one method for handling the request SOAP message and another method for handling the response SOAP message. An ordered group of handlers is referred to as a handler chain. You specify that a Web service has a handler chain attached to it with one of two JWS annotations: @HandlerChain or @SOAPMessageHandler. When to use which is discussed in a later section.

When invoking a Web service, WebLogic Server executes handlers as follows:

1. The handleRequest() methods of the handlers in the handler chain are all executed in the order specified by the JWS annotation. Any of these handleRequest() methods might change the SOAP message request.

2. When the handleRequest() method of the last handler in the handler chain executes, WebLogic Server invokes the back-end component that implements the Web service, passing it the final SOAP message request.

3. When the back-end component has finished executing, the handleResponse() methods of the handlers in the handler chain are executed in the reverse order specified in by the JWS annotation. Any of these handleResponse() methods might change the SOAP message response.

4. When the handleResponse() method of the first handler in the handler chain executes, WebLogic Server returns the final SOAP message response to the client application that invoked the Web service.

For example, assume that you are going to use the @HandlerChain JWS annotation in your JWS file to specify an external configuration file, and the configuration file defines a handler chain called SimpleChain that contains three handlers, as shown in the following sample:

<jwshc:handler-config xmlns:jwshc="http://www.bea.com/xml/ns/jws"
xmlns:soap1="http://HandlerInfo.org/Server1"
xmlns:soap2="http://HandlerInfo.org/Server2"
xmlns="http://java.sun.com/xml/ns/j2ee" >

<jwshc:handler-chain>

<jwshc:handler-chain-name>SimpleChain</jwshc:handler-chain-name>

<jwshc:handler>
<handler-name>handlerOne</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler1</handler-class>
</jwshc:handler>

<jwshc:handler>
<handler-name>handlerTwo</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler2</handler-class>
</jwshc:handler>

<jwshc:handler>
<handler-name>handlerThree</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler3</handler-class>
</jwshc:handler>

</jwshc:handler-chain>

</jwshc:handler-config>

The following graphic shows the order in which WebLogic Server executes the handleRequest() and handleResponse() methods of each handler.

Figure 9-1 Order of Execution of Handler Methods

Each SOAP message handler has a separate method to process the request and response SOAP message because the same type of processing typically must happen for the inbound and outbound message. For example, you might design an Encryption handler whose handleRequest() method decrypts secure data in the SOAP request and handleResponse() method encrypts the SOAP response.

You can, however, design a handler that process only the SOAP request and does no equivalent processing of the response.

You can also choose not to invoke the next handler in the handler chain and send an immediate response to the client application at any point.

Creating the GenericHandler Class

Your SOAP message handler class should extend the javax.rpc.xml.handler.GenericHandler abstract class, which itself implements the javax.rpc.xml.handler.Handler interface.

The GenericHandler class is a convenience abstract class that makes writing handlers easy. This class provides default implementations of the life cycle methods init() and destroy() and the various handleXXX() methods of the Handler interface. When you write your handler class, only override those methods that you need to customize as part of your Handler implementation class.

In particular, the Handler interface contains the following methods that you can implement in your handler class that extends GenericHandler:

- init()
See Implementing the Handler.init() Method.

- destroy()
See Implementing the Handler.destroy() Method.

- getHeaders()
See Implementing the Handler.getHeaders() Method.

- handleRequest()
See Implementing the Handler.handleRequest() Method.

- handleResponse()
See Implementing the Handler.handleResponse() Method.

- handleFault()
See Implementing the Handler.handleFault() Method.

Sometimes you might need to directly view or update the SOAP message from within your handler, in particular when handling attachments, such as image. In this case, use the javax.xml.soap.SOAPMessage abstract class, which is part of the SOAP With Attachments API for Java 1.1 (SAAJ) specification at http://java.net/projects/saaj/. For details, see Directly Manipulating the SOAP Request and Response Message Using SAAJ.

The following example demonstrates a simple SOAP message handler that prints out the SOAP request and response messages to the WebLogic Server log file:

package examples.webservices.soap_handlers.global_handler;

import javax.xml.namespace.QName;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.GenericHandler;
import javax.xml.rpc.handler.MessageContext;
import javax.xml.rpc.handler.soap.SOAPMessageContext;
import javax.xml.rpc.JAXRPCException;

import weblogic.logging.NonCatalogLogger;

/**
* This class implements a handler in the handler chain, used to access the SOAP
* request and response message.
* <p>
* This class extends the <code>javax.xml.rpc.handler.GenericHandler</code>
* abstract classs and simply prints the SOAP request and response messages to
* the server log file before the messages are processed by the backend
* Java class that implements the Web Service itself.
*/

public class ServerHandler1 extends GenericHandler {

private NonCatalogLogger log;

private HandlerInfo handlerInfo;

/**
*  Initializes the instance of the handler.  Creates a nonCatalogLogger to
*  log messages to.
*/

public void init(HandlerInfo hi) {

log = new NonCatalogLogger("WebService-LogHandler");
handlerInfo = hi;
}

/**
* Specifies that the SOAP request message be logged to a log file before the
* message is sent to the Java class that implements the Web Service.
*/

public boolean handleRequest(MessageContext context) {

SOAPMessageContext messageContext = (SOAPMessageContext) context;

System.out.println("** Request: "+messageContext.getMessage().toString());
log.info(messageContext.getMessage().toString());
return true;

}

/**
* Specifies that the SOAP response message be logged to a log file before the
* message is sent back to the client application that invoked the Web
* service.
*/

public boolean handleResponse(MessageContext context) {

SOAPMessageContext messageContext = (SOAPMessageContext) context;

System.out.println("** Response: "+messageContext.getMessage().toString());
log.info(messageContext.getMessage().toString());
return true;

}

/**
* Specifies that a message be logged to the log file if a SOAP fault is
* thrown by the Handler instance.
*/

public boolean handleFault(MessageContext context) {

SOAPMessageContext messageContext = (SOAPMessageContext) context;

System.out.println("** Fault: "+messageContext.getMessage().toString());
log.info(messageContext.getMessage().toString());
return true;

}

public QName[] getHeaders() {

return handlerInfo.getHeaders();

}

}

Implementing the Handler.init() Method

The Handler.init() method is called to create an instance of a Handler object and to enable the instance to initialize itself. Its signature is:

public void init(HandlerInfo config) throws JAXRPCException {}

The HandlerInfo object contains information about the SOAP message handler, in particular the initialization parameters. Use the HandlerInfo.getHandlerConfig() method to get the parameters; the method returns a java.util.Map object that contains name-value pairs.

Implement the init() method if you need to process the initialization parameters or if you have other initialization tasks to perform.

Sample uses of initialization parameters are to turn debugging on or off, specify the name of a log file to which to write messages or errors, and so on.

Implementing the Handler.destroy() Method

The Handler.destroy() method is called to destroy an instance of a Handler object. Its signature is:

public void destroy() throws JAXRPCException {}

Implement the destroy() method to release any resources acquired throughout the handler's life cycle.

Implementing the Handler.getHeaders() Method

The Handler.getHeaders() method gets the header blocks that can be processed by this Handler instance. Its signature is:

public QName[] getHeaders() {}

Implementing the Handler.handleRequest() Method

The Handler.handleRequest() method is called to intercept a SOAP message request before it is processed by the back-end component. Its signature is:

public boolean handleRequest(MessageContext mc)
throws JAXRPCException,SOAPFaultException  {}

Implement this method to perform such tasks as decrypting data in the SOAP message before it is processed by the back-end component, and so on.

The MessageContext object abstracts the message context processed by the SOAP message handler. The MessageContext properties allow the handlers in a handler chain to share processing state.

Use the SOAPMessageContext sub-interface of MessageContext to get at or update the contents of the SOAP message request. The SOAP message request itself is stored in a javax.xml.soap.SOAPMessage object. For detailed information on this object, see Directly Manipulating the SOAP Request and Response Message Using SAAJ.

The SOAPMessageContext class defines two methods for processing the SOAP request:

- SOAPMessageContext.getMessage()returns a javax.xml.soap.SOAPMessage object that contains the SOAP message request.

- SOAPMessageContext.setMessage(javax.xml.soap.SOAPMessage)updates the SOAP message request after you have made changes to it.

After you code all the processing of the SOAP request, code one of the following scenarios:

- Invoke the next handler on the handler request chain by returning true.
The next handler on the request chain is specified as either the next <handler> subelement of the <handler-chain> element in the configuration file specified by the @HandlerChain annotation, or the next @SOAPMessageHandler in the array specified by the @SOAPMessageHandlers annotation. If there are no more handlers in the chain, the method either invokes the back-end component, passing it the final SOAP message request, or invokes the handleResponse() method of the last handler, depending on how you have configured your Web service.

- Block processing of the handler request chain by returning false.
Blocking the handler request chain processing implies that the back-end component does not get executed for this invoke of the Web service. You might want to do this if you have cached the results of certain invokes of the Web service, and the current invoke is on the list.

Although the handler request chain does not continue processing, WebLogic Server does invoke the handler response chain, starting at the current handler. For example, assume that a handler chain consists of two handlers: handlerA and handlerB, where the handleRequest() method of handlerA is invoked before that of handlerB. If processing is blocked in handlerA (and thus the handleRequest() method of handlerB is not invoked), the handler response chain starts at handlerA and the handleRequest() method of handlerB is not invoked either.

- Throw the javax.xml.rpc.soap.SOAPFaultException to indicate a SOAP fault.
If the handleRequest() method throws a SOAPFaultException, WebLogic Server catches the exception, terminates further processing of the handler request chain, and invokes the handleFault() method of this handler.

- Throw a JAXRPCException for any handler-specific runtime errors.
If the handleRequest() method throws a JAXRPCException, WebLogic Server catches the exception, terminates further processing of the handler request chain, logs the exception to the WebLogic Server log file, and invokes the handleFault() method of this handler.

Implementing the Handler.handleResponse() Method

The Handler.handleResponse() method is called to intercept a SOAP message response after it has been processed by the back-end component, but before it is sent back to the client application that invoked the Web service. Its signature is:

public boolean handleResponse(MessageContext mc) throws JAXRPCException {}

Implement this method to perform such tasks as encrypting data in the SOAP message before it is sent back to the client application, to further process returned values, and so on.

The MessageContext object abstracts the message context processed by the SOAP message handler. The MessageContext properties allow the handlers in a handler chain to share processing state.

Use the SOAPMessageContext sub-interface of MessageContext to get at or update the contents of the SOAP message response. The SOAP message response itself is stored in a javax.xml.soap.SOAPMessage object. See Directly Manipulating the SOAP Request and Response Message Using SAAJ.

The SOAPMessageContext class defines two methods for processing the SOAP response:

- SOAPMessageContext.getMessage(): returns a javax.xml.soap.SOAPMessage object that contains the SOAP message response.

- SOAPMessageContext.setMessage(javax.xml.soap.SOAPMessage): updates the SOAP message response after you have made changes to it.

After you code all the processing of the SOAP response, code one of the following scenarios:

- Invoke the next handler on the handler response chain by returning true.
The next response on the handler chain is specified as either the preceding <handler> subelement of the <handler-chain> element in the configuration file specified by the @HandlerChain annotation, or the preceding @SOAPMessageHandler in the array specified by the @SOAPMessageHandlers annotation. (Remember that responses on the handler chain execute in the reverse order that they are specified in the JWS file. See Designing the SOAP Message Handlers and Handler Chains for more information.)

If there are no more handlers in the chain, the method sends the final SOAP message response to the client application that invoked the Web service.

- Block processing of the handler response chain by returning false.
Blocking the handler response chain processing implies that the remaining handlers on the response chain do not get executed for this invoke of the Web service and the current SOAP message is sent back to the client application.

- Throw a JAXRPCException for any handler specific runtime errors.
If the handleRequest() method throws a JAXRPCException, WebLogic Server catches the exception, terminates further processing of the handler request chain, logs the exception to the WebLogic Server logfile, and invokes the handleFault() method of this handler.

Implementing the Handler.handleFault() Method

The Handler.handleFault() method processes the SOAP faults based on the SOAP message processing model. Its signature is:

public boolean handleFault(MessageContext mc) throws JAXRPCException  {}

Implement this method to handle processing of any SOAP faults generated by the handleResponse() and handleRequest() methods, as well as faults generated by the back-end component.

The MessageContext object abstracts the message context processed by the SOAP message handler. The MessageContext properties allow the handlers in a handler chain to share processing state.

Use the SOAPMessageContext sub-interface of MessageContext to get at or update the contents of the SOAP message. The SOAP message itself is stored in a javax.xml.soap.SOAPMessage object. See Directly Manipulating the SOAP Request and Response Message Using SAAJ.

The SOAPMessageContext class defines the following two methods for processing the SOAP message:

- SOAPMessageContext.getMessage(): returns a javax.xml.soap.SOAPMessage object that contains the SOAP message.

- SOAPMessageContext.setMessage(javax.xml.soap.SOAPMessage): updates the SOAP message after you have made changes to it.

After you code all the processing of the SOAP fault, do one of the following:

- Invoke the handleFault() method on the next handler in the handler chain by returning true.

- Block processing of the handler fault chain by returning false.

Directly Manipulating the SOAP Request and Response Message Using SAAJ

The javax.xml.soap.SOAPMessage abstract class is part of the SOAP With Attachments API for Java 1.1 (SAAJ) specification (see http://java.net/projects/saaj/). You use the class to manipulate request and response SOAP messages when creating SOAP message handlers. This section describes the basic structure of a SOAPMessage object and some of the methods you can use to view and update a SOAP message.

A SOAPMessage object consists of a SOAPPart object (which contains the actual SOAP XML document) and zero or more attachments.

Refer to the SAAJ Javadocs for the full description of the SOAPMessage class.

The SOAPPart Object

The SOAPPart object contains the XML SOAP document inside of a SOAPEnvelope object. You use this object to get the actual SOAP headers and body.

The following sample Java code shows how to retrieve the SOAP message from a MessageContext object, provided by the Handler class, and get at its parts:

SOAPMessage soapMessage =  messageContext.getMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();
SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
SOAPBody soapBody = soapEnvelope.getBody();
SOAPHeader soapHeader = soapEnvelope.getHeader();

The AttachmentPart Object

The javax.xml.soap.AttachmentPart object contains the optional attachments to the SOAP message. Unlike the rest of a SOAP message, an attachment is not required to be in XML format and can therefore be anything from simple text to an image file.

Note:

If you are going to access a java.awt.Image attachment from your SOAP message handler, see Manipulating Image Attachments in a SOAP Message Handler for important information.

Use the following methods of the SOAPMessage class to manipulate the attachments:

- countAttachments(): returns the number of attachments in this SOAP message.

- getAttachments(): retrieves all the attachments (as AttachmentPart objects) into an Iterator object.

- createAttachmentPart(): create an AttachmentPart object from another type of Object.

- addAttachmentPart(): adds an AttachmentPart object, after it has been created, to the SOAPMessage.

Manipulating Image Attachments in a SOAP Message Handler

It is assumed in this section that you are creating a SOAP message handler that accesses a java.awt.Image attachment and that the Image has been sent from a client application that uses the client JAX-RPC stubs generated by the clientgen Ant task.

In the client code generated by the clientgen Ant task, a java.awt.Image attachment is sent to the invoked WebLogic Web service with a MIME type of text/xml rather than image/gif, and the image is serialized into a stream of integers that represents the image. In particular, the client code serializes the image using the following format:

- int width

- int height

- int[] pixels

This means that, in your SOAP message handler that manipulates the received Image attachment, you must deserialize this stream of data to then re-create the original image.

Configuring Handlers in the JWS File

There are two standard annotations you can use in your JWS file to configure a handler chain for a Web service: @javax.jws.HandlerChain and @javax.jws.soap.SOAPMessageHandlers.

@javax.jws.HandlerChain

When you use the @javax.jws.HandlerChain annotation (also called @HandlerChain in this chapter for simplicity) you use the file attribute to specify an external file that contains the configuration of the handler chain you want to associate with the Web service. The configuration includes the list of handlers in the chain, the order in which they execute, the initialization parameters, and so on.

Use the @HandlerChain annotation, rather than the @SOAPMessageHandlers annotation, in your JWS file if one or more of the following conditions apply:

- You want multiple Web services to share the same configuration.

- Your handler chain includes handlers for multiple transports.

- You want to be able to change the handler chain configuration for a Web service without recompiling the JWS file that implements it.

The following JWS file shows an example of using the @HandlerChain annotation; the relevant Java code is shown in bold:

package examples.webservices.soap_handlers.global_handler;

import java.io.Serializable;

import javax.jws.HandlerChain;
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.soap.SOAPBinding;

import weblogic.jws.WLHttpTransport;

@WebService(serviceName="HandlerChainService",
name="HandlerChainPortType")

// Standard JWS annotation that specifies that the handler chain called
// "SimpleChain", configured in the HandlerConfig.xml file, should fire
// each time an operation of the Web Service is invoked.

@HandlerChain(file="HandlerConfig.xml", name="SimpleChain")

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WLHttpTransport(contextPath="HandlerChain", serviceUri="HandlerChain",
portName="HandlerChainServicePort")

/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHello.  The Web Service also
* has a handler chain associated with it, as specified by the
* @HandlerChain annotation.
*/

public class HandlerChainImpl  {

public String sayHello(String input) {
weblogic.utils.Debug.say( "in backend component. input:" +input );
return "'" + input + "' to you too!";
}
}

Before you use the @HandlerChain annotation, you must import it into your JWS file, as shown in the preceding example.

Use the file attribute of the @HandlerChain annotation to specify the name of the external file that contains configuration information for the handler chain. The value of this attribute is a URL, which may be relative or absolute. Relative URLs are relative to the location of the JWS file at the time you run the jwsc Ant task to compile the file.

Use the name attribute to specify the name of the handler chain in the configuration file that you want to associate with the Web service. The value of this attribute corresponds to the name attribute of the <handler-chain> element in the configuration file.

Note:

It is an error to specify more than one @HandlerChain annotation in a single JWS file. It is also an error to combine the @HandlerChain annotation with the @SOAPMessageHandlers annotation.

For details about creating the external configuration file, see Creating the Handler Chain Configuration File.

For additional detailed information about the standard JWS annotations discussed in this section, see the Web services Metadata for the Java Platform specification at http://www.jcp.org/en/jsr/detail?id=181.

@javax.jws.soap.SOAPMessageHandlers

Note:

This annotation has been deprecated as of the Web services Metadata for the Java Platform specification (JSR-181) at http://www.jcp.org/en/jsr/detail?id=181.

When you use the @javax.jws.soap.SOAPMessageHandlers (also called @SOAPMessageHandlers in this section for simplicity) annotation, you specify, within the JWS file itself, an array of SOAP message handlers (specified with the @SOAPMessageHandler annotation) that execute before and after the operations of a Web service. The @SOAPMessageHandler annotation includes attributes to specify the class name of the handler, the initialization parameters, list of SOAP headers processed by the handler, and so on. Because you specify the list of handlers within the JWS file itself, the configuration of the handler chain is embedded within the Web service.

Use the @SOAPMessageHandlers annotation if one or more of the following conditions apply:

- You prefer to embed the configuration of the handler chain inside the Web service itself, rather than specify the configuration in an external file.

- Your handler chain includes only SOAP handlers and none for any other transport.

- You prefer to recompile the JWS file each time you change the handler chain configuration.

The following JWS file shows a simple example of using the @SOAPMessageHandlers annotation; the relevant Java code is shown in bold:

package examples.webservices.soap_handlers.simple;

import java.io.Serializable;

import javax.jws.soap.SOAPMessageHandlers;
import javax.jws.soap.SOAPMessageHandler;
import javax.jws.soap.SOAPBinding;
import javax.jws.WebService;
import javax.jws.WebMethod;

import weblogic.jws.WLHttpTransport;

@WebService(name="SimpleChainPortType",
serviceName="SimpleChainService")

// Standard JWS annotation that specifies a list of SOAP message handlers
// that exeucte before and after an invocation of all operations in the
// Web Serice.

@SOAPMessageHandlers ( {
@SOAPMessageHandler (
className="examples.webservices.soap_handlers.simple.ServerHandler1"),
@SOAPMessageHandler (
className="examples.webservices.soap_handlers.simple.ServerHandler2")
} )

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WLHttpTransport(contextPath="SimpleChain", serviceUri="SimpleChain",
portName="SimpleChainServicePort")

/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHello.  The Web Service also
* has a handler chain associated with it, as specified by the
* @SOAPMessageHandler/s annotations.
*/

public class SimpleChainImpl  {

// by default all public methods are exposed as operations

public String sayHello(String input)  {
weblogic.utils.Debug.say( "in backend component. input:" +input );
return "'" + input + "' to you too!";
}
}

Before you use the @SOAPMessageHandlers and @SOAPMessageHandler annotations, you must import them into your JWS file, as shown in the preceding example. Note that these annotations are in the javax.jws.soap package.

The order in which you list the handlers (using the @SOAPMessageHandler annotation) in the @SOAPMessageHandlers array specifies the order in which the handlers execute: in forward order before the operation, and in reverse order after the operation. The preceding example configures two handlers in the handler chain, whose class names are examples.webservices.soap_handlers.simple.ServerHandler1 and examples.webservices.soap_handlers.simple.ServerHandler2.

Use the initParams attribute of @SOAPMessageHandler to specify an array of initialization parameters expected by a particular handler. Use the @InitParam standard JWS annotation to specify the name/value pairs, as shown in the following example:

@SOAPMessageHandler(
className = "examples.webservices.soap_handlers.simple.ServerHandler1",
initParams = { @InitParam(name="logCategory", value="MyService")}
)

The @SOAPMessageHandler annotation also includes the roles attribute for listing the SOAP roles implemented by the handler, and the headers attribute for listing the SOAP headers processed by the handler.

Note:

It is an error to combine the @SOAPMessageHandlers annotation with the @HandlerChain annotation.

For additional detailed information about the standard JWS annotations discussed in this section, see the Web services Metadata for the Java Platform specification http://www.jcp.org/en/jsr/detail?id=181.

Creating the Handler Chain Configuration File

If you decide to use the @HandlerChain annotation in your JWS file to associate a handler chain with a Web service, you must create an external configuration file that specifies the list of handlers in the handler chain, the order in which they execute, the initialization parameters, and so on.

Because this file is external to the JWS file, you can configure multiple Web services to use this single configuration file to standardize the handler configuration file for all Web services in your enterprise. Additionally, you can change the configuration of the handler chains without needing to recompile all your Web services. Finally, if you include handlers in your handler chain that use a non-SOAP transport, then you are required to use the @HandlerChain annotation rather than the @SOAPMessageHandler annotation.

The configuration file uses XML to list one or more handler chains, as shown in the following simple example:

<jwshc:handler-config xmlns:jwshc="http://www.bea.com/xml/ns/jws"
xmlns:soap1="http://HandlerInfo.org/Server1"
xmlns:soap2="http://HandlerInfo.org/Server2"
xmlns="http://java.sun.com/xml/ns/j2ee" >
<jwshc:handler-chain>
<jwshc:handler-chain-name>SimpleChain</jwshc:handler-chain-name>
<jwshc:handler>
<handler-name>handler1</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler1</handler-class>
</jwshc:handler>
<jwshc:handler>
<handler-name>handler2</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler2</handler-class>
</jwshc:handler>
</jwshc:handler-chain>
</jwshc:handler-config>

In the example, the handler chain called SimpleChain contains two handlers: handler1 and handler2, implemented with the class names specified with the <handler-class> element. The two handlers execute in forward order before the relevant Web service operation executes, and in reverse order after the operation executes.

Use the <init-param>, <soap-role>, and <soap-header> child elements of the <handler> element to specify the handler initialization parameters, SOAP roles implemented by the handler, and SOAP headers processed by the handler, respectively.

For the XML Schema that defines the external configuration file, additional information about creating it, and additional examples, see the Web services Metadata for the Java Platform specification at http://www.jcp.org/en/jsr/detail?id=181.

Compiling and Rebuilding the Web Service

It is assumed in this section that you have a working build.xml Ant file that compiles and builds your Web service, and you want to update the build file to include handler chain. See "Developing WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server for information on creating this build.xml file.

Follow these guidelines to update your development environment to include message handler compilation and building:

- After you have updated the JWS file with either the @HandlerChain or @SOAPMessageHandlers annotation, you must rerun the jwsc Ant task to recompile the JWS file and generate a new Web service. This is true anytime you make a change to an annotation in the JWS file.
If you used the @HandlerChain annotation in your JWS file, reran the jwsc Ant task to regenerate the Web service, and subsequently changed only the external configuration file, you do not need to rerun jwsc for the second change to take affect.

- The jwsc Ant task compiles SOAP message handler Java files into handler classes (and then packages them into the generated application) if all the following conditions are true:

- The handler classes are referenced in the @HandlerChain or @SOAPMessageHandler(s) annotations of the JWS file.

- The Java files are located in the directory specified by the sourcepath attribute.

- The classes are not currently in your CLASSPATH.

If you want to compile the handler classes yourself, rather than let jwsc compile them automatically, ensure that the compiled classes are in your CLASSPATH before you run the jwsc Ant task.

- You deploy and invoke a Web service that has a handler chain associated with it in the same way you deploy and invoke one that has no handler chain. The only difference is that when you invoke any operation of the Web service, the WebLogic Web services runtime executes the handlers in the handler chain both before and after the operation invoke.

Creating and Using Client-Side SOAP Message Handlers

The preceding sections describe how to create server-side SOAP message handlers that execute as part of the Web service running on WebLogic Server. You can also create client-side handlers that execute as part of the client application that invokes a Web service operation. In the case of a client-side handler, the handler executes twice:

- Directly before the client application sends the SOAP request to the Web service

- Directly after the client application receives the SOAP response from the Web service

You can configure client-side SOAP message handlers for both stand-alone clients and clients that run inside of WebLogic Server.

You create the actual Java client-side handler in the same way you create a server-side handler: write a Java class that extends the javax.xml.rpc.handler.GenericHandler abstract class. In many cases you can use the exact same handler class on both the Web service running on WebLogic Server and the client applications that invoke the Web service. For example, you can write a generic logging handler class that logs all sent and received SOAP messages, both for the server and for the client.

Similar to the server-side SOAP handler programming, you use an XML file to specify to the clientgen Ant task that you want to invoke client-side SOAP message handlers. However, the XML Schema of this XML file is slightly different, as described in the following procedure.

Using Client-Side SOAP Message Handlers: Main Steps

The following procedure describes the high-level steps to add client-side SOAP message handlers to the client application that invokes a Web service operation.

It is assumed that you have created the client application that invokes a deployed Web service, and that you want to update the client application by adding client-side SOAP message handlers and handler chains. It is also assumed that you have set up an Ant-based development environment and that you have a working build.xml file that includes a target for running the clientgen Ant task. For more information, see "Invoking a Web Service from a Stand-alone Client: Main Steps" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

1. Design the client-side SOAP handlers and the handler chain which specifies the order in which they execute. This step is almost exactly the same as that of designing the server-side SOAP message handlers, except the perspective is from the client application, rather than a Web service.
See Designing the SOAP Message Handlers and Handler Chains.

2. For each handler in the handler chain, create a Java class that extends the javax.xml.rpc.handler.GenericHandler abstract class. This step is very similar to the corresponding server-side step, except that the handler executes in a chain in the client rather than the server.
See Creating the GenericHandler Class for details about programming a handler class. See Example of a Client-Side Handler Class for an example.

3. Create the client-side SOAP handler configuration file. This XML file describes the handlers in the handler chain, the order in which they execute, and any initialization parameters that should be sent.
See Creating the Client-Side SOAP Handler Configuration File.

4. Update the build.xml file that builds your client application, specifying to the clientgen Ant task the name of the SOAP handler configuration file. Also ensure that the build.xml file compiles the handler files into Java classes and makes them available to your client application.
See Specifying the Client-Side SOAP Handler Configuration File to clientgen.

5. Rebuild your client application by running the relevant task:

prompt> ant build-client

When you next run the client application, the SOAP messaging handlers listed in the configuration file automatically execute before the SOAP request message is sent and after the response is received.

Note:

You do not have to update your actual client application to invoke the client-side SOAP message handlers; as long as you specify to the clientgen Ant task the handler configuration file, the generated JAX-RPC stubs automatically take care of executing the handlers in the correct sequence.

Example of a Client-Side Handler Class

The following example shows a simple SOAP message handler class that you can configure for a client application that invokes a Web service.

package examples.webservices.client_handler.client;

import javax.xml.namespace.QName;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.GenericHandler;
import javax.xml.rpc.handler.MessageContext;

public class ClientHandler1 extends GenericHandler {

private QName[] headers;

public void init(HandlerInfo hi) {
System.out.println("in " + this.getClass() + " init()");
}

public boolean handleRequest(MessageContext context) {
System.out.println("in " + this.getClass() + " handleRequest()");
return true;
}

public boolean handleResponse(MessageContext context) {
System.out.println("in " + this.getClass() + " handleResponse()");
return true;
}

public boolean handleFault(MessageContext context) {
System.out.println("in " + this.getClass() + " handleFault()");
return true;
}

public QName[] getHeaders() {
return headers;
}
}

Creating the Client-Side SOAP Handler Configuration File

The client-side SOAP handler configuration file specifies the list of handlers in the handler chain, the order in which they execute, the initialization parameters, and so on. See XML Schema for the Client-Side Handler Configuration File for a full description of this file.

The configuration file uses XML to describe a single handler chain that contains one or more handlers, as shown in the following simple example:

<weblogic-wsee-clientHandlerChain
xmlns="http://www.bea.com/ns/weblogic/90"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:j2ee="http://java.sun.com/xml/ns/j2ee">

<handler>
<j2ee:handler-name>clienthandler1</j2ee:handler-name>
<j2ee:handler-class>examples.webservices.client_handler.client.ClientHandler1</j2ee:handler-class>
<j2ee:init-param>
<j2ee:param-name>ClientParam1</j2ee:param-name>
<j2ee:param-value>value1</j2ee:param-value>
</j2ee:init-param>
</handler>

<handler>
<j2ee:handler-name>clienthandler2</j2ee:handler-name>
<j2ee:handler-class>examples.webservices.client_handler.client.ClientHandler2</j2ee:handler-class>
</handler>

</weblogic-wsee-clientHandlerChain>

In the example, the handler chain contains two handlers: clienthandler1 and clienthandler2, implemented with the class names specified with the <j2ee:handler-class> element. The two handlers execute in forward order directly before the client application sends the SOAP request to the Web service, and then in reverse order directly after the client application receives the SOAP response from the Web service.

The example also shows how to use the <j2ee:init-param> element to specify one or more initialization parameters to a handler.

Use the <soap-role>, <soap-header>, and <port-name> child elements of the <handler> element to specify the SOAP roles implemented by the handler, the SOAP headers processed by the handler, and the port-name element in the WSDL with which the handler is associated with, respectively.

XML Schema for the Client-Side Handler Configuration File

The following XML Schema file defines the structure of the client-side SOAP handler configuration file:

<?xml version="1.0" encoding="UTF-8"?>

<schema
targetNamespace="http://www.bea.com/ns/weblogic/90"
xmlns:wls="http://www.bea.com/ns/weblogic/90"
xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
>
<include schemaLocation="weblogic-j2ee.xsd"/>

<element name="weblogic-wsee-clientHandlerChain"
type="wls:weblogic-wsee-clientHandlerChainType">
<xsd:key name="wsee-clienthandler-name-key">
<xsd:annotation>
<xsd:documentation>

Defines the name of the handler. The name must be unique within the
chain.

</xsd:documentation>
</xsd:annotation>
<xsd:selector xpath="j2ee:handler"/>
<xsd:field xpath="j2ee:handler-name"/>
</xsd:key>
</element>

<complexType name="weblogic-wsee-clientHandlerChainType">
<sequence>
<xsd:element name="handler"
type="j2ee:service-ref_handlerType"
minOccurs="0" maxOccurs="unbounded">
</xsd:element>
</sequence>
</complexType>
</schema>

A single configuration file specifies a single client-side handler chain. The root of the configuration file is <weblogic-wsee-clientHandlerChain>, and the file contains zero or more <handler> child elements, each of which describes a handler in the chain.

The structure of the <handler> element is described by the Java EE service-ref_handlerType complex type, specified in the Java EE 1.4 Web service client XML Schema http://java.sun.com/xml/ns/j2ee/j2ee_web_services_client_1_1.xsd.

Specifying the Client-Side SOAP Handler Configuration File to clientgen

Use the handlerChainFile attribute of the clientgen Ant task to specify the client-side SOAP handler configuration file, as shown in the following excerpt from a build.xml file:

<clientgen
wsdl="http://ariel:7001/handlers/ClientHandlerService?WSDL"
destDir="${clientclass-dir}"
handlerChainFile="ClientHandlerChain.xml"
packageName="examples.webservices.client_handler.client"/>

The JAX-RPC stubs generated by clientgen automatically ensure that the handlers described by the configuration file execute in the correct order before and after the client application invokes the Web service operation.

10 Using Database Web Services

This chapter describes how to use database Web services.

This chapter includes the following topics:

- Overview of Database Web Services

- Type Mapping Between SQL and XML

- Developing Database Web Services Using Oracle JDeveloper

Overview of Database Web Services

In heterogeneous and disconnected environments, there is an increasing need to access stored procedures, data and metadata, through Web service interfaces. Database Web service technology enables Web services for databases. It works in two directions:

- Database Call-in—Access database resources as a Web service

- Database Call-out—Consuming external Web services from the database itself

Database Call-in

Turning the Oracle database into a Web service provider takes advantage of your investment in Java stored procedures, PL/SQL packages, Advanced Queues, pre-defined SQL queries and DML.

Note:

Creating Web services out of Query, Java, DML, and Advanced Queues is not supported in this release.

Client applications can query and retrieve data from Oracle databases and invoke stored procedures using standard Web service protocols. There is no dependency on Oracle specific database connectivity protocols. Applications can employ any cached WebLogic Server connection. This approach is very beneficial in heterogeneous, distributed, and non-connected environments.

Since database Web services are a part of WebLogic Web services, they can participate in a consistent and uniform development and deployment environment. Messages exchanged between the Web service exposed database and the Web service client can take advantage of all of the management features provided by WebLogic Web services, such as security, reliability, auditing and logging.

The following figure illustrates Web service call-in.

Figure 10-1 Web Service Calling in to the Database

The following steps describe the process shown in the previous figure:

1. A request for a type of database service arrives at the application server. The service endpoint implicitly specifies the type of service requested.

2. The JAX-RPC processing servlet references the SOAP libraries and XML parser to decode the request.

3. The servlet passes the request to the classes that correspond to the exposed database operations. The generated classes can represent PL/SQL packages, queries, DML, AQ Streams, or Java classes in the database.

4. The database passes the response to the JAX-RPC processing servlet, which references the SOAP libraries and XML parser to encode it.

5. A SOAP response formed in accordance with the WSDL is returned to the client.

Database Call-out

You can extend a relational database's storage, indexing, and searching capabilities to include Web services. By calling a Web service, the database can track, aggregate, refresh, and query dynamic data produced on-demand, such as stock prices, currency exchange rates, or weather information. An example of using the database as a service consumer would be to call an external Web service from a predefined database job to obtain inventory information from multiple suppliers, then update your local inventory database. Another example is that of a Web Crawler: a database job can be scheduled to collate product and price information from a number of sources.

The following figure illustrates database call-out.

Figure 10-2 Calling Web Services from Within the Database

The following steps describe the process shown in the previous figure:

- SQL and PL/SQL call specs—Invoke a Web service through a user-defined function call either directly within a SQL statement or view, or through a variable.

- Dynamic Web service invocation using the UTL_DBWS PL/SQL package. A Call object can be dynamically created based on a WSDL and subsequently, Web services operations can be invoked.
Oracle Database PL/SQL Packages and Types Reference provides more information on using the UTL_DBWS PL/SQL package.

- Pure Java static proxy class—Generate a client proxy class which uses JAX-RPC. This method simplifies the Web service invocation as the location of the service is already known without needing to look up the service in the UDDI registry. The client proxy class does all of the work to construct the SOAP request, including marshalling and unmarshalling parameters.

- Pure Java using DII (dynamic invocation interface) over JAX-RPC—Dynamic invocation provides the ability to construct the SOAP request and access the service without the client proxy.

Which method to use depends on whether you want to execute from SQL or PL/SQL, from Java classes, or whether the service is known ahead of time (static invocation) or only at runtime (DII).

Type Mapping Between SQL and XML

The following sections describe the type mappings between SQL and XML for call-ins and call-outs when the Web service is known ahead of time (static invocation).

When the Web service is known at runtime you can use only the Dynamic Invocation Interface (DII) or the UTL_DBWS PL/SQL package.

SQL to XML Type Mappings for Web Service Call-Ins

In a database Web service call-in, a SQL operation, such as a PL/SQL stored procedure or a SQL statement, is mapped into one or more Web service operations. The parameters to the SQL operation are mapped from SQL types into XML types.

Note:

The reason there may be more than one operation is because OracleAS Web services may be providing additional data representation choices for the SQL values in XML, such as different representations of SQL result sets.

The following table illustrates the SQL-to-XML mappings for Web service call-ins. The first column lists the SQL types. The second column of the table, XML Type (Literal), shows SQL-to-XML type mappings for the default literal value of the use attribute. The third column, XML Type (Encoded), shows the mappings for the encoded value of the use attribute. The literal and encoded values refer to the rules for encoding the body of a SOAP message.

Table 10-1 SQL-to-XML Type Mappings for Web Services Call-ins

SQL Type

XML Type (Literal)

XML Type (Encoded)

INT

int

int

INTEGER

int

int

FLOAT

double

double

NUMBER

decimal

decimal

VARCHAR2

string

string

DATE

dateTime

dateTime

TIMESTAMP

dateTime

dateTime

BLOB

byte[]

byte[]

CLOB

String

String

LONG

String

String

RAW

byte[]

byte[]

Primitive PL/SQL indexby table

Array

Array

PL/SQL Boolean

boolean

boolean

PL/SQL indexby table

complexType

complexType

PL/SQL record

complexType

complexType

REF CURSOR (nameBeans)

Array

Array

REF CURSOR

nameXML)

any

test_xml

REF CURSOR

nameMLRowSet

swaRef

test_xml

SQL object

complexType

complexType

SQL table

complexType

complexType

SYS.XMLTYPE

any

test_xml

Note:

If National Language Support (also known as "NLS" or "Globalization Support") characters are used in a SQL SYS.XMLTYPE value, they may not be properly handled.

A query or a PL/SQL function returning REF CURSOR will be mapped into the three methods listed below, where name is the name of the query or the PL/SQL function.

- nameBeans—This method returns an array, where each element is an instance of an XSD complex type that represents one row in the cursor. A complex type sub-element corresponds to a column in that row.

- nameXMLRowSet—This method returns a swaRef or text_xml response that contains an OracleWebRowSet instance in XML format.

- nameXML—this method returns an XML any or text_xml response that contains an Oracle XDB row set.

Both OUT and IN OUT PL/SQL parameters are mapped to IN OUT parameters in the WSDL file.

Note that Table 10-1 provides two different mappings: one for literal and another for encoded use. The default mapping is literal. From a database Web service's perspective, there is no special reason why encoded should be used. The mapping for encoded is provided in case you encounter scenarios which call for the encoded use setting. All of the descriptions in this chapter assume that you will be using the literal use setting unless otherwise specified.

XML-to-SQL Type Mapping for Web Service Call-outs

In database Web services call-outs, XML types are mapped into SQL types. The following table lists the XML-to-SQL type mappings used in call-outs.

Table 10-2 XML-to-SQL Type Mappings for Web Service Call-outs

XML Type

SQL Type

int

NUMBER

float

NUMBER

double

NUMBER

decimal

NUMBER

dateTime

DATE

String

VARCHAR2

byte[]

RAW

complexType

SQL OBJECT

Array

SQL TABLE

test_xml

XML Type

Developing Database Web Services Using Oracle JDeveloper

Using Oracle JDeveloper 11g you can generate and deploy a PL/SQL Web service. JDeveloper's Create PL/SQL Web service wizard makes it easy to generate a web service from a PL/SQL package or a Java stored procedure that uses object types. A Java stored procedure is defined by a SQL specification that invokes it, and the PL/SQL Web service wizard treats these in the same way as packages.You can create Web services in a bottom-up fashion; that is, you cannot create a database Web service from a WSDL.

For more information, see "Creating PL/SQL Web Services" in the "Developing with Web Services" section of the Oracle JDeveloper online help.

Note:

Creating Web services out of Query, Java, DML, and Advanced Queues is not supported in this release.

11 Publishing and Finding Web Services Using UDDI

This chapter describes how to publish and find Web services using Universal Description, Discovery, and Integration (UDDI).

This chapter includes the following topics:

- Overview of UDDI

- WebLogic Server UDDI Features

- UDDI 2.0 Server

- UDDI Directory Explorer

- UDDI Client API

- Pluggable tModel

Note:

The UDDI v2.0 registry and UDDIExplorer applications are deprecated in this release. Customers are encouraged to consider upgrading to Oracle Enterprise Repository or Oracle Service Registry, which provide SOA visibility and governance. For more information, see http://www.oracle.com/technologies/soa/docs/enterprise-repository-svc-registry-datasheet.pdf.

Overview of UDDI

The UDDI Project is an industry initiative aims to enable businesses to quickly, easily, and dynamically find and carry out transactions with one another.

A populated UDDI registry contains cataloged information about businesses; the services that they offer; and communication standards and interfaces they use to conduct transactions.

Built on the Simple Object Access Protocol (SOAP) data communication standard, UDDI creates a global, platform-independent, open architecture space that will benefit businesses.

The UDDI registry can be broadly divided into two categories:

- UDDI and Web services

- UDDI and Business Registry

For details about the UDDI data structure, see UDDI Data Structure.

UDDI and Web Services

The owners of Web services publish them to the UDDI registry. Once published, the UDDI registry maintains pointers to the Web service description and to the service.

The UDDI allows clients to search this registry, find the intended service, and retrieve its details. These details include the service invocation point as well as other information to help identify the service and its functionality.

Web service capabilities are exposed through a programming interface, and usually explained through Web Services Description Language (WSDL). In a typical publish-and-inquire scenario, the provider publishes its business; registers a service under it; and defines a binding template with technical information on its Web service. The binding template also holds reference to one or several tModels, which represent abstract interfaces implemented by the Web service. The tModels might have been uniquely published by the provider, with information on the interfaces and URL references to the WSDL document.

A typical client inquiry may have one of two objectives:

- To find an implementation of a known interface. In other words, the client has a tModel ID and seeks binding templates referencing that Model.

- To find the updated value of the invocation point (that is., access point) of a known binding template ID.

UDDI and Business Registry

As a Business Registry solution, UDDI enables companies to advertise the business products and services they provide, as well as how they conduct business transactions on the Web. This use of UDDI complements business-to-business (B2B) electronic commerce.

The minimum required information to publish a business is a single business name. Once completed, a full description of a business entity may contain a wealth of information, all of which helps to advertise the business entity and its products and services in a precise and accessible manner.

A Business Registry can contain:

- Business Identification—Multiple names and descriptions of the business, comprehensive contact information, and standard business identifiers such as a tax identifier.

- Categories—Standard categorization information (for example a D-U-N-S business category number).

- Service Description—Multiple names and descriptions of a service. As a container for service information, companies can advertise numerous services, while clearly displaying the ownership of services. The bindingTemplate information describes how to access the service.

- Standards Compliance—In some cases it is important to specify compliance with standards. These standards might display detailed technical requirements on how to use the service.

- Custom Categories—It is possible to publish proprietary specifications (tModels) that identify or categorize businesses or services.

UDDI Data Structure

The data structure within UDDI consists of four constructions: a businessEntity structure, a businessService structure, a bindingTemplate structure and a tModel structure.

The following table outlines the difference between these constructions when used for Web service or Business Registry applications.

Table 11-1 UDDI Data Structure

Data Structure

Web Service

Business Registry

businessEntity

Represents a Web service provider:

- Company name

- Contact detail

- Other business information

Represents a company, a division or a department within a company:

- Company name(s)

- Contact details

- Identifiers and Categories

businessService

A logical group of one or several Web services.

API(s) with a single name stored as a child element, contained by the business entity named above.

A group of services may reside in a single businessEntity.

- Multiple names and descriptions

- Categories

- Indicators of compliancy with standards

bindingTemplate

A single Web service.

Technical information needed by client applications to bind and interact with the target Web service.

Contains access point (that is, the URI to invoke a Web service).

Further instances of standards conformity.

Access points for the service in form of URLs, phone numbers, email addresses, fax numbers or other similar address types.

tModel

Represents a technical specification; typically a specifications pointer, or metadata about a specification document, including a name and a URL pointing to the actual specifications. In the context of Web services, the actual specifications document is presented in the form of a WSDL file.

Represents a standard or technical specification, either well established or registered by a user for specific use.

WebLogic Server UDDI Features

WebLogic Server provides the following UDDI features:

- UDDI 2.0 Server

- UDDI Directory Explorer

- UDDI Client API

- Pluggable tModel

UDDI 2.0 Server

The UDDI 2.0 Server is part of WebLogic Server and is started automatically when WebLogic Server is started. The UDDI Server implements the UDDI 2.0 server specification. For more infomration, see http://uddi.org.

Configuring the UDDI 2.0 Server

To configure the UDDI 2.0 Server:

1. Stop WebLogic Server.

2. Update the uddi.properties file, located in the WL_HOME/server/lib directory, where WL_HOME refers to the main WebLogic Server installation directory.

Note:

If your WebLogic Server domain was created by a user different from the user that installed WebLogic Server, the WebLogic Server administrator must change the permissions on the uddi.properties file to give access to all users.

3. Restart WebLogic Server.

Never edit the uddi.properties file while WebLogic Server is running. Should you modify this file in a way that prevents the successful startup of the UDDI Server, refer to the WL_HOME/server/lib/uddi.properties.booted file for the last known good configuration.

To restore your configuration to its default, remove the uddi.properties file from the WL_HOME/server/lib directory. Oracle strongly recommends that you move this file to a backup location, because a new uddi.properties file will be created and with its successful startup, the uddi.properties.booted file will also be overwritten. After removing the properties file, start the server. Minimal default properties will be loaded and written to a newly created uddi.properties file.

The following section describes the UDDI Server properties that you can include in the uddi.properites file. The list of properties has been divided according to component, usage, and functionality. At any given time, you do not need all these properties to be present.

Configuring an External LDAP Server

The UDDI 2.0 Server is automatically configured with an embedded LDAP server. You can, however, also configure an external LDAP Server by following the procedure in this section.

Note:

Currently, WebLogic Server supports only the SunOne Directory Server for use with the UDDI 2.0 Server.

To configure the SunOne Directory Server to be used with UDDI, follow these steps:

1. Create a file called 51acumen.ldif in the LDAP_DIR/Sun/MPS/slapd-LDAP_INSTANCE_NAME/config/schema directory, where LDAP_DIR refers to the root installation directory of your SunOne Directory Server and LDAP_INSTANCE_NAME refers to the instance name.

2. Update the 51acumen.ldif file with the content described in 51acumen.ldif File Contents.

3. Restart the SunOne Directory Server.

4. Update the uddi.properties file of the WebLogic UDDI 2.0 Server, adding the following properties:

datasource.ldap.manager.password
datasource.ldap.manager.uid
datasource.ldap.server.root
datasource.ldap.server.url

The value of the properties depends on the configuration of your SunOne Directory Server. The following example shows a possible configuration that uses default values:

datasource.ldap.manager.password=password
datasource.ldap.manager.uid=cn=Directory Manager
datasource.ldap.server.root=dc=beasys,dc=com
datasource.ldap.server.url=ldap://host:port

See Table 11-1 for information about these properties.

5. Restart WebLogic Server.

51acumen.ldif File Contents

Use the following content to create the 51acumen.ldif file:

dn: cn=schema
#
# attribute types:
#
attributeTypes: ( 11827.0001.1.0 NAME 'uddi-Business-Key'                DESC 'Business Key' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{41} SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.1 NAME 'uddi-Authorized-Name'             DESC 'Authorized Name for publisher of
data' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.2 NAME 'uddi-Operator'                    DESC 'Name of UDDI Registry Operator'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.3 NAME 'uddi-Name'                        DESC 'Business Entity Name' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{258} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.4 NAME 'uddi-Description'                 DESC 'Description of Business Entity'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.7 NAME 'uddi-Use-Type'                    DESC 'Name of convention that the
referenced document follows' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.8 NAME 'uddi-URL'                         DESC 'URL' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.9 NAME 'uddi-Person-Name'                 DESC 'Name of Contact Person' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.10 NAME 'uddi-Phone'                      DESC 'Telephone Number' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{50} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.11 NAME 'uddi-Email'                      DESC 'Email address' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.12 NAME 'uddi-Sort-Code'                  DESC 'Code to sort addresses' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{10} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.13 NAME 'uddi-tModel-Key'                 DESC 'Key to reference a tModel entry'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.14 NAME 'uddi-Address-Line'               DESC 'Actual address lines in free
form text' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{80} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.15 NAME 'uddi-Service-Key'                DESC 'Service Key' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{41} SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.16 NAME 'uddi-Service-Name'               DESC 'Service Name' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.17 NAME 'uddi-Binding-Key'                DESC 'Binding Key' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{41} SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.18 NAME 'uddi-Access-Point'               DESC 'A text field to convey the entry
point address for calling a web service' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.19 NAME 'uddi-Hosting-Redirector'         DESC 'Provides a Binding Key attribute
to redirect reference to a different binding template' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{41} SINGLE-VALUE
X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.20 NAME 'uddi-Instance-Parms'             DESC 'Parameters to use a specific
facet of a bindingTemplate description' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.21 NAME 'uddi-Overview-URL'               DESC 'URL reference to a long form of
an overview document' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.22 NAME 'uddi-From-Key'                   DESC 'Unique key reference to first
businessEntity assertion is made for' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{41} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.23 NAME 'uddi-To-Key'                     DESC 'Unique key reference to second
businessEntity assertion is made for' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{41} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.24 NAME 'uddi-Key-Name'                   DESC 'An attribute of the
KeyedReference structure' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.25 NAME 'uddi-Key-Value'                  DESC 'An attribute of the
KeyedReference structure' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.26 NAME 'uddi-Auth-Info'                  DESC 'Authorization information'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{4096} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.27 NAME 'uddi-Key-Type'                   DESC 'The key for all UDDI entries'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{16} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.28 NAME 'uddi-Upload-Register'            DESC 'The upload register' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.29 NAME 'uddi-URL-Type'                   DESC 'The type for the URL' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{16} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.30 NAME 'uddi-Ref-Keyed-Reference'        DESC 'reference to a keyedReference
entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12{255}  X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.31 NAME 'uddi-Ref-Category-Bag'           DESC 'reference to a categoryBag
entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12{255}  X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.32 NAME 'uddi-Ref-Identifier-Bag'         DESC 'reference to a identifierBag
entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12{255}  X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.33 NAME 'uddi-Ref-TModel'                 DESC 'reference to a TModel entry'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12{255} SINGLE-VALUE X-ORIGIN 'acumen defined' )
# id names for each entry
attributeTypes: ( 11827.0001.1.34 NAME 'uddi-Contact-ID'                 DESC 'Unique ID which will serve as
the Distinguished Name of each entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{16} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.35 NAME 'uddi-Discovery-URL-ID'           DESC 'Unique ID which will serve as
the Distinguished Name of each entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{16} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.36 NAME 'uddi-Address-ID'                 DESC 'Unique ID which will serve as
the Distinguished Name of each entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{16} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.37 NAME 'uddi-Overview-Doc-ID'            DESC 'Unique ID which will serve as
the Distinguished Name of each entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{16} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.38 NAME 'uddi-Instance-Details-ID'        DESC 'Unique ID which will serve as
the Distinguished Name of each entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{16} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.39 NAME 'uddi-tModel-Instance-Info-ID'    DESC 'Unique ID which will serve as
the Distinguished Name of each entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{16} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.40 NAME 'uddi-Publisher-Assertions-ID'    DESC 'Unique ID which will serve as
the Distinguished Name of each entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{16} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.41 NAME 'uddi-Keyed-Reference-ID'         DESC 'Unique ID which will serve as
the Distinguished Name of each entry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{16} SINGLE-VALUE X-ORIGIN 'acumen
defined' )
attributeTypes: ( 11827.0001.1.42 NAME 'uddi-Ref-Attribute'              DESC 'a reference to another entry'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.43 NAME 'uddi-Entity-Name'                DESC 'Business entity Name' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{258} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.44 NAME 'uddi-tModel-Name'                DESC 'tModel Name' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{255} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.45 NAME 'uddi-tMII-TModel-Key'            DESC 'tModel key referneced in
tModelInstanceInfo' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.46 NAME 'uddi-Keyed-Reference-TModel-Key' DESC 'tModel key referneced in
KeyedReference' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.47 NAME 'uddi-Address-tModel-Key'         DESC 'tModel key referneced in
Address' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.48 NAME 'uddi-isHidden'                   DESC 'a flag to indicate whether an
entry is hidden' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.49 NAME 'uddi-Time-Stamp'                 DESC 'modification time satmp' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{255} SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.50 NAME 'uddi-next-id'                    DESC 'generic counter' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.51 NAME 'uddi-tModel-origin'              DESC 'tModel origin' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.52 NAME 'uddi-tModel-type'                DESC 'tModel type' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.53 NAME 'uddi-tModel-checked'             DESC 'tModel field to check or not'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.54 NAME 'uddi-user-quota-entity'          DESC 'quota for business entity'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.55 NAME 'uddi-user-quota-service'         DESC 'quota for business services per
entity' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.56 NAME 'uddi-user-quota-binding'         DESC 'quota for binding templates per
service' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.57 NAME 'uddi-user-quota-tmodel'          DESC 'quota for tmodels' SYNTAX
1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.58 NAME 'uddi-user-quota-assertion'       DESC 'quota for publisher assertions'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.59 NAME 'uddi-user-quota-messagesize'     DESC 'quota for maximum message size'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.60 NAME 'uddi-user-language'              DESC 'user language' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.61 NAME 'uddi-Name-Soundex'               DESC 'name in soundex format' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15{258} X-ORIGIN 'acumen defined' )
attributeTypes: ( 11827.0001.1.62 NAME 'uddi-var'                        DESC 'generic variable' SYNTAX
1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'acumen defined' )
#
# objectclasses:
#
objectClasses: ( 11827.0001.2.0 NAME 'uddi-Business-Entity'              DESC 'Business Entity object' SUP top
STRUCTURAL MUST (uddi-Business-Key $ uddi-Entity-Name $ uddi-isHidden $ uddi-Authorized-Name ) MAY (
uddi-Name-Soundex $ uddi-Operator $ uddi-Description $ uddi-Ref-Identifier-Bag $ uddi-Ref-Category-Bag )
X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.1 NAME 'uddi-Business-Service'             DESC 'Business Service object' SUP top
STRUCTURAL MUST ( uddi-Service-Key $ uddi-Service-Name $ uddi-isHidden ) MAY ( uddi-Name-Soundex $
uddi-Description $ uddi-Ref-Category-Bag ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.2 NAME 'uddi-Binding-Template'             DESC 'Binding Template object' SUP TOP
STRUCTURAL   MUST ( uddi-Binding-Key $ uddi-isHidden ) MAY ( uddi-Description $ uddi-Access-Point $
uddi-Hosting-Redirector ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.3 NAME 'uddi-tModel'                       DESC 'tModel object' SUP top
STRUCTURAL   MUST (uddi-tModel-Key $ uddi-tModel-Name $ uddi-isHidden $ uddi-Authorized-Name ) MAY (
uddi-Name-Soundex $ uddi-Operator $ uddi-Description $ uddi-Ref-Identifier-Bag $ uddi-Ref-Category-Bag $
uddi-tModel-origin $ uddi-tModel-checked $ uddi-tModel-type ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.4 NAME 'uddi-Publisher-Assertion'          DESC 'Publisher Assertion object' SUP
TOP STRUCTURAL   MUST ( uddi-Publisher-Assertions-ID $ uddi-From-Key $ uddi-To-Key $ uddi-Ref-Keyed-Reference )
X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.5 NAME 'uddi-Discovery-URL'                DESC 'Discovery URL' SUP TOP
STRUCTURAL   MUST ( uddi-Discovery-URL-ID $ uddi-Use-Type $ uddi-URL ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.6 NAME 'uddi-Contact'                      DESC 'Contact Information' SUP TOP
STRUCTURAL   MUST ( uddi-Contact-ID $ uddi-Person-Name ) MAY ( uddi-Use-Type $ uddi-Description $ uddi-Phone $
uddi-Email $ uddi-tModel-Key ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.7 NAME 'uddi-Address'                      DESC 'Address information for a
contact entry' SUP TOP STRUCTURAL   MUST ( uddi-Address-ID ) MAY ( uddi-Use-Type $ uddi-Sort-Code $
uddi-Address-tModel-Key $ uddi-Address-Line ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.8 NAME 'uddi-Keyed-Reference'              DESC 'KeyedReference' SUP TOP
STRUCTURAL   MUST ( uddi-Keyed-Reference-ID $ uddi-Key-Value ) MAY ( uddi-Key-Name $
uddi-Keyed-Reference-TModel-Key ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.9 NAME 'uddi-tModel-Instance-Info'         DESC 'tModelInstanceInfo' SUP TOP
STRUCTURAL   MUST ( uddi-tModel-Instance-Info-ID $ uddi-tMII-TModel-Key ) MAY ( uddi-Description ) X-ORIGIN
'acumen defined' )
objectClasses: ( 11827.0001.2.10 NAME 'uddi-Instance-Details'            DESC 'instanceDetails' SUP TOP
STRUCTURAL   MUST ( uddi-Instance-Details-ID ) MAY ( uddi-Description $ uddi-Instance-Parms ) X-ORIGIN 'acumen
defined' )
objectClasses: ( 11827.0001.2.11 NAME 'uddi-Overview-Doc'                DESC 'overviewDoc' SUP TOP STRUCTURAL
MUST ( uddi-Overview-Doc-ID ) MAY ( uddi-Description $ uddi-Overview-URL ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.12 NAME 'uddi-Ref-Object'                  DESC 'an object class conatins a
reference to another entry' SUP TOP STRUCTURAL MUST ( uddi-Ref-Attribute ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.13 NAME 'uddi-Ref-Auxiliary-Object'        DESC 'an auxiliary type object used in
another structural class to hold a reference to a third entry' SUP TOP AUXILIARY MUST ( uddi-Ref-Attribute )
X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.14 NAME 'uddi-ou-container'                DESC 'an organizational unit with uddi
attributes' SUP organizationalunit STRUCTURAL MAY ( uddi-next-id $ uddi-var ) X-ORIGIN 'acumen defined' )
objectClasses: ( 11827.0001.2.15 NAME 'uddi-User'                        DESC 'a User with uddi attributes' SUP
inetOrgPerson STRUCTURAL MUST ( uid $ uddi-user-language $ uddi-user-quota-entity $ uddi-user-quota-service $
uddi-user-quota-tmodel $ uddi-user-quota-binding $ uddi-user-quota-assertion $ uddi-user-quota-messagesize )
X-ORIGIN 'acumen defined' )

Description of Properties in the uddi.properties File

The following tables describe properties of the uddi.properties file, categorized by the type of UDDI feature they describe:

- Table 11-2, "Basic UDDI Configuration"

- Table 11-3, "UDDI User Defaults"

- Table 11-4, "General Server Configuration"

- Table 11-5, "Logger Configuration"

- Table 11-6, "Connection Pools"

- Table 11-7, "LDAP Datastore Configuration"

- Table 11-8, "Replicated LDAP Datastore Configuration"

- Table 11-9, "File Datastore Configuration"

- Table 11-10, "General Security Configuration"

- Table 11-11, "LDAP Security Configuration"

- Table 11-12, "File Security Configuration"

Table 11-2 Basic UDDI Configuration

UDDI Property Key

Description

auddi.discoveryurl

DiscoveryURL prefix that is set for each saved business entity. Typically this is the full URL to the uddilistener servlet, so that the full DiscoveryURL results in the display of the stored BusinessEntity data.

auddi.inquiry.secure

Permissible values are true and false. When set to true, inquiry calls to UDDI Server are limited to secure https connections only. Any UDDI inquiry calls through a regular http URL are rejected.

auddi.publish.secure

Permissible values are true and false. When set to true, publish calls to UDDI Server are limited to secure https connections only. Any UDDI publish calls through a regular http URL are rejected.

auddi.search.maxrows

Maximum number of returned rows for search operations. When the search results in a higher number of rows then the limit set by this property, the result is truncated.

auddi.search.timeout

Timeout value for search operations. The value is indicated in milliseconds.

auddi.siteoperator

Name of the UDDI registry site operator. The specified value will be used as the operator attribute, saved in all future BusinessEntity registrations. This attribute will later be returned in responses, and indicates which UDDI registry has generated the response.

security.cred.life

Credential life, specified in seconds, for authentication. Upon authentication of a user, an AuthToken is assigned which will be valid for the duration specified by this property.

pluggableTModel.file.list

UDDI Server is pre-populated with a set of Standard TModels. You can further customize the UDDI server by providing your own taxonomies, in the form of TModels. Taxonomies must be defined in XML files, following the provided XML schema. The value of this property a comma-separated list of URIs to such XML files. Values that refer to these TModels are checked and validated against the specified taxonomy.

Table 11-3 UDDI User Defaults

UDDI Property Key

Description

auddi.default.lang

User's initial language, assigned to user profile by default at the time of creation. User profile settings can be changed at sign-up or later.

auddi.default.quota.assertion

User's initial assertion quota, assigned to user profile by default at the time of creation. The assertion quota is the maximum number of publisher assertions that the user is allowed to publish. To impose no limits, set a value of -1. A user's profile settings can be changed at sign-up or later.

auddi.default.quota.binding

User's initial binding quota, assigned to user profile by default at the time of creation. The binding quota is the maximum number of binding templates that the user is allowed to publish, per each business service. To impose no limits, set a value of -1. A user's profile settings can be changed at sign-up or later.

auddi.default.quota.entity

User's initial business entity quota, assigned to user profile by default at the time of creation. The entity quota is the maximum number of business entities that the user is allowed to publish. To impose no limits, set a value of -1. A user's profile settings can be changed at sign-up or later.

auddi.default.quota.messageSize

User's initial message size limit, assigned to his user profile by default at the time of creation. The message size limit is the maximum size of a SOAP call that the user may send to UDDI Server. To impose no limits, set a value of -1. A user's profile settings can be changed at sign-up or later.

auddi.default.quota.service

User's initial service quota, assigned to user profile by default at the time of creation. The service quota is the maximum number of business services that the user is allowed to publish, per each business entity. To impose no limits, set a value of -1. A user's profile settings can be changed at sign-up or later.

auddi.default.quota.tmodel

User's initial TModel quota, assigned to user profile by default at the time of creation. The TModel quota is the maximum number of TModels that the user is allowed to publish. To impose no limits, set a value of -1. A user's profile settings can be changed at sign-up or later.

Table 11-4 General Server Configuration

UDDI Property Keys

Description

auddi.datasource.type

Location of physical storage of UDDI data. This value defaults to WLS, which indicates that the internal LDAP directory of WebLogic Server is to be used for data storage. Other permissible values include LDAP, ReplicaLDAP, and File.

auddi.security.type

UDDI Server's security module (authentication). This value defaults to WLS, which indicates that the default security realm of WebLogic Server is to be used for UDDI authentication. As such, a WebLogic Server user would be an UDDI Server user and any WebLogic Server administrator would also be an UDDI Server administrator, in addition to members of the UDDI Server administrator group, as defined in UDDI Server settings. Other permissible values include LDAP and File.

auddi.license.dir

Location of the UDDI Server license file. In the absence of this property, the WL_HOME/server/lib directory is assumed to be the default license directory, where WL_HOME is the main WebLogic Server installation directory. Some WebLogic users are exempt from requiring a UDDI Server license for the basic UDDI Server components, while they may need a license for additional components (for example., UDDI Server Browser).

auddi.license.file

Name of the license file. In the absence of this property, uddilicense.xml is presumed to be the default license filename. Some WebLogic users are exempt from requiring an UDDI Server license for the basic UDDI Server components, while they may need a license for additional components (e.g., UDDI Server Browser).

Table 11-5 Logger Configuration

UDDI Property Key

Description

logger.file.maxsize

Maximum size of logger output files (if output is sent to file), in Kilobytes. Once an output file reaches maximum size, it is closed and a new log file is created.

logger.indent.enabled

Permissible values are true and false. When set to true, log messages beginning with "+" and "-", typically TRACE level logs, cause an increase or decrease of indentation in the output.

logger.indent.size

Size of each indentation (how many spaces for each indent), specified as an integer.

logger.log.dir

Absolute or relative path to a directory where log files are stored.

logger.log.file.stem

String that is prefixed to all log file names.

logger.log.type

Determines whether log messages are sent to the screen, to a file or to both destinations. Permissible values, respectively, are: LOG_TYPE_SCREEN, LOG_TYPE_FILE, and LOG_TYPE_SCREEN_FILE.

logger.output.style

Determines whether logged output will simply contain the message, or thread and timestamp information will be included. Permissible values are OUTPUT_LONG and OUTPUT_SHORT.

logger.quiet

Determines whether the logger itself displays information messages. Permissible values are true and false.

logger.verbosity

Logger's verbosity level. Permissible values (case sensitive) are TRACE, DEBUG, INFO, WARNING and ERROR, where each severity level includes the following ones accumulatively.

Table 11-6 Connection Pools

UDDI Property Key

Description

datasource.ldap.pool.increment

Number of new connections to create and add to the pool when all connections in the pool are busy

datasource.ldap.pool.initialsize

Number of connections to be stored at the time of creation and initialization of the pool.

datasource.ldap.pool.maxsize

Maximum number of connections that the pool may hold.

datasource.ldap.pool.systemmaxsize

Maximum number of connections created, even after the pool has reached its capacity. Once the pool reaches its maximum size, and all connections are busy, connections are temporarily created and returned to the client, but not stored in the pool. However, once the system max size is reached, all requests for new connections are blocked until a previously busy connection becomes available.

Table 11-7 LDAP Datastore Configuration

UDDI Property Key

Description

datasource.ldap.manager.uid

Back-end LDAP server administrator or privileged user ID, (for example, cn=Directory Manager) who can save data in LDAP.

datasource.ldap.manager.password

Password for the datasource.ldap.manager.uid, establishes connections with the LDAP directory used for data storage.

datasource.ldap.server.url

"ldap://" URL to the LDAP directory used for data storage.

datasource.ldap.server.root

Root entry of the LDAP directory used for data storage (e.g., dc=acumenat, dc=com).

Note:

In a replicated LDAP environment, there are "m" LDAP masters and "n" LDAP replicas, respectively numbered from 0 to (m-1) and from 0 to (n-1). The fifth part of the property keys below, quoted as "i", refers to this number and differs for each LDAP server instance defined.

Table 11-8 Replicated LDAP Datastore Configuration

UDDI Property Key

Description

datasource.ldap.server.master.i.manager.uid

Administrator or privileged user ID for this "master" LDAP server node, (for example, cn=Directory Manager) who can save data in LDAP.

datasource.ldap.server.master.i.manager.password

Password for the datasource.ldap.server.master.i.manager.uid, establishes connections with the relevant "master" LDAP directory to write data.

datasource.ldap.server.master.i.url

"ldap://" URL to the corresponding LDAP directory node.

datasource.ldap.server.master.i.root

Root entry of the corresponding LDAP directory node (for example, dc=acumenat, dc=com).

datasource.ldap.server.replica.i.manager.uid

User ID for this "replica" LDAP server node (for example, cn=Directory Manager); this person can read the UDDI data from LDAP.

datasource.ldap.server.replica.i.manager.password

Password for datasource.ldap.server.replica.i.manager.uid, establishes connections with the relevant "replica" LDAP directory to read data.

datasource.ldap.server.replica.i.url

"ldap://" URL to the corresponding LDAP directory node.

datasource.ldap.server.replica.i.root

Root entry of the corresponding LDAP directory node (for example, dc=acumenat, dc=com).

Table 11-9 File Datastore Configuration

UDDI Property Key

Description

datasource.file.directory

Directory where UDDI data is stored in the file system.

Table 11-10 General Security Configuration

UDDI Property Key

Description

security.custom.group.operators

Security group name, where the members of this group are treated as UDDI administrators.

Table 11-11 LDAP Security Configuration

UDDI Property Key

Description

security.custom.ldap.manager.uid

Security LDAP server administrator or privileged user ID (for example, cn=Directory Manager); this person can save data in LDAP.

security.custom.ldap.manager.password

The value of this property is the password for the above user ID, and is used to establish connections with the LDAP directory used for security.

security.custom.ldap.url

The value of this property is an ldap:// URL to the LDAP directory used for security.

security.custom.ldap.root

Root entry of the LDAP directory used for security (for example, dc=acumenat, dc=com).

security.custom.ldap.userroot

User's root entry on the security LDAP server. For example, ou=People.

security.custom.ldap.group.root

Operator entry on the security LDAP server. For example, "cn=UDDI Administrators, ou=Groups". This entry contains IDs of all UDDI administrators.

Table 11-12 File Security Configuration

UDDI Property Key

Description

security.custom.file.userdir

Directory where UDDI security information (users and groups) is stored in the file system.

UDDI Directory Explorer

The UDDI Directory Explorer allows authorized users to publish Web services in private WebLogic Server UDDI registries and to modify information for previously published Web services. The Directory Explorer provides access to details about the Web services and associated WSDL files (if available.)

The UDDI Directory Explorer also enables you to search both public and private UDDI registries for Web services and information about the companies and departments that provide these Web services.

To invoke the UDDI Directory Explorer in your browser, enter:

http://host:port/uddiexplorer

where

- host is the computer on which WebLogic Server is running.

- port is the port number where WebLogic Server listens for connection requests. The default port number is 7001.

Note:

To access the UDDI Directory Explorer pages, use your Oracle WebLogic Server username and password.

You can perform the following tasks with the UDDI Directory Explorer:

- Search public registries

- Search private registries

- Publish to a private registry

- Modify private registry details

- Setup UDDI directory explorer

For more information about using the UDDI Directory Explorer, click the Explorer Help link on the main page.

UDDI Client API

WebLogic Server includes an implementation of the client-side UDDI API that you can use in your Java client applications to programmatically search for and publish Web services.

The two main classes of the UDDI client API are Inquiry and Publish. Use the Inquiry class to search for Web services in a known UDDI registry and the Publish class to add your Web service to a known registry.

WebLogic Server provides an implementation of the following client UDDI API packages:

- "weblogic.uddi.client.service"

- "weblogic.uddi.client.structures.datatypes"

- "weblogic.uddi.client.structures.exception"

- "weblogic.uddi.client.structures.request"

- "weblogic.uddi.client.structures.response"

For detailed information on using these packages, see the Oracle WebLogic Server API Reference.

Pluggable tModel

A taxonomy is basically a tModel used as reference by a categoryBag or identifierBag. A major distinction is that in contrast to a simple tModel, references to a taxonomy are typically checked and validated. WebLogic Server's UDDI Server takes advantage of this concept and extends this capability by introducing custom taxonomies, called "pluggable tModels". Pluggable tModels allow users (UDDI administrators) to add their own checked taxonomies to the UDDI registry, or overwrite standard taxonomies.

To add a pluggable tModel:

1. Create an XML file conforming to the specified format described in XML Schema for Pluggable tModels, for each tModelKey/categorization.

2. Add the comma-delimited, fully qualified file names to the pluggableTModel.file.list property in the uddi.properties file used to configure UDDI Server. For example:

pluggableTModel.file.list=c:/temp/cat1.xml,c:/temp/cat2.xml

See Configuring the UDDI 2.0 Server for details about the uddi.properties file.

3. Restart WebLogic Server.

The following sections include a table detailing the XML elements and their permissible values, the XML schema against which pluggable tModels are validated, and a sample XML.

XML Elements and Permissible Values

The following table describes the elements of the XML file that describes your pluggable tModels.

Table 11-13 Description of the XML Elements to Configure Pluggable tModels

Element/Attribute

Required

Role

Values

Comments

Taxonomy

Required

Root Element

-

None.

checked

Required

Whether this categorization is checked or not.

true / false

If false, keyValue will not be validated.

type

Required

The type of the tModel.

categorization / identifier / valid values as defined in uddi-org-types

See uddi-org-types tModel for valid values.

applicability

Optional

Constraints on where the tModel may be used.

-

No constraint is assumed if this element is not provided

scope

Required if the applicability element is included.

Constraints on where the tModel may be used.

businessEntity / businessService / bindingTemplate / tModel

tModel may be used in tModelInstanceInfo if scope "bindingTemplate" is specified.

tModel

Required

The actual tModel, according to the UDDI data structure.

Valid tModelKey must be provided.

None.

categories

Required if checked is set to true.

-

-

None.

category

Required if element categories is included

Holds actual keyName and keyValue pairs.

keyName / keyValue pairs

category may be nested for grouping or tree structure.

keyName

Required

-

-

None.

keyValue

Required

-

-

None.

XML Schema for Pluggable tModels

The XML Schema against which pluggable tModels are validated is as follows:

<simpleType name="type">
<restriction base="string"/>
</simpleType>

<simpleType name="checked">
<restriction base="NMTOKEN">
<enumeration value="true"/>
<enumeration value="false"/>
</restriction>
</simpleType>

<element name="scope" type="string"/>

<element name = "applicability" type = "uddi:applicability"/>

<complexType name = "applicability">
<sequence>
<element ref = "uddi:scope" minOccurs = "1" maxOccurs = "4"/>
</sequence>
</complexType>

<element name="category" type="uddi:category"/>

<complexType name = "category">
<sequence>
<element ref = "uddi:category" minOccurs = "0" maxOccurs = "unbounded"/>

</sequence>
<attribute name = "keyName" use = "required" type="string"/>
<attribute name = "keyValue" use = "required" type="string"/>
</complexType>
<element name="categories" type="uddi:categories"/>

<complexType name = "categories">
<sequence>
<element ref = "uddi:category" minOccurs = "1" maxOccurs = "unbounded"/>
</sequence>
</complexType>

<element name="Taxonomy" type="uddi:Taxonomy"/>

<complexType name="Taxonomy">
<sequence>
<element ref = "uddi:applicability" minOccurs = "0" maxOccurs = "1"/>
<element ref = "uddi:tModel" minOccurs = "1" maxOccurs = "1"/>
<element ref = "uddi:categories" minOccurs = "0" maxOccurs = "1"/>
</sequence>
<attribute name = "type" use = "required" type="uddi:type"/>
<attribute name = "checked" use = "required" type="uddi:checked"/>
</complexType>

Sample XML for a Pluggable tModel

The following shows a sample XML for a pluggable tModel:

<?xml version="1.0" encoding="UTF-8" ?>

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Body>

<Taxonomy checked="true" type="categorization" xmlns="urn:uddi-org:api_v2" >
<applicability>
<scope>businessEntity</scope>
<scope>businessService</scope>
<scope>bindingTemplate</scope>
</applicability>
<tModel  tModelKey="uuid:C0B9FE13-179F-41DF-8A5B-5004DB444tt2" >
<name> sample pluggable tModel </name>
<description>used for test purpose only </description>
<overviewDoc>
<overviewURL>http://www.abc.com </overviewURL>
</overviewDoc>
</tModel>
<categories>
<category keyName="name1 " keyValue="1">
<category keyName="name11" keyValue="12">
<category keyName="name111" keyValue="111">
<category keyName="name1111" keyValue="1111"/>
<category keyName="name1112" keyValue="1112"/>
</category>
<category keyName="name112" keyValue="112">
<category keyName="name1121" keyValue="1121"/>
<category keyName="name1122" keyValue="1122"/>
</category>
</category>
</category>
<category keyName="name2 " keyValue="2">
<category keyName="name21" keyValue="22">
<category keyName="name211" keyValue="211">
<category keyName="name2111" keyValue="2111"/>
<category keyName="name2112" keyValue="2112"/>
</category>
<category keyName="name212" keyValue="212">
<category keyName="name2121" keyValue="2121"/>
<category keyName="name2122" keyValue="2122"/>
</category>
</category>
</category>
</categories>
</Taxonomy>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

A Pre-Packaged WS-Policy Files for Reliable Messaging

This appendix describes the pre-packaged WS-Policy files that contain typical reliable messaging assertions that you can use to support reliable messaging with WebLogic Java API for XML-based RPC (JAX-RPC) Web services.

This appendix includes the following topics:

- DefaultReliability1.1.xml (WS-Policy File)

- Reliability1.1_SequenceTransportSecurity.xml (WS-Policy File)

- Reliability1.1_SequenceSTR.xml (WS-Policy File)

- Reliability1.0_1.1.xml (WS-Policy.xml File)

- DefaultReliability.xml (WS-Policy File) [Deprecated]

- LongRunningReliability.xml (WS-Policy File) [Deprecated]

You cannot change these pre-packaged files. If their values do not suit your needs, you must create your own WS-Policy file. See Creating the Web Service Reliable Messaging WS-Policy File for details. See "Web Service Reliable Messaging Policy Assertion Reference" in WebLogic Web Services Reference for Oracle WebLogic Server for reference information about the reliable messaging policy assertions.

DefaultReliability1.1.xml (WS-Policy File)

The DefaultRealiability1.1.xml WS-Policy file specifies policy assertions related to quality of service. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.1 at http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf.

<?xml version="1.0"?>

<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
>
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702"
>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce />
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:Policy>

Reliability1.1_SequenceTransportSecurity.xml (WS-Policy File)

The Reliability1.1_SequenceTransportSecurity.xml file specifies policy assertions related to transport-level security and quality of service. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.1 at http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf.

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceTransportSecurity/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:Policy>

Reliability1.1_SequenceSTR.xml (WS-Policy File)

The Reliability1.1_SequenceSTR.xml file specifies that in order to secure messages in a reliable sequence, the runtime will use the wsse:SecurityTokenReference that is referenced in the CreateSequence message. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.1 at http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf.

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceSTR/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:Policy>

Reliability1.0_1.1.xml (WS-Policy.xml File)

The Reliability1.0_1.1.xml WS-Policy.xml file combines 1.1 and 1.0 WS-Reliable Messaging policy assertions. This sample relies on smart policy selection to determine the policy assertion that is applied at runtime. For more information about smart policy selection, see Using Multiple Policy Alternatives.

Note:

The 1.0 Web service reliable messaging assertions are prefixed by wsrmp10.

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:ExactlyOne>
<wsp:All>
<wsrmp10:RMAssertion
xmlns:wsrmp10="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
<wsrmp10:InactivityTimeout Milliseconds="600000"/>
<wsrmp10:BaseRetransmissionInterval Milliseconds="3000"/>
<wsrmp10:ExponentialBackoff/>
<wsrmp10:AcknowledgementInterval Milliseconds="200"/>
</wsrmp10:RMAssertion>
</wsp:All>
<wsp:All>
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceSTR/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

DefaultReliability.xml (WS-Policy File) [Deprecated]

This WS-Policy file is deprecated. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion Version 1.0 at http://schemas.xmlsoap.org/ws/2005/02/rm/policy/. In the current release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

The DefaultReliability.xml WS-Policy file specifies typical values for the reliable messaging policy assertions, such as inactivity timeout of 10 minutes, acknowledgement interval of 200 milliseconds, and base retransmission interval of 3 seconds.

<?xml version="1.0"?>

<wsp:Policy
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:beapolicy="http://www.bea.com/wsrm/policy"
>

<wsrm:RMAssertion >

<wsrm:InactivityTimeout
Milliseconds="600000" />
<wsrm:BaseRetransmissionInterval
Milliseconds="3000" />
<wsrm:ExponentialBackoff />
<wsrm:AcknowledgementInterval
Milliseconds="200" />
<beapolicy:Expires Expires="P1D" optional="true"/>
</wsrm:RMAssertion>

</wsp:Policy>

LongRunningReliability.xml (WS-Policy File) [Deprecated]

This WS-Policy file is deprecated. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion Version 1.0 at http://schemas.xmlsoap.org/ws/2005/02/rm/policy/. In the current release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

The LongRunningRelibility.xml WS-Policy files specifies values that are similar to the DefaultReliability.xml WS-Policy file, except that it specifies a much longer activity timeout interval (24 hours). See LongRunningReliability.xml (WS-Policy File) [Deprecated].

<?xml version="1.0"?>

<wsp:Policy
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:beapolicy="http://www.bea.com/wsrm/policy"
>

<wsrm:RMAssertion >

<wsrm:InactivityTimeout
Milliseconds="86400000" />
<wsrm:BaseRetransmissionInterval
Milliseconds="3000" />
<wsrm:ExponentialBackoff />
<wsrm:AcknowledgementInterval
Milliseconds="200" />
<beapolicy:Expires Expires="P1M" optional="true"/>
</wsrm:RMAssertion>

</wsp:Policy>

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2014, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.