Go to main content
1/44
Contents
Title and Copyright Information
Preface
Documentation Accessibility
Conventions
What's New in This Guide
New and Changed Features for 12
c
(12.2.1.x)
New and Changed Features for 12
c
(12.2.1)
Part I Introduction
1
Introduction to JAX-WS Web Services
Overview of JAX-WS Web Service Development
The Programming Model—Metadata Annotations
The Development Model—Bottom-up and Top-down
Bottom-up Approach: Starting from Java
Top-down Approach: Starting from WSDL
Roadmap for Implementing JAX-WS Web Services
2
Examples for JAX-WS Web Service Developers
Part II Developing Basic JAX-WS Web Services
3
Developing JAX-WS Web Services
Overview of the WebLogic Web Service Programming Model
Configuring Your Domain For Advanced Web Services Features
Resources Required by Advanced Web Service Features
Configuring a Domain for Advanced Web Service Features Using the Configuration Wizard
Creating a Domain With the Web Services Extension Template
Extending a Domain With the Web Services Extension Template
Using WLST to Extend a Domain With the Web Services Extension Template
Updating Resources Added After Extending Your Domain
Developing WebLogic Web Services Starting From Java: Main Steps
Developing 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
Specifying the Transport Used to Invoke the Web Service
Defining the Context Path of a WebLogic Web Service
Examples of Using 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
Web service is not a callback service and can be invoked using HTTP/S
Web service is a callback service
Web service is invoked using a proxy server
Testing the Web Service
Integrating Web Services Into the WebLogic Split Development Directory Environment
4
Programming the JWS File
Overview of JWS Files and JWS Annotations
Java Requirements for a JWS File
Programming the JWS File: Typical Steps
Example of a JWS File
Specifying that the JWS File Implements a Web Service (@WebService Annotation)
Specifying the Mapping of the Web Service to the SOAP Message Protocol (@SOAPBinding Annotation)
Specifying That a JWS Method Be Exposed as a Public Operation (@WebMethod and @OneWay Annotations)
Customizing the Mapping Between Operation Parameters and WSDL Elements (@WebParam Annotation)
Customizing the Mapping Between the Operation Return Value and a WSDL Element (@WebResult Annotation)
Specifying the Binding to Use for an Endpoint (@BindingType Annotation)
Accessing Runtime Information About a Web Service
Accessing the Protocol Binding Context
Accessing the Web Service Context
Using the MessageContext Property Values
Should You Implement a Stateless or Singleton Session EJB?
Programming the User-Defined Java Data Type
Invoking Another Web Service from the JWS File
Using SOAP 1.2
Validating the XML Schema
Enabling Schema Validation on the Server
Enabling Schema Validation on the Client
JWS Programming Best Practices
5
Using JAXB Data Binding
Overview of Data Binding Using JAXB
Developing the JAXB Data Binding Artifacts
Standard Data Type Mapping
Supported Built-In Data Types
XML-to-Java Mapping for Built-in Data Types
XML Schema
Default Java Binding
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
Customizing Java-to-XML Schema Mapping Using JAXB Annotations
Example of JAXB Annotations
Specifying Default Serialization of Fields and Properties (@XmlAccessorType Annotation)
Mapping Properties to Local Elements (@XmlElement)
Specifying the MIME Type (@XmlMimeType Annotation)
Mapping a Top-level Class to a Global Element (@XmlRootElement)
Binding a Set of Classes (@XmlSeeAlso)
Mapping a Value Class to a Schema Type (@XmlType)
Customizing XML Schema-to-Java Mapping Using Binding Declarations
Creating an External Binding Declarations File
Creating an External Binding Declarations File Using JAX-WS Binding Declarations
Specifying the Root Element
Specifying Child Elements
Creating an External Binding Declarations File Using JAXB Binding Declarations
Specifying the Root Element
Specifying Child Elements
Embedding Binding Declarations
Embedding JAX-WS or JAXB Binding Declarations in the WSDL File
Embedding JAXB Binding Declarations in the XML Schema
JAX-WS Custom Binding Declarations
JAXB Custom Binding Declarations
Using the Glassfish RI JAXB Data Binding and JAXB Providers
Configuring Global Server-Level Data Binding and JAXB Providers
Configuring Application-Level Data Binding and JAXB Providers
Configuring Java System Properties for JAXB
6
Examples of Developing JAX-WS Web Services
Creating a Simple HelloWorld Web Service
Sample HelloWorldImpl.java JWS File
Sample Ant Build File for HelloWorldImpl.java
Creating a Web Service With User-Defined Data Types
Sample BasicStruct JavaBean
Sample ComplexImpl.java JWS File
Sample Ant Build File for ComplexImpl.java JWS File
Creating a Web Service from a WSDL File
Sample WSDL File
Sample TemperatureService_TemperaturePortImpl Java Implementation File
Sample Ant Build File for TemperatureService
Part III Developing Basic JAX-WS Web Service Clients
7
Roadmap for Developing JAX-WS Web Service Clients
8
Developing Web Service Clients
Overview of WebLogic Web Services Client Development
Invoking a Web Service from a Java SE Client
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 Java Client
Invoking a Web Service from a Standalone Java SE Client
Invoking a Web Service from Another WebLogic Web Service
Sample build.xml File for a Web Service Client
Sample JWS File That Invokes a Web Service
Configuring Web Service Clients
Defining a Web Service Reference Using the @WebServiceRef Annotation
Managing Client Identity
Defining the Client ID During Port Initialization
Accessing the Server-generated Client ID
Client Identity Lifecycle
Using a Proxy Server When Invoking a Web Service
Using the ClientProxyFeature API to Specify the Proxy Server
Using System Properties to Specify the Proxy Server
Client Considerations When Redeploying a Web Service
Client Considerations When Web Service and Client Are Deployed to the Same Managed Server
9
Examples of Developing JAX-WS Web Service Clients
Developing a JAX-WS Java SE Client
Sample Java Client Application
Sample Ant Build File For Building Java Client Application
Invoking a Web Service from a WebLogic Web Service
Sample ClientServiceImpl.java JWS File
Sample Ant Build File For Building ClientService
Part IV Developing Advanced Features of JAX-WS Web Services
10
Using Web Services Addressing
Overview of WS-Addressing
Enabling WS-Addressing on the Web Service
Enabling WS-Addressing on the Web Service (Starting From Java)
Enabling WS-Addressing on the Web Service (Starting from WSDL)
Enabling WS-Addressing on the Web Service Client
Explicitly Enabling WS-Addressing on the Web Service Client
Implicitly Enabling WS-Addressing on the Web Service Client
Disabling WS-Addressing on the Web Service Client
Associating WS-Addressing Action Properties
Explicitly Associating WS-Addressing Action Properties (Starting from Java)
Explicitly Associating WS-Addressing Action Properties (Starting from WSDL)
Implicitly Associating WS-Addressing Action Properties
Configuring Anonymous WS-Addressing
11
Roadmap for Developing Asynchronous Web Service Clients
12
Developing Asynchronous Clients
Overview of Asynchronous Web Service Invocation
Steps to Invoke Web Services Asynchronously
Configuring Your Servers for Asynchronous Web Service Invocation
Building the Client Artifacts for Asynchronous Web Service Invocation
Developing Scalable Asynchronous JAX-WS Clients (Asynchronous Client Transport)
Enabling and Configuring the Asynchronous Client Transport Feature
Configuring the Address of the Asynchronous Response Endpoint
Configuring the ReplyTo and FaultTo Headers of the Asynchronous Response Endpoint
Configuring the Context Path of the Asynchronous Response Endpoint
Publishing the Asynchronous Response Endpoint
Configuring Asynchronous Client Transport for Synchronous Operations
Developing the Asynchronous Handler Interface
Propagating User-defined Request Context to the Response
Using Asynchronous Web Service Clients From Behind a Firewall (Make Connection)
Enabling and Configuring Make Connection on a Web Service
Creating the Web Service Make Connection WS-Policy File (Optional)
Programming the JWS File to Enable Make Connection
Enabling and Configuring Make Connection on a Web Service Client
Configuring the Expiration Time for Sending Make Connection Messages
Configuring the Polling Interval
Configuring the Exponential Backoff
Configuring Make Connection as the Transport for Synchronous Methods
Using the JAX-WS Reference Implementation
Propagating Request Context to the Response
Monitoring Asynchronous Web Service Invocation
Clustering Considerations for Asynchronous Web Service Messaging
13
Roadmap for Developing Reliable Web Services and Clients
Roadmap for Developing Reliable Web Service Clients
Roadmap for Developing Reliable Web Services
Roadmap for Accessing Reliable Web Services from Behind a Firewall (Make Connection)
Roadmap for Securing Reliable Web Services
14
Using Web Services Reliable Messaging
Overview of Web Services Reliable Messaging
Using WS-Policy to Specify Reliable Messaging Policy Assertions
Supported Transport Types for Reliable Messaging
The Life Cycle of the Reliable Message Sequence
Reliable Messaging Failure Recovery Scenarios
RM Destination Down Before Request Arrives
RM Source Down After Request is Made
RM Destination Down After Request Arrives
Failure Scenarios with Non-buffered Reliable Web Services
Steps to Create and Invoke a Reliable Web Service
Configuring the Source and Destination WebLogic Server Instances
Creating the Web Service Reliable Messaging WS-Policy File
Creating a Custom WS-Policy File Using WS-ReliableMessaging Policy Assertions Versions 1.2 and 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
Invoking a Reliable Web Service from a Web Service Client
Configuring Reliable Messaging
Configuring Reliable Messaging on WebLogic Server
Using the Administration Console
Using WLST
Configuring Reliable Messaging on the Web Service Endpoint
Configuring Reliable Messaging on Web Service Clients
Configuring the Base Retransmission Interval
Configuring the Base Retransmission Interval on WebLogic Server or the Web Service Endpoint
Configuring the Base Retransmission Interval on the Web Service Client
Configuring the Retransmission Exponential Backoff
Configuring the Retransmission Exponential Backoff on WebLogic Server or Web Service Endpoint
Configuring the Retransmission Exponential Backoff on the Web Service Client
Configuring the Sequence Expiration
Configuring the Sequence Expiration on WebLogic Server or Web Service Endpoint
Configuring the Sequence Expiration on the Web Service Client
Configuring Inactivity Timeout
Configuring the Inactivity Timeout on WebLogic Server or Web Service Endpoint
Configuring the Inactivity Timeout on the Web Service Client
Configuring a Non-buffered Destination for a Web Service
Configuring the Acknowledgement Interval
Implementing the Reliability Error Listener
Managing the Life Cycle of a Reliable Message Sequence
Managing the Reliable Sequence
Getting and Setting the Reliable Sequence ID
Accessing the State of the Reliable Sequence
Managing the Client ID
Managing the Acknowledged Requests
Accessing Information About a Message
Identifying the Final Message in a Reliable Sequence
Closing the Reliable Sequence
Terminating the Reliable Sequence
Resetting a Client to Start a New Message Sequence
Monitoring Web Services Reliable Messaging
Grouping Messages into Business Units of Work (Batching)
Client Considerations When Redeploying a Reliable Web Service
Interoperability with WebLogic Web Service Reliable Messaging
15
Using Web Services Atomic Transactions
Overview of Web Services Atomic Transactions
Configuring the Domain Resources Required for Web Service Advanced Features
Enabling the Web Services Atomic Transactions Feature
Enabling Web Services Atomic Transactions on Web Services
Using the @Transactional Annotation in Your JWS File
Example: Using @Transactional Annotation on a Web Service Class
Example: Using @Transactional Annotation on a Web Service Method
Example: Using the @Transactional and the EJB @TransactionAttribute Annotations Together
Enabling Web Services Atomic Transactions Starting From WSDL
Enabling Web Services Atomic Transactions on Web Service Clients
Using @Transactional Annotation with the @WebServiceRef Annotation
Passing the TransactionalFeature to the Client
Configuring Web Services Atomic Transactions Using the Administration Console
Securing Messages Exchanged Between the Coordinator and Participant
Enabling and Configuring Web Services Atomic Transactions
Using Web Services Atomic Transactions in a Clustered Environment
More Examples of Using Web Services Atomic Transactions
16
Optimizing XML Transmission Using Fast Infoset
Overview of Fast Infoset
Enabling Fast Infoset on Web Services
Enabling and Configuring Fast Infoset on Web Services Clients
Configuring the Content Negotiation Strategy
Example Using @FastInfosetClient Annotation at Design Time
Example Using FastInfosetClientFeature Feature Class at Design Time
Disabling Fast Infoset on Web Services and Clients
17
Using SOAP Over JMS Transport
Overview of SOAP Over JMS Transport
Configuring the WebLogic Server Domain for JMS Transport
Developing Web Services Using JMS Transport—Starting From Java
Using the @JMSTransportService Annotation
Using the <jmstransportservice> Child Element in the Ant build.xml File
Developing Web Services Using JMS Transport—Starting From WSDL
Updating the WSDL to Use JMS Transport
Enabling JMS Transport at the WSDL Binding Level
Configuring JMS Transport Properties in the WSDL
Example of Enabling JMS Transport in WSDL
Invoking a WebLogic Web Service Using JMS Transport
Using the <jmstransportclient> Element in the Ant build.xml File
Using the @JMSTransportClient Annotation
Using the JMSTransportClientFeature Client API
Configuring the JMS URI as the Target Endpoint Address
Using AsyncClientTransportFeature to Configure Asynchronous Clients
Configuring JMS Transport Properties
Summary of JMS Transport Configuration Properties
Configuration Methods and Order of Precedence
Configuring JMS Transport Using the Administration Console
Configuring JMS Transport Using WLST
Configuring the JMS URI
Configuring the JMS Request URI
Configuring the WS-Addressing Headers
Configuring the JMS Response Queue
Configuring the JMS Message Type
Configuring HTTP Access to the WSDL File
Monitoring SOAP Over JMS Transport
18
Creating and Using SOAP Message Handlers
Overview of SOAP Message Handlers
Adding Server-side SOAP Message Handlers: Main Steps
Adding Client-side SOAP Message Handlers: Main Steps
Designing the SOAP Message Handlers and Handler Chains
Server-side Handler Execution
Client-side Handler Execution
Creating the SOAP Message Handler
Example of a SOAP Handler
Example of a Logical Handler
Implementing the Handler.handleMessage() Method
Implementing the Handler.handleFault() Method
Implementing the Handler.close() Method
Using the Message Context Property Values and Methods
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 Handler Chains in the JWS File
Creating the Handler Chain Configuration File
Compiling and Rebuilding the Web Service
Configuring the Client-side SOAP Message Handlers
19
Handling Exceptions Using SOAP Faults
Overview of Exception Handling Using SOAP Faults
Contents of the SOAP Fault Element
SOAP 1.2 <Fault> Element Contents
SOAP 1.1 <Fault> Element Contents
Using Modeled Faults
Creating and Using a Custom Exception
How Modeled Faults are Mapped in the WSDL File
How the Fault is Communicated in the SOAP Message
Creating the Web Service Client
Reviewing the Generated Java Exception Class
Reviewing the Generated Java Fault Bean Class
Reviewing the Client-side Service Implementation
Creating the Client Implementation Class
Using Unmodeled Faults
Customizing the Exception Handling Process
Disabling the Stack Trace from the SOAP Fault
Other Exceptions
20
Optimizing Binary Data Transmission
Optimizing Binary Data Transmission Optimization Using MTOM/XOP
Annotating the Data Types
Annotating the Data Types: Start From Java
Annotating the Data Types: Start From WSDL
Enabling MTOM on the Web Service
Enabling MTOM on the Web Service Using Annotation
Enabling MTOM on the Web Services by Attaching a WS-Policy File
Enabling MTOM on the Client
Setting the Attachment Threshold
Enabling HTTP Chunking
Streaming SOAP Attachments
Client Side Example
Server Side Example
Configuring Streaming SOAP Attachments
Configuring Streaming SOAP Attachments on the Server
Configuring Streaming SOAP Attachments on the Client
Sending SOAP Messages With Attachments Using swaRef
21
Managing Web Service Persistence
Overview of Web Service Persistence
Roadmap for Configuring Web Service Persistence
Configuring Web Service Persistence
Configuring the Logical Store
Configuring Web Service Persistence for a Web Service Endpoint
Configuring Web Service Persistence for Web Service Clients
Using Web Service Persistence in a Cluster
Cleaning Up Web Service Persistence
22
Configuring Message Buffering for Web Services
Overview of Message Buffering
Configuring Messaging Buffering
Configuring the Request Queue
Configuring the Response Queue
Configuring Message Retry Count and Delay
23
Managing Web Services in a Cluster
Overview of Web Services Cluster Routing
Cluster Routing Scenarios
Scenario 1: Routing a Web Service Response to a Single Server
Scenario 2: Routing Web Service Requests to a Single Server Using Routing Information
Scenario 3: Routing Web Service Requests to a Single Server Using an ID
How Web Service Cluster Routing Works
Adding Routing Information to Outgoing Requests
Detecting Routing Information in Incoming Requests
Routing Requests Within the Cluster
Maintaining the Routing Map on the Front-end SOAP Router
X-weblogic-wsee-storetoserver-list HTTP Response Header
X-weblogic-wsee-storetoserver-hash HTTP Response Header
Configuring Web Services in a Cluster
Setting Up the WebLogic Cluster
Configuring the Domain Resources Required for Web Service Advanced Features in a Clustered Environment
Extending the Front-end SOAP Router to Support Web Services
Enabling Routing of Web Services Atomic Transaction Messages
Enabling Routing of Web Services Make Connection Messages
Configuring the Identity of the Front-end SOAP Router
Configuring the Identity of the Front-end SOAP Router Using Network Channels
Monitoring Cluster Routing Performance
24
Using Provider-based Endpoints and Dispatch Clients to Operate on SOAP Messages
Overview of Web Service Provider-based Endpoints and Dispatch Clients
Usage Modes and Message Formats for Operating at the XML Level
Developing a Web Service Provider-based Endpoint (Starting from Java)
Developing a Synchronous Provider-based Endpoint
Developing an Asynchronous Provider-based Endpoint
Specifying the Message Format
Specifying that the JWS File Implements a Web Service Provider (@WebServiceProvider Annotation)
Specifying the Usage Mode (@ServiceMode Annotation)
Defining the invoke() Method for a Synchronous Provider-based Endpoints
Defining the invoke() Method for an Asynchronous Provider-based Endpoints
Defining the Callback Handler for the Asynchronous Provider-based Endpoint
Developing a Web Service Provider-based Endpoint (Starting from WSDL)
Using SOAP Handlers with Provider-based Endpoints
Developing a Web Service Dispatch Client
Example of a Web Service Dispatch Client
Creating a Dispatch Instance
Invoking a Web Service Operation
25
Sending and Receiving SOAP Headers
Overview of Sending and Receiving SOAP Headers
Sending SOAP Headers Using WSBindingProvider
Receiving SOAP Headers Using WSBindingProvider
26
Using Callbacks
Overview of Callbacks
Example Callback Implementation
Steps to Program Callbacks
Programming Guidelines for Target Web Service
Programming Guidelines for the Callback Client Web Service
Programming Guidelines for the Callback Web Service
Updating the build.xml File for the Target Web Service
27
Developing Dynamic Proxy Clients
Overview of Static Versus Dynamic Proxy Clients
Steps to Develop a Dynamic Proxy Client
Additional Considerations When Specifying WSDL Location
28
Publishing a Web Service Endpoint
29
Using XML Catalogs
Overview of XML Catalogs
Defining and Referencing XML Catalogs
Defining an External XML Catalog
Creating an External XML Catalog File
Referencing the External XML Catalog File
Embedding an XML Catalog
Creating an Embedded XML Catalog
Referencing an Embedded XML Catalog
Disabling XML Catalogs in the Client Runtime
Getting a Local Copy of XML Resources
30
Programming Web Services Using XML Over HTTP
About Programming Web Services Using XML Over HTTP
Programming Guidelines for the Web Service Using XML Over HTTP
Accessing the Web Service from a Client
Securing Web Services that Use XML Over HTTP
31
Programming Stateful JAX-WS Web Services Using HTTP Session
Overview of Stateful Web Services
Accessing HTTP Session on the Server
Enabling HTTP Session on the Client
Developing Stateful Services in a Cluster Using Session State Replication
A Note About the JAX-WS RI @Stateful Extension
32
Testing and Monitoring Web Services
Testing Web Services
Monitoring Web Services and Clients
Monitoring Web Services
Monitoring Web Service Clients
Using Work Managers to Prioritize Web Services Work and Reduce Stuck Execute Threads
Part V Reference
A
Pre-packaged WS-Policy Files for Web Services Reliable Messaging and Make Connection
DefaultReliability1.2.xml (WS-Policy File)
DefaultReliability1.1.xml (WS-Policy File)
DefaultReliability.xml WS-Policy File (WS-Policy) [Deprecated]
LongRunningReliability.xml WS-Policy File (WS-Policy) [Deprecated]
Mc1.1.xml (WS-Policy File)
Mc.xml (WS-Policy File)
Reliability1.2_ExactlyOnce_WithMC1.1.xml (WS-Policy File)
Reliability1.2_SequenceSTR.xml (WS-Policy File)
Reliability1.1_SequenceSTR.xml (WS-Policy File)
Reliability1.2_SequenceTransportSecurity.xml (WS-Policy File)
Reliability1.1_SequenceTransportSecurity.xml (WS-Policy File)
Reliability1.0_1.2.xml (WS-Policy File)
Reliability1.0_1.1.xml (WS-Policy.xml File)
B
Example Client Wrapper Class for Batching Reliable Messages
C
Migrating JAX-RPC Web Services and Clients to JAX-WS
Setting the Final Context Root of a WebLogic Web Service
Using WebLogic-specific Annotations
Generating a WSDL File
Using JAXB Custom Types
Using EJB 3.0
Migrating from RPC Style SOAP Binding
Updating SOAP Message Handlers
Invoking JAX-WS Clients
Scripting on this page enhances content navigation, but does not change the content in any way.