Programming Web Services for WebLogic Server

Introduction and Roadmap

Document Scope and Audience

Guide to This Document

Samples for the Web Services Developer

Downloading Examples Described in this Guide

Avitek Medical Records Application (MedRec) and Tutorials

Web Services Examples in the WebLogic Server Distribution

Additional Web Services Examples Available for Download

Release-Specific WebLogic Web Services Information

Differences Between 8.1 and 9.0 WebLogic Web Services

Summary of WebLogic Web Services Features

Differences Between Beta and GA WebLogic Web Services

Understanding WebLogic Web Services

What Are Web Services?

Why Use Web Services?

Anatomy of a WebLogic Web Service

Roadmap of Common Web Service Development Tasks

Standards Supported by WebLogic Web Services

BEA Implementation of Web Service Specifications

Web Services Metadata for the Java Platform (JSR-181)

Enterprise Web Services 1.1

SOAP 1.1

SAAJ 1.2

WSDL 1.1

JAX-RPC 1.1

Web Services Security (WS-Security) 1.0

UDDI 2.0

JAX-R 1.0

WS-Addressing 1.0

WS-Policy 1.0

WS-PolicyAttachment 1.0

WS-ReliableMessaging 1.0

Additional Specifications Supported by WebLogic Web Services

Common Web Services Use Cases and Examples

Creating a Simple HelloWorld Web Service

Creating a Web Service With User-Defined Data Types

Creating a Web Service from a WSDL File

Invoking a Web Service from a Stand-alone JAX-RPC Java Client

Invoking a Web Service from a WebLogic Web Service

Iterative Development of WebLogic Web Services

Overview of the WebLogic Web Service Programming Model

Iterative Development of WebLogic Web Services Starting From Java: Main Steps

Iterative Development of WebLogic Web Services Starting From a WSDL File: Main Steps

Creating the Basic Ant build.xml File

Running the jwsc WebLogic Web Services Ant Task

Running the wsdlc WebLogic Web Services Ant Task

Updating the Stubbed-Out JWS Implementation Class File Generated By wsdlc

Deploying and Undeploying WebLogic Web Services

Using the wldeploy Ant Task to Deploy Web Services

Using the Administration Console to Deploy Web Services

Browsing to the WSDL of the Web Service

Testing the Web Service

Integrating Web Services Into the WebLogic Split Development Directory Environment

Programming the JWS File

Overview of JWS Files and JWS Annotations

Programming the JWS File: Java Requirements

Programming the JWS File: Typical Steps

Example of a JWS File

Specifying That the JWS File Implements a Web Service

Specifying the Mapping of the Web Service to the SOAP Message Protocol

Specifying the Context Path and Service URI of the Web Service

Specifying That a JWS Method Be Exposed as a Public Operation

Customizing the Mapping Between Operation Parameters and WSDL Parts

Customizing the Mapping Between the Operation Return Value and a WSDL Part

Accessing Runtime Information about a Web Service Using the JwsContext

Guidelines for Accessing the Web Service Context

Methods of the JwsContext

Should You Implement a Stateless Session EJB?

Programming Guidelines When Implementing an EJB in Your JWS File

Example of a JWS File That Implements an EJB

Programming the User-Defined Java Data Type

Throwing Exceptions

Invoking Another Web Service from the JWS File

JWS Programming Best Practices

Advanced JWS Programming: Implementing Asynchronous Features

Using Web Service Reliable Messaging

Use of WS-Policy Files for Web Service Reliable Messaging Configuration

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

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

Invoking a Web Service Using Asynchronous Request-Response

Using Asynchronous Request-Response: Main Steps

Writing the Asynchronous JWS File

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

Creating 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

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

Creating 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

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 Reliable Messaging or Asynchronous Request Response With a Proxy Server

Advanced JWS Programming: JMS Tranpsort and SOAP Message Handlers

Using JMS Transport as the Connection Protocol

Using JMS Transport: Main Steps

Using the @WLJmsTransport JWS Annotation

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

Invoking a WebLogic Web Service Using JMS Transport

Creating and Using 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

Data Types and Data Binding

Overview of Data Types and Data Binding

Supported Built-In Data Types

XML-to-Java Mapping for Built-In Data Types

Java-to-XML Mapping for Built-In Data Types

Supported User-Defined Data Types

Supported XML User-Defined Data Types

Supported Java User-Defined Data Types

Invoking Web Services

Overview of Invoking Web Services

Types of Client Applications

JAX-RPC

The clientgen Ant Task

Examples of Clients That Invoke Web Services

Invoking a Web Service from a Stand-alone Client: Main Steps

Using the clientgen Ant Task To Generate Client Artifacts

Getting Information About a Web Service

Writing the Java Client Application Code

Compiling and Running the Client Application

Sample Ant Build File for a Stand-Alone Java Client

Invoking a Web Service from Another Web Service

Sample build.xml File for a Web Service Client

Sample JWS File That Invokes a 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

Using a Client-Side Security WS-Policy File

Associating a Client-Side WS-Policy File with a Client Application: Main Steps

Updating clientgen to Generate Methods That Load a WS-Policy File

Updating a Client Application To Load a WS-Policy File

