Programming Web Services for WebLogic Server

Introduction and Roadmap

Document Scope and Audience

Guide to This Document

Related Documentation

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.X WebLogic Web Services

Summary of WebLogic Web Services Features

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 and 1.2

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

WS-Trust 1.0

WS-SecureConversation 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

Configuring Your Domain For Web Services Features

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

Examples of Using jwsc

Advanced Uses of jwsc

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

Configuring the Server Address Specified in the Dynamic WSDL

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

Programming Additional Miscellaneous Features Using JWS Annotations and APIs

Streaming SOAP Attachments

Using SOAP 1.2

Specifying that Operations Run Inside of a Transaction

Getting the HttpServletRequest/Response Object

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

WsrmUtils Utility Class

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

Client Considerations When Redeploying 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

Disabling The Internal Asynchronous Service

Using Callbacks to Notify Clients of Events

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

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

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

Client Considerations When Redeploying 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 Transport and SOAP Message Handlers

Using JMS Transport as the Connection Protocol

Using JMS Transport Starting From Java: Main Steps

Using JMS Transport Starting From WSDL: Main Steps

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

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

The SOAPPart Object

The AttachmentPart Object

Manipulating Image Attachments in a SOAP Message Handler

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 Web Services Invocation

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 to Invoke a Web Service

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

Using a Proxy Server When Invoking a Web Service

Using the HttpTransportInfo API to Specify the Proxy Server

Using System Properties to Specify the Proxy Server

Client Considerations When Redeploying 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 WS-Policy File with a Client Application: Main Steps

Updating clientgen to Generate Methods That Load WS-Policy Files

Updating a Client Application To Load WS-Policy Files

WebLogic Web Services Stub Properties

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 of Message-Level Security

Using WS-Policy Files for Message-Level Security Configuration

WebLogic Server WS-Policy Files

Abstract and Concrete WS-Policy Files

Configuring Simple Message-Level Security: Main Steps

Ensuring That WebLogic Server Can Validate the Client’s Certificate

Updating the JWS File with @Policy and @Policies Annotations

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

Configuring and Using Security Contexts and Derived Keys (WS-SecureConversation)

Using Custom WS-Policy Files To Configure Security Contexts and Derived Keys

Updating a Client Application to Negotiate Security Contexts

Associating WS-Policy Files at Runtime Using the Administration Console

Using Security Assertion Markup Language (SAML) Tokens For Identity

Using Only X.509 Certificate Tokens for Identity

Using a Password Digest In the SOAP Message Rather Than Plaintext

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

Using System Properties to Debug Message-Level Security

Updating a Client Application to Invoke a Message-Secured Web Service

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

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 Security-Related Annotations

Updating the JWS File With the @RunAs Annotation

Setting the Username and Password When Creating the JAX-RPC Service Object

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

Using Work Managers to Prioritize Web Services Work and Reduce Stuck Execute Threads

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 WebLogic Web Services From Previous Releases to 9.2

Upgrading a 9.0 or 9.1 WebLogic Web Service to 9.2

Upgrading an 8.1 WebLogic Web Service to 9.2

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

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

8.1 SessionBean Class

8.1 Remote Interface

8.1 EJB Home Interface

Equivalent 9.2 JWS File

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.Binding

weblogic.jws.BufferQueue

weblogic.jws.Callback

weblogic.jws.CallbackMethod

weblogic.jws.CallbackService

weblogic.jws.Context

weblogic.jws.Conversation

weblogic.jws.Conversational

weblogic.jws.MessageBuffer

weblogic.jws.Policies

weblogic.jws.Policy

weblogic.jws.ReliabilityBuffer

weblogic.jws.ReliabilityErrorHandler

weblogic.jws.ServiceClient

weblogic.jws.StreamAttachments

weblogic.jws.Transactional

weblogic.jws.Types

weblogic.jws.WildcardBinding

weblogic.jws.WildcardBindings

weblogic.jws.WLHttpTransport

weblogic.jws.WLHttpsTransport

weblogic.jws.WLJmsTransport

weblogic.jws.WSDL

weblogic.jws.security.CallbackRolesAllowed

weblogic.jws.security.RolesAllowed

weblogic.jws.security.RolesReferenced

weblogic.jws.security.RunAs

weblogic.jws.security.SecurityRole

weblogic.jws.security.SecurityRoleRef

weblogic.jws.security.UserDataConstraint

weblogic.jws.security.WssConfiguration

weblogic.jws.soap.SOAPBinding

weblogic.jws.security.SecurityRoles (deprecated)

weblogic.jws.security.SecurityIdentity (deprecated)

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

Label

Length

MessageAge

MessageParts

SecurityToken

SecurityTokenReference

SignatureAlgorithm

SupportedTokens

Target

TokenLifeTime

Transform

UsePassword

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

XPath 1.0

Pre-Defined wsp:Body() Function

WebLogic-Specific Header Functions

WebLogic Web Service Deployment Descriptor Element Reference

Overview of weblogic-webservices.xml

Graphical Representation

XML Schema

Example of a weblogic-webservices.xml Deployment Descriptor File

Element Description

deployment-listener-list

deployment-listener

exposed

login-config

mbean-name

port-component

port-component-name

service-endpoint-address

transport-guarantee

weblogic-webservices

webservice-contextpath

webservice-description

webservice-description-name

webservice-security

webservice-serviceuri

wsdl

wsdl-publish-file