Configuring Security

Overview of Web Services Security

What Type of Security Should You Configure?

Configuring Message-Level Security (Digital Signatures and Encryption)

Main Use Cases

Using WS-Policy Files for Message-Level Security Configuration

WebLogic Server and Custom WS-Policy Files

Auth.xml

Sign.xml

Encrypt.xml

Abstract and Concrete WS-Policy Files

Configuring Simple Message-Level Security: Main Steps

Using Key Pairs Other Than the Out-Of-The-Box SSL Pair

Setting the SOAP Message Expiration

Creating and Using a Custom WS-Policy File

Associating WS-Policy Files at Runtime Using the Administration Console

Using Security Assertion Markup Language (SAML) Tokens For Identity

Using X.509 Certificate Tokens for Identity

Using a Password Digest In the SOAP Message Rather Than Plaintext

Invoking a Message-Secured Web Service From A Client Running in a WebLogic Server Instance

Associating a Web Service with a Security Configuration Other Than the Default

Configuring Transport-Level Security

Configuring Two-Way SSL for a Client Application

Additional Web Services SSL Examples

Configuring Access Control Security: Main Steps

Updating the JWS File With the @SecurityRoles and @SecurityIdentity Annotations

Updating a Client Application to Authenticate Itself Using JAX-RPC Properties

Administering Web Services

Overview of WebLogic Web Services Administration Tasks

Administration Tools

Using the Administration Console

Invoking the Administration Console

How Web Services Are Displayed In the Administration Console

Creating a Web Services Security Configuration

Using the WebLogic Scripting Tool

Using WebLogic Ant Tasks

Using the Java Management Extensions (JMX)

Using the J2EE Deployment API

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

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

Upgrading an 8.1 Web Service to 9.0

Overview of Upgrading an 8.1 WebLogic Web Service

Upgrading an 8.1 Java Class-Implemented WebLogic Web Service to 9.0: Main Steps

Example of an 8.1 Java File and the Corresponding 9.0 JWS File

Example of an 8.1 and Updated 9.0 Ant Build File for Java Class-Implemented Web Services

Upgrading an 8.1 EJB-Implemented WebLogic Web Service to 9.0: Main Steps

Example of 8.1 EJB Files and the Corresponding 9.0 JWS File

Example of an 8.1 and Updated 9.0 Ant Build File for an 8.1 EJB-Implemented Web Service

Mapping of servicegen Attributes to JWS Annotations or jwsc Attributes

Ant Task Reference

Overview of WebLogic Web Services Ant Tasks

List of Web Services Ant Tasks

Using the Web Services Ant Tasks

Setting the Classpath for the WebLogic Ant Tasks

Differences in Operating System Case Sensitivity When Manipulating WSDL and XML Schema Files

clientgen

jwsc

wsdlc

JWS Annotation Reference

Overview of JWS Annotation Tags

Standard JSR-181 JWS Annotations Reference

javax.jws.WebService

javax.jws.WebMethod

javax.jws.Oneway

javax.jws.WebParam

javax.jws.WebResult

javax.jws.HandlerChain

javax.jws.soap.SOAPBinding

javax.jws.soap.SOAPMessageHandler

javax.jws.soap.InitParam

javax.jws.soap.SOAPMessageHandlers

WebLogic-Specific JWS Annotations Reference

weblogic.jws.AsyncFailure

weblogic.jws.AsyncResponse

weblogic.jws.BufferQueue

weblogic.jws.Context

weblogic.jws.Conversation

weblogic.jws.Conversational

weblogic.jws.MessageBuffer

weblogic.jws.Policies

weblogic.jws.Policy

weblogic.jws.ReliabilityBuffer

weblogic.jws.ServiceClient

weblogic.jws.Transactional

weblogic.jws.WLHttpTransport

weblogic.jws.WLHttpsTransport

weblogic.jws.WLJmsTransport

weblogic.jws.WSDL

weblogic.jws.security.SecurityRoles

weblogic.jws.security.SecurityIdentity

weblogic.jws.security.WssConfiguration

Web Service Reliable Messaging Policy Assertion Reference

Overview of a WS-Policy File That Contains Web Service Reliable Messaging Assertions

Graphical Representation

Example of a WS-Policy File With Web Service Reliable Messaging Assertions

Element Description

beapolicy:Expires

beapolicy:QOS

wsrm:AcknowledgementInterval

wsrm:BaseRetransmissionInterval

wsrm:ExponentialBackoff

wsrm:InactivityTimeout

wsrm:RMAssertion

Security Policy Assertion Reference

Overview of a WS-Policy File That Contains Security Assertions

Graphical Representation

Example of a Policy File With Security Elements

Element Description

CanonicalizationAlgorithm

Claims

Confidentiality

ConfirmationMethod

DigestAlgorithm

EncryptionAlgorithm

Identity

Integrity

KeyInfo

KeyWrappingAlgorithm

MessageAge

MessageParts

SecurityToken

SecurityTokenReference

SignatureAlgorithm

SupportedTokens

Target

Transform

UsePassword

Using MessageParts To Specify Parts of the SOAP Messages that Must Be Encrypted or Signed