0% found this document useful (0 votes)

3 views474 pages

D59163GC10 sg1

This document is a student guide for the Oracle Fusion Middleware 11g course focused on building web services. It includes course objectives, prerequisites, and a detailed outline of topics such as web services, SOAP, WSDL, and JAX-WS implementation. The materials are proprietary and intended for classroom use only, with strict restrictions on copying and distribution.

Uploaded by

MOHAMED

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

3 views474 pages

D59163GC10 sg1

Uploaded by

MOHAMED

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 474

Oracle University and Egabi Solutions use only

Oracle Fusion Middleware 11g:

Build Web Services
Volume I • Student Guide

D59163GC10
Edition 1.0
October 2009
D63214

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Authors Copyright © 2009, Oracle. All rights reserved.

Iris Li Disclaimer

Al Saganich This document contains proprietary information and is protected by copyright and other intellectual
property laws. You may copy and print this document solely for your own use in an Oracle training
Technical Contributors course. The document may not be modified or altered in any way. Except where your use constitutes
"fair use" under copyright law, you may not use, share, download, upload, copy, print, display,
and Reviewers perform, reproduce, publish, license, post, transmit, or distribute this document in whole or in part
without the express authorization of Oracle.
Pyounguk Cho
Steve Friedberg The information contained in this document is subject to change without notice. If you find any
problems in the document, please report them in writing to: Oracle University, 500 Oracle Parkway,
Joe Greenwald Redwood Shores, California 94065 USA. This document is not warranted to be error-free.
Vasiliy Strelnikov
Restricted Rights Notice
Holger Rasmussen
If this documentation is delivered to the United States Government or anyone using the
documentation on behalf of the United States Government, the following notice is applicable:

Oracle University and Egabi Solutions use only

Editor
Nita Pavitran U.S. GOVERNMENT RIGHTS
The U.S. Government’s rights to use, modify, reproduce, release, perform, display, or disclose these
training materials are restricted by the terms of the applicable Oracle license agreement and/or the
Graphic Designer applicable U.S. Government contract.
Rajiv Chandrabhanu
Trademark Notice

Publisher Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be
trademarks of their respective owners.
Pavithran Adka

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Contents

I Oracle Fusion Middleware 11g: Build Web Services Course Introduction

Audience I-2
Class Introductions I-3

Oracle University and Egabi Solutions use only

Goal I-4
Course Objectives I-5
Prerequisites I-7
Course Map I-8
Course Environment I-9
Course Schedule I-10
How Can I Learn More? I-12

1 Introducing Web Services

Objectives 1-2
The Drive Towards Web Services 1-3
What Web Services Are 1-5
The Integration Problem 1-7
Web Services Versus Web Applications 1-8
The Building Blocks of Web Services 1-9
SOAP 1-10
WSDL 1-11
UDDI 1-12
Quiz 1-13
Web Services Interaction 1-14
Web Services Interoperability 1-15
WS-I Basic Profile 1-16
WS - * Specifications 1-17
Web Services Architectural Styles 1-19
RESTful Versus SOAP-Based Web Services 1-20
Quiz 1-21
Definition: Service-Oriented Architecture (SOA) 1-22
SOA Further Defined 1-23
Services Are SOA Building Blocks 1-24
Standards That Enable SOA 1-25
Web Services and SOA 1-26

iii
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Summary 1-28
Practice 1 Overview: Reviewing Terms and Concepts 1-29
Describing the Course Environment 1-30
Configuring a Grid VM Connection 1-31
Configuring a Grid VM Connection: Session 1-32
Configuring a Grid VM Connection: Desktop 1-33
Configuring a Grid VM Connection: Configuration Completed 1-34
Connecting to the Grid VM Instance 1-35

2 Java Web Services Technologies Overview

Oracle University and Egabi Solutions use only

Objectives 2-2
Java Technology for Web Services 2-3
Java Web Services 2-4
Java Web Services Standards 2-5
JAX-WS Programming Model 2-6
JAX-WS Benefits 2-7
WS-Metadata Benefits 2-8
A Simple Annotated Java Class 2-9
Java Web Service from POJO Rules 2-10
Quiz 2-11
JAXB 2-12
SOAP with Attachments API for Java (SAAJ) 2-13
WSEE 2-14
Roles of APIs in Web Services Invocation 2-15
JAX-RPC and JAX-WS Stack Comparison 2-17
Java Web Service Development Approaches 2-18
Bottom-Up Approach 2-19
Top-Down Approach 2-20
WebLogic Server Support for JWS 2-21
Quiz 2-22
Web Service Development Process 2-23
Tools for JWS Development 2-24
Creating Web Services by Using Oracle JDeveloper 11g 2-25
Creating a Web Service from a Java Class by Using JDeveloper 2-27
Summary 2-28
Practice 2 Overview: Developing a Simple Web Service 2-29

3 Exploring SOAP and WSDL

Objectives 3-2
Basics of XML 3-3

iv
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
XML Namespace and XML Schema 3-5
SOAP: XML Messaging for Web Services 3-7
Communication with SOAP 3-8
SOAP over HTTP 3-9
Basic Structure of SOAP 3-10
SOAP Messages: Example 3-12
Examining SOAP Messages Using the HTTP Analyzer 3-13
SOAP Message Formats 3-14
Quiz 3-16
RPC-Style SOAP Message Structure 3-17

Oracle University and Egabi Solutions use only

Document-Style SOAP Message Structure: document/literal 3-19
Document-Style SOAP Message Structure: document/wrapped 3-20
SOAP Attachment 3-21
WSDL 3-22
WSDL Model 3-23
A Basic WSDL Document 3-25
Defining the Structure of Content in the SOAP Body 3-27
WSDL Binding 3-28
WSDL Styles 3-29
RPC/literal Message WSDL 3-30
document/literal Message WSDL 3-31
document/wrapped Message WSDL 3-34
An Example with SOAP Binding 3-35
Quiz 3-36
Steps for Creating a WSDL File Using JDeveloper 3-37
Creating a WSDL File Using JDeveloper 3-38
Mapping of a Java Method to WSDL 3-40
WSDL Message Exchange Patterns 3-42
Summary 3-43
Practice 3 Overview: Creating WSDL-Based Contracts 3-44

4 Implementing JAX-WS Web Services: Server Side

Objectives 4-2
JAX-WS 2.1 Features 4-3
Server-Side JAX-WS Run Time 4-5
Service Granularity 4-6
Designing Coarse-Grained Interfaces 4-7
JAX-WS Development Model 4-8
Steps for Implementing Web Services Using POJOs 4-9
Using Annotations 4-10

v
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
JSR 181 Annotations 4-12
Complex Return Results 4-13
Web Service Life Cycle 4-14
PostConstruct and PreDestroy Life Cycle Annotations 4-15
An Example of POJO-Based Service Endpoint 4-17
Quiz 4-19
Implementing Web Services Using EJB 4-20
An Example of EJB Endpoint 4-21
The Provider API: Working with XML Directly 4-22
A Sample of Provider Endpoint 4-23

Oracle University and Egabi Solutions use only

Creating Web Services from a WSDL File 4-24
A Sample WSDL and Generated Java File 4-25
Quiz 4-27
Summary 4-28
Practice 4 Overview: Creating Server-Side Web Services 4-29

5 Implementing JAX-WS Web Services: Client Side

Objectives 5-2
Agenda 5-3
JAX-WS Client-Side Programming Model 5-4
Accessing Web Services 5-5
Service Objects 5-6
Invoking a Web Service with Proxy 5-7
Clients and Web Services 5-8
Generated Client Artifacts 5-9
HelloWorld Web Service (Server-Side) 5-10
HelloWorld Web Service WSDL File 5-11
Generated HelloWorld (Client-Side) 5-13
Generated HelloWorldService 5-14
Enabling Features: WebServiceFeature 5-15
Generated HelloWorldPortClient 5-16
BindingProvider Interface 5-17
Tools for Generating a Web Service Proxy 5-18
Creating a Web Service Proxy Using JDeveloper 5-19
Creating a Client JAR Using Ant 5-20
Injecting Web Service References 5-21
Quiz 5-22
Agenda 5-23
Dispatch Client API 5-24
Using the Dispatch API for XML Messaging 5-25

vi
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Dispatch Client Support Matrix 5-26
A Sample of Dispatch Client 5-27
Invoking a Web Service Using the Dispatch API 5-28
Agenda 5-29
JAX-WS Web Services Invocation Mechanisms: Synchronous 5-30
JAX-WS Web Services Invocation Mechanisms: Asynchronous 5-31
Asynchronous Invocation Models 5-32
HelloWorld (SEI) with Asynchronous Method Calls 5-33
HelloWorldPortClient: Asynchronous Polling 5-35
Asynchronous Callback: Sequence Diagram 5-36

Oracle University and Egabi Solutions use only

HelloWorldPortClient: Asynchronous Callback 5-37
Creating an SEI Proxy Using the Asynchronous Invocation Models 5-39
Creating a Dispatch Client Using the Polling Asynchronous Invocation Model 5-40
Dispatch Client: Asynchronous Polling 5-41
Creating a Dispatch Client Using the Callback Asynchronous Invocation Model 5-42
Dispatch Client: Asynchronous Callback 5-43
Quiz 5-44
Summary 5-45
Practice 5 Overview: Accessing Web Services 5-46

6 Packaging, Deploying, and Managing Web Services

Objectives 6-2
Web Services Packaging and Deployment 6-3
Port Component 6-4
Packaging a POJO Endpoint 6-5
Packaging an EJB Endpoint 6-7
WLS Container Deployment Processing 6-8
Deploying Web Services Without a Deployment Descriptor 6-10
WSDL Generated from the SIB 6-11
Supplying a WSDL File 6-12
Deploying Web Services with a Deployment Descriptor 6-13
Customizing Endpoint URLs 6-14
Example Deployment Descriptors 6-15
Example Generated WSDL File 6-16
Overview of webservice.xml and weblogic-webservice.xml 6-17
Example of webservice.xml File 6-18
Using webservice.xml to Override Annotations 6-19
Quiz 6-20
Packaging and Deployment Tools 6-21
Deploying Web Services by Using JDeveloper 6-22

vii
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Deploying Web Services Using OEPE 6-23
Deploying a Web Service with a SIB 6-24
Steps for Deploying a Web Service with an SIB and WSDL 6-25
Using jwsc Ant to Package Web Services 6-26
Updating the build.xml File for the jwsc Ant Task 6-27
Using the wldeploy Ant Task to Deploy Web Services 6-28
Overview of WebLogic Web Services Administration Tasks 6-29
Basics of WebLogic Server Administration Console 6-31
Managing Web Services by Using the Administration Console 6-33
Web Service Configuration 6-34

Oracle University and Egabi Solutions use only

Configuring a Policy 6-35
Testing via the Console 6-36
Quiz 6-37
Summary 6-38
Practice 6 Overview: Packaging and Deploying Web Services 6-39

7 Fault and Exception Handling in JAX-WS Web Services

Objectives 7-2
What Are SOAP Faults? 7-3
Java and SOAP Faults 7-4
Unmodeled Faults 7-5
Common Unmodeled Faults 7-6
SOAP Fault Structure 7-7
SOAP 1.1 Fault 7-8
SOAP 1.1 Standard Fault Codes 7-9
SOAP 1.1 Fault Message Example 7-10
SOAP 1.2 Faults 7-11
SOAP 1.2 Fault Codes 7-12
SOAP 1.2 Fault Message Structure 7-13
SOAP 1.2 Fault Message Example 7-14
JAX-WS Fault Processing Infrastructure 7-15
Quiz 7-16
Creating Modeled Faults 7-17
Web Service and Exception 7-18
Web Service WSDL with Fault Message 7-19
FaultBean Class (Generated JavaBean) 7-21
Exception Class 7-22
Client-Side Service Implementation 7-24
Client 7-25
Creating Modeled Faults 7-26

viii
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Implicit Fault Example on the Server Side 7-27
Implicit Fault Example on the Client Side 7-28
Exceptions in the Log File 7-29
Quiz 7-30
Summary 7-31
Practice 7 Overview: Handling Web Service Exceptions 7-32

8 Web Services Security

Objectives 8-2

Oracle University and Egabi Solutions use only

Overview of Web Services Security 8-3
Transport-Level Security 8-4
Message-Level Security 8-5
WS-Security Overview 8-6
What Is SAML? 8-8
SAML Architecture 8-9
WS-Security and SAML 8-10
WebLogic’s Support for SAML Token 8-11
WS-Security Architecture 8-12
WS-Security Stack 8-13
Quiz 8-15
WS-Policy Overview 8-17
Policy Assertion 8-18
Policy Operators 8-19
Sample of a Policy File 8-20
WS-SecurityPolicy 8-21
Quiz 8-22
WebLogic WS-Security Support 8-23
Message-Level Security Configuration Using Policy Files 8-24
Sample of Using @Policy and @Policies Annotations 8-25
Specifying the Policy File Location 8-26
WebLogic Prepackaged Policy Files 8-27
Associating Policy Files Using JDeveloper 8-29
Associating Policy Files at Run Time Using Administration Console 8-30
Quiz 8-32
Message Encryption and Signing Mechanisms 8-33
Configuring Message-Level Security 8-34
Creating Key Pairs, Keystore on the Server Side 8-36
Web Service Security Configuration 8-37

ix
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Quiz 8-38
Invoking a Message-Secured Web Service 8-39
Sample Client Code 8-40
Invoking a Web Service from Within a WebLogic Server Instance 8-42
Oracle WSM WS-Security Policies 8-44
Adding Oracle WSM WS-Security Policies to a Web Service 8-45
Nonsupported Oracle WSM WS-Security Policies 8-46
Summary 8-47
Practice 8 Overview: Securing Web Services Using WS-Policy 8-48

Oracle University and Egabi Solutions use only

9 Using Handlers in JAX-WS Web Services
Objectives 9-2
SOAP Message Handlers 9-3
Handler Types 9-5
Handler Framework 9-6
Creating Message Handlers 9-7
Quiz 9-8
Handler Interfaces 9-9
Handler Life Cycle 9-10
Message Context 9-11
MessageContext Interface 9-12
MessageContext Injection in Web Services 9-14
Handler Interface Methods 9-15
Interfaces of Logical and SOAP Handlers 9-16
A Simple Logical Handler Class 9-17
A Simple SOAP Handler Class 9-18
Quiz 9-19
Handler Chain 9-20
WebLogic Server-Side Handler Execution 9-22
Handler Chain Processing Order 9-23
Configuring Handler Chains on the Server Side 9-24
Sample Service Implementation Class with Handler Chain Annotation 9-25
Sample Handler Chain Configuration File 9-26
Quiz 9-28
Configuring Handler Chains on the Client Side 9-29
Implementing HandlerResolver Interface 9-31
Using a Binding Interface 9-33
Quiz 9-35
Adding Server-Side Handlers 9-36
Creating a Configuration File by Using JDeveloper Wizard 9-37

x
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Adding Client-Side Handlers 9-38
Summary 9-39
Practice 9 Overview: Creating Handlers for Web Services 9-40

10 Optimizing Binary Data Transmission Using MTOM/XOP

Objectives 10-2
Challenges of Binary Data Transmission 10-3
SOAP Message with Text-Encoded Binary 10-4
SOAP with Attachment (SwA) 10-5
Using MIME with SOAP 10-6

Oracle University and Egabi Solutions use only

SOAP Message in MIME Package 10-7
Message Transmission Optimization Mechanism (MTOM) Addresses Challenges
10-9
XOP 10-10
How MTOM/XOP Works 10-11
MTOM/XOP Version of SOAP Message 10-12
Quiz 10-14
Enabling MTOM for JAX-WS Web Services 10-15
Using MTOM/XOP to Send Binary Data 10-16
MIME and Java Data Type Mappings 10-17
Annotating the Data Types: Start from Java 10-18
Annotating the Data Types: Start from WSDL 10-19
Enabling MTOM on the Server Side: Annotation 10-20
Enabling MTOM on the Server Side: WS-Policy 10-21
Enabling MTOM by Using JDeveloper 10-23
Quiz 10-24
Enabling MTOM on the Client Side 10-25
Setting the Attachment Threshold 10-27
Quiz 10-28
Streaming MTOM 10-29
Server-Side Implementation Code 10-30
Client-Side Implementation Code 10-31
Configuring Streaming SOAP Attachments 10-32
Summary 10-34
Practice 10 Overview: Enabling MTOM in JAX-WS Web Services 10-35

11 JAX-WS Binding Customization

Objectives 11-2
JAX-WS and JAXB 11-3
Data Binding with JAXB 11-4

xi
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Type Mapping Mechanisms 11-5
JAXB Binding Scenarios 11-6
Quiz 11-7
Binding XML Schema to Java Representation 11-8
Example of XML Schema-to-Java Mapping 11-9
Mapping Java Types to XML Schema 11-10
Data Type Mapping 11-11
Built-in Data Types: XML-to-Java Mapping 11-12
Built-in Data Types: Java-to-XML Mapping 11-13
Supported User-Defined XML Schema Data Types 11-14

Oracle University and Egabi Solutions use only

Supported Java User-Defined Data Types 11-15
Customizing Java-to-XML Using Annotations 11-16
JAXB Mapping Annotations 11-17
Example of JAXB Annotations 11-18
Quiz 11-19
Customizing XML Schema-to-Java Mapping Using Binding Declaration 11-20
Scopes of Custom Binding Declarations 11-21
Creating an External Binding Declaration File 11-23
JAX-WS Custom Binding Declarations 11-24
Example of JAX-WS Custom Binding Declarations 11-26
Creating an External Binding Declarations File Using JAXB Binding Declarations
11-27
JAXB Custom Binding Declarations 11-28
Example of JAXB Custom Binding Declarations 11-30
Embedding Binding Declarations 11-31
Embedding JAX-WS or JAXB Binding Declarations in the WSDL File 11-32
Embedding JAXB Binding Declarations in the XML Schema 11-33
Quiz 11-34
Summary 11-35
Practice 11 Overview: Customizing JAX-WS Web Services Data Binding 11-36

12 Implementing JAX-RPC Web Services

Objectives 12-2
JAX-RPC Versus JAX-WS 12-3
Standards/Features Supported by JAX-RPC and JAX-WS 12-4
WebLogic’s Support for JAX-RPC 12-5
JAX-RPC Server-Side Programming Models 12-6
JAX-RPC Service Endpoints Run-Time Architecture 12-7
JAX-RPC Service Endpoints 12-8
EJB Endpoints 12-9

xii
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Creating a Web Service Using Annotations 12-10
Creating a JAX-RPC Web Service Using JDeveloper 12-11
Quiz 12-12
JAX-RPC Client-Side Programming Models 12-13
Invoking Web Services Using a Generated Stubs Model 12-14
Endpoint Interface Generated from WSDL 12-15
Generated Stub Class 12-16
Generated Service Interface and Implementation 12-17
Using the Stub Interface to Access Run-Time Information 12-18
WebLogic Web Services Stub Properties 12-19

Oracle University and Egabi Solutions use only

Quiz 12-20
JAX-RPC Data Binding 12-21
Mapping XML Schema Complex Types 12-22
Mapping XML Schema Complex Types: Generated Endpoint Interface 12-23
Packaging and Deploying JAX-RPC Services 12-24
Packaging and Deployment Tools 12-25
Summary 12-26
Practice 12 Overview: Creating JAX-RPC Web Services 12-27

13 Using Web Services Reliable Messaging

Objectives 13-2
What Is Web Service Reliable Messaging? 13-3
Reliable Messaging Model 13-4
WSRM Versus Java Message Service 13-6
Life Cycle of Reliable Message Sequence 13-7
One-Way Reliable Message Sequence 13-8
WSRM SOAP Message: CreateSequence 13-10
WSRM SOAP Message: CreateSequenceResponse 13-11
WSRM SOAP Message: Application Message 13-12
WSRM SOAP Message: SequenceAcknowledgement 13-13
Reliable Messaging Ordering Model 13-14
Delivery Assurances 13-15
Quiz 13-16
WebLogic WSRM Architecture 13-17
WebLogic WSRM Interaction 13-19
Using WS-Policy to Specify Reliability Requirements 13-20
DefaultReliability1.1.xml WS-Policy File 13-21
Associating WSRM Policy Files Using JDeveloper 13-22
Quiz 13-23
Configuring WSRM for a WebLogic Web Service 13-24

xiii
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Configuring Destination WebLogic Server Instance 13-25
Configuring JMS and SAF Resources Using Configuration Wizard 13-27
Configuring Source WebLogic Server Instance 13-28
Quiz 13-29
Annotations for Reliable Messaging 13-30
Sample RM Web Service 13-32
Invoking a Reliable Web Service 13-34
Reliable Web Service Client 13-35
Web Service Client 13-36
Quiz 13-37

Oracle University and Egabi Solutions use only

Summary 13-38
Practice 13 Overview: Configuring and Creating Reliable Web Services 13-39

14 Creating Conversational Web Services

Objectives 14-2
Conversational Web Service 14-3
Maintaining a Conversational State 14-4
Conversation Phases 14-5
The Process of Conversational Service 14-6
Quiz 14-7
Conversation Provider and Consumer 14-8
Implementing Conversational Web Services 14-9
Sample of a Conversational Web Service 14-11
Invoking a Conversational Web Service 14-13
Sample of a Conversational Web Service Client 14-14
Using a Stand-Alone Java Client to Invoke a Conversational Web Service 14-15
Sample of a Stand-Alone Java Client 14-16
Quiz 14-17
Summary 14-18
Practice 14 Overview: Developing Conversational Web Services 14-19

15 Developing Database Web Services

Objectives 15-2
What Is a Database Web Service? 15-3
Database Call-In 15-4
Database Call-Out 15-5
Generating Wrapper Classes by Using JDeveloper 15-6
SQL-to-XML Type Mappings for Web Service Call-Ins 15-7
SQL-to-XML Type Mappings 15-8

xiv
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Quiz 15-9
Developing Web Services That Expose Database Resources 15-10
Exposing PL/SQL Packages as Web Services 15-12
Steps for Exposing PL/SQL Packages as Web Services by Using JDeveloper 15-13
Creating a Database Connection 15-14
Examining the PL/SQL Package 15-15
Publishing the PL/SQL Package as a Web Service 15-16
Generated Web Service’s Artifacts 15-19
Creating the Application Deployment Profile 15-20
Testing the Generated Web Service by Usingthe Administration Console 15-21

Oracle University and Egabi Solutions use only

Quiz 15-23
Generating a Client and Invoking the Database Web Service 15-24
Generating the Web Service Client Proxy 15-25
Creating a Client to Invoke the DB Web Service 15-26
Summary 15-27
Practice 15 Overview: Developing Database Web Services 15-28

16 Developing Web Services Best Practices

Objectives 16-2
Web Service Design Principles 16-3
Designing Coarse-Grained Interfaces 16-4
Choosing SOAP Binding 16-5
Using EJB Endpoint in Web Services 16-6
Using Annotations 16-7
Data Serialization and XML Schema 16-8
Practical XML Schema Interoperability 16-9
Type Mapping 16-10
Using Modeled SOAP Fault 16-11
WS-Security Interoperability Best Practices 16-12
Terminating Reliable Message Sequence 16-14
Quiz 16-16
Summary 16-18

17 Building SOA Applications with Web Services

Objectives 17-2
Defining SOA 17-3
Enabling SOA Through Web Services 17-4
Sample SOA Application 17-5
ADF Web Services 17-7
Standards That Enable SOA 17-8

xv
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Introducing Orchestration 17-9
Introducing Business Process Execution Language (BPEL) 17-10
Introducing SCA in Oracle SOA Suite 11g 17-11
Service Component Architecture (SCA) 17-12
Elements of SCA 17-13
Service Data Object (SDO) 17-14
Designing with an SOA Approach 17-15
Types of Service Access and Implementation 17-16
Implementing SOA: General Concepts 17-17
Oracle SOA Suite 11g Components 17-18

Oracle University and Egabi Solutions use only

Quiz 17-20
Summary 17-21

Appendix A: Practices and Solutions - JDeveloper

Appendix B: Practices and Solutions - Eclipse with OEPE

Glossary

xvi
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web
Services

Oracle University and Egabi Solutions use only

Course Introduction

Copyright © 2009, Oracle. All rights reserved.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Audience

The target audience includes:

• Java developers
• Java architects
• System integrators
• Other technical personnel who are interested in building

Oracle University and Egabi Solutions use only

interoperable Web services using Java technologies in
their enterprise

Copyright © 2009, Oracle. All rights reserved.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services I - 2
Class Introductions

Briefly introduce yourself:

• Name
• Title/position
• Company
• Java/Java EE and XML knowledge

Oracle University and Egabi Solutions use only

• WebLogic Server and JDeveloper experience
• Reasons for attending

Copyright © 2009, Oracle. All rights reserved.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services I - 3
Goal

The main goal of this course is to use the Java Web Services
API to develop interoperable Web Services.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services I - 4
Course Objectives

After completing this course, you should be able to:

• Describe Web Services concepts and standards
• Explain how Java APIs relate to the underlying Web
Services standards and Java EE container services
• Describe WLS support for JAX-WS and JAX-RPC

Oracle University and Egabi Solutions use only

• Describe the role SOAP and WSDL play in Web services
• Create JAX-WS Web services using JDeveloper
• Implement JAX-WS Web service clients
• Package, deploy, and manage Web services
• Handle exceptions of JAX-WS Web services
• Develop secure JAX-WS Web services by using message-
layer security

Copyright © 2009, Oracle. All rights reserved.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services I - 5
Course Objectives

• Create and configure SOAP handlers to manipulate SOAP

messages
• Develop JAX-RPC Web services
• Implement JAX-RPC Web service clients
• Develop Web services with reliability (JAX-RPC)

Oracle University and Egabi Solutions use only

• Develop conversational Web services (JAX-RPC)
• Expose database resources as Web services (JAX-RPC)
• Use best practices to develop Web services
• Describe how Web services enable SOA application
development

Copyright © 2009, Oracle. All rights reserved.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services I - 6
Prerequisites

To successfully complete this course, you must meet the

following requirements:
• Working experience in the Java programming language
• Knowledge of Java EE platform
• Knowledge of XML and XML schema

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services I - 7
Course Map

Fundamentals Intro Web Java WS Exploring SOAP

Services Overview and WSDL

JAX-WS JAX-WS Web JAX-WS We Packaging, Fault and

Services: Services: Deploying, and Exception
Basics Client-side Server-side Managing WS Handling

Oracle University and Egabi Solutions use only

Using Handlers Optimizing Data JAX-WS
JAX-WS Web Services
in JAX-WS Web Transmission Binding
Advanced Security
Services via MTOM/XOP Customization

JAX-RPC Implementing Web Service Creating Developing

JAX-RPC Web Reliable Conversational Database Web
Stack Services Messaging Web Services Services

Building SOA
Best Practices
with Web Services

Copyright © 2009, Oracle. All rights reserved.

Course Map
The course map shows all the lessons of this course and how they are grouped into sections.

Oracle Enterprise Linux 5

Oracle WebLogic Server (10.3.1.0)

provides the Web Service
deployment/execution environment.
ORACLE
WebLogic Server

Oracle University and Egabi Solutions use only

ORACLE
JDeveloper 11g

JDeveloper
provides the Java development environment.
Oracle Database Express 10g (10.2.0.1.0)
provides the database environment.

Copyright © 2009, Oracle. All rights reserved.

Course Environment
In this course, the following products are used for the lesson practices:
• Oracle Enterprise Linux 5
• Oracle WebLogic Server 11g R1 (10.3.1.0)
• Oracle Database XE 10.2.0.1.0
• JDeveloper 11.1.1.1.0
• Eclipse with OEPE (3.4.2 and OEPE 11.1.1.1.0)
• Java JDK 1.6.0_13

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services I - 9
Course Schedule

Session Module
I: Course Introduction
A.M. 1: Introducing Web Services
Day
2: Java Web Services Technologies Overview
1
3: Exploring SOAP and WSDL
P.M.

Oracle University and Egabi Solutions use only

4: Implementing JAX-WS Web Services: Server-side
5:Implementing JAX-WS Web Services: Client-side
A.M.
Day 6: Packaging, Deploying, and Managing Web Services
2 7: Fault and Exception Handling in JAX-WS Web Services
P.M.
8: Web Services Security

Copyright © 2009, Oracle. All rights reserved.

Course Schedule
The class schedule might vary according to the pace of the class. The instructor will provide
updates.
At the end of the course, the instructor facilitates a feedback session that includes a written
questionnaire.
Oracle University uses your feedback to improve our training programs. We appreciate your
honest evaluation.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services I - 10
Course Schedule

Session Module
9: Using Handlers in JAX-WS Web Services
A.M. 10: Optimizing Binary Data Transmission Using
Day
MTOM/XOP
3
11: JAX-WS Binding Customization
P.M.
12: Implementing JAX-RPC Web Services

Oracle University and Egabi Solutions use only

13: Using Web Services Reliable Messaging
A.M. 14: Creating Conversational Web Services
Day
15: Developing Database Web Services
4
16: Developing Web Services Best Practices
P.M.
17: Building SOA Applications with Web Services

Copyright © 2009, Oracle. All rights reserved.

Topic Website
Education and Training http://education.oracle.com
Product Documentation http://www.oracle.com/technology/documentation
Product Downloads http://www.oracle.com/technology/software
Product Articles http://www.oracle.com/technology/pub/articles
Product Support http://www.oracle.com/support

Oracle University and Egabi Solutions use only

Product Forums http://forums.oracle.com
Product Tutorials http://www.oracle.com/technology/obe
Sample Code http://www.oracle.com/technology/sample_code

Copyright © 2009, Oracle. All rights reserved.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe the motivation for developing Web services in business
software
• Describe what Web services are
• Describe the role of SOAP, WSDL, and UDDI in Web services
• Explain why Web Services Basic Profile (BP) is needed for

Oracle University and Egabi Solutions use only

creating interoperable Web services
• Compare SOAP-based and RESTful Web services
• Describe how Web services enable SOA application
development

Copyright © 2009, Oracle. All rights reserved.

Objectives
This lesson presents a brief architectural overview of Web services.

• Business needs, not technology, powered the drive toward

Web services:
– Application-to-application integration (also known as
enterprise application integration or EAI)
– Business-to-business (B2B) communication
• Traditional technologies hinder the integration because of:

Oracle University and Egabi Solutions use only

– High cost: Traditional technologies use Remote Method
Invocation (RMI), Distributed Component Object Model
(DCOM), or Common Object Request Broker Architecture
(CORBA) to implement distributed systems.
– Lack of flexibility: Traditional technologies are tightly
coupled, bound to a particular transport.
• Web services, based on standards, provide simple and
efficient integration solutions.

Copyright © 2009, Oracle. All rights reserved.

The Drive Towards Web Services

Enterprise application integration (EAI) is the process of creating an integrated infrastructure for
linking disparate systems, applications, and data sources within a single organization. B2B
e-commerce refers to data exchange and communication across multiple organizations, typically
business partners. As companies move in the direction of EAI and collaborative business-to-
business e-commerce, the need for a technology that has open standards and is simple, flexible,
and efficient drives the wide adoption of Web services.
The traditional EAI and B2B solutions typically involve the high cost of distributed technology
such as DCOM and CORBA, require human interaction, and lack a common message exchange
format. Addressing these issues, Web services use standard XML protocols and formats and
leverage open Internet standards to provide an alternative way of exposing application logic to a
heterogeneous client base. Because Web services are standards-based, clients running on
disparate systems can programmatically access application functionality exposed by using Web
service technology in a standard way, independent of the service implementation details or run-
time environment. With Web services technology, disparate pieces of software within an
enterprise can be quickly and easily joined and can communicate with other business services
over the Internet.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 3
The Drive Towards Web Services (continued)
The basic prerequisite for all IT is that the applications ought to reflect the changing needs of
business—specifically, the need for changing a business process from one version to another.
This requirement has been the main driver for SOA. Web services have been around for at least
10 years as a platform-independent distributed component attempting to solve business
functions. Later, it has been shown that it could be used as a non-proprietary integration
component. As seen from a SOA perspective, which is of highest importance, integration ability
is just a nice side effect, but not the key driver, of implementing a SOA infrastructure.
Furthermore, HTTP as the primary transport protocol, in spite of the performance penalties, is
also a key driver towards Web Services because of its ease of use in most networks.

Oracle University and Egabi Solutions use only

Web services:
• Provide a simple and interoperable messaging framework
• Are easily accessible from heterogeneous environments
because they are:
– Loosely coupled

Oracle University and Egabi Solutions use only

– Modular and self-contained
– Self-describing
– Based on standard Internet and XML protocols
– Language and platform neutral

Copyright © 2009, Oracle. All rights reserved.

What Web Services Are

Web services is a technology that incorporates existing standards and introduces a new suite of
specifications and APIs for communicating between application components across the Internet.
Web services provide a standardized mechanism for remotely accessing data and application
functionality.
Web services are built on loose coupling between the application publishing the services and the
application using those services. Loose coupling means that the client of a service is essentially
independent of the service. The way a client (which can be another service) communicates with
the service does not depend on the implementation of the service. Web services employ an
interface that abstracts the implementation of the Web service, so changing the implementation
of an interface does not affect the implementation of consumers. Comparing to the point-to-point
integrated system, which requires changes made at one end to be propagated to the other end,
Web services are much more flexible.
Larger software systems are broken down into smaller modular and self-contained
components—shared services—that can be discovered and used by other applications and other
Web services.
Web services use an XML-based description language to describe themselves.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 5
What Web Services Are (continued)
Web services provide a distributed computing technology using standard XML protocols and
formats. Because a Web service uses standard protocols for communication and data transfer, it
is platform and implementation independent. You interact with a Web service in a standard way,
independently of the technology—such as the underlying protocols, component models,
programming language, or operating system—used to implement the service.

Oracle University and Egabi Solutions use only

Traditional applications pose a number of problems from an

application integration perspective:
• Data: Data is often in a proprietary format, perhaps even
specific to architecture (for example, Big Endian)
• Communications: Interapplication communication is based
on proprietary protocols and is often built based on low-

Oracle University and Egabi Solutions use only

level infrastructure such as sockets.
• Reusability: Applications are monolithic and typically not
reusable at any meaningful level.
• Non-standards based: Applications are often not based on
any external standards.

Copyright © 2009, Oracle. All rights reserved.

The Integration Problem

Historically application integration was a large problem. Applications were rarely designed with
integration or expansion in mind. Data, code, communications, and reusability were never
considered and as a result applications were built to use whatever mechanisms are the developer
or architect favored. Chief of these were lack of a standardized data layer, lack of a standard
communications protocol and a lack of interface definition. To make matters worse frameworks
and supporting tools for RMI, CORBA and DCOM were not interoperable at any meaningful
level forcing developers to develop their own custom mechanisms.

Web Applications Web Services

• User-to-program  Program-to-program
interaction interaction
 Static integration of  Dynamic integration
components of components

Oracle University and Egabi Solutions use only

 Monolithic service  Service aggregation

Copyright © 2009, Oracle. All rights reserved.

Web Services Versus Web Applications

Web applications generally rely on the user to control application flow through the user
interface. A Web service returns its processing results in an XML-based message format that can
be parsed and processed by the client application code enabling program-to-program
communication. A Web service client can operate independently and not require human
intervention to control program flow.
Web services reside on different computers implemented by vastly different technologies, but
they can be packaged and accessible using standard Web protocols, such as XML and HTTP,
thus making them easily accessible by any user on the Web.

Web services is a technology that specifies a common

interoperable approach for communicating over the Internet.
These standards typically include:
• XML: Documents that contain the information being
exchanged between parties Historically known as Simple Object Access Protocol
• SOAP: A standard format for messaging over a network

Oracle University and Egabi Solutions use only

• Web Service Description Language (WSDL): The
language that provides a description for Web services
• Universal Description, Discovery, and Integration (UDDI):
A Web-based distributed directory to publish and locate
information about Web services

Copyright © 2009, Oracle. All rights reserved.

The Building Blocks of Web Services

Web services eliminate the interoperability issues of existing solutions, such as CORBA and
DCOM, by leveraging open Internet standards. XML, SOAP, WSDL, and UDDI are used in
concert to provide Web service applications.
• XML documents contain the information being exchanged between two parties.
• SOAP (to communicate) defines an XML-based structure for passing information, such as
messages and data, between Web services and applications.
• WSDL (to describe) is an XML-based standard for describing the external interface to a
Web service.
• UDDI (to advertise and syndicate) allows organizations to register their Web services in a
uniform manner within a directory, so clients can locate their Web services and learn how
to access them.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 9
SOAP

• SOAP is an XML-based message format based on a World

Wide Web Consortium (W3C) open standard.
• The purpose of SOAP is to exchange structured
information over the network.
– Exchange documents.

Oracle University and Egabi Solutions use only

– Invoke operations between applications.
• HTTP is the most common way of exchanging SOAP
messages.

Copyright © 2009, Oracle. All rights reserved.

SOAP
Using SOAP as a message exchange format is the most agreed-upon piece of the Web services
architectures. Some basic facts about SOAP:
• SOAP is just another XML markup language accompanied by rules that dictate its use.
SOAP defines an XML-based structure for passing information, such as messages and data,
between a Web service and a service client.
• The purpose of SOAP is to exchange data over network. Specifically, it concerns itself
with encapsulating XML data and defining the rules for transmitting and receiving that
data.
• A SOAP message is a SOAP XML document instance, which is designed to be embedded
inside other network protocols. SOAP only defines the structure of the payload of XML
messages as they are transported over the wire. The most common network protocol of
sending and receiving SOAP messages is via HTTP. Other network protocols that can
carry SOAP messages include Simple Mail Transfer Protocol (SMTP), FTP, JMS, e-mail,
and so on.
Note: This lesson just provides an introduction of SOAP standard, the structure of SOAP
messages and processing rules are discussed in Lesson 3 – Exploring SOAP and WSDL.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 10
WSDL

• WSDL is an XML-based language for modeling Web

services.
• WSDL definitions provide basic metadata about Web
services, including: What, where, and how
– Interface description

Oracle University and Egabi Solutions use only

– Data type information: Message format
– Binding information: Network protocol
– Address information: Service location
• WSDL uses an XML schema to describe a Web service in
the form of a WSDL document.

Copyright © 2009, Oracle. All rights reserved.

WSDL
Web Services Description Language or WSDL:
• Is at version 2.0 and is a W3C recommendation
• Is currently supported at level 1.2 in WebLogic Server
• Is an XML-based format to describe the message format, network protocol, and address
that a client uses to communicate with a particular Web service
• Adheres to the WSDL XML schema and must be well formed
• Can be used by clients to locate a service and invoke public functions
For each Web service, the service provider should create a WSDL file that describes it (most
commonly these are generated rather than hand coded). The WSDL file is then available to
potential clients through a variety of mechanisms including registration with a service broker.
The WSDL file used by the client to understand the syntax for communication with the Web
service can be retrieved from third parties such as a service broker or from the service provider
itself.
Armed with a WSDL document describing a service, developers can implement clients or
services with confidence that their implementations will work successfully.

• Provides a standard data model for storing organization

information and their Web services
• Uses SOAP APIs to publish and locate Web services in its
registry
• Is described in a set of specifications that separately cover
the programmer’s API, common data structures,

Oracle University and Egabi Solutions use only

administrative issues, and related topics

Copyright © 2009, Oracle. All rights reserved.

UDDI
Universal Description, Discovery and Integration, or UDDI, is a data model by which Web
services and the businesses that support them can be published, discovered, and used. UDDI is
currently at version 3.0. UDDI is described in a set of specifications that separately cover the
programmer’s API, common data structures, administrative issues, and other related topics.
UDDI identifies the registry as the standard component for publishing to and querying
repositories of information about businesses, common models for data and behavior, and Web
services.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 12
Quiz

Web Services Description Language:

1. Defines Types and methods
2. Contains location information
3. Defines protocol information
4. All of the above

Oracle University and Egabi Solutions use only

Answer: 4

Service
registrar
(UDDI)

2 3 1
Look up Retrieve the service Publish

Oracle University and Egabi Solutions use only

the service description the service
via UDDI. via WSDL. via UDDI.

4 Connect via SOAP.

Service requester Service provider

Copyright © 2009, Oracle. All rights reserved.

Web Service Interaction

SOAP, WSDL and UDDI become de facto standards of Web services, with universal acceptance
and widespread implementation by vendors. The above figure shows how three pieces fit
together in a Web service interaction:
1. Once a Web service is created and deployed, the Web service provider can publish
information about the Web service in a service registry.
Published information, a WSDL document, might include a description of the service, the
service interface definition, and the service instance location. A service provider can also
associate a service with a variety of classification schemes to facilitate locating services
that satisfy a particular criteria.
2. Web service requesters search a service registry for services that meet their needs using
UDDI.
3. After locating an appropriate service, a service requester retrieves information about the
service (described in a WSDL document), such as the service location and interface
description, from the registry entry.
4. The service requester invokes the Web service at the location specified in the service
description, passing the required parameters in a SOAP request message. The service
provider executes using the parameters contained in the incoming SOAP message, and
returns the processing results to the client in a SOAP response message.
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 14
Web Services Interoperability

Interoperability is essential to the success of Web services:

• The respective specifications for SOAP, WSDL, and UDDI
leave too much space for interpretation.
• The Web Services Interoperability (WS-I) Organization
was founded to help ensure interoperability by agreeing on
a common interpretation of the SOAP, WSDL, and UDDI

Oracle University and Egabi Solutions use only

specifications.
• The WS-I Organization defines the WS-I Basic Profile, a
set of rules, to ensure interoperability across a broad range
of platforms.

Copyright © 2009, Oracle. All rights reserved.

Web Service Interoperability

Web services are about interoperability. It is essential to the success of Web services that the
interoperability between various implementations can be guaranteed. The respective
specifications for SOAP, WSDL, and UDDI leave too much space for interpretation - and this is
a killer for successful interoperability.
The goal of Interoperability is to blur the lines between the various development environments
used to implement services so that developers using those services do not have to think about
which programming language or operating system the services are hosted on.
Web Services Interoperability Organization (WS-I.org) has gathered major corporate and non-
commercial participants to work out common scenarios, do’s and don'ts for three areas of
interest in Web services: messages, descriptions, and registry data. These best practices have
been assembled into a document called the Basic Profile 1.0.

The WS-I Basic Profile (BP) makes Web service interoperability

practical by providing a set of rules that govern how
applications make use of common Web service technologies so
that everyone is speaking the same language.
WS-I BP 1.0 is a set of specifications, which includes:
• SOAP 1.1

Oracle University and Egabi Solutions use only

• WSDL 1.1
• UDDI 2.0
Additionally, other basic profiles exist, such as Basic Security
Profile 1.0, Reliable Secure Profile 1.0 and others.
WebLogic Server supports SOAP 1.(1/2) and WSDL1.1.

Copyright © 2009, Oracle. All rights reserved.

WS-I Basic Profile

The BP 1.0 addresses issues that can arise with SOAP 1.1 messages, allowing for future
compatibility with SOAP 1.2 messages:
• The BP has done a lot to clear up ambiguities in SOAP 1.1.
• BP 1.0 discusses the WSDL 1.1 documents exposed by Web services. WSDL 1.1 is more
flexible than the WS-I BP allows, but the requirements of the Basic Profile make WSDL
documents more portable and the SOAP messages they describe interoperable. For
example, WSDL allows HTTP, SMTP, and MIME bindings, but in practice, this makes
interoperability more difficult, so BP only supports SOAP over HTTP.
• BP describes how to use registry data for discovery, such as UDDI Models.
The BP 1.0 is the de facto standard document to follow when building on Web services
interoperability.
Every Web service you create in JDeveloper or Oracle Enterprise Pack for Eclipse (OEPE) will
be BP1.0 compliant by default. This helps to ensure and enable true interoperability if all other
Web services runtime/engine vendors will do the same in their upcoming revisions of their
products.

Messaging Metadata Exchange

SOAP WSDL
SOAP MTOM WS-Policy
WS-Addressing WS-MetadataExchange
XML
WS-ReliableMessaging UDDI

Oracle University and Egabi Solutions use only

Security

WS-SecurityPolicy

WS-Security

WS-SecureConveration

Copyright © 2009, Oracle. All rights reserved.

WS-* Specifications
SOAP, WSDL and UDDI, are standards at the core of Web services, and they are followed by
many additional specifications that define reliability, security, metadata management,
transactions, and orchestration to meet requirements for enterprise features and qualities of
service. These specifications are generally referred to as WS-*. The diagram above shows a
variety of specifications categorized in three main groups, and they will be discussed in this
course later on.
Messaging
• Message Transmission Optimization Mechanism (MTOM): Is used for optimizing the
wire format of SOAP messages
• WS-Addressing: Supports normalized Web service addresses, enabling multiple transports
to be used (besides HTTP)
• WS-ReliableMessaging: Enables Web services running on different servers to
communicate reliably in the presence of failures in software components, systems, or
networks exchanges

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 17
WS-* Specifications (continued)
Metadata Exchange
• WSDL: Base service and message description
• WS-Policy: Policies express and handle requirements and capabilities of Web service
consumers and providers.
• WS-MetadataExchange: A protocol to enable a consumer to obtain a service’s metadata
(its WSDL and policies). Think of it as a bootstrap mechanism for communication.
• UDDI: Provides information about where the Web services are and how to access them
Security
• WS-SecurityPolicy: Defines specific policies (assertions) that describe how messages are
secured
• WS-Security: Provides message content integrity and confidentiality

Oracle University and Egabi Solutions use only

• WS-SecureConversation: Can be viewed as a security optimization (better message level
security and efficiency in multiple-message)

Architectural styles for building Web services include:

• Representational State Transfer (REST)
• SOAP
REST-style services adhere to a set of constraints that include
the following:

Oracle University and Egabi Solutions use only

• Web services are viewed as resources.
• Resources are identified by URIs.
• Resources are manipulated using a standard interface:
HTTP.
• Information is exchanged using resources’
representations.

Copyright © 2009, Oracle. All rights reserved.

Web Services Architecture Styles

There are currently two architectural styles in developing Web services: SOAP and REST. A
great debate has been going on about the merits of these two. For this course, we focus on the
SOAP-based Web services development.
In many ways SOAP is an interoperable cross-platform RPC system. SOAP focuses on actions,
which are a thin layer over a method call. RPC messages typically contain information about the
procedure to be invoked or action to be taken.
REST is an architecture that uses the strengths of the Web to build services. It proposes a set of
constrains that simplifies development and encourages scalable design. REST style of designing
Web services relies on named resources rather than messages. The resources are uniquely
identified by URIs. For example, in a RESTful book store system, each book order has a unique
URI. RESTful services mostly use HTTP as the protocol. Resources manipulation is based upon
the correct use of the HTTP verbs - GET, POST, PUT, and DELETE. REST components
manipulate resources by exchanging representations of the resources. For example, a book order
resource can be represented by an XML document. The book order might be updated by posting
an XML document containing the changed purchase order to its URI.

REST SOAP

Communication Representation of RPC

resources

Oracle University and Egabi Solutions use only

Message Format HTTP Get – Arguments XML
HTTP Put – XML

Transport HTTP HTTP, SMTP, MIME,

FTP, etc

Interface Web Application WSDL

Definition Description Language
(WADL)

Copyright © 2009, Oracle. All rights reserved.

RESTful Versus SOAP-Based Web Services

The decision between the REST and SOAP will be your first choice in designing a Web service,
so it is important to understand the differences of the two.
In many ways SOAP is an interoperable cross-platform RPC system. In the RPC approach,
typically many operations are invoked at the same URI. This contrasts with the REST approach
of having a unique URI for each resource.
REST uses simple XML over HTTP without a WSDL interface definition. It requires no
additional standards and is based on well-known existing standards. Though REST exposes a
much simpler interface than SOAP, it has some limitations:
• REST is bound to HTTP. Since it is difficult to handle different transports like JMS and
SMTP, the REST approach is suitable for designing an application to be used exclusively
on the Web. If you are designing a SOA for an Enterprise, that needs to connect to many
systems using multiple transports, then it is better to go with SOAP.
• REST simply rely on the built-in HTTP authentication and SSL to provide security. With
SOAP, you can have more sophisticated choices, such as WS-Security that allows you to
encrypt a portion of the messages and moves the security handling from the wire layer to
the message layer.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 20
Quiz

RESTful Web services use a variety of protocols for

messaging.
1. True
2. False

Oracle University and Egabi Solutions use only

Answer: 2

Service-Oriented Architecture (SOA) can be thought of as:

• A “paradigm for organizing and utilizing distributed
capabilities that may be under the control of different
ownership domains” (from an OASIS definition)
• An IT strategy that organizes the discrete functions
contained in enterprise applications into interoperable,

Oracle University and Egabi Solutions use only

standards-based services that can be combined and
reused quickly to meet business needs.

In computing terms, SOA is a standards-based method of

systems development and integration.

Copyright © 2009, Oracle. All rights reserved.

Definition: Service-Oriented Architecture (SOA)

SOA is a strategy for developing and integrating systems through the use of interoperable
standards-based services.
The benefits of following an SOA approach include:
• Reuse of function across different business organizations and processes
• Integration between different business systems by following a standards-based approach
• Agile development that adapts business changes through use of discrete functions and
standardized interfaces
In summary, in computing terminology SOA is a system integration process, based on using
services developed according to standards that make the process integration easier. The idea of
SOA does not prescribe a specific technological implementation. However, industry has
embraced the standards, flexibility, and reusability of Web Service style technology
implementations.

• SOA can be thought of as:

– An enterprise-level design approach
– A collection of services on a network that communicate with
one another
– A set of services that are loosely coupled, with well-defined,
reusable, platform-independent interfaces

Oracle University and Egabi Solutions use only

– A higher level of application development
• Services provide access to data, business processes, and
IT infrastructure, ideally in an asynchronous manner.
• SOA leverages standards-based integration (XML and
Web services) to connect heterogeneous systems.

Copyright © 2009, Oracle. All rights reserved.

SOA Further Defined

SOA-based application development and integration solves many issues and shortcomings of the
traditional approaches mentioned earlier. SOA describes a set of well-established patterns that
help a client application connect to a service. These patterns represent mechanisms used to
describe a service, to advertise and discover a service, and to communicate with a service.
Most communication middleware systems, such as RPC, CORBA, DCOM, EJB, and RMI, rely
on similar patterns. However, there are some differences between each implementation and
weaknesses among them. The primary issue has been acceptable standards and interoperability.
SOA is built upon these technologies and has tried to eliminate apparent weaknesses. Each of
these technologies has a fixed granularity, function for RPC, object for CORBA, and so on.
Services do not have this fixed granularity. Instead, a service can be a function, an object, an
application, and so on. SOA is, therefore, adaptable to any existing system and does not force
the system to conform to any particular level of granularity.
SOA helps information systems to move towards a “leave-and-layer” architecture. Instead of
replacing the existing architectures, it helps to reuse all existing systems and applications in the
company and transform them into agile services. SOA not only covers information from
packaged, customer, and legacy applications systems, but also the functionality/data from IT
infrastructure such as security, content management, search, and so on. A significant reduction
of the time to develop new applications based on SOA is now much easier to do by adding
THESE functionality
eKIT MATERIALSthatARE
arises
FORfrom
YOURthese
USE IT infrastructure
IN THIS CLASSROOM services.
ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 23
Services Are SOA Building Blocks

Client

XML messages (defined by an XSD) WSDL

Oracle University and Egabi Solutions use only

Interactions

Service
Service

WSDL

Service

Copyright © 2009, Oracle. All rights reserved.

Services Are SOA Building Blocks

Services:
• Form the basic building block for an SOA implementation
• Perform work based on business interactions and requirements
• Interact by exchanging messages with other clients and other services
• Describe their interface by using Web Service Definition Language (WSDL) that specifies:
- Operations that may be executed
- Message structures for communicating the required data for each operation. Message
structures are based on types expressed in an XML Schema document (XSD).
Note: Before embarking on any SOA implementation, the business process requirements needs
to be defined, and a portfolio of services that support the business requirements need to be
identified or created.

Specifications Service Component Assembly

forming a Architecture (SCA) Model
collection of
standards Service Data Objects (SDO) Data Access

Business
Orchestration: BPEL4WS
processes

Oracle University and Egabi Solutions use only

Management Quality of
WS-Reliable Messaging WS-Security
WS-Policy service
WS-Security
UDDI Discovery

WSDL Description

SOAP
Message
XML

HTTP(S), IIOP, JMS, SMTP Transport

Copyright © 2009, Oracle. All rights reserved.

Standards That Enable SOA

The graphic illustrates the many existing W3C standards upon which a SOA-enable approach
can be implemented. The SCA and SDO specifications are a work in progress guided by the
OASIS organization that may lead to a new collection of standards with an SOA-enabled
approach in mind.
The collection of standards listed work together and build on simple, stand-alone standards (such
as XML and XPath) to enable an SOA approach (that is, using the Web service foundations of
SOAP, WSDL, and UDDI). The idea of Service-Oriented Architecture is elevated to a higher
level through process orchestration and integration.
Note: Embracing a set of standards for an SOA-enable approach enables independence of
hardware, operating systems, and languages used for application implementation for the business
process and service functionality.
All the standards above the transport category, such as Business Process Execution Language
(BPEL) often known as “BPEL for Web Services” (BPEL4WS), SCA and SDO are all XML-
based implementations. As many may have heard before: “XML is the lingua franca of the
Internet” and more so in the case of SOA-enabled approaches today.

Web services are an ideal platform for SOA because:

• Web services are designed to achieve interoperability
• Web services interfaces are good for enabling the
development of services that encapsulate business
functions

Oracle University and Egabi Solutions use only

• The core and extended specifications of Web services
contribute significantly to the ability to implement SOA-
enabled solutions

Copyright © 2009, Oracle. All rights reserved.

Web Services and SOA

SOA is emerging as the premier integration and architecture framework in today’s complex and
heterogeneous computing environment. SOA can help organizations streamline processes so that
they can do business more efficiently, and adapt to changing needs and competition, enabling
the software as a service concept.
Web services are an ideal platform for SOA. Whether you use Java, C++, C#, CORBA, or any
other development platform or software system, such as Java EE or the .NET Framework, SOA
provides the architecture, and Web services provide the unifying glue:
• Web services are designed to achieve interoperability and to hide the details of the
execution environments behind them.
• SOA with Web services enables the development of services that encapsulate business
functions and that are easily accessible from any other service.
• Integrating existing and new applications using an SOA involves defining the basic
interoperability layer and the enterprise capabilities layer, e.g. quality of service to bridge
features and functions used in current applications such as security, reliability, and
transactions. The Web services platform contains the basic and extended features
necessary to support these requirements.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 26
Web Services and SOA (continued)
There are a number of reasons to not consider Web Services in SOA as well, for example:
• Real time system Performance: Web Services are typically too slow for R/T systems.
• Large payloads: Direct datasource to datasource should be considered for very large
payloads, rather then subject the application to network latency to send large document
transfers.
• Choose JMS for better performance: Message driven middleware, where messages need
to be handled sequentially etc may be a better choice for some implementations.
• Transactional challenges: Web Services do not support call correlation or long running
transactions.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 27
Summary

In this lesson, you should have learned:

• What Web services are
• The role of SOAP, WSDL, and UDDI in Web services
• The benefits of using Web Services BP in creating
interoperable Web services

Oracle University and Egabi Solutions use only

• The basics of SOAP-based and REST architectural styles
of Web services design
• How Web services enable SOA application development

Copyright © 2009, Oracle. All rights reserved.

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 1 - 28
Practice 1 Overview:
Reviewing Terms and Concepts
This practice covers the following topics:
• Reviewing Web Service terms and definitions
• Connecting to your assigned Grid VM machine
• Exploring the development environment

Oracle University and Egabi Solutions use only

Grid VM
Server
Classroom PC Linux Virtual
Machine

Your Grid VM Instance

Oracle University and Egabi Solutions use only

WebLogic
Console

Oracle WebLogic
JDeveloper Server

Oracle Database 10g XE

Copyright © 2009, Oracle. All rights reserved.

Describing the Course Environment

The course development and practice environment provides you with a desktop (classroom) PC
from which you use the NX Client software to connect with a virtual machine (VM) instance
running on a VM server called a Grid VM server. The VM instance you connect with, called a
Grid VM instance, runs the Oracle Enterprise Linux Version 5 update 2 operating system.
On the Grid VM instance allocated to you for the course practices, you have all the software
required to perform you practices. The basic software configuration includes:
• Oracle JDeveloper, which is used to develop and deploy your Web service applications and
projects created as part of the course practices.
• An instance of Oracle WebLogic Server, which provides the Java EE container for running
your deployed Web services and WebLogic console Web application.
• An Oracle Database 10g Express Edition database for tables and PL/SQL package that will
be exposed as Web services.

Oracle University and Egabi Solutions use only

2
1

Copyright © 2009, Oracle. All rights reserved.

Configuring a Grid VM Connection

The course environment provides a Grid Virtual Machine (VM) instance that runs all the
software used in the course practices. From your local desktop machine, you create and
configure a connection to a Grid VM instance allocated to you by using the NoMachine (NX)
client software installed on the local desktop. The steps to configure the connection are:
1. Launch the NX Client software from your menu. If you are using an operating system
other than windows, this will look different than as shown above.
2. To begin the configuration process, on the NX Connection Wizard Welcome page, click
Next.

Oracle University and Egabi Solutions use only

Configuring a Grid VM Connection: Session

3. On the NX Connection Wizard Session page, configure your connection to the Grid VM
machine that is assigned to you for the duration of the course. Enter appropriate values for
the following fields:
- Session: vxNNNN (Replace NNNN with your assigned VM instance number.)
- Host: vxNNNN.us.oracle.com. Accept the defaults for all other values
Note: Values are assigned to you by your instructor.

Oracle University and Egabi Solutions use only

Configuring a Grid VM Connection: Desktop

4. On the NX Connection Wizard Desktop page, choose the operating system and UI
components for the host environment that you are connecting to. For this course, select
UNIX and GNOME, respectively.
Note: You can optionally select the size of the session window for your remote desktop. Usually
accepting the default value (Available area) is sufficient.

Oracle University and Egabi Solutions use only

Configuring a Grid VM Connection: Configuration Completed

5. On the NX Connection Wizard Configuration Completed page, ensure that the “Create
shortcut on desktop” option is selected to add a shortcut to the desktop.
Note: The desktop shortcut enables you to reconnect to your Grid VM instance after you
disconnect or terminate a session.

Oracle University and Egabi Solutions use only

Copyright © 2009, Oracle. All rights reserved.

Connecting to the Grid VM Instance

To connect to the Grid VM instance you have configured use the following steps:
1. Double-click the NX client shortcut on your desktop to start the NX client.
2. To connect to the Grid VM instance, in the NX login window, enter a username and
password combination provided by your instructor.
Note: The username is usually oracle.
After you successfully connect to your remote desktop, you should see a desktop view similar to
the one shown in the image. The remote desktop provides desktop icons to start JDeveloper,
Oracle SOA Suite and other applications needed to perform your practices.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Java Web Services Technologies Overview

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe the benefits provided by the Java technology for
creating Web services
• Describe the core Java APIs for Web services
• Describe WebLogic Server’s support for Java Web

Oracle University and Egabi Solutions use only

services
• Create, deploy, and test a simple Web service on the Java
EE platform

Copyright © 2009, Oracle. All rights reserved.

Objectives
This lesson presents a high-level overview of Java Web Services APIs. It intends to provide an
appreciation for the big picture and sets the stage to go into the programming details in subsequent
lessons.

Java technology offers many clear advantages for

implementing and using Web services.
• The Java programming language is platform-neutral.
• The Java run-time environment includes a large library of
code for many of the tasks that a Web service must
perform.

Oracle University and Egabi Solutions use only

• Java technology components enable developers to build
Web services that are interoperable.

Copyright © 2009, Oracle. All rights reserved.

Java Technology for Web Services

Java technology offers many clear advantages for implementing and using Web services.
• The Java programming language is platform-neutral, so services implemented using Java can
be built and deployed on any platform, such as Linux, UNIX, or Microsoft Windows, that
supports the Java run-time environment.
• The Java run-time environment includes a library of code for many of the tasks that a Web
service must perform, such as network communication, object serialization, database access,
and XML processing.
• Java technology components enable you to build Web service applications that are
interoperable with any other system, including the .NET Framework, PERL, and C++.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 3
Java Web Services

• Java Web Services (JWS) is:

– A set of enabling technologies for consuming and creating
Web services
– Built on Java Enterprise Edition (EE) 5 and Java Standard
Edition (SE) 6 features such as annotations
– A toolkit, not an application framework

Oracle University and Egabi Solutions use only

• Java EE and Java SE platforms have native support for
JWS.

Copyright © 2009, Oracle. All rights reserved.

Java Web Services

Java Web Services (JWS) has the following qualities:
• Basically, JWS is composed of a set of enabling technologies for creating and consuming Web
services.
• JWS is built on some features introduced in Java Enterprise Edition (EE) 5 and Java Standard
Edition (SE) 6 to implement Web services. Those features include annotations and generics.
• JWS provides a toolset for invoking and deploying Web services. It is not an application
framework. Therefore, when creating Web services with the JWS technologies, you need some
discipline and design best practices.
• JWS is included as part of the standard JVM installation, so developers will avoid the need for
including them in individual applications.

JWS standards provide tools for working with WSDL and

SOAP/HTTP from within the Java programming language. Java
APIs for Web services include:
• Web Services Metadata for the Java Platform (WS-
Metadata) [Java Specification Request (JSR) 181]
• Java API for XML Web Services (JAX-WS) [JSR 224]

Oracle University and Egabi Solutions use only

• Java API for XML Binding (JAXB) [JSR 222]
• SOAP with Attachments API for Java (SAAJ) [JSR 67]
• Web Services for J2EE (WSEE) [JSR 109]
• Java API for XML-Based RPC (JAX-RPC)

Copyright © 2009, Oracle. All rights reserved.

Java Web Services Standards

The core Java specifications for Web Services include:
• Java API for XML Web Services (JAX-WS) [JSR 224] is designed to replace JAX-RPC in Web
services and Web applications.
• Web Services Metadata (WS-Metadata) [JSR 181] defines an annotated Java format that uses
Java Language Metadata (JSR 175) to enable easy definition of Java Web services level for the
Java EE platform.
• Java Architecture for XML Binding (JAXB) [JSR 222] defines an extensible mapping between
the Java and XML schema type models. This makes it easy for developers to incorporate XML
data and processing functions in applications based on Java without having to know much
about XML itself.
• SOAP with Attachments API for Java (SAAJ) [JSR 67] provides a standard way to send XML
documents over the Internet from the Java platform. It can be used to develop Web services that
enable attachments to be sent from the client to the server or vice versa.
• Web Services for J2EE (WSEE) [JSR 109] defines the deployment process and the packaging
structure of Web services in Java.

Client Service

Service Endpoint
Implementation
(SEI)

Oracle University and Egabi Solutions use only

SOAP message
JAX-WS JAX-WS
Run time Run time

Copyright © 2009, Oracle. All rights reserved.

JAX-WS Programming Model

JAX-WS is the core of Java Web Services. It defines the standard programming model for both Web
service clients and endpoints in Java EE. There are essentially two sides to the JAX-WS model:
client-side and server-side. The client-side programming model allows you to access a remote Web
service as if it were a local object, using methods that represent SOAP operations. The server-side
programming model allows you to develop Web service endpoints as Java objects, which run on the
Java EE platform.
A service endpoint interface or service endpoint implementation (SEI) is a Java interface or class,
respectively, that declares the methods that a client can invoke on the service.
Note: An interface is not required when building a JAX-WS endpoint. The Web service
implementation class implicitly defines an SEI.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 6
JAX-WS Benefits

The JAX-WS programming model:

• Is a simpler way to develop/deploy Web services through
standards-based annotations model:
– WS-Metadata [JSR181]
– JAX-WS 2.0 [JSR 224]: Manipulate the style of WSDL

Oracle University and Egabi Solutions use only

– JAXB 2.0 [JSR 222]: Manipulate the representation of Java
parameters and return types as XML Schema components
– Common Annotations for the Java Platform [JSR 250]
• Hides SOAP complexity from the application developer
• Improves messaging support and schema support by
using JAXB data binding

Copyright © 2009, Oracle. All rights reserved.

JAX-WS Benefits
JAX-WS is the next generation Web services programming model to extend the foundation provided
by the JAX-RPC programming model. JAX-WS offers the following benefits:
• Using the JAX-WS programming model, development of Web services and clients is simplified
through support of a standards-based annotations model. The JAX-WS standard supports the
use of annotations that are based on several JSRs: JSR 181, JSR 224, JSR 222 and Common
Annotations for the Java Platform [JSR 250]. Annotations used in JAX-WS will be covered
later in this course.
• JAX-WS represents remote procedure calls or messages using XML-based protocols such as
SOAP, but hides SOAP’s complexity behind a Java API by using standard Java/WSDL
mapping. When a SOAP message invokes a WSDL described operation, the Java/WSDL
mapping decides which Java method gets invoked and how that SOAP message is mapped to
the method’s parameters. Conversely, the mapping also determines how the method’s return
value gets mapped to the SOAP response.
• Improve messaging support, including asynchronous operations and transports besides HTTP,
and improve schema support by using JAXB data binding as the replacement of JAX-RPC
1.X’s simple built-in binding. JAX-WS and JAXB technologies are well integrated. When
starting from Java classes, JAXB can generate XML Schema documents that are automatically
embedded inside a WSDL document, saving users from performing this time-consuming and
error-prone integration manually.
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 7
WS-Metadata Benefits

The WS-Metadata specification [JSR181]:

• Enables developers to create JWS from a simple Plain Old
Java Object (POJO) class by using annotations
• Enables developers to expose the entire class or only the
selected methods as the Web service:

Oracle University and Egabi Solutions use only

– @WebService: Marks either a Java class or a service
endpoint interface (SEI) as a Web service interface
– @WebMethod: Indicates a method as a Web service
operation
• Helps reduce deployment complexity; requires no
deployment descriptors

Copyright © 2009, Oracle. All rights reserved.

WS-Metadata Benefits
Annotations are at the center of the ease-of-use features of Java EE 5. WS-Metadata [JSR181]
defines the standard annotations that are used to develop and deploy Web Services within a Java EE
5 container. Using annotations, developers can create portable JWS from a simple Plain Old Java
Object (POJO) class.
You can annotate types, methods, fields, and parameters in your Java class to specify a Web service.
The developer can take advantage of the annotations to specify how a Web Service should be
exposed to the outside world as the annotation development model provides fine-grained control over
exposing the Web Services. For example, if you want only to expose certain business operations in
the Java class, you may find @WebMethod annotation useful.
WS-Metadata can be used to shape the deployment of a Web service. Web service developers define
only the annotated Java Web service file and leave the job of creating necessary deployment and
configuration files to the vendor. With annotations, you usually do not need deployment descriptors
when deploying a Web service.
Note: JSR181 also defines other annotations, such as configuring bindings and handler chains,
setting WSDL parameters, and so on. They will be discussed in the subsequence lessons.

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

@WebService Required
public class AddNumbersServiceImpl {
@WebMethod Optional

Oracle University and Egabi Solutions use only

public int addNumbers(int op1, int op2) {
return op1 + op2;
}
}

Copyright © 2009, Oracle. All rights reserved.

A Simple Annotated Java Class

The code example shows how to use @WebSevice and @WebMethod to expose a Java method as
Web service operation.
According to WS-Metadata annotation definition, @WebSevice annotation is applicable for a SEI
or a service endpoint implementation class. @WebMethod annotation is applicable for public
methods in a SEI or a service endpoint implementation class. The @WebMethod annotation is only
supported on classes that have the @WebSevice annotation.
Actually by default, all public methods in a class that specifies the @WebSevice annotation are
exposed in the Web service, so without the @WebMethod annotation in the example here,
addNumbers method will still be exposed. The rules for using methods in classes will be discussed
later in this course.
For more information about WS-Metadata annotations’ definition, please see
http://java.sun.com/javaee/5/docs/api/

• Java classes must follow certain rules if they are to be

used as Web services
– Must have a public no-argument constructor
– Must not be abstract
– Must define at least one public method, which will be exposed as a
Web service method

Oracle University and Egabi Solutions use only

– Should not start any threads and are thread-safe
• Java classes, used as input to or return from Web
services, must:
– Define a default no argument constructor
– Implement getXXX and setXXX methods for exposed variable
– Use only built-in types, or types that meet these guidelines
– Be serializable

Copyright © 2009, Oracle. All rights reserved.

Java Web Service from POJO Rules

The slide describes the minimum requirements to convert a POJO to a Web Service. While most are
self explanatory, its important to understand a Web service from a thread perspective. Web services
are ultimately handled by a specialized servlet calling the POJO. Because servlets are shared
resources, their associated Web services are also shared services. As such Web services must be
thread safe. Additionally, it is considered a bad idea to start a thread from a Web service since such
threads may outlive the call to the Web services and by definition are not allocated from the WLS
thread pool.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 10
Quiz

To be a valid POJO for a JAX-WS, the class requires:

1. An @WebService annotation
2. An @WebService annotation and at least one public
method
3. An @WebService annotation and an @WebMethod

Oracle University and Egabi Solutions use only

annotation
4. None of the above

Copyright © 2009, Oracle. All rights reserved.

Answer: 2

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 11
JAXB

JAXB 2.0 is Java/XML binding framework for JAX-WS 2.0.

• The binding provides a mechanism by associating a set of
Java classes with an XML schema so that schema
instances are manipulated using Java methods.
• JAXB 2.0 defines a standard Java/XML binding from Java
to XML Schema components and vice versa.

Oracle University and Egabi Solutions use only

• JAXB 2.0 uses mapping annotations for customizing
Java/XML binding.

Copyright © 2009, Oracle. All rights reserved.

JAXB
Both Java and XML Schema are complex and expressive languages. Implementing a standard
binding between these languages is a large, complex task. In JAX-WS 2.0, all data binding has been
delegated to JAXB 2.0 which provides a higher level of abstraction than Java implementations of
SAX, DOM, and XPath to make it easier for Java programmers to work with XML instances of the
schema.
Binding two scenarios:
• Start from Java: JAXB implementations provide a schema generator that creates schema from
existing classes using the standard map. The classes need not be explicitly annotated, because
JAXB 2.0 defines defaults to supply implied annotations wherever needed.
• Start from XML Schema: JAXB 2.0 implementations provide a schema compiler that
generates Java classes from an XML schema.
• JAXB 2.0 uses mapping annotations for customizing standard Java/XML binding. When a class
has no annotations, the XML schema generated by schema generator is based entirely on the
default Java/XML binding. If mapping annotations are provided, the Java class maps to a
unique XML Schema component based on its annotations. This topic will be discussed in depth
later in this course.

• SAAJ:
– Provides Java APIs to read, write, send, and receive SOAP
messages
– Allows binary content to be attached to a SOAP message
• The SAAJ 1.3 APIs conform to the SOAP 1.1 and 1.2
specifications and the SOAP with Attachments (SwA)

Oracle University and Egabi Solutions use only

specification.
• Typical developers do not need to use SAAJ APIs to write
applications—most tasks can be accomplished with the
JAX-WS programming model.

Copyright © 2009, Oracle. All rights reserved.

SOAP with Attachments API for Java (SAAJ)

SAAJ is used mainly for the SOAP messaging that goes on behind the scenes in JAX-WS and JAX-
RPC implementation. However, there are situations where programmers need to access SOAP
messages including binary content. SAAJ provides a set of APIs to read, write, send and receive
SOAP messages and binary data attached to those messages. SAAJ 1.3 is based on the SOAP 1.1 and
SOAP 1.2 and SOAP with Attachments specifications. As a best practice, only use SAAJ, when
necessary, with JAX-WS.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 13
WSEE

WSEE (JSR-109) is intended to promote the building of

interoperable and portable Web services in the Java EE
environment.
WSEE 1.2:
• Defines the proper use and packaging of WS-Metadata
annotated classes

Oracle University and Egabi Solutions use only

– Specifies a POJO to be deployed to the Web container
– Specifies a stateless session bean to be deployed to the EJB
container.
• Simplifies Web services deployment, working with WS-
Metadata
– The service implementation bean (SIB) is the only artifact
required for deployment.

Copyright © 2009, Oracle. All rights reserved.

WSEE
WSEE (JSR-109) is to promote the building of interoperable and portable Web services in the Java
EE environment. WSEE has been around since J2EE 1.4. WSEE 1.2 is the release that works with
JAX-WS 2.0. Some basics about WSEE 1.2 include:
• WS-Metadata describes how annotations on the packaged classes shape the deployment, while
WSEE 1.2 defines the deployment process and the packaging structure. For example, it
specifies that a POJO can be deployed to the Web container, and a stateless session bean can be
deployed to the EJB container.
• Web services deployment using WSEE 1.0. is quite complicated in J2EE 1.4. This deployment
complexity has been greatly reduced through the use of annotations, together with the
simplified architecture and packaging as defined in WSEE 1.2. In the new programming model,
service implementation bean (SIB) is the only required artifact for deployment. Many artifacts
required by J2EE 1.4, such as Web services deployment descriptors and SEI, are optional.
Note: WS-Metadata defines the requirements for deploying a Java class as a Web service.
Classes that meet these requirements are called service implementation beans (SIBs).

XML Java
parameters parameters
1
WSDL

7 6
POJOs
SOAP 5

Oracle University and Egabi Solutions use only

2 Endpoint 3 4

Web XML Java

Container Return Return
EJB Container

JAX-WS
JAXB
JAX-WS JAXB
WS-Metadata

Copyright © 2009, Oracle. All rights reserved.

Roles of APIs in Web Services Invocation

The diagram illustrates the roles of JWS APIs in a server-side Web services invocation:
1. Web service information described in WSDL can be retrieved by the service requester.
2. A SOAP request is sent to the endpoint to invoke the deployed Web service. The Web service’s
endpoint is typically implemented by a servlet class listening at the endpoint URL specified
during deployment. This servlet is part of the internal Java EE 5 implementation of JWS.
During deployment, WSEE run time reads the annotations and/or deployment descriptors,
determines the endpoint URL, and the container’s internals are configured to deploy the listener
at that endpoint.
3. The SOAP request has become a set of XML parameters—instances of the XML Schema
components specified as parameters in the WSDL. The JAX-WS run time is responsible for
extracting these parameters from the SOAP message.
4. The XML parameters are deserialized into Java parameters. This is handled by the JAXB run
time.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 15
Roles of APIs in Web Services Invocation (continued)
5. Once the parameters have been created, the JAX-WS run time invokes the target Java
class/method. The class providing the method for invocation can be either an Enterprise
JavaBeans bean (EJB) or a Plain Old Java object (POJO). Annotations from JAX-WS, JAXB,
and WS-Metadata are all used in these Java classes that comprise the Web service application.
6. After the invocation, Java return type class is handed off for JAXB serialization to become an
XML return type instance. This serialization is controlled by the annotations on the Java return
class.
7. Then, the JAX-WS run time takes the XML return type instance and wraps it in a SOAP
response.
Finally, the SOAP response is sent back to the requester as the payload of the HTTP response.

Oracle University and Egabi Solutions use only

Standards/Features JAX-WS JAX-RPC

SOAP 1.1 and 1.2 1.1

WSDL 1.1 1.1

WS-I BP 1.0 and 1.1 1.0

Oracle University and Egabi Solutions use only

SAAJ 1.2 1.1

Data mapping and JAXB and StAX Built-in binding

parsing model and parsing
MTOM support Yes No

Messaging Synchronous and Synchronous

asynchronous operations,
operations Reliability and
Conversations

Copyright © 2009, Oracle. All rights reserved.

JAX-RPC and JAX-WS Stack Comparison

JAX-RPC is a J2EE API. JAX-RPC was the original standard for Web services in Java. It was
created to promote interoperability between Web services executing in heterogeneous platforms and
developed in different languages. JAX-RPC was a standards-based implementation, but the binding
and parsing layers underneath it were proprietary. Additionally, JAX-RPC 1.1 does not completely
cover schema specification. JAX-WS evolved from JAX-RPC, with JAX-RPC 1.2 becoming JAX-
WS 2.0.
Some advantages with JAX-WS are:
• fully standard-based
• ease of development
• high performance
The table above shows the standards/features supported by JAX-RPC and JAX-WS.

There are two approaches:

• Bottom-up approach
– Annotate POJOs.
– WSDL file can generated automatically (requires little or no
knowledge of WSDL or XML).

Oracle University and Egabi Solutions use only

• Contract-first (top-down) approach
– Generate the Web service from an existing WSDL file.
– Add business logic to the services implementation class.
– Server-side and client-side development can be done
simultaneously.

Copyright © 2009, Oracle. All rights reserved.

Java Web Service Development Approaches

Web services can be generated by using either a bottom-up approach or a top-down approach. Each
of these has advantages and disadvantages that determine the pattern that should be used in a given
situation.
The bottom-up approach starts with coding the business logic that is being abstracted into an
interface definition and is typically used when the underlying implementations either mostly or partly
exist. The interface is then exposed as a Web service. It requires little or no knowledge of Web
Services Description Language (WSDL) or Extensible Markup Language (XML) because the WSDL
document is automatically generated by the development tools.
With the top-down approach, both the server-side and the client-side developers use a WSDL
document to produce the artifacts necessary for their respective environments. The server-side
developer can start with the WSDL document to define new implementations of portType (defined
by WSDL), and the client-side developer can start with the same WSDL document to develop a Web
service client. This leads to the independent development of the client-side and the server-side
simultaneously. The top-down approach model also provides reusability of new schema types
developed for the current Web service. It can be achieved by simply incorporating the new XML
Schema Definition (XSD) schema into the required Web services.

Generate WSDL 2
WSDL 1 Generate Java
artifacts artifacts

Oracle University and Egabi Solutions use only

Java-to-WSDL WSDL-to-Java
1 2

Web service
POJO client

Web service Web service

development client development

Copyright © 2009, Oracle. All rights reserved.

Bottom-Up Approach
Web Service Development
1. The business logic is provided using either Java classes or EJBs and contain methods that are
exposed in the Web service interface.
2. A Web service generation tool (in this case, Java-to-WSDL) generates the WSDL. The Web
service generation tool can be the JDeveloper, OEPE, or an Ant task.
Web Service Client Development
1. The Web service generation tool (in this case, WSDL-to-Java) generates the client-side
proxy class and other client-side artifacts from WSDL.
2. The Web service client application uses the proxy class to communicate with the Web service
application.
Note: With the bottom-up approach, the development of the Web service client is dependent on the
implementation of the Web service because the entire client-side artifacts (such as the proxy) are
developed from the WSDL document.

XSD schemas

1 1

Oracle University and Egabi Solutions use only

WSDL-to-Java WSDL-to-Java
WSDL
Generate Java Generate Java
2 2 artifacts
artifacts

Web service Web service

implementation client

Web service Web service

development client development

Copyright © 2009, Oracle. All rights reserved.

Top-Down Approach
Web Service Development
1. A WSDL document is created. You can incorporate multiple XSD schemas in the WSDL
document, which describes the input and the output data types for the Web service operation.
2. The Web service generation tool (in this case, wsdlc) generates the Java artifacts, such as the
service endpoint interface, which are implemented as a Web service.
Web Service Client Development
1. Similar to that of the Web service development.
2. The Web service generation tool (in this case, clientgen) generates the Java artifacts, such
as the client-side proxy, which are used by the client application to communicate with the Web
service.
Note: In the top-down approach, the development of the client-side and the server-side can be done
in parallel, and without any dependency on each other.

JAX-WS Stack JAX-RPC Stack

• JAX-WS 2.1* • JAX-RPC 1.1*

• JAXB 2.1 * • WSEE1.0*
• WSEE1.2 * • WS-ReliableMessaging+
• Asynch client programming • WS-SecureConversation+

Oracle University and Egabi Solutions use only

model * • WS-Trust+
• XML Catalog • Conversational Web Services+
• WS-Security 1.1
*Part of the JAX-RPC spec
• Dynamic endpoint publishing * +Provided by WebLogic Server

• WS-Policy 1.5
• WS-SecurityPolicy 1.2
• Asynchronous request-response

*Part of the JAX-WS spec

Copyright © 2009, Oracle. All rights reserved.

WebLogic Server Support for JWS

• JAX-WS 2.1: Java Web Services, rechristened from JAX-RPC2.0
• JAX-B: Java API for XML Binding
• WSEE: Web Services for J2EE
• XML Catalog: Mapping of generic address to specific objects such as directories etc
• WS-Security: A communications protocol providing a means to secure web services released
by OASIS-Open February 2006.
• WS-Policy: A set of specific WS specifications which define minimum requirements to support
intercommunications between Web services.
• WS-SecurityPolicy: An extension to WS-Policy which added basic security definitions to
standard policy
• JAX-RPC: Java API for XML Remote Procedure Call
• WS-ReliableMessaging: A protocol that allows messages to be reliably delivered between two
web services
• WS-Trust: A specification which extends WS-Security to deal with security tokens and trust
relationships.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 21
Quiz

The top-down approach to Web service development:

1. Starts with WSDL and typically generates a schema
2. Starts with WSDL and typically generates Java stubs
3. Starts with a POJO with annotations
4. 1 and 2

Oracle University and Egabi Solutions use only

Answer: 2

MyService.java
Create SEI
(w/ annotation)

Build javac

Oracle University and Egabi Solutions use only

web.xml or
.class ejb-jar.xml
Package

war/ear
Deploy

Application
Server
Test

Copyright © 2009, Oracle. All rights reserved.

Web Service Development Process

The diagram in the slide shows the process for creating a Web service by using the “Java-to-WSDL”
development approach.
The general steps for creating a Web service are:
1. Create a Web service implementation class or a Web service interface with annotations, and
implement the service business logic.
2. Invokes the javac process and generates the .class files for the service implementation bean.
3. Package the artifacts as a WAR (servlet endpoint) or EAR (EJB endpoint) file
4. Deploy the package onto the application server which hosting the JAX-WS run time.
5. Verify the deployment.

JDeveloper MyService.java
Create SEI
OEPE (w/ annotation)

JDeveloper
OEPE Build javac
Ant task web.xml
or

Oracle University and Egabi Solutions use only

JDeveloper .class ejb-jar.xml
OEPE Package
Ant task
JDeveloper war/ear
OEPE Deploy
Ant task
Application
Browser Server
JDeveloper Test
OEPE

Copyright © 2009, Oracle. All rights reserved.

Tools for JWS Development

Oracle offers Web services development tools designed to increase programmers productivity.
• JDeveloper: JDeveloper provides an integrated development environment (IDE) that presents a
graphical user interface (GUI) to develop and deploy different types of Web services, such as
JAX-WS Web services, JAX-RPC Web services, and PL/SQL Web services. JDeveloper also
provides a complete Web services test framework as well as wizard and property support for
building, testing and modifying Web services.
• Oracle Enterprise Pack for Eclipse (OEPE): OEPE is a free set of certified plug-ins, which
enable developers to support Java EE and Web service standards where Eclipse is the preferred
IDE within an organization. It supports development with technologies including Java SE, Java
EE, Web Services, and XML. It installs as a plug-in to your existing Eclipse, or will install
Eclipse for you, and enhances Eclipse's capabilities for Java, Java EE, Spring, Object Relational
Mapping (ORM), and Web services.
• Apache Ant: Ant provides a set of command line tools for dependency based development.
Targets are defined, along with the commands to create them, which can have dependency
relationships with other tasks. Ant then executes the tasks in the correct order to build the
various targets. Ant tasks are used to execute system tools, such as the java compiler, and exist
for Java to WSDL, WSDL to Java, client generation, schema generation and others.

Resources Palette
pane
Application

Oracle University and Egabi Solutions use only

Navigator pane

Code Editor pane

Structure
pane

Property Editor pane

Copyright © 2009, Oracle. All rights reserved.

Creating Web Services by Using Oracle JDeveloper 11g

You can use the Oracle JDeveloper 11g integrated development environment (IDE) to develop Web
services. You can expose any Java resource (such as a Java class or an EJB) as a Web service in
JDeveloper. It also enables you to generate a Web service from a WSDL document and a PL/SQL
package.
The slide displays the JDeveloper IDE. It consists of the Application Navigator pane, Structure pane,
and code editor pane. In the Application Navigator pane, all the resources corresponding to different
applications and projects are displayed. For example, myTest is an application workspace that
contains a single project, HelloWorld. The project further contains all the necessary resources or
artifacts (such as the WSDL document and XSD schema) to develop and deploy a Web service
application.
The Structure pane displays the contents of a specific module within a project. For example, the Web
service module, HelloWorld, contains a list of Java and XML resources, including the WSDL. If you
select the Web service module in the Application Navigator, the entire list of resources
corresponding to the Web service module is displayed in the Structure pane.
Similarly, if you select any of the Web service resources from the Structure pane, the corresponding
code is displayed in the code editor pane. You can edit the code in the code editor pane to implement
your own business logic within the Web service.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 25
Creating Web Services by Using Oracle JDeveloper 11g (continued)
JDeveloper 11g is shipped with WebLogic server 10.3.1. You can directly deploy a Web service
application from JDeveloper to WLS.
In addition, JDeveloper 11g provides a complete Web services test framework, and a comprehensive
WSDL editor. There are also many developer productivity enhancements to the IDE and Java
development features to explore.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 26
Creating a Web Service from a Java Class by
Using JDeveloper
To create a simple Web service from a Java class by using
JDeveloper:
1. Create a Java class.
2. Add the @WebService annotation to the Java class.
3. Build the project—compile and generate artifacts.

Oracle University and Egabi Solutions use only

4. Start a WLS instance.
5. Deploy the project in the WLS instance
6. Verify the deployment:
a. Review the WSDL file in a Web browser.
http://localhost:<WLS_instance_port>/<web_context>/
<class_name>Port?wsdl
b. Use HTTP Analyzer to test the deployed Web service.
c. Via WLS Admin Console

Copyright © 2009, Oracle. All rights reserved.

Creating a Web Service from a Java Class Using JDeveloper

This slide lists the steps for creating a simple Web Service from a Java Class using JDeveloper.
Once you create a Web service, you can use the Http Analyzer of Oracle JDeveloper 11g to test the
Web service. Http Analyzer acts as a SOAP client connecting to a Web service. Using the Http
Analyzer, you can:
• Observe the exact content of the request and response TCP packets of the Web service
• Edit a request packet
• Resend the packet and see the contents of the response packet

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 27
Summary

In this lesson, you should have learned:

• The benefits provided by the Java technology for creating
Web services
• How to describe the core Java APIs for Web Services
• Weblogic Server’s support for Java Web Services

Oracle University and Egabi Solutions use only

• How to create, deploy, and test a simple Web service by
using JDeveloper

Copyright © 2009, Oracle. All rights reserved.

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 2 - 28
Practice 2 Overview:
Developing a Simple Web Service
This practice covers the following topics:
• Creating a JDeveloper Project
• Creating an annotation-based Web Service
• Deploying an application into WebLogic Server from
JDeveloper

Oracle University and Egabi Solutions use only

• Testing the new Web Service within JDeveloper

Copyright © 2009, Oracle. All rights reserved.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Exploring SOAP and WSDL

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe the structure of a SOAP message and the
function of each primary SOAP element
• Describe the messaging models available when creating
SOAP-based Web services

Oracle University and Egabi Solutions use only

• Describe the role that WSDL plays in the Web service
model and the primary elements contained in a WSDL file
• Compare the use of WSDL in document-style and RPC-
style services
• Describe how Java methods mapped to WSDL
• Create a simple WSDL file using JDeveloper

Copyright © 2009, Oracle. All rights reserved.

Objectives
SOAP and WSDL are the core of Web services. This lesson is intended to provide a conceptual
understanding of these two fundamental WS standards.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 2
Basics of XML

Extensible Markup Language (XML):

• Is self-describing
• Is extensible
• Can use a Document Type Definition (DTD) or XML
Schema to formally describe the data

Oracle University and Egabi Solutions use only

• Is used for two different purposes:
– Document-oriented applications
– Data-oriented applications

Copyright © 2009, Oracle. All rights reserved.

Basics of XML
XML is an extensible, non-proprietary, text-based markup language that has become the de facto
standard for data interchange on the Internet and within distributed applications and web services.
• An XML markup language defines a set of tags that are used to organize and describe data.
• XML is self-describing as XML organizes data into a hierarchy, and it describes its
organization directly in the text, so you do not need to look at a separate document that
describes the organization of the data.
• XML allows the author to define their own tags and their own document structure. So you can
extend XML almost limitlessly, defining markup and rules as needed for the kinds of data and
information you use.
• XML uses DTD to define the rules that specify the elements, element formats, and attributes
that are valid in a document instance, as well as the rules defining the relationships between
those elements. The DTD provides a basic grammar for defining an XML document in terms of
the metadata that comprise the shape of the document. An XML Schema provides this, plus a
detailed way to define what the data can and cannot contain.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 3
Basics of XML (continued)
• XML implementations can be divided into two general categories: document-centric and data-
centric:
- Document-centric XML refers to documents intended for human consumption, but which
can still be processed programmatically, and are based on structured or semi-structured
markup. Examples include technical documentation, product catalogs and legal
documents.
- Data-centric XML refers to highly structured XML files intended for machine
consumption rather than human readability. Examples of this kind of XML include
programmatic structures, and data from relational databases.

Oracle University and Egabi Solutions use only

When developing Web Services with XML, it is important to:

• Use namespaces—to interpret the tag in the proper
context
– An attribute=value pair in an XML document
– With syntax: namespace:attribute=URI

Oracle University and Egabi Solutions use only

• Employ XML Schema (XSD)—to validate the integrity of
XML documents
– An XML schema defines the syntax of an XML document.
– XML schema contains a root element called schema and a
sequence of global data type definitions.
– A global data type can be Primitive or Complex.

Copyright © 2009, Oracle. All rights reserved.

XML Namespace and XML Schema

XML Namespace
When duplicate element names exist in a document, the result is a namespace collision. The W3C
namespace specification defines mechanisms for qualifying the names so as to eliminate ambiguity—
that is, provide unique names for all elements and attributes.XML namespace provides a qualified
name for an XML element or attribute.
A namespace is an attribute=value pair just below the prolog in an XML document, and uses the
following syntax:
namespace:attribute=URI
For example, consider the following namespace declaration:
xmlns:java=http://www.javasoft.com/2006/software
To reference a namespace-specific element in your markup, use the following syntax:
<prefix:tagname>content</tagname>
For example, the following defines a prefix (java) and an attribute (JDK) for a namespace-specific
element called JDK:
<java:JDK>Java SE 1.6</java:JDK>

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 5
XML Namespace and XML Schema (continued)
XML Schema
An XML schema is an XML document that defines the syntax of XML documents governed by the
schema. Because all XML schema must follow the rules set out in the primal XML schema, they can
be validated against that schema. It is important for maintaining data quality and integrity when
sharing information among multiple systems. Data types in schemas have two general forms: Simple
and Complex. Simple is a terminal element; complex contains a sequence of child elements.

Oracle University and Egabi Solutions use only

SOAP is at the heart of Web Services interoperable messaging

framework:
• SOAP grounded in XML
– The SOAP message format is defined by an XML schema,
which uses XML namespaces to make SOAP very
extensible.

Oracle University and Egabi Solutions use only

• SOAP carried by HTTP protocol
– SOAP messages can pass through firewalls.
• SOAP supports the transfer of remote procedure calls
(RPC) and document-style information over the Internet.

Copyright © 2009, Oracle. All rights reserved.

SOAP: XML Messaging for Web Services

SOAP was developed to address some of the issues and limitations when passing information
between applications.
SOAP provides a mechanism for exchanging structured and typed information between peers in a
decentralized, distributed environment. SOAP is grounding in XML. The SOAP message format is
defined by an XML schema, which uses XML namespaces to make SOAP very extensible.
Though SOAP supports many network transport protocols in theory, for example, HTTP, SMTP,
JMS, and so on, HTTP is the dominant transport mechanism for Web Services, for several reasons:
understandability, firewall-traversal, and loose coupling.
SOAP is a means for encoding remote procedure calls (RPCs) and document-style information as
XML.

Communication with SOAP includes:

• A request message to the invoked service
• A response message from the invoked service

Oracle University and Egabi Solutions use only

Request
Service
Client

Response Server

Copyright © 2009, Oracle. All rights reserved.

Communication with SOAP

SOAP is used for communication between applications. It hides technology choices and
implementation details from both the service requestor and the service provider. It introduces a self-
describing data representation in XML. By simply looking at the request and response messages, you
can easily find out what was sent as part of a request and what is the response. If the response has a
fault element, then by looking at it, you know what caused the error.
The communication takes place as follows:
1. A client sends a request for a service. This request is a SOAP message and is in the standard
XML format. The request includes information about the recipient of the message and
parameters for successfully invoking the service.
2. The Request Handler invokes the requested service. The service returns a response to the
Request Handler servlet.
3. The Request Handler returns the response of the service to the client. The response includes
return values from the method.
4. If an errors occur while the request is being processed, SOAP fault messages containing fault
codes are returned.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 8
SOAP over HTTP

Request

Response

Oracle University and Egabi Solutions use only

SOAP client Firewall Web server

• HTTP POST is used to handle the SOAP

request/response exchanges.
• HTTP GET requests are issued to retrieve the WSDL
interface definitions from services.

Copyright © 2009, Oracle. All rights reserved.

SOAP over HTTP

A benefit of using SOAP/HTTP messaging is the ability for SOAP messages to pass through
firewalls that exist along the message path.
• This is a common and desirable feature of web services that use HTTP as a transport protocol.
• The inability to seamlessly pass through firewalls has been troublesome for other distributed-
computing infrastructures such as DCOM and CORBA.
HTTP GET requests are issued to retrieve the WSDL interface definitions from services, and HTTP
POST is used to handle the SOAP request/response exchanges. SOAP messages sent over HTTP are
placed in the payload of an HTTP request or response, an area that is normally occupied by form data
and HTML. Since the HTTP GET doesn't have a payload area, it cannot be used to carry SOAP
messages. The HTTP POST request, on the other hand, does have a payload area and is perfectly
suited to carrying a SOAP message.

A SOAP message is an XML Communication

document that consists of: protocol envelope (HTTP)
• Mandatory SOAP envelope
envelope as the
SOAP header
top-level element
Headers
• Optional header

Oracle University and Egabi Solutions use only

• Mandatory body SOAP body
• Optional fault Message name,
data, and
fault element
Mapped to Java
Exceptions

Copyright © 2009, Oracle. All rights reserved.

Basic Structure of SOAP

First-generation XML protocols such as Web Distributed Data Exchange (WDDX) and XML-RPC
rely on XML 1.0 and are not extensible. First-generation protocols stick to a document type
definition (DTD) to describe the data in XML. SOAP is a second-generation XML protocol. It uses
XML schema for data types and is highly extensible. For this reason, you can add any number of
headers to a SOAP message.
The slide shows a SOAP message over HTTP and contains the following elements:
• HTTP headers: When SOAP is used over HTTP, the packet starts with an HTTP header,
which contains information about the operation, method, content-type, content-length, error
codes, and recipient of the message.
• SOAP envelope: The envelope is the top-level element in the document.
• SOAP header: The header element is optional. It is included to add features to a SOAP
message without prior agreement between the communicating parties. A header can, in turn,
have any number of headers. These headers are included to provide additional information that
is handled by infrastructure services. In a real-world scenario, login information, session
information, security information, transactional information, and other information types can be
included in the body; however, this approach makes the SOAP message more complicated.
Instead, this information can be included as multiple headers.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 10
Basic Structure of SOAP (continued)
• SOAP body: The body element is a mandatory element that contains information for the
recipient of the message.
• SOAP fault: The body element can contain an optional fault element to report errors.
A SOAP application should include proper SOAP namespaces on all elements defined in messages.
SOAP messages should not contain Document Type Declaration (DTD) and Processing Instructions
(PI).

Oracle University and Egabi Solutions use only

<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/ SOAP
envelope/" namespace
Xmlns:ns="http://mypackage/">
Request

Application
<soap:Body>
<ns:add> namespace
<num1>1</num1> SOAP
<num2>1.1f</num2> Operation
</ns:add> (RPC style)

Oracle University and Egabi Solutions use only

</soap:Body>
</soap:Envelope>

<soap:Envelope ...
xmlns:ns="http://mypackage/">
Response

<soap:Body>
<ns:addResponse>
<result>2.1</result>
</ns:addResponse>
</soap:Body>
</soap:Envelope>

Copyright © 2009, Oracle. All rights reserved.

SOAP Messages: Example

The example in the slide shows SOAP request and response messages. They are associated with a
Web service operation add, which adds two numbers (an integer type and a float type) and returns the
result (as a float type).
Request: The SOAP request message has an envelope element, defined as
<soap:Envelope>. The <soap:Body> element contains the actual message to be sent to the
recipient. The <ns:add> element clearly indicates that the request is to add two numbers. The two
numbers are represented as <num1> and <num2> elements that take an integer value and a float
value, respectively.
Response: The response message begins with the <soap:Envelope> element. The
<soap:Body> element contains the response for the client. The <result> element is the return
type of the add method. In the response message shown, <result> has a value of 2.1, which is the
summation of <num1> and <num2>.
Observe that the messages do not have a Header element, but still are valid SOAP messages, because
Header is an optional element.

Oracle University and Egabi Solutions use only

Request Response

Copyright © 2009, Oracle. All rights reserved.

Examining SOAP Messages Using the HTTP Analyzer

You can use the Http Analyzer of Oracle JDeveloper 11g to examine the SOAP messages of a client
(or proxy) connecting to a Web service. Using the Http Analyzer, you can:
• Observe the exact content of the request and response packets of the Web service
• Edit a request packet
• Resend the packet and see the contents of the response packet
The slide displays an example of using the Http Analyzer to examine the SOAP request and response
messages when the add operation for a Web service is invoked.
Note: By default, the Http Analyzer opens in History mode. It this mode, you can view information
such as date, call time, HTTP method (POST or GET), and URL, relating to different aspects of
communication between a client and a Web service. You have to select a particular communication
to view its details in Data mode, as shown in the slide.

• A message format is defined by its:

– Messaging style: RPC or Document
– Encoding style: SOAP or Literal encoding
• SOAP supports four modes of messaging:
– RPC/Literal

Oracle University and Egabi Solutions use only

– RPC/Encoded—not WS-I compliant
– Document/Literal
– Document/Encoded—not WS-I compliant, and nobody uses
it

Copyright © 2009, Oracle. All rights reserved.

SOAP Message Formats

A messaging mode is defined by its messaging style (RPC or Document) and its encoding style.
You can characterize a Web service by the information or messaging model that the service
implements. The data or information model describes the type of data, contained within the
messages, that is passed between a service and service client during a Web service interaction. There
are two basic information or messaging models: document-style and RPC-style (also known as a
parameter-style).
• A RPC-style Web service responds to a request submitted as an XML-formatted procedure call
with parameters. The Web service executes the procedure call specified by the request and
returns the result to the service client.
• A document-style service uses the information contained within a document to determine how
to process a specific request. For example, a travel booking service client might present a user
with a form that collects a set of trip information from the user, such as start and end dates,
destination, itinerary, method of travel, and lodging preferences. When the client submits this
information in document form to the booking service, the service determines how to process the
request by parsing the document, and interpreting some or all of the request information.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 14
SOAP Message Formats (continued)
The SOAP envelope, header, and body offer a lot of flexibility in expressing message information.
However, for general purposes in SOAP messaging there is a need for commonly understood
encoding rules that address questions of data representation to assure that a message recipient will
correctly interpret the data contained in a service request. RPC-style services, in particular, require
strict set of encoding rules.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 15
Quiz

A SOAP message typically consists of:

1. A SOAP header, message body, and one or more
attachments
2. A SOAP header, message body, and one or more
message headers

Oracle University and Egabi Solutions use only

3. A SOAP header and a SOAP body containing a message

Copyright © 2009, Oracle. All rights reserved.

Answer: 3

<soap:Envelope ... >

<soap:Body ... >
RPC/encoded <add>
<a xsi:type="xsd:int">3</a>
<b xsi:type="xsd:float">3.0</b>
</add>
</soap:Body>

Oracle University and Egabi Solutions use only

</soap:Envelope>

RPC/literal <soap:Envelope ... >

<soap:Body ... >
<add>
<a>3</a>
<b>3.0</b>
</add>
</soap:Body>
</soap:Envelope>

Copyright © 2009, Oracle. All rights reserved.

RPC-Style SOAP Message Structure

RPC/encoded
In case of RPC-style services, the parameters and return values appear inside a wrapper of the SOAP
body. The wrapper name is the name of the operation (in this case, add). The important thing to
notice about the RPC/encoded style is that the SOAP body consists of the information about the
method parameters, and also about their type defined in the WSDL document. The operation name
appears in the message, so the Web service client can easily send the message to the implementation
of the operation. RPC/encoded SOAP messages are not WS-I compliant. This style is usually used
for data graphs.
Note: The prefixes used in the example above are defined with the following namespaces:
• xmlns:xsd="http://www.w3.org/2001/XMLSchema
• xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 17
RPC-Style SOAP Message Structure (continued)
RPC/literal
RPC/literal messages are like RPC/encoded messages, except that the type encoding information is
eliminated. The RPC/literal format uses the RPC style of message payload structure but supports a
literal way of describing the types passed by a method. It means there exists a schema for every
parameter type but not for the payload of the message body itself. RPC/literal messages are WS-I
compliant.
The drawback of RPC-Style messages is they cannot be easily validated. Because the data typed are
defined in a schema/schemas, but the rest of the soap:body contents comes from WSDL definitions.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 18
Document-Style SOAP Message Structure:
document/literal
document/literal
<soap:Envelope ... >
<soap:Header>
<bElement>3.0</bElement>
</soap:Header>
<soap:Body ... >
<aElement>3</aElement>

Oracle University and Egabi Solutions use only

</soap:Body> ...

Copyright © 2009, Oracle. All rights reserved.

Document-Style SOAP Message Structure: document/literal

For document/literal style Web services, the SOAP message directly appears under the
<soap:Body> element without any additional wrappers. The SOAP message consists of no type
encoding information, so it can be validated with any XML validator. But the operation name is lost
in the message, which makes the dispatching difficult. The type encoding information is defined as
an element in the WSDL document, which will be visited later in this lesson.
The Document/literal messages are WS-I compliant, and the WS-I specification allows only one
child of the <soap:Body> element in a SOAP message. Therefore, the method that needs to be
exposed as a Web service operation can have only one parameter mapped to the SOAP body. If the
method has multiple parameters, then only one can be mapped to the body part and the other
parameters must be mapped to SOAP headers.

<soap:Envelope ... >

<soap:Body ... >
<addElement>
<aElement>3</aElement>

Oracle University and Egabi Solutions use only

<bElement>3.0</bElement>
</addElement>
</soap:Body> . . .

Copyright © 2009, Oracle. All rights reserved.

Document-Style SOAP Message Structure: document/wrapped

With document/literal, you can validate the message, but you lose the operation name. A new pattern
called document/literal wrapped, also known as document/wrapped, emerged to address this issue.
With document/wrapped service, the entire SOAP message structure is defined within the schema in
the WSDL document. The schema defines a wrapper element wraps the parameters within the
<soap:Body> element of the SOAP message. In the example, addElement is the wrapper element
defined in the WSDL document. This is different from the example of the RPC/literal SOAP
message, the <add> child of <soap:body> is the name of the operation. The benefits of using this
message style are:
• You have the method name in the SOAP message.
• Everything that appears in the soap:body is defined by the schema, so you can easily validate
this message.
The document/wrapped operation style Web services are WS-I compliant because they meet the WS-
I restriction that the <soap:Body> element of the SOAP request message can have only one child.
This Web service operation style also gives you the liberty to define any number of method
parameters for a particular method to be exposed as a Web service operation.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 20
SOAP Attachment

SOAP Message with

Attachment SOAP envelope

Header

Body
Primary MIME Part

Oracle University and Egabi Solutions use only

SOAP attachment

Graphic
SOAP attachment

Copyright © 2009, Oracle. All rights reserved.

SOAP Attachment
A SOAP message can include documents and file types that are otherwise difficult or inefficient to
encode as XML, such as graphics or database files, as SOAP attachments. SOAP attachments are
treated as secondary components of a SOAP message that are referenced by using a URI.
Diagram above illustrates the structure of a SOAP message that includes attachments. Using
attachments, certain information sets can travel along with the SOAP envelope, as MIME-type
attachments, rather than embedded in the SOAP body as XML. This is a useful feature especially
when passing medium to large quantities of binary-encoded information, such as images and sound
waves and other digitally sampled data.
The Web Services community have adopted SOAP Messages with Attachments (SwA) specification
to provides a mechanism to attach binary data to a SOAP message without converting binary data to
ASCII characters using Base64 encoding.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 21
WSDL

• A WSDL document describes:

– What the service does WSDL document
– How the service is accessed
– Where the service is located Types

• It defines the messages and

Messages

Oracle University and Egabi Solutions use only

the operations of a service
abstractly in XML.
Port types

Bindings

Services

WSDL document structure

Copyright © 2009, Oracle. All rights reserved.

WSDL
SOAP provides a standard way of transporting messages for use by Web services, whereas WSDL
provides a standard way to describe Web services. WSDL uses the XML format for describing Web
services. It describes what functionality a Web service offers, how it communicates, and where it is
accessible. Because WSDL is in the standard XML format, the services developed can easily be
made available to thousands of users. Users must invoke the correct services with the appropriate
parameters. WSDL defines an XML grammar to specify the location of the service and to describe
the operations of a service.
A WSDL document describes a Web service by using these major elements:
• <types>: Defines the data types used by the Web service
• <message>: Describes the payload of a message used by a Web service
• <portType>: Describes a Web service, the operations that can be performed, and the messages
that are involved
• <binding>: Defines the communication protocols used by the Web service
• <service>: Describes the name and location of the Web service and the context with which it
can be accessed
Note that types, message and portType are abstract types which are then used in bindings and
services in much the same way an instance of a java class represents a java class.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 22
WSDL Model

XML Elements
Definition
attributes
targetNamespace

Types Message PortType Binding Service

name name name name
type

Oracle University and Egabi Solutions use only

Schema Part Operation SOAPBinding Port
name name style name
transport binding

Input
message
Address
Element
Output location
name message
type
What How Where

Abstract Concrete

Copyright © 2009, Oracle. All rights reserved.

WSDL Model
The slide shows a structural model of the WSDL specification. The most important parts are:
• Element: Elements are defined with in the <types> tag. An element consists of a unique name,
and data type. An element describes the data and defines the tag which delimits the data sent in
the message parameters. Elements can be simple types such as strings or integers. Simple Types
can have enumerations (lists of acceptable values) or restrictions defined (length not to exceed
10 characters). In addition, elements can have complex types. Complex types can nest other
elements with in them.
• Message: The message describes the structure of the information that will be sent and received
when calling an operation. Each message consist of one or more logical parts. Each part is
associated with a message-typing attribute, usually a previously defined element.
• Operation: Each operation can be compared to a method or function call in a traditional
programming language. Here the SOAP actions are defined and the way the message is
encoded for example, “literal.”
• Port Type: The port type defines a web service, the operations that can be performed, and the
messages that are used to perform the operation.
• Binding: Specifies the port type, defines the SOAP binding style (RPC/Document) and
transport (SOAP Protocol). The binding section also defines the operations.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 23
WSDL Model (continued)
• Port: The port does nothing more than define the address or connection point to a web service.
This typically is a represented by a simple HTTP URL string.
• Service: The service can be thought of as a container for a set of system functions that have
been exposed to the web based protocols.

Oracle University and Egabi Solutions use only

<?xml version='1.0'?>
2 <definitions targetNamespace=“urn:Math”
xmlns=“http://schemas.xmlsoap.org/wsdl/”
xmlns:sxd=“http://www.w3.org/2001/XMLSchema”
xmlns:soap=“http://schemas.xmlsoap.org/wsdl/soap/”>

7 <types/>
8 <message name='MathRequest'>

Oracle University and Egabi Solutions use only

9 <part name='x' type='xsd:double'/>
10 <part name='y' type='xsd:double'/>
11 </message>
12 <message name='MathResponse'>
13 <part name='return' type='xsd:double'/>
14 </message>
15

Copyright © 2009, Oracle. All rights reserved.

A Basic WSDL Document

WSDL namespace
The WSDL specification defines several namespaces for use in descriptors. The example shows the
primary WSDL namespace URI:
http://schemas.xmlsoap.org/wsdl/
WSDL gives messaging protocol bindings their own namespaces. The example shows the SOAP
binding namespace, commonly prefixed SOAP:
http://schemas.xmlsoap.org/wsdl/soap/
Types
WSDL adopts XML schema built-in types. The types element serves as a container for defining any
data types that are not described by the XML schema built-in types, such as complex types. In this
case, the types element is not used because the message definitions MathRequest and MathResponse,
refer to simple built-in types.
Message
The message element describes the payload of a message that are directly sent to or received from a
Web service. The way to define a message element depends on whether you use RPC-style or
document-style messaging.

16 <portType name='Math'>
17 <operation name='Add' parameterOrder='x y'>
18 <input message='tns:MathRequest'/>
19 <output message='tns:MathResponse'/>
20 </operation>
21 ...
22 </portType>
23

Oracle University and Egabi Solutions use only

24 
25
26 <service name='MathService'>
27 <port name='Math' binding='tns:MathBinding'>
28 <soap:address location=
29 'http://localhost:7071/Math-context-root/MathPort'/>
30 </port>
31 </service>
32
33 </definitions>

Copyright © 2009, Oracle. All rights reserved.

A Basic WSDL Document (continued)

portType
In WSDL, services are modeled as collections of ports. Each port has a portType. The port type is
much like an interface declaration in EJB. A portType is composed of operations, the “methods” of
the portType. In WSDL the portType is implemented by the binding and service elements, which
dictate the protocols, encoding schemes, and an Internet address used by a Web service
implementation.
Service
The service element contains one or more port elements, each of which represents a different Web
service. The port element assigns the URL to a specific binding.
Binding element will be discussed later in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 26
Defining the Structure of Content in the SOAP
Body
The structure of the content of the SOAP body is defined by
XML schema type definitions:
• Declared explicitly in WSDL
• Imported from an XML Schema Definition (XSD), as the
preferred approach for document/literal encoding
style

Oracle University and Egabi Solutions use only

<schema>
XML schema <complexType name="hellostr">
...

<import...>
Shared
<message name="helloReqest">
Other WSDL <part ... element="ns:hellostr"/>
services </message>

Copyright © 2009, Oracle. All rights reserved.

Defining the Structure of Content in the SOAP Body

The structure of the content of the SOAP body is:
• Defined in WSDL by associating a <message> element with an XML schema type. A
<message> element (defined in the WSDL) is associated with a SOAP request message, the
<input> element, or a SOAP response message, the <output> element. The <input> element
and the <output> element are defined in the <operation> element contained in the <portType>
element of the WSDL.
• Based on XML type definitions in a <schema> element nested in a WSDL <types> element,
which can:
- Declare XML schema type definitions explicitly
- Import XML schema type from an XML Schema Definition (XSD)
By using an XSD to declare XML types, the XSD can be:
• Shared across cooperating services
• Used as a single source to validate XML message structures by different services
• Maintained in one location to propagate changes across services by using the same message
structures

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 27
WSDL Binding

The binding element maps a portType to a set of:

• Network protocols such as SOAP, MIME
• Messaging styles: RPC or document
• Encoding styles: Literal or SOAP Encoding

Oracle University and Egabi Solutions use only

WSDL Binding
The binding element, and its subelements, are used in combination with protocol-specific elements.
The binding elements identify which portType and operation elements are being bound, while the
protocol-specific elements declare the protocol and encoding style to be associated with the
portType.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 28
WSDL Styles

Web Services support several specific types of binding

combinations:
• RPC/Encoded: Operations and parameters are defined in WSDL.
Operations and parameters are specified in SOAP, along with types.
• RPC/Literal: Operations and parameters are provided with the
WSDL. Operations and parameters are specified in SOAP but

Oracle University and Egabi Solutions use only

without type.
• Document/encoded: Only used for backwards compatibility,
otherwise unused
• Document/literal: Operation and parameters in WSDL; operation
name not specified in SOAP message, nor type information
• Document/wrapped (a special type of document/literal): Similar
to document/literal where WSDL defines all messages and
parameters, but SOAP messages also include method and
parameter information

Copyright © 2009, Oracle. All rights reserved.

WSDL Styles
There four styles of WSDL definitions, specifically:
• RPC/Encoded: In RPC/Encoded the method names, and parameters are defined in the WSDL.
But the SOAP message itself has typing information. For example a type=e “xsd:xxx” attribute
is provided for each parameter. This bloats the SOAP message and often makes the WSDL not
WS-I compliant. For the most part RPC/Encoded is ignored in favor of RPC/literal.
• RPC/Literal: In RPC/Literal the method and parameters in the WSDL are effectively the same
as those in RPC/encoded however the SOAP messages themselves do not contain typing
information. One of the strengths of RPC/Literal is its compliance with the WS-I basic profile.
One of the weaknesses of RPC/Literal is that the message cannot be validated based on the
SOAP content itself.
• Document/encoded: Document/encoded exists for historical purposes and should not be used
unless you are require backward compatibility.
• Document/literal: In Document/literal the WSDL defines the methods and parameters, but the
SOAP message does not contain method information, just parameter information. Because of
the extensive typing in the WSDL Document/literal can be validated.

Oracle University and Egabi Solutions use only

</operation>
</portType>

<binding .../> --------- Binding is RPC/literal

<soap:Envelope ... >

<soap:Body ... >
RPC/literal <add>
<a>3</a>
<b>3.0</b>
</add>
</soap:Body>
</soap:Envelope>

Copyright © 2009, Oracle. All rights reserved.

RPC/literal Message WSDL

In RPC/Literal, the method, parameters, and their type are all defined in the WSDL. The SOAP
messages themselves do not contain typing information.

Oracle University and Egabi Solutions use only

</message>
...

<binding .../> --------- Binding is document/literal

<soap:Envelope ... >

SOAP <soap:Header>
message <bElement>3.0</bElement>
</soap:Header>
<soap:Body ... >
<aElement>3</aElement>
</soap:Body> ...

Copyright © 2009, Oracle. All rights reserved.

document/literal Message WSDL

With document/literal services, the WSDL document is a bit more complicated when
compared with the WSDL documents of RPC/encoded and RPC/literal services. The type
information of the method parameters is exposed as an XML schema.
The Document/literal messages are WS-I compliant, and the WS-I specification allows only
one child of the <soap:Body> element in a SOAP message. Therefore, the method that needs to be
exposed as a Web service operation can have only one parameter mapped to the SOAP body. If the
method has multiple parameters, then only one can be mapped to the body part and the other
parameters must be mapped to SOAP headers. For example, you have to modify the WSDL
document as follows:
<definitions ...>
<types>
<schema ...>
<element name="aElement" type="int"/>
<element name="bElement" type="float"/>
<element name="cElement" type="string"/>
</schema>
</types>
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 31
document/literal Message WSDL (continued)
<message name="addRequest">
<part name="param1" element="aElement"/>
<part name="param2" element="bElement"/>
</message>
<message name="addResponse">
<part name="result" element="cElement"/>
</message>
<portType name="docLiteral">
<operation name="add">

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 32
document/literal Message WSDL (continued)
<binding name="docLiteralSoapHttp" type="docLiteral">
<soap:binding style="document" ... />
<operation name="add">
<soap:operation soapAction="http://literal2//add"/>
<input>
<soap:header message="addRequest" part="param2"
use="literal"/>
<soap:body use="literal" parts="param1"/>
</input>

Oracle University and Egabi Solutions use only

Oracle University and Egabi Solutions use only

<message name="addRequest">
<part name="parameters" element="addElement"/>
</message>
...

<binding .../> --------- Binding is document/literal

SOAP <soap:Envelope ... >

<soap:Body ... > Wrapper
message
<addElement>
<aElement>3</aElement>
<bElement>3.0</bElement>
</addElement> ...

Copyright © 2009, Oracle. All rights reserved.

document/wrapped Message WSDL

With document/wrapped services:
• The entire SOAP message structure is defined within the schema and can be validated with any
XML validator.
• The schema definition of a wrapper element wraps the parameters that belong to a method. For
example, the <addElement> element that is defined in the schema in the WSDL document
wraps the method parameters within the <soap:Body> element of the SOAP request message.
• The messages are not SOAP encoded and do not use SOAP RPC conventions.
• The input message consist of a single part that is defined as an element in the WSDL document.

<binding name="MathBinding" type="tns:Math">

<soap:binding
transport="http://schemas.xmlsoap.org/soap/http"
style="rpc"/>
<operation name="add">
<soap:operation soapAction=""/>
<input>
<soap:body use="literal"

Oracle University and Egabi Solutions use only

namespace="http://ws.library.com/"/>
</input>
<output>
<soap:body use="literal"
namespace="http://ws.library.com/"/>
</output>
</operation>
</binding>

Copyright © 2009, Oracle. All rights reserved.

An Example with SOAP Binding

This example shows the WSDL file with SOAP binding.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 35
Quiz

Which of the following are abstract elements in a WSDL

document?
1. Bindings
2. Services
3. Bindings and services

Oracle University and Egabi Solutions use only

4. Types and messages
5. Types, messages, and portTypes
6. All of the above

Copyright © 2009, Oracle. All rights reserved.

Answer: 5

The main steps for creating a WSDL file using JDeveloper’s

WSDL Editor:
1. Create or import an XSD .
2. Create a WSDL Document type of Web service in your
project with the Create portType option selected.

Oracle University and Egabi Solutions use only

3. A default portType’s operation placeholder is created for
you; add input and output elements.
4. Create a SOAP binding by using the Binding component in
the Component Palette.
5. Create a Service by using the service component in the
Component Palette.

Copyright © 2009, Oracle. All rights reserved.

Steps for Creating a WSDL File Using JDeveloper

JDeveloper includes an WSDL Editor, which is a specialized schema-driven editor for editing WSDL
documents. The WSDL Editor is integrated with the Application Navigator and the Structure
window. You can edit the WSDL document by creating new elements here or in the Structure
window, and by dragging elements from one type to another.
The main steps to create a WSDL document using WSDL Editor are:
1. Create or import a XSD if there is one
2. Create a WSDL Document type of Web service in your project with Create portType option
selected
3. A default portType’s operation placeholder is created for you, add input and output elements
4. Create a SOAP binding by using the Binding component in the Component Palette
5. Create a Service by using the service component in the Component Palette

Component
Palette

Oracle University and Egabi Solutions use only

Property Editor

Copyright © 2009, Oracle. All rights reserved.

Creating a WSDL File Using JDeveloper

If you are new to working with WSDL documents, you might find it useful to relate WSDL terms to
their Java equivalents:
• Service is equivalent to class
• Port type is equivalent to interface
• Operation is equivalent to method
• Message is equivalent to parameter(s) (there could be multiple parts)
When creating a WSDL, you start with portType first, adding operations and its sub-element from
the Component Palette to the Port Types pane, and making changes in the associated property editor.
The message elements will be automatically generated based on the portType you create, and you
can make customization to them.

Oracle University and Egabi Solutions use only

Creating a WSDL File Using JDeveloper (continued)

The figure shows the structure of Message, portType, Binding and Service elements, and how they
are linked to each other.

WSDL:
...
<message name="addRequest"> 2
<part name="param1" type="xsd:int"/>

Oracle University and Egabi Solutions use only

<part name="param2" type="xsd:float"/>
</message> a
...
<portType name="MyWebService">
<operation name="add">
<input message="ns:addRequest"/>
...
</operation>
</portType> b
...

Copyright © 2009, Oracle. All rights reserved.

Mapping of a Java Method to WSDL

JAX-WS defines the default mappings between Java methods/parameters and WSDL artifacts. JAX-
WS provides a way to override default mapping behaviors via customization binding mechanism.
The above example shows how to expose a Java method as a Web service by providing its abstract
description in a WSDL document.
1. The add Java method that takes two parameters is defined: param1 of the int type and
param2 of the float type.
2. A part of the WSDL document that describes the abstract description of the add method (or the
add Web service operation).
a. Defines the <message> element that is associated with the input parameters of the add
operation. The two <part> elements signify that the add operation takes two parameters,
param1 and param2 of the types int and float, respectively.
b. Describes the Web service that consists of one operation, namely, add. The operation
further contains the <input> element that refers to the message part defined in the
previous step.

WSDL:
3
...
<binding name="MyWebServiceSoapHttp" ... >
<soap:binding style="rpc" ... />
<operation name="add">

Oracle University and Egabi Solutions use only

<soap:operation ... />
<input>
<soap:body use="encoded" ... />
</input>
...
</operation>
</binding>
...

Copyright © 2009, Oracle. All rights reserved.

Mapping of a Java Method to WSDL (continued)

3. Displays the binding part of the WSDL document. The <binding> element defines the structure
of the SOAP message that is used for communication between the Web service and the Web
service client. It consists of the <soap:binding> element that specifies the style attribute as rpc.
It also defines the <soap:body> element that specifies the use attribute as encoded.
Note: The style attribute is set to rpc for RPC-style Web services and document for document-style
Web services. If the style attribute is not declared in the <soap:binding> element, then document is
the default style.

One-way messaging

Service
Sender SOAP message

Receiver

Oracle University and Egabi Solutions use only

Request/response messaging

Request
Service
Sender

Response Receiver

Copyright © 2009, Oracle. All rights reserved.

WSDL Messaging Exchange Patterns

Most Web services today use two message exchange patterns (MEPs), One-Way and
Request/Response messaging, and they’re the only MEPs that can be used with Java EE Web
Services. In the former, SOAP messages travel in only one direction, from a sender to a receiver. In
the latter, the sender sends a SOAP request message and expects a reply from the receiver.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 42
Summary

In this lesson, you should have learned:

• The basic structure of a SOAP message and the function
of each primary SOAP element
• The messaging models available when creating SOAP-
based Web services

Oracle University and Egabi Solutions use only

• The role that WSDL plays in the Web service model and
the primary elements contained in a WSDL file
• How to use WSDL to describe document-style and RPC-
style services
• The mappings between Java methods and WSDL
• How to create a simple WSDL file using JDeveloper

Copyright © 2009, Oracle. All rights reserved.

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 3 - 43
Practice 3 Overview:
Creating WSDL-Based Contracts
This practice covers the following topics:
• Creating a WSDL file
• Adding an operation to a WSDL file

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe the features of JAX-WS 2.1
• Illustrate JAX-WS run-time architecture of a service
endpoint
• Describe the benefits of using coarse-grained interface for

Oracle University and Egabi Solutions use only

designing Web services
• Implement Web services using POJOs
• Implement Web services using EJBs
• Implement Web services that send and receive XML
messages directly using Provider APIs
• Describe the procedure of implementing Web services
from a WSDL document

Copyright © 2009, Oracle. All rights reserved.

Key features of JAX-WS 2.1 include:

• Data binding using JAXB 2.1
• Document attachments using Message Transmission
Optimized Mechanism (MTOM)
• Operate on messages at the XML level

Oracle University and Egabi Solutions use only

• XML catalogs
• XML-based customizations
• Asynchronous invocation

Copyright © 2009, Oracle. All rights reserved.

JAX-WS 2.1 Features

JAX-WS is the very soul of Java EE Web Services. The key features of JAX-WS 2.1 include:
Data binding using JAXB 2.1
JAX-WS 2.1 fully supports the JAXB 2.1 specification (http://jcp.org/en/jsr/detail?id=222) and
provides full XML Schema support. JAXB provides a convenient way to bind an XML schema to a
representation in Java code. This makes it easy for you to incorporate XML data and processing
functions in applications based on Java technology without having to know much about XML itself.
Document attachments using Message Transmission Optimized Mechanism (MTOM)
The MTOM feature allows you to specify a Web Service to use a streaming API when reading
inbound SOAP messages that include attachments, rather than the default behavior in which the
service reads the entire message into memory. This feature increases the performance of Web
Services whose SOAP messages are particularly large.
Operate on messages at the XML level
The JAX-WS Provider and Dispatch APIs enable the Web Service to operate at the XML message
level, accessing the XML payloads directly.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 3
JAX-WS 2.1 Features (continued)
XML catalogs
JAX-WS provides support for XML Catalogs as defined by the OASIS XML Catalogs 1.1
specification. All of the JAX-WS APIs and annotation that take a WSDL URI use the XML Catalogs
to resolve the WSDL document’s location. If your WSDL documents have imported external
schemas, an XML Catalog lets you map external references to imported schemas to local instances of
such schemas.
XML-based customizations
The JAX-WS 2.1 specification defines standard and portable XML-based customizations. These
customizations, or binding declarations, can customize almost all WSDL components that can be
mapped to Java, such as the service endpoint interface class, method name, parameter name,
exception class, and so on. Using binding declarations you can also control certain features, such as

Oracle University and Egabi Solutions use only

asynchrony, provider, wrapper style, and additional headers.
Asynchronous invocation
JAX-WS adds asynchronous support to the invocation model defined by JAX-RPC. This is a big step
forward for enterprise Java, since asynchrony is a fundamental requirement for SOA.

Client

Handles context Via JAX-B

and policy

Web

Oracle University and Egabi Solutions use only

Service
SOAP SOAP
Request Endpoint Java/XML SEI
Protocol
Servlet Binding
Binding
Other
classes
SOAP
Response
JAX-WS Run-time services

Copyright © 2009, Oracle. All rights reserved.

Server-Side JAX-WS Run Time

The endpoint servlet is part of the internal Java EE 5 implementation of JWS. This wrapper servlet
class is responsible for dispatching SOAP requests to the service endpoint.
JAX-WS specifies a SOAP binding for SOAP message processing. The SOAP binding maps handler
and service exceptions to SOAP fault messages. The SOAP binding also supports SOAP handlers for
SOAP header processing.

• Service granularity:
– Is a measure of the number of operations, amount of
processing done, and message size
– Is a trade-off between network latency and usability
• Fine-grained services tend to have:

Oracle University and Egabi Solutions use only

– Many operations, with shorter processing requirements
– Smaller message sizes
• Coarse-grained services are designed with:
– Fewer operations having longer processing requirements
– Larger message sizes

Copyright © 2009, Oracle. All rights reserved.

Service Granularity
Ultimately, a good Service-Oriented Architecture (SOA) should expose the right services that do the
right things, and be less concerned about granularity. Granularity can also be seen as measure of the
interaction between a service consumer and provider to address the business requirements. Fine-
grained services perform smaller tasks and process smaller quantities of data. A coarse-grained
service performs larger tasks on more data in a given interaction.
Fine-grained services generally:
• Provide many operations
• Execute smaller processing tasks
• Exchange smaller message sizes
• Require many calls which, when called remotely, can degrade performance a lot, due to higher
communication overhead
Coarse-grained services generally:
• Expose fewer operations
• Execute a larger amount of processing
• Exchange larger messages structures for operation request and response values
• Require fewer calls to do the same amount of work, which lessens the communication overhead
• Provide more business value than fine-grained services

Coarse-grained interfaces:
• Pass as much useful data as needed for each request
• Return as much useful data as needed with each response
• Define all messages structures using an XML schema to
define complex data types for requests and responses

Oracle University and Egabi Solutions use only

• Limit the number of operations to the fewest possible,
while observing the business requirements and service
contract definition

Object Components Web Services

Fine-grained Coarse-grained
interfaces interfaces

Copyright © 2009, Oracle. All rights reserved.

Designing Coarse-Grained Interfaces

The level of granularity for services depends on its business purpose and interface requirements.
Generally, a Web service tends to have a coarser granularity compared to components, which in turn
are coarser than objects. A coarse-grained service exposes a single business process.
Coarse-grained interfaces are recommended for externally exposed services, enabling:
• Web services to be less “chatty”
• Network overhead and performance to be improved due to fewer invocations
• Client design and development to be simplified
Fine-grained services are useful for internal services that support larger services to address business
process requirements.
Note: Useful data means data that may be needed by a client, or what is needed by a service to
perform the tasks defined by business requirements and its contract (interface). Be pragmatic to find
a balance between the amount of data exchanged and the number of operations needed. In general,
the number invocations executed has a higher overhead than the message sizes. It is best practice to
use an XML schema design data types for service operation requests and responses.

Server
• SEI
– POJO-based Bottom-up
– Using EJB 3.0
• Provider API

Oracle University and Egabi Solutions use only

Contract-first
• Starting from WSDL
Client
• Dynamic proxy client
• Dispatch API
• Starting from WSDL

Copyright © 2009, Oracle. All rights reserved.

JAX-WS Development Model

There are two sides of the JAX-WS model: client-side and server-side.
Server-side
JWS defines two ways of implementing a Web Service endpoint. The first, based on the Java class
programming model, is implemented by a Java class running in a web container. The second is based
on the EJB programming model - the web service is implemented as a stateless session bean running
in an EJB container.
JAX-WS supports two different service endpoint implementations types, the standard Web service
endpoint interface and a new Provider interface to enable services to work at the XML message level.
Besides the bottom-up approaches, you can also use the “Start from WSDL” or contract-first
development mode. Using this approach, you create or take a existing WSDL and use the WSDL
compiler to generate a set of Java program artifacts that implement the WSDL.
This lesson discusses how to implement Web Services (server-side) use the approaches listed in the
slide.
Client-side
JAX-WS client programming model supports the Dispatch client API and the Dynamic Proxy client
API.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 8
Steps for Implementing Web Services Using
POJOs
1. Add the annotations to the Java class and the optional
service endpoint interface.
2. Compile the endpoint implementation class or Service
Implementation Bean (SIB).
3. Generate portable artifacts required for Web service
execution (optional).

Oracle University and Egabi Solutions use only

4. Assemble the artifacts for your Web service as a WAR file.
5. Deploy the WAR file into the application server.

Copyright © 2009, Oracle. All rights reserved.

Steps for Implementing Web Services Using POJOs

For a JAX-WS service endpoint, the service endpoint interface or service endpoint implementation is
a Java interface or class, respectively, that declares the business methods provided by a particular
Web service.
When developing JAX-WS Web services starting from a Java class, you can expose the Java class as
a JAX-WS Web service by using @WebService annotations. In addition to annotating the Java
class and the optional service endpoint interface, you must compile and assemble all the artifacts that
the Web service requires, and deploy the resulting application into the application server
environment to complete the process of enabling the Java class as a Web service.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 9
Using Annotations

Rules of using annotations:

• You can annotate methods, types, fields, and parameters
in your Java class to specify a Web service.
• By default, all public methods in a class that specifies the
@WebService annotation are exposed in the Web service.

Oracle University and Egabi Solutions use only

• Specify the @WebMethod annotation on each method that
you want to customize for the service, such as excluding a
method from your service.
• Specify the @WebParam annotation on method parameters
to customize name mapping, namespace, mode, and other
properties.
• Specify the @WebResult annotation on return values to
customize name, namespace, and other properties.

Copyright © 2009, Oracle. All rights reserved.

Using Annotations
Using annotations, the service endpoint implementation can independently describe the Web service
without requiring a WSDL file. Annotations can provide all of the WSDL information necessary to
configure your service endpoint implementation or Web services client.
You can annotate methods, types, fields, and parameters in your Java class to specify a Web service.
@WebMethod annotation is applicable for public methods in a SEI, or in a service implementation
class. @WebMethod annotation is only supported on classes that have the @WebService
annotation. All public methods are treated as exposed, even if the @WebMethod annotation is not
specified. When you use the @WebService annotation, several rules control how methods are
exposed in your Web service and how you can use the @WebMethod annotation:
• If the @WebService annotation of an implementation class refers to a SEI, the
implementation class cannot have @WebMethod annotations.
• In an SEI or in an implementation class that does not refer to an SEI, if a @WebMethod
annotation has an attribute of exclude=true, the method is not exposed.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 10
Using Annotations (continued)
On the methods that are exposed in your Web service, use the @WebParam and @WebResult
annotations to customize the mapping of your parameters and results to message parts and XML
elements.
• @WebParam: Associates a SEI method’s parameter with a particular wsdl:part (rpc style) or a
wrapper child of a particular wsdl:part’s element definition (document style). In either case, the
@WebParam associates a Java representation of a parameter with the WSDL/SOAP
representation.
• @WebResult: Associates the SEI method’s return value to a wsdl:part or the wsdl:part’s
element definition.

Oracle University and Egabi Solutions use only

Name Description
@WebService Marks either a Java class or a service endpoint interface
(SEI) as a Web service interface

@WebMethod Indicates a method as a Web service operation

@WebParam Customizes the mapping of a single parameter to a

message part or element

Oracle University and Egabi Solutions use only

@WebResult Customizes the mapping of the method return value to a
WSDL part or XML element

@OneWay Marks a method as a Web service one-way operation

@HandlerChain Associates the Web service to an externally defined

handler chain

@SOAPBinding Specifies the mapping of the Web service onto the SOAP
message protocol

Copyright © 2009, Oracle. All rights reserved.

JSR 181 Annotations

Annotations are used to map Java to WSDL and schema, and to control how the JAX-WS runtime
processes and responds to Web service invocations. Using the JWS annotations programming model
makes programming a Web Service much easier. Currently the annotations utilized by JAXR-WS 2.1
are defined in several JSRs (See Lesson2 – JAX-WS). JSR 181 defines the basic annotations for
implementing Web Services by using class or a SEI as shown in the table above. For more
information of each annotation, please see https://jax-ws.dev.java.net/jax-ws-
ea3/docs/annotations.html.
We will look at other JSRs annotations as we progress through this course.

Web Service methods that return objects constructed of

nonprimitive types must follow these rules:
• They must define the default constructor, no argument
constructor.
• They must define both getXXX() and setXXX() methods
for each exposed member variable.

Oracle University and Egabi Solutions use only

• Member variable data types must be built-in data types, or
use objects that follow these rules.

Copyright © 2009, Oracle. All rights reserved.

Web Services have a well-defined life cycle that can be

managed.
Does not
exist

Oracle University and Egabi Solutions use only

1. Class.newInstance()
2. dependency injection [if any] PreDestroy callbacks [if any]

3. PostConstruct [if any]

Ready
Business methods

Copyright © 2009, Oracle. All rights reserved.

Web Service Life Cycle

Web services follow a very standard lifecycle similar to that of a stateless session EJB. Initially, a
web service does not exist, the web application representing the web service is then created and the
web service is now ready to handle requests.
Two lifecycle events can be hooked or intercepted for Web Services, post-construct and pre-destroy.
The post-construct event is invoked when the web service is being created. This event can be used to
perform any sort of initialization required by the service. Additionally, the pre-destroy event is
invoked when the web service is being shut down and is used to dispose of resources, close
connections and so on.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 14
PostConstruct and PreDestroy Life Cycle
Annotations
import javax.annotation.PreDestroy;
import javax.annotation.PostConstruct;
. . .
@WebService
public class MyWebService {

@PreDestroy
The methods can have any name,
public void destroy() {

Oracle University and Egabi Solutions use only

but they:
// close database connections, MUSTreturn
- Must returnvoid
void
// files, streams, and so on. MUSTnot
- Must NOT throw
throw checked
checked
} exceptions
MUSTnot
- Must NOT
taketake
anyany parameters
parameters
@PostConstruct .
public void initialize() {
// independently obtain db connections,
// open files and streams, and so on.
}
. . .
}

Copyright © 2009, Oracle. All rights reserved.

PostConstruct and PreDestroy Life Cycle Annotations

A web service can decorate one method with PreDestroy, and one method with PostConstruct. These
annotations mark the method as a receiver of container callback notifications to signal that the
instance is in the process of being created or evicted. The annotations are general to the Java EE
platform, not just EJBs. Here is what the Java EE Specification says about these annotations:
In some cases a class may need to perform initialization of its own after all resources have been
injected. To support this case, one method of the class may be annotated with the PostConstruct
annotation. This method will be called after all injections have occurred and before the class is put
into service. This method will be called even if the class doesn’t request any resources to be injected.
Similarly, for classes whose life cycle is managed by the container, the PreDestroy annotation may
be applied to one method that will be called when the class is taken out of service and will no longer
be used by the container. Each class in a class hierarchy may have PostConstruct and PreDestroy
methods. The order in which the methods are called matches the order of the class hierarchy, with the
methods on a superclass being called before the methods on a subclass.
The PostConstruct and PreDestroy annotations are specified by the Common Annotations
specification. All classes that support injection also support the PostConstruct annotation. All classes
for which the container manages the full life cycle of the object also support the PreDestroy
annotation.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 15
PostConstruct and PreDestroy Life Cycle Annotations (continued)
Note: Don’t rely solely on PreDestroy. There are situations where the container might never call
your bean’s PreDestroy method, for example if the server crashes or a system exception occurs.
When a system exception occurs, the container invalidates the web services session object and
destroys the instance (moving it to the Does Not Exist state), without invoking any PreDestroy
methods.

Oracle University and Egabi Solutions use only

@SOAPBinding(style = SOAPBinding.Style.RPC)
@WebService
public class Math {
@WebMethod(operationName=“add1”)
public double add(@WebParam(name="num1") double num1,
@WebParam(name = "num2") double num2){
return num1+num2;
}
Associates a

Oracle University and Egabi Solutions use only

}
Identifies that
method’s
the associated
<message name="add1"> parameter with
method is
<part name="num1" type="xsd:double"/> wsdl:part
mapped to a
wsdl:operation <part name="num2" type="xsd:double"/>
</message>
WSDL <portType name="Math">
<operation name=“add1" parameterOrder="num1 num2">
<input message="tns:add"/>
<output message="tns:addResponse"/>
</operation>
</portType>

Copyright © 2009, Oracle. All rights reserved.

An Example of POJO-Based Service Endpoint

The @WebMethod annotation exposes a method as a web service method. The operationName
property value in the annotation of the Math class identifies a WSDL operation (add1) and specifies
an XML namespace for the WSDL and some of the elements generated from this web service
operation. This property is optional. If you don't specify it, the WSDL operation value defaults to
method name: add.
The @WebParam annotation customizes Web service method’s parameter name. In this case, num1
and num2, instead of default arg0 and arg1.
The @SOAPBinding annotation specifies the SOAP binding style, in this case, as RPC/literal.

@SOAPBinding(style = SOAPBinding.Style.RPC)
.. Map to WSDL
soap:binding
element’s style
<binding name="MathPortBinding" type="tns:Math"> attribute.
<soap:binding
transport="http://schemas.xmlsoap.org/soap/http"
style="rpc"/>

Oracle University and Egabi Solutions use only

<operation name="add1">
<soap:operation soapAction=""/>
<input>
<soap:body use="literal“
namespace="http://ws.library.com/"/>
</input>
<output>
…
</output>f
</operation>
</binding>
…

Copyright © 2009, Oracle. All rights reserved.

An Example of POJO-Based Service Endpoint (continued)

The @SOAPBinding.style element indicates that this Web service should be deployed using
the RPC style. This annotation sets the WSDL soap:binding element’s style attribute as shown above.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 18
Quiz

Which annotation would you use to specify a name for the

WSDL version of a method parameter:
1. @SOAPBinding
2. @WebReturn
3. @WebParam

Oracle University and Egabi Solutions use only

4. @WebName

Copyright © 2009, Oracle. All rights reserved.

Answer: 3

Use cases of exposing EJBs as Web Services:

• Write the EJB 3.0 stateless session bean class.
– Java EE 5 simplifies the bean implementation by annotating
the class with the @Stateless annotation.
• Make the EJB 3.0 Bean as a Web Service.

Oracle University and Egabi Solutions use only

• The compile, package, and deploy is very similar to POJO
endpoint implementation.
– EJB Web service can be deployed as an EJB JAR or an
EAR file.

Copyright © 2009, Oracle. All rights reserved.

Implementing Web Services Using EJB

EJB 3.0 specification removes a lot of the complexity associated with creating and deploying EJBs. It
enables developers to deploy POJOs as stateless session beans simply by adding the @Stateless
annotation. You no longer need to implement the javax.ejb.SessionBean interface, and a
component interface or home interface for a session bean. This makes it much easier to deploy
existing POJOs to implement Web services within the EJB container.
To mark a stateless session bean as a web service, you simply annotate the class with the
@WebService annotation. This is the same as making a POJO-based service endpoint
implementation.

import javax.ejb.Stateless;
import javax.jws.WebService;
From EJB 3.0
@Stateless
@WebService Turns stateless session EJB into WS
public class Math {
public Math() {}

Oracle University and Egabi Solutions use only

public double add(@WebParam(name="num1") double num1,
@WebParam(name = "num2") double num2){
return num1+num2;
}
}

Copyright © 2009, Oracle. All rights reserved.

An Example of EJB Endpoint

The above code shows a stateless session bean as the Math class, and marked as a web service.
EJB 3.0 does specify additional rules for the bean implementation class:
• It must be declared public and must have a default constructor that doesn’t take any arguments.
• It must not be final or abstract and must be a top-level class.
• It must not define a finalize() method.

• JAX-WS supports a new Provider interface, as an

alternative to SEI, to enable services to work at the XML
message level.
• The benefits of implementing WS using Provider interface
are:
– Service implementation operates on XML Message

Oracle University and Egabi Solutions use only

– Bypasses JAXB and can be used to enable other bindings
– Can operate on whole SOAP message or just payload
• All Provider endpoints must
– Implement the javax.xml.ws.Provider interface
– Be annotated with the @WebServiceProvider annotation

Copyright © 2009, Oracle. All rights reserved.

The Provider API: Working with XML Directly

JAX-WS supports two different service endpoint implementations types, the standard Web service
endpoint interface and a new Provider interface to enable services to work with XML directly. The
Provider interface supports a more messaging oriented approach to Web services. The new Provider
API (javax.xml.ws.Provider) is an alternative to service endpoint interfaces. With the
Provider interface, you can create a Java class that implements a simple interface to produce a
generic service implementation class.
All Provider endpoints must be annotated with the @WebServiceProvider
(javax.xml.ws.WebServiceProvider) annotation. The @WebServiceProvider
annotation is only supported on classes that implement the javax.xml.ws.Provider interface.

import javax.xml.ws.Provider;
import javax.xml.ws.WebServiceProvider;
import javax.xml.ws.ServiceMode
import javax.xml.transform.Source;

@WebServiceProvider
@ServiceMode(Service.Mode.PAYLOAD)

Oracle University and Egabi Solutions use only

public class ProviderWS implements Provider<Source> {
public Source invoke(Source request) {
Source response;
// do something about request & generate response
return response;
}
}

Copyright © 2009, Oracle. All rights reserved.

A Sample of Provider Endpoint

The javax.xml.ws.Provider interface requires implementations to support
Provider<Source>, Provider<SOAPMessage> and Provider<DataSource>,
depending on the binding in use and the service mode.
The ServiceMode annotation can be used to control whether the Provider instance will receive
entire protocol messages or just message payloads.
The Provider interface has one method, the invoke method, which uses generics to control both the
input and output types when working with various messages or message payloads.
In the above Provider implementation example, ProviderWS supports Provider<Source>,
and will receive just message payloads. The only method defined in Provider<T> interface is a
generic method,
T invoke(T)
where T is specified as javax.xml.transform.Source here.

Steps for creating Web Services from a WSDL file are:

• Generate the artifacts from an existing WSDL file using
JDeveloper, OEPE, or wsdlc Ant task. The artifacts
include:
– JWS service endpoint interface (SEI) that implements the
Web Service described by the WSDL file

Oracle University and Egabi Solutions use only

– JWS implementation file that contains a partial
implementation of the generated JWS SEI. This file must be
customized by the developer.
– JAXB data-binding artifacts (optional)
• Add business logic to the JWS implementation file.
• Compile and generate the deployable Web Service.

Copyright © 2009, Oracle. All rights reserved.

Creating Web Services from a WSDL File

Another common use case of creating a Web Service is to start from an existing WSDL file, often
referred to as the golden WSDL. Based on this WSDL file, you generate the artifacts that implement
the Web Service so that it can be deployed to WebLogic Server. Using this approach, you get a set of
SEIs that map to the WSDL. Your job is to implement the SEIs with the appropriate business logic to
implement the Web services defined by the WSDL. After you have coded the JWS implementation
file, you run the tools (JDeveloper, Eclipse with OEPE, jwsc Ant task) to generate the deployable
Web Service.

<definitions
targetNamespace="urn:AdvMath“> Generated Java
... implementation file
<portType name="AdvMath"> 1 @WebService(name="AdvMath", 1
<operation name="multiply"> 2 targetNamespace =
<input message="tns:request"/> "urn:AdvMath",
<output message="tns:response"/>
</operation>
serviceName =
"AdvMathService",
4
</portType> portName =
"AdvMathPort", 5

Oracle University and Egabi Solutions use only

<binding name="AdvMathSOAP11Binding"
type="tns:AdvMath"> wsdlLocation = "/WEB-
<soap:binding style="rpc" 3 INF/wsdl/AdvMath.wsdl")
transport="http://schemas.xmlsoap. @SOAPBinding(style =
org/soap/http"/> SOAPBinding.Style.RPC) 3
<operation name="multiply">
...
</binding>
<service name="AdvMathService"> 4
<port name="AdvMathPort" 5
binding="tns:AdvMathSOAP11Binding">
...</port>
</service>
</definitions>

Copyright © 2009, Oracle. All rights reserved.

A Sample WSDL and Generated Java File

In the sample WSDL file, notice that the portType name is AdvMath, operation name is multiply,
SOAP binding style is RPC/literal, and service name is AdvMathService. We will take a look how
they get mapped in the AdvMath Java implementation file.
On the right side is the AdvMath Java implementation file generated from the WSDL document.
1. name: AdvMath. This value maps to the wsdl:portType name in the WSDL. By default, it
uses the class name: AdvMathImpl.
2. Method name: Multiply. This value maps the operation name of portType.
3. SOAPBinding Style: SOAPBinding.Style.RPC. This value maps to the wsdl: binding
4. serviceName: AdvMathService. This value maps to the wsdl:service
5. portName: AdvMathPort. This value is generated from the wsdl:port
Other properties of @WebServices annotation generated from WSDL are:
• targetNamespace: This value will be used as the XML namespace containing your WSDL
declaration. It’s required that this value is a URI.
• wsdlLocation: This value describe where the JAX-WS container, at runtime, will be able to
find the associated WSDL. In this case it's in the standard directory (META-INF/wsdl)

public class AdvMathImpl {

public AdvMathImpl() {
}

@WebMethod
@WebResult(name = "result", partName = "result")
public double multiply( 2
@WebParam(name = "num1", partName ="num1") double num1,
@WebParam(name = "num2", partName = "num2") double num2) {

Oracle University and Egabi Solutions use only

...
}
}

Copyright © 2009, Oracle. All rights reserved.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 26
Quiz

In order for a Java Bean to be returned by a Web Service, it

must:
1. Have an arg-less constructor
2. Have a properties-based constructor
3. Implement Serializable

Oracle University and Egabi Solutions use only

4. Have getter and setter methods for all exposed properties
5. May include other classes that follow the same rules
6. 2, 3, and 4
7. All of the above
8. 1, 4, and 5

Copyright © 2009, Oracle. All rights reserved.

Answer: 8

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 27
Summary

In this lesson, you should have learned:

• The key features of JAX-WS 2.1
• The JAX-WS run-time architecture for a service endpoint
• The benefits of using coarse-grained interface for
designing Web Services

Oracle University and Egabi Solutions use only

• Implementing Web Services using POJOs
• Implementing Web Services using EJBs
• Implementing Web Services using Provider APIs
• The steps for implementing Web services from a WSDL
document

Copyright © 2009, Oracle. All rights reserved.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 4 - 28
Practice 4 Overview:
Creating Server-Side Web Services
This practice covers the following topics:
• Implementing a contract-based Web Service
• Building JAX-WS–based Web Services

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Implementing JAX-WS Web Services:
Client Side

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Illustrate the process of invoking a Web Service with static
and dynamic clients
• Create Web Service clients using JDeveloper
• Explain how to invoke a Web Service using the Dispatch

Oracle University and Egabi Solutions use only

client API
• Invoke Web Services using the JAX-WS asynchronous
client programming model

Copyright © 2009, Oracle. All rights reserved.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 2
Agenda

• Client concepts and static clients

• Dynamic clients
• Calling Web Services asynchronously

Oracle University and Egabi Solutions use only

• JAX-WS programming model supports:

– Proxy client: Invoke a service endpoint interface
– Dispatch client: Work at the XML message level
• Both clients support synchronous and asynchronous
invocation of JAX-WS Web services.

Oracle University and Egabi Solutions use only

• A JAX-WS client is an instance of
javax.xml.ws.Service corresponding to a
wsdl:service element of the WSDL document.
• Service acts as a factory for proxies and instances of
Dispatch.

Copyright © 2009, Oracle. All rights reserved.

JAX-WS Client-Side Programming Model

JAX-WS enables the programmer to use a local method call to invoke a service on a remote host.
The service on the other host can be implemented as a .NET application, Java application, or
CORBA service.
JAX-WS client programming model supports the Proxy and Dispatch clients. Proxy client is used
when you want to invoke a Web service based on a service endpoint interface; whereas Dispatch
client is used when you want to work at the XML message level or when you want to work without
any generated artifacts at the JAX-WS level. Support for invoking services at the XML message
level is provided by the Dispatch client API, javax.xml.ws.Dispatch. Both clients enable
synchronous and asynchronous invocation of JAX-WS Web services.
JAX-WS clients are instances of javax.xml.ws.Service. An instance of Service
corresponds to a wsdl:service element of the target Web service’s WSDL document. Service
acts as a factory of the following:
• Proxies for a target service endpoint.
• Instances of Dispatch for dynamic message-oriented invocation of a remote operation.

To access a Web service from a client:

1. Obtain an instance of the service class, which is used as a
“port factory” to create port instances.
2. Obtain a port, which is then used as a traditional Java
POJO.

Oracle University and Egabi Solutions use only

Instance of the
. . .
service,
SomeWebService myService = new SomeWebService(); disconnected.

SomeWebServicePort port = myService.getPort(. . .);

. . . Connect to the
port.someMethod(. . . ); service, and obtain a
callable stub.

Call methods normally.

Copyright © 2009, Oracle. All rights reserved.

Accessing Web Services

To access a Web service from a java client a number of factors must be addressed. First and foremost
a JAR file which contains a Java version of the Web service interfaces must exist. This specific JAR
file is normally created using the clientgen or similar utility. The next step is to obtain an
instance of the Web services service object. This object acts as a port factory for returning ports via
its getPort method. In the example shown the getPort method is called showing how it might
take optional arguments. These arguments represent the location (QName) of the Web service. These
are necessary because clientgen hard codes into the service object the location of the Web
service, based on its WSDL, when it runs.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 5
Service Objects

Service instances can be created dynamically or statically:

• Dynamic: Use Service.create methods:
– public static Service create (QName
serviceName)
– public static Service create (URL
wsdlDocumentLocation, QName serviceName)

Oracle University and Egabi Solutions use only

• Static: Use tools to generate a subclass of Service from
a WSDL document.

Copyright © 2009, Oracle. All rights reserved.

Service Objects
Service instances can be created dynamically or statically. For dynamic generation, the Service
is created at runtime by one of the Service.create factory methods:
public static Service create (QName serviceName)
public static Service create (URL wsdlDocumentLocation, QName
serviceName)
You must pass the service name and optionally the location of the WSDL document. For example:
URL wsdlLocation = new URL("http://example.org/my.wsdl");
QName serviceName = new QName("http://example.org/sample",
"MyService");
Service s = Service.create(wsdlLocation, serviceName);
Alternatively, during development, you can generate a subclass of Service from a WSDL
document using the JAX-WS tools, such as clientgen Ant task or JDeveloper.

Web Service
Service 1 WSDL to Java
Endpoint Mapping Tool
Interface (clientgen) WSDL

Develop time

Oracle University and Egabi Solutions use only

javax.xml.ws.Service Runtime
SOAP
Response
2
getPort(…)
SOAP
4
Request
3 Invoke
Proxy Instance
an SEI method
(SEI, Handlers)

Copyright © 2009, Oracle. All rights reserved.

Invoking a Web Service with Proxy

The diagram above illustrates the process of creating a SEI and its proxy instance to invoke a Web
Service:
1. A WSDL to Java mapping tool (for example, the WLS clientgen) reads the Web service’s
WSDL (a wsdl:portType definition), and generate a service endpoint interface (SEI),
which is a Java representation of a Web service endpoint. This step happens prior to compiling
and running the client code that invokes the Web service.
2. At runtime, the getPort() method from the javax.xml.ws.Service class creates a
proxy instance that implements the SEI.
3. The Web service is invoked by invoking a method from the SEI. The internals of the proxy
instance convert the SEI method invocation parameters into a SOAP request and send it to the
Web service’s endpoint.
4. The return value from the invocation of the Web service endpoint is marshaled to a SOAP
response, and sent back to the proxy instance.
Note: JAX-WS uses the dynamic proxy class to create a run-time instance of a SEI that can be used
to invoke a Web service. For more information of dynamic proxies, see the Javadoc for
java.lang.reflect.Proxy.

A Java SE client application:

• Is a Java program with a Main public class that you invoke
with the java command
• Can run completely separately from the application server
A Java EE component client application:

Oracle University and Egabi Solutions use only

• Is deployed to the application server
• Is part of the code that implements an EJB, servlet, or
another Web Service
• Runs inside a Web or EJB container
• May use dependency injection specified by the
@WebServiceRef annotation to inject a proxy instance of
SEI

Copyright © 2009, Oracle. All rights reserved.

Clients and Web Services

The Web services client can be a standalone Java client or Java EE component client. Each client
type relies on the service’s WSDL file for information required to interact with the service and the
Web service runtime to manage the client-service communication.
When you invoke an operation of a deployed Web Service from a client application, the Web Service
could be deployed to WebLogic Server or to any other application server. All you need to know is
the URL to its public contract file, or WSDL.
Additionally WS can be consumed by any number of other client types, including .NET and ADF
Data Controls.

JDeveloper
Class Interface
HelloWorldService (implements HelloWorld
Java.xml.ws.Service)
(SEI)
@WebServiceClient()

Stand-alone
HelloWorldPortClient

Oracle University and Egabi Solutions use only

Create an instance of
HelloWorldService new HelloWorldService()
Instance of HelloWorldService
Java EE component
getHelloWorldPort() HelloWorldPortClient
(internally calls getPort) @WebServiceRef

Generated
Proxy instance (implements sayHello (…) artifacts
HelloWorld SEI) Created at
run time

Copyright © 2009, Oracle. All rights reserved.

Generated Client Artifacts

JDeveloper uses the WSDL of the deployed Web Service to generate the necessary artifacts and puts
them into the project directory, using the specified package name. The diagram illustrates the key
client artifacts generated from the WSDL of the HelloWorld Web service:
• HelloWorld.java is the SEI.
• HelloWorldService.java is a Java class generated along with the SEI. It is a
javax.xml.ws.Service implementation that acts as a factory class that can generate
instances of the SEI. It is annotated with @WebServiceClient() to represent a client view
of the Web service.
• HelloWorldPortClient.java is a Web service client. At runtime, it creates an instance
of the HelloWorldService class, in turn uses the instance’s getHelloWorldPort()
method (which internally calls getPort() method) to create a proxy instance that
implements the SEI.
The Web service client can be a standalone or Java EE component. In this case, JDeveloper
generates a standalone client. For Java EE component client, use the @WebServiceRef
annotation to declare a reference to a Web service.

@WebService
public class HelloWorld {
public String sayHello(String s) {
String result = "hello";
if ( s == null || s.isEmpty()) {
return result + " unknown!";
}
return result + " " + s;

Oracle University and Egabi Solutions use only

}
}

Copyright © 2009, Oracle. All rights reserved.

HelloWorld Web Service (Server-Side)

The slide shows the code of the HelloWorld service endpoint implementation class on the server
side.

<?xml version="1.0" encoding="UTF-8"?> The parameters contained

<wsdl:definitions ...> in these wrapper elements
<wsdl:types> get mapped to method
<schema xmlns=...> parameters in the SEI.
<xsd:complexType name="sayHello">
<xsd:sequence>
<xsd:element name="arg0" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType> WSDL Types
defined by the

Oracle University and Egabi Solutions use only

<xsd:element name="sayHello" type="tns:sayHello"/>
<xsd:complexType name="sayHelloResponse"> HelloWold WS
<xsd:sequence>
<xsd:element name="return" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="sayHelloResponse" type="tns:sayHelloResponse"/>
</schema>
</wsdl:types>
<wsdl:message name="sayHelloInput">
<wsdl:part name="parameters" element="tns:sayHello"/>
</wsdl:message>

Copyright © 2009, Oracle. All rights reserved.

HelloWorld Web Service WSDL File

This and next slides show the WSDL file of the HelloWorld Web service. The key parameters in this
WSDL are populated with the default values defined by the JAX-WS specification, derived from the
class name and method name of the Java class.
This HelloWorld Web service uses the document/wrapped style of WSDL. The parameters
contained in the wrapper elements get mapped to method parameters in the SEI using the JAXB 2.0
XML Schema to Java mapping. The method signatures in the SEI, on the other hand, get mapped
from the operations defined in the wsdl:portType.

<wsdl:message name="sayHelloOutput">
<wsdl:part name="parameters" element="tns:sayHelloResponse"/>
</wsdl:message>
<wsdl:portType name="HelloWorld"> Maps to HelloWorld
<wsdl:operation name="sayHello"> (SEI) on client side
<wsdl:input message="tns:sayHelloInput“ .../>
<wsdl:output message="tns:sayHelloOutput“ .../>
</wsdl:operation>
</wsdl:portType>

Oracle University and Egabi Solutions use only

<wsdl:binding name="HelloWorldSoapHttp" type="tns:HelloWorld">
<soap:binding style="document“
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="sayHello">
<soap:operation soapAction=""/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
...

Copyright © 2009, Oracle. All rights reserved.

@WebService(wsdlLocation="HelloWorldService.wsdl",
targetNamespace=“…” name="HelloWorld")
@XmlSeeAlso( A mapped SEI
{ com.library.wsclient.ObjectFactory.class }) must be annotated
public interface HelloWorld Identifies that the with @WebService.
associated method is
{
mapped from a
@WebMethod wsdl:operation.
@RequestWrapper(localName="sayHello", Defines the wrapper
element for the SOAP

Oracle University and Egabi Solutions use only

targetNamespace="http://ws.library.com/",
request message.
className="com.library.wsclient.SayHello") Only used with
@ResponseWrapper(localName="sayHelloResponse", Document/wrapped
targetNamespace="http://ws.library.com/",
className="com.library.wsclient.SayHelloResponse")
@WebResult(targetNamespace=“”)
public String
sayHello(@WebParam(targetNamespace="",name="arg0")
String arg0);
}

Copyright © 2009, Oracle. All rights reserved.

Generated HelloWorld (Client-Side)

This slide shows the generated SEI for the client, which is the Java representation of the HelloWorld
Web service endpoint. SEI is mapped from wsdl:portType by using the JAX-WS WSDL to Java
mapping.
The annotations used here serve two purposes: they annotate a SEI and determine, at runtime, how to
map a method invocation to SOAP request/response messages.

@WebServiceClient(wsdlLocation=“…", name="HelloWorldService")
public class HelloWorldService
extends Service
{
…
public HelloWorldService()
{
super(wsdlLocationURL,

Oracle University and Egabi Solutions use only

new QName("http://ws.library.com/", HelloWorldService"));
}
…
@WebEndpoint(name="HelloWorldPort")
public com.library.wsclient.HelloWorld getHelloWorldPort()
{
Qname qname = new QName("http://ws.library.com/", Internally call
"HelloWorldPort");
return super.getPort(qname,
com.library.wsclient.HelloWorld.class);
}

Copyright © 2009, Oracle. All rights reserved.

Generated HelloWorldService
This slide shows the code of HelloWorldService.java, which extends
java.xml.ws.Service. At runtime, JAX-WS needs to generate an instance of a SEI that
enables the programmer to invoke a Web service by invoking the method on the SEI. This file
implementing javax.xml.ws.Service acts as a factory class that can generate instances of the
SEI.
With @WebServiceClient annotation, it represents a client view of the Web service. The
getHelloWorldPort() method, annotated with @WebEndpoint, is used to obtain a run-time
instance of the SEI. Notice that internally it calls Service.getPort method.

• The JAX-WS specification defines some standard features.

• JAX-WS allows your implementation to customize or extend
features if necessary.
• To represent a feature that can be enabled or disabled for a Web
service, use the protected boolean enabled field of
javax.xml.ws.WebServiceFeature.

Oracle University and Egabi Solutions use only

@WebEndpoint(name="HelloWorldPort")
public com.library.wsclient.HelloWorld
getHelloWorldPort(WebServiceFeature... features)
{
return (com.library.wsclient.HelloWorld) super.getPort(new
QName("http://ws.library.com/", "HelloWorldPort"),
com.library.wsclient.HelloWorld.class, features);
}

Copyright © 2009, Oracle. All rights reserved.

Enabling Features: WebServiceFeature

The JAX-WS 2.1 specification defines some standard features, such as MTOM feature and Web
service Addressing feature. With the same mechanism, JAX-WS allows your implementations to
define additional features if necessary. The features have to be enabled through either:
• WSDL
• Java Annotations on endpoint implementation classes
• Programmatic configuration of features on the client
Note that vendor specific features may not be portable so caution should be used when using them.

public class HelloWorldPortClient

{
public static void main(String [] args)
{
helloWorldService = new HelloWorldService();
HelloWorld helloWorld =
helloWorldService.getHelloWorldPort();

Oracle University and Egabi Solutions use only

// Add your code to call the desired methods.

String result = helloWorld.sayHello("myname");

System.out.println("result is: "+result);
}
}

Copyright © 2009, Oracle. All rights reserved.

Generated HelloWorldPortClient
HelloWorldPortClient is the stand-alone Java program to accesses the sayHello method of
HelloWorldService. To do that, it needs to create an instance of the HelloWorldService
class, in turn uses the instance’s getHelloWorldPort() method to create a proxy instance that
implements the SEI. These code are generated by the tool, and you are responsible to add code to
accesses the sayHello method of HelloWorldService.

The javax.xml.ws.BindingProvider interface provides:

• A representation of the underlying protocol binding (for
example, SOAP/HTTP) being used for Web services
communication
– Binding getBinding()

Oracle University and Egabi Solutions use only

• Access to context objects for request and response
message processing
– java.util.Map<String,Object> getRequestContext()
– java.util.Map<String,Object> getResponseContext()

Copyright © 2009, Oracle. All rights reserved.

BindingProvider Interface
The BindingProvider interface provides access to the protocol binding and associated context
objects for request and response message processing.
When a BindingProvider does a request/response, the request and response messages are
embedded in a context that is binding-specific. The message and its context move through a chain of
handlers during the invocation process. This is discussed further in the lesson titled “Using Handlers
in JAX-WS Web Services.”

• JDeveloper: Create Web Service Proxy Wizard

• OEPE: Client generation wizard
• The clientgen Ant task

Oracle University and Egabi Solutions use only

Tools for Generating a Web Service Proxy

The tools listed above can help developers to generate JAX-WS client artifacts from an existing
WSDL file. These artifacts can be used to invoke the Web services.
Clientgen, a WebLogic Web Service Ant task, uses the WSDL of the deployed Web Service to
generate the necessary artifacts and puts them into the client project directory, using the specified
package name. The fully qualified name of clientgen supported in WebLogic Server is
weblogic.wsee.tools.anttasks.ClientGenTask.

Oracle University and Egabi Solutions use only

Creating a Web Service Proxy Using JDeveloper

Steps for creating a Web Service Proxy using the JDeveloper wizard are:
1. Right-click the service endpoint, and select Generate Web Service Proxy to launch the Create
Generic Project wizard.
2. Specify a target project for the proxy.
3. Select Client Style as JAX-WS Style.
4. In Web Service Description, the WSDL file you use to generate the SEI displays, and you can
copy it into the project.
5. Specify Default Mapping options provides default mappings from WSDL namespaces to Java
packages. You need to provide the package name for the generated client classes and mapping
types.
6. For Port Endpoints, select Run against a service deployed to Integrated WLS.
7. For Asynchronous Methods, select “Don’t generate any asynchronous methods.” We will
discuss asynchronous invocation later in this lesson.
8. Skip the Defined Handlers step. (SOAP handler will be covered in the lesson titled “Using
Handlers in JAX-WS We Services.”)
9. Click Finish. The client artifacts will be generated for you.

The clientgen Ant task is used to generate client-specific

Web service JAR files.

Oracle University and Egabi Solutions use only

Copyright © 2009, Oracle. All rights reserved.

Creating a Client JAR Using Ant

Clientgen is used via Ant to build JAR files used by client-side Web services.
To run the clientgen Ant task, you need to add taskdef and a target. In the example above:
• wsdl is a fully qualified URL to a WSDL file
• packageName is the name of the package that will be assigned to the generated java stub
classes
• clientJar is the name of the to be generated JAR file
For more information and a complete list of attributes for the clientgen task, see the WebLogic
Server Ant tasks reference.

Web Services References can be injected into other WebLogic

Web Services via the ServiceReference annotation.
To use a service reference:
1. Add the service reference annotation and the associated
port variable.

Oracle University and Egabi Solutions use only

2. Add the appropriate client-side JAR file to the classpath.
3. Access the Web service normally.
. . .

@ServiceClient(wsdlLocation="...WebService?WSDL",
serviceName="WebService",portName="WebServicePort")
private WebPortType port;
. . .
Port.doSomething(. . . );

Copyright © 2009, Oracle. All rights reserved.

Injecting Web Service References

The WebLogic Server container provides a mechanism for injecting Web service references into
Web services or EJBs running inside it in much the same way that an EJB can inject another EJB.
Using the @ServiceReference annotation you can insert or inject directly a Web service,
however a few requirements must be met.
1. The classes representing the Web Service and its port must exist in the classpath. Normally
clientgen is used to create the JAR file and is packaged into a Web applications WEB-
INF/lib directory.
2. The ServiceClient annotation must:
- Specify the location of the running Web service via the wsdlLocation attribute
- Specify the name of service and its port name correctly
3. There must be an instance variable which matches in type the Port as shown in the example.
4. The Web service or EJB can then reference the Web service normally.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 21
Quiz

The clientgen Ant task:

1. Is used by JDeveloper to create client-side JAR files
2. Requires a WSDL, package name, and JAR file attributes

Oracle University and Egabi Solutions use only

Answer: 2

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 22
Agenda

• Client concepts and static clients

• Dynamic clients
• Calling Web Services asynchronously

Oracle University and Egabi Solutions use only

JAX-WS provides the Dispatch client API

(javax.xml.ws.Dispatch<T>) to support:
• Dynamic invocation of Web services: Invoke a Web
service without having generated a SEI prior to run time.
• XML messaging interactions with Web services: There is
no need to bind the XML to a Java class.

Oracle University and Egabi Solutions use only

Dispatch Client API

The javax.xml.ws.Dispatch<T> interface allows you to write code that can dynamically
invoke a Web service. When the WSDL is not known prior to run time, for example, a target Web
service is looked up, using a registry, at runtime. In such scenarios, you need to invoke a Web service
without having generated and compiled a SEI prior to runtime.
Like the server-side Provider API, the Dispatch client API supports for invoking services at the XML
message level. You can work with XML messages directly without XML to Java binding. This way
increases the performance.

The Dispatch client:

• Can operate on a whole SOAP message or just payload
• Requires to construct a message or a payload as XML
• javax.xml.ws.Service acts as a factory for the
creation of Dispatch instances.

Oracle University and Egabi Solutions use only

Example of creating a Dispatch instance to handle a
javax.xml.transform.Source object:
Dispatch<Source> sourceDispatch =
service.createDispatch(
portQName, Source.class, Service.Mode.PAYLOAD);
Source response = sourceDispatch.invoke(
new StreamSource(new StringReader(request)));

Copyright © 2009, Oracle. All rights reserved.

Using Dispatch API for XML Messaging

Dispatch client directly deals with XML and can be used to enable other bindings. For example, you
can use HTTP bindings for Source objects, JAXB objects, or DataSource objects.
The Dispatch client API requires application clients to construct messages or payloads as XML. The
Dispatch API can send data in either MESSAGE or PAYLOAD mode. When using the
javax.xml.ws.Service.Mode.MESSAGE mode, the Dispatch client is responsible for
providing the entire SOAP envelope. When using the
javax.xml.ws.Service.Mode.PAYLOAD mode, the Dispatch client is only responsible for
providing the contents of the <soap:Body> and JAX-WS includes the payload in a
<soap:Envelope> element. The above code snippet shows creating dispatch instance in
PAYLOAD mode.

Types of Objects Bindings MESSAGE or

PAYLOAD

javax.xml.transform.Source SOAP or HTTP Message or

Payload

JAXB objects SOAP or HTTP Message or

Oracle University and Egabi Solutions use only

Payload

javax.xml.soap.SOAPMessage SOAP Message

javax.activation.DataSource HTTP Message

Copyright © 2009, Oracle. All rights reserved.

Dispatch Client Support Matrix

The Dispatch client supports the following types of objects:
• javax.xml.transform.Source: Source is one of the primary types defined by API for
Source objects contain or have access to XML documents. Source objects can be used with
SOAP and HTTP bindings, and support MESSAGE and PAYLOAD modes.
• JAXB objects: Clients can use JAXB objects that are generated from an XML schema to create
and manipulate XML with JAX-WS applications. You can use JAXB objects with SOAP and
HTTP bindings.
• javax.xml.soap.SOAPMessage: SOAPMessage objects allows clients to work with
SOAP messages. You can only use SOAPMessage objects with SOAP bindings.
• javax.activation.DataSource: javax.activation.DataSource, the
interface type defined in Java Activation Framework (JAF), is useful when attaching data
derived from some resource like a file or a Web server. Use DataSource objects so that
clients can work with Multipurpose Internet Mail Extension (MIME) messages. DataSource
is used only with HTTP bindings.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 26
A Sample of Dispatch Client
Qnames for service
as defined in
WSDL
QName serviceName =
new Qname("http://www.example.com/services/HelloWorld",
"HelloWorldService");
Create a dynamic
Service instance
Service service = Service.create(serviceName);
Create QName for
QName portName = the service port

Oracle University and Egabi Solutions use only

new Qname("http://www.example.com/services/HelloWorld",
"HelloWorldPort");

Dispatch<Source> dispatch = Create a dispatch

service.createDispatch(portQName, Source.class, instance
Service.Mode.PAYLOAD);

Source responseSource = dispatch.invoke(

new StreamSource(new StringReader(request)));
…

Copyright © 2009, Oracle. All rights reserved.

A Sample of Dispatch Client

The code example illustrates a dispatch client created from a WSDL document. The WSDL describes
a service, HelloWorldService, with a single port called HelloWorldPort. The portType
HelloWorld defines a single sayHello operation.

Steps to invoke an operation on an endpoint using the Dispatch

API:
1. Create a dynamic Service instance.
2. Create a Dispatch client.
3. Compose a request message.

Oracle University and Egabi Solutions use only

4. Invoke the operation on the endpoint
(synchronous/asynchronous).
5. Process the response message.

Copyright © 2009, Oracle. All rights reserved.

Invoking a Web Service Using the Dispatch API

The slide lists the steps to invoke an operation on an endpoint using the Dispatch API.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 28
Agenda

• Client concepts and static clients

• Dynamic clients
• Calling Web Services asynchronously

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 29
JAX-WS Web Services Invocation Mechanisms:
Synchronous
• Both Proxy and Dispatch clients support synchronous and
asynchronous invocations.
• Synchronous invocation:
– Clients are blocked until operation completes.
– Clients are immediately aware of invocation failures.

Oracle University and Egabi Solutions use only

– Invocations are typically less scalable and more vulnerable.
– Invocation execution may be more high-performing.

Synchronous Method Call

Sync Client Web Service

The client’s calling thread is blocked until the Web service has finished processing.

Copyright © 2009, Oracle. All rights reserved.

JAX-WS Web Services Invocation Mechanisms: Synchronous

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 is common.
Synchronous designs are traditionally simpler to understand and implement. With remote
invocations, synchronous systems are vulnerable to network interruptions if the operation execution
is lengthy. In other words, a network interruption can abort an otherwise successful (and expensive)
operation.
From a scalability perspective, synchronous designs demand that the service execute the operations
immediately. Consequently, during peak demand, the service may not provide enough availability for
all clients.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 30
JAX-WS Web Services Invocation Mechanisms:
Asynchronous
Asynchronous invocation:
• Clients are decoupled from operation execution.
• Clients may not be directly aware of invocation failures.
• Invocations are typically more scalable and less
vulnerable.

Oracle University and Egabi Solutions use only

• Invocation execution may be less effective.

Asynchronous Method Call

Async Client Web Service
Call back

The client’s calling thread is released to perform other work.

The response will be returned when the Web service has finished processing.

Copyright © 2009, Oracle. All rights reserved.

JAX-WS Web Services Invocation Mechanisms: Asynchronous

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 Web Services.
Asynchronous service designs are usually essential to robust and scalable service-oriented
architectures.
Asynchronous designs typically minimize the duration of blocking over the network, which thereby
mitigates the vulnerability to network interruptions. Common examples of slow services include
working with external partners and slow legacy applications.
When implementing asynchronous request-response in your client, rather than invoking the operation
directly, you invoke an asynchronous version of the same operation. For example, rather than
invoking an operation called addNumbers directly, you would invoke addNumbersAsync.

JAX-WS supports two models for asynchronous request-

response messaging:
• Polling: Enables clients to repeatedly check a response
object to determine whether a response has been received
– Polling an instance of java.xml.ws.Response<T>

Oracle University and Egabi Solutions use only

• Callback: Defines a handler that processes the response
asynchronously when it is available
– Provides an instance of javax.xml.ws.AsyncHandler to
process the results of the Web service invocation

Copyright © 2009, Oracle. All rights reserved.

Asynchronous Invocation Models

With the asynchronous invocation APIs provided by JAX-WS, along with the interface
java.util.concurrent.Future<T>, you don’t have to worry about thread use and other
low-level concurrency issues in order to invoke Web services asynchronously.
JAX-WS supports two models for asynchronous request-response messaging: polling and callback.
In the polling form of asynchronous invocation, a client can issue a request and receive a response
object that can subsequently be polled to determine if the server has responded. When the server
responds, the actual response can then be retrieved.
In the callback form of asynchronous invocation, the client provides an AsyncHandler callback
handler to accept and process the response object. The client callback handler implements the
javax.xml.ws.AsynchHandler interface. AsyncHandler is much like
javax.jms.MessageListener on a JMS queue. Like the MessageListener processes
messages asynchronously as they arrive, the AsyncHandler processes a Web service response
asynchronously when it arrives. The major difference here is that a MessageListener is
configured once for a queue and handles many messages, whereas an AsyncHandler must be
specified with each asynchronous Web service invocation.
Note: java.xml.ws.Response<T> extends the interface
java.util.concurrent.Future<T>.

@WebService(wsdlLocation="HelloWorldService.wsdl",
targetNamespace=“…” name="HelloWorld")
@XmlSeeAlso(
{ com.library.wsclient.ObjectFactory.class })
public interface HelloWorld
{
@WebMethod Synchronous
@ResponseWrapper(…) method call

Oracle University and Egabi Solutions use only

@RequestWrapper(…)
public String
sayHello(@WebParam(targetNamespace="",name="arg0")
String arg0);
Asynchronous
@WebMethod(operationName="sayHello") polling
…
public Response<com.library.ws.async.SayHelloResponse>
sayHelloAsync(@WebParam(targetNamespace="", name="arg0")
String arg0);

Copyright © 2009, Oracle. All rights reserved.

HelloWorld (SEI) with Asynchronous Method Calls

The example above illustrates a SEI (HelloWorld.java) with methods for asynchronous requests from
the client. As you see, in addition to the synchronous method call, it defines two more asynchronous
method calls for polling and callback respectively. For the polling form of asynchronous invocation,
the method call returns javax.xml.ws.Response object.

@WebMethod(operationName="sayHello")
…
public Future<?> sayHelloAsync(
@WebParam(targetNamespace="", name="arg0")
String arg0,
AsyncHandler<com.library.ws.async.SayHelloResponse>
asyncHandler);

Oracle University and Egabi Solutions use only

}
Asynchronous
callback

Copyright © 2009, Oracle. All rights reserved.

HelloWorld (SEI) with Asynchronous Method Calls (continued)

For the callback form of asynchronous invocation, the method contains one additional parameter of
type javax.xml.ws.AsyncHandler. The asynchronous invocations return instances of
Future<?>. The Future<?> instance returned can be polled to determine when the operation has
completed. However, this is not necessary since the response message is processed by the
AsynchHandler in a separate thread.

public class HelloWorldPortClient

{
public static void main(String [] args)
{
helloWorldService = new HelloWorldService();
HelloWorld helloWorld =
helloWorldService.getHelloWorldPort();

Oracle University and Egabi Solutions use only

// Add your code to call the desired methods.
Response<SayHelloResponse> resp =
helloWorld.sayHelloAsync("your name"); Check whether the
invocation has
while(!resp.isDone()) { completed.
// Do something in local space while you wait.
}
SayHelloResponse sayHelloResp = resp.get();
System.out.println("Result of sayHello(): Response object
"+sayHelloResp.getReturn()); calls the get()
} } method to return the
response content.

Copyright © 2009, Oracle. All rights reserved.

HelloWorldPortClient: Asynchronous Polling

The above code example illustrates an asynchronous polling client.
Using the polling model, your code is responsible for polling an instance of
java.xml.ws.Response<T> to determine when a Web service invocation has completed.
You include sayHelloAsync method in your client that handles the asynchronous response or
failures when it returns later. The client receives an object of type javax.xml.ws.Response
from this sayHelloAsync method. The Response object is used to monitor the status of the
request to the server, determine when the operation has completed, and retrieve the response results.
You put the business logic that processes the return value of the response object or a potential failure
in these methods. In this case, the isDone() method checks whether the invocation has completed.
If not, you can do something locally. When the isDone() method returns a value of true, call the
get() method to retrieve the response object.

Client
main thread

1: new HelloWorldService()

2: getHelloWorldPort()

3: handler= new AsyncHandler<SayHellowResponse>()

Oracle University and Egabi Solutions use only

4: sayHelloAsync (…, handler) WS Client
thread
5: makes SOAP call
6: while(!done) {…} and gets response

8: done=true 7: handleResponse
Response)

9: println(“Main Program ends”)

Copyright © 2009, Oracle. All rights reserved.

Asynchronous Callback: Sequence Diagram

This UML sequence diagram illustrates how the two threads coordinate to invoke an operation on an
endpoint using the asynchronous callback model.

public class HelloWorldPortClient{

private static boolean done = false;

public static void main(String [] args)

{
helloWorldService = new HelloWorldService();
HelloWorld helloWorld = helloWorldService.getHelloWorldPort();

// Add your code to call the desired methods.

Oracle University and Egabi Solutions use only

AsyncHandler<SayHelloResponse> handler =
new AsyncHandler<SayHelloResponse>() {
public void handleResponse(Response<SayHelloResponse> res){
SayHelloResponse result;
try {
result = res.get();
System.out.println("Result of callback:
"+result.getReturn());
} finally {
done = true;
}
}
};

Copyright © 2009, Oracle. All rights reserved.

HelloWorldPortClient: Asynchronous Callback

The above code example illustrates an asynchronous callback client.
Using the callback model, your code provides an instance of javax.xml.ws.AsyncHandler to process
the results of the Web service.
The code you need to implement:
• Create an instance of AsyncHandler<T> with your implementation of method void
handleResponse(Response<T> res)
• Call asynchronous method, in this case, sayHelloAsync, and take one more parameter with
type AsyncHandler<T> (code snippet is on next slide)
The client callback handler implements the javax.xml.ws.AsynchHandler interface, which
contains the application code that is run when an asynchronous response is received from the server.
The AsynchHandler interface contains the handleResponse (java.xml.ws.Response)
method that is called after the run time has received and processed the asynchronous response from
the server. The response is delivered to the callback handler in the form of a Response object. The
response object returns the response content when the get() method is called. Additionally, if an
error was received, then an exception is returned to the client during that call.

helloWorld.sayHelloAsync("your name", handler);

while(!done) {
try {
// Do something while you wait.
}
catch(InterruptedException e) {}
}
System.out.println("Main program ends.");

Oracle University and Egabi Solutions use only

}

Copyright © 2009, Oracle. All rights reserved.

HelloWorldPortClient: Asynchronous Callback

The code excerpt shows the call asynchronous method sayHelloAsync, and take one more
parameter with type AsyncHandler<T>.

Oracle University and Egabi Solutions use only

Creating an SEI Proxy Using the Asynchronous Invocation Models

Steps for creating a static SEI proxy using the asynchronous models in JDeveloper are similar to
creating a synchronous SEI Proxy as discussed previously. The only difference is, in Asynchronous
Methods step, you need to select “Generate asynchronous methods for all operations” in the Create
Client wizard. Once the artifacts are generated, open the Web Service client (XXXXPortClient), and
add your code to call the desired method, which is the asynchronous flavor of the operation.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 39
Creating a Dispatch Client Using the Polling
Asynchronous Invocation Model
Steps for creating a dynamic Dispatch client using the
asynchronous polling model:
1. Create a dynamic service instance.
2. Create QName for the service port.
3. Create a Dispatch instance using one of Service class

Oracle University and Egabi Solutions use only

createDispatch(…) methods.
4. Call Dispatch instance’s invokeAsync(T msg) method:

Response<T> response = dispatch.invokeAsync(request);

Copyright © 2009, Oracle. All rights reserved.

Creating a Dispatch Client Using the Polling Asynchronous Invocation Model

The first three steps are the same as creating a Dispatch client using the synchronous invocation
model as discussed previously in this lesson. The difference is Step 4, when dispatching a request,
you use invokeAsync() method, instead of invoke(), on the Dispatch instance.

QName serviceName =
new Qname("http://www.example.com/services/HelloWorld",
"HelloService");

// Create a dynamic Service instance

Service service = Service.create(serviceName);

//Create QName for the service port

Oracle University and Egabi Solutions use only

QName portName =
new Qname("http://www.example.com/services/HelloWorld",
"HelloPort");

//Create a dispatch instance

Dispatch<Source> dispatch =
service.createDispatch(portQName, Source.class,
Service.Mode.MESSAGE);

Response<Source> responseSource =
dispatch.invokeAsync(xmlSource);

Copyright © 2009, Oracle. All rights reserved.

Dispatch Client: Asynchronous Polling

The code example shows the Dispatch client that invokes an operation using the asynchronous
polling model.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 41
Creating a Dispatch Client Using the Callback
Asynchronous Invocation Model
Creating a Dispatch client using the asynchronous callback
model, you need to:
1. Create a dynamic Service instance
2. Create QName for the service port
3. Create Dispatch instance by using one of
service.createDispatch(…) methods

Oracle University and Egabi Solutions use only

4. Create an instance of AsyncHandler<T> with your
implementation of method
void handleResponse(Response<T> response)
5. Call Dispatch instance’s invokeAsync(T msg,
AsyncHandler<T> handler) method

Copyright © 2009, Oracle. All rights reserved.

Creating a Dispatch Client Using the Callback Asynchronous Invocation Model

This slide lists the steps for creating a Dispatch client using the asynchronous callback model.

…
Step 3
Dispatch<Source> dispatch = service.createDispatch(portName,
Source.class, Service.Mode.MESSAGE);
Step 4
AsyncHandler<Source> asyncHandler =
new AsyncHandler<Source>() {

Oracle University and Egabi Solutions use only

public void handleResponse(Response<Source> resp){
// Your implementation code
}
}
Step 5
Response<Source> resp = dispatch.invokeAsync(request,
asyncHandler);
…

Copyright © 2009, Oracle. All rights reserved.

Dispatch Client: Asynchronous Callback

The three blocks of code match Steps 3, 4 and 5 listed in previous slide.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 43
Quiz

An asynchronous callback:
1. Is called repeatedly in user code to determine whether a
Web service is complete
2. Is called by the framework at call completion
3. Both

Oracle University and Egabi Solutions use only

Answer: 2

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 5 - 44
Summary

In this lesson, you should have learned:

• The process of invoking a Web Service with a Dynamic
Proxy client
• How to create Web Service Proxy using JDeveloper
• Explain how to invoke a Web Service using the Dispatch

Oracle University and Egabi Solutions use only

client API
• Invoke Web Services using a JAX-WS asynchronous client
programming model

Copyright © 2009, Oracle. All rights reserved.

Summary
This slide summarizes what you have learned in this lesson.

This practice covers the following topics:

• Accessing Web Services via typed synchronous clients
• Accessing long-running services using asynchronous
clients

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe JWS standards for packaging and deployment
• Package and deploy POJO endpoints
• Package and deploy EJB endpoints
• Illustrate the deployment process in the WebLogic Server

Oracle University and Egabi Solutions use only

container
• Deploy Web services without deployment descriptors
• Use deployment descriptors to override the annotations
• Manage Web services by using WLS Administration
Console

Copyright © 2009, Oracle. All rights reserved.

Objectives
This lesson discusses packaging and deploying Web services endpoints to WebLogic Server, as well
as managing endpoints using WebLogic Server Administration Console. This lesson also discusses
various components that can be included in the package and different deployment options.

• Enterprise Web services run in a contained environment

that provides:
– Life cycle management
– Concurrency management
– Security

Oracle University and Egabi Solutions use only

– Portability
• Two JAX-WS specifications provide the details for
packaging and deployment of Web services:
– WS-Metadata 2.0 [JSR 181]: Describes container/Web
service behavior
– WSEE 1.2 [JSR 109]: Defines packaging options for
deployment

Copyright © 2009, Oracle. All rights reserved.

Web Services Packaging and Deployment

Programmers use annotations defined in WS-Metadata to configure how the container will deploy a
Java class as a Web service. During deployment, the JWS container interprets those annotations to
generate artifacts and configure itself to deploy the specified Web service.
WSEE defines types of objects that can be deployed as Web services, how the Java class and other
artifacts must be packaged, and what annotations and/or deployment descriptors are required for
deployment. The purpose is to ensure portability of Web services across Java EE application server
implementations.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 3
Port Component

A port component:
• Defines the artifacts that get packaged and deployed to the
container to implement a Web service
• Includes:
– Service Implementation Bean (SIB) (required)

Oracle University and Egabi Solutions use only

– SEI (optional)
– Web service deployment descriptor (webservice.xml)
(optional)
– WSDL document (optional)

Copyright © 2009, Oracle. All rights reserved.

Port Component
A port component is an addition to the Java EE platform defined by WSEE and can be considered the
Web services counterpart to other deployable components such as servlets and JSPs or EJBs. Like
those other components, a port component depends on the functionality provided by the Web and
EJB containers.
A port component defines the artifacts that make up a portable Web service application. These
components are defined in detail by the WSEE specification. A port component must include a
service implementation bean (SIB), and may optionally include a SEI, a WSDL document, and a
Web services deployment descriptor (webservices.xml).
• SIB: Is a Java class that contains the business logic of a Web service. It may also be a wrapper
that invokes other classes containing the business logic. A SIB must be annotated with
@WebService or @WebServiceProvider.
• SEI: Is a Java interface. If a SEI is included in a port component, the container uses the SEI
(including its annotations) to generate the WSDL file of the Web service. If no SEI is present,
the container generates the WSDL representation directly from the SIB.
• Web services deployment descriptor (webservices.xml): The file is not required by
JAX-WS because you can use annotations to specify all of the information that is contained
within this file. However, you may want to use a webservices.xml if you need to override
any existing JAX-WS annotations or deploy legacy classes.
• WSDL: When a WSDL document is provided in a port component, the container does not
generate WSDL, but rather uses the document supplied.
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 4
Packaging a POJO Endpoint

WAR

WEB-INF

Oracle University and Egabi Solutions use only

classes wsdl lib

WSDL web.xml
SIB
webservice.xml
SEI weblogic-web.xml
jax-ws-catalog.xml

Directory name File/Component name

Copyright © 2009, Oracle. All rights reserved.

Packaging a POJO Endpoint

POJO-based endpoints are packaged in a WAR file with the other system components that comprise
a web application. The figure illustrates the packaging structure for a web application that contains a
POJO-based endpoint.
• SIB: A SIB is the only required artifact in a port component. A SIB is usually contained in the
WEB-INF/classes/<package-path>/, where <package-path> is determined by the
class’s package name. This location is customary.
• SEI (optional): Like SIB, SEI is usually contained in the WEB-INF/classes/<package-
path>/.
• WSDL (optional): WSDL file is contained in the WEB-INF/wsdl directory. Note that any
files referenced by the WSDL must be referenced relative to the WSDL’s location. For
example, if the WSDL is in the META-INF/wsdl directory and it references a schema as
myschema.xsd, then this schema should also be placed in META-INF/wsdl.
• web.xml (optional): The WAR deployment descriptor file is contained in the WEB-INF/
directory.
• webservices.xml (optional): The Web services deployment descriptor file is contained in the
WEB-INF/ directory.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 5
Packaging a POJO Endpoint (continued)
• Vendor-specific-web.xml (optional): A vendor specific Web application descriptor. In case of
WebLogic Application Server, it is weblogic.xml. The file is contained in the WEB-INF/
directory.
• jax-ws-catalog.xml (optional): This file is used in connection with OASIS XML Catalog. It is
contained in the WEB-INF/ directory.
• lib (optional): Any classes the SIB or SEI depend on are bundled in a JAR and contained under
the WEB-INF/lib directory where they are available on the application classpath.

Oracle University and Egabi Solutions use only

WEB-INF
EAR WAR
JAR

EJB-JAR

Oracle University and Egabi Solutions use only

META-INF <package-path>

ejb-jar.xml wsdl
webservice.xml SIB
weblogic-ejbjar.xml
SEI
jax-ws-catalog.xml WSDL

Copyright © 2009, Oracle. All rights reserved.

Packaging an EJB Endpoint

When you package a SIB for deployment as a stateless EJB endpoint, the package may be structured
as shown in the figure.
• SIB (required): A SIB is contained in the <package-path>/ directory, where
<package-path> is determined by the class’s package name. Alternatively, the SIB could
be included in another JAR and referenced by the EJB-JAR’s manifest file Class-Path
attribute.
• SEI (optional): Like SIB, SEI is contained in the <package-path>/ directory.
• WSDL (optional): Is contained in the WEB-INF/wsdl directory.
• ejb-jar.xml (optional): The EJB deployment descriptor file is contained in the WEB-INF/
directory.
• webservices.xml (optional) is contained in the WEB-INF/ directory.
• weblogic-ejbjar.xml (optional) is a EJB deployment descriptor. The file is contained in the
WEB-INF/ directory.
• jax-ws-catalog.xml (optional) is used in connection with OASIS XML Catalog. It is contained
in the WEB-INF/ directory.

Load all deployment

descriptors(if any)

1
Process
annotations

Oracle University and Egabi Solutions use only

Y Use values
Is there a
defined in
webservices.xml
webservices.xml
3
4 N

create a bean, and

populate its values
from annotation

Copyright © 2009, Oracle. All rights reserved.

WLS Container Deployment Processing

The WebLogic Server container includes a deployment subsystem that is responsible for deployment.
The diagram illustrates the logical deployment process in the WebLogic Server container.
1. The deployment subsystem loads all deployment descriptors (if any) included in the
deployment module, and then processes annotations.
2. When processing the annotation, the framework checks whether webservices.xml entry is
already available.
3. If so, the annotation values will not override the equivalent defined in the descriptor.
4. If there is no webservice.xml, deploy subsystem will create a deployment descriptor bean, and
populate its values from annotation. At the end of the annotation processing phase, all the
information has been gathered that is required to generate the WSDL and other portable
artifacts.

5
Is there a Y
Use WSDL file
WSDL file
6
7 N

Generate WSDL file

Oracle University and Egabi Solutions use only

Publish WSDL file

Copyright © 2009, Oracle. All rights reserved.

WLS Container Deployment Processing

5. Before generating the WSDL file, deployment subsystem checks if the WSDL file is already
available.
6. If so, use this WSDL for publish
7. If not, generate the WSDL file.
Once the Web services are deployed successfully, the deployment subsystem publishes the WSDL
documents representing the deployed Web services, configures the server, and starts the application.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 9
Deploying Web Services Without a Deployment
Descriptor
With Java EE 5, you can deploy a servlet/EJB endpoint:
• With only a SIB
• With a SIB and WSDL

HelloWorld SIB

Oracle University and Egabi Solutions use only

@WebService
public class HelloWorld {

public String sayHello(String name) {

return "Hello " + name;
}
}

Copyright © 2009, Oracle. All rights reserved.

Deploying Web Services Without a Deployment Descriptor

One of the big benefits of JAX-WS is that you no longer need to use any deployment descriptors for
deploying a servlet/EJB endpoint. The next several slides will show the examples of deployment with
only a SIB, and with a SIB, and supplying your own WSDL.

Oracle University and Egabi Solutions use only

Copyright © 2009, Oracle. All rights reserved.

WSDL Generated from the SIB

If you bundle a SIB (HelloWorld) in a WAR, without any descriptors and deploy it, you get a
Web service with the WSDL shown in example. The key parameters in this WSDL are populated
with the default values defined by the JAX-WS specification, derived from the class name and
method name. They are as follows:
• The wsdl:portType name (HelloWorld) comes from the simple name of the SIB.
• The wsdl:serviceName (HelloWorldService) comes from the simple name of the SIB +
“Service”
• The wsdl:port name (HelloWorldPort) comes from the simple name of the SIB + “Port”

HelloWorld SIB specifying a user-defined WSDL

@WebService(wsdlLocation="WEB-INF/wsdl/helloWorld.wsdl")
public class HelloWorld {

public String sayHello(String name) {

Oracle University and Egabi Solutions use only

return "Hello " + name;
}
}

Copyright © 2009, Oracle. All rights reserved.

Supplying a WSDL File

You can also bundle a WSDL file with your WAR or EJB-JAR, rather than have the container
generate the WSDL file of the Web service for you. This can be done when no deployment
descriptors are used.
This example shows how to specify the use of a bundled WSDL file using the @WebService
annotation. Notice that the location of the WSDL within the WAR package is WEB-INF/wsdl as
discussed previously.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 12
Deploying Web Services with a Deployment
Descriptor
• Information defined in the deployment descriptors
overrides any corresponding information that is specified
by annotations.
• You can use Web services deployment descriptor in the
following scenarios:
– Customizing the endpoint URL where a service gets

Oracle University and Egabi Solutions use only

deployed
– Overriding the value of an annotation

Copyright © 2009, Oracle. All rights reserved.

Deploying Web Services with a Deployment Descriptor

Using annotations simplifies the development and deployment of Web applications, but it also has
limitations by encoding the definition of the Web service inside the Java class definition itself. If you
want to deploy the same class, with different Web service representations, in different contexts, you
need to use deployment descriptors to override those annotations. Some of the use cases requiring
deployment descriptors are:
• Customizing the endpoint URL where a service gets deployed
• Overriding the value of an annotation

To customize the endpoint URL for a servlet-based Web

service, you need to use:
• web.xml file, to specify a URL pattern
• weblogic.xml, to specify the Context Root

Oracle University and Egabi Solutions use only

Customizing Endpoint URLs

A web service endpoint URL is defined by WSDL port address. And the WSDL port address for the
Port component is the combination of the web application context-root and url-pattern of the servlet-
mapping.

web.xml specifies the URL pattern.

<web-app ...>
<servlet>
<servlet-name>HelloWorld</servlet-name>
<servlet-class>samples.HelloWorld</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>HelloWorld</servlet-name>
<url-pattern>/HelloWorld</url-pattern>

Oracle University and Egabi Solutions use only

</servlet-mapping>
...
</web-app>

weblogic.xml specifies the Context Root.

<weblogic-web-app>
<context-root>mycontext</context-root>
</weblogic-web-app>

Copyright © 2009, Oracle. All rights reserved.

Example Deployment Descriptors

These examples show how to use the web.xml to specify a URL pattern of /HelloWorld, and
the weblogic.xml to specify a context root of mycontext.

Generated soap:address location in WSDL

Oracle University and Egabi Solutions use only

</service>

Copyright © 2009, Oracle. All rights reserved.

Example Generated WSDL File

This example shows what the WSDL generated for the HelloWorld SIB looks like after using the
previous techniques for specifying the context-root and url-pattern.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 16
Overview of webservice.xml and
weblogic-webservice.xml
• The webservice.xml deployment descriptor file:
– Defines the set of Web services that are to be deployed to a
Java EE-enabled container
– Is optional
– Is used only to override existing annotation attributes or
specify attributes that are not defined by the annotation

Oracle University and Egabi Solutions use only

• WebLogic also has a weblogic-webservice.xml file,
which:
– Specifies WebLogic-specific information about a WebLogic
Web service
– Has a similar structure of the webservices.xml file

Copyright © 2009, Oracle. All rights reserved.

Overview of webservice.xml and weblogic-webservice.xml

The standard Java EE deployment descriptor for Web services is called webservices.xml. This file
specifies the set of Web services that are to be deployed to an application server and the
dependencies they have on container resources and other services. With JAX-WS the use of
webservices.xml is optional because you can use annotations to specify most of the information that
is contained within this file. So the deployment descriptors are used to augment or override the
annotation member attributes.
The WebLogic equivalent to the standard Java EE webservices.xml deployment descriptor file
is called weblogic-webservices.xml. This file contains WebLogic-specific information
about a WebLogic Web service, such as the URL used to invoke the deployed Web service,
configuration settings such as timeout values, and so on.
The structure of the weblogic-webservices.xml file is similar to the structure of the
webservices.xml file in how it lists and identifies the Web services that are contained within the
archive. For example, for each Web service in the archive, both files have a <webservice-
description> child element of the appropriate root element (<webservices> for the
webservices.xml file and <weblogic-webservices> for the weblogic-
webservices.xml file).
Both deployment descriptor files are located in the same location in the Java EE archive that contains
the Web service.
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 17
Example of webservice.xml File

<webservices ...>
<webservice-description> @WebService.wsdlLocation
<display-name>HelloWorld</display-name>
<wsdl-file>WEB-INF/wsdl/HelloWorld.wsdl</wsdl-file>
<port-component> @WebService.name

<port-component-name>HelloWorldPort</port-component-name>

Oracle University and Egabi Solutions use only

<wsdl-service>HelloWorldService</wsdl-service>
@WebService.servi
<wsdl-port>HelloWorldPort</wsdl-port> ceName
<service-endpoint-interface>samples.HelloWorld</service-
endpoint-interface>
<service-impl-bean>
<servlet-link>HelloWorld</servlet-link>
</service-impl-bean>
</port-component> Use SIB class name to
map the Port component to
</webservice-description> the actual servlet
</webservices>

Copyright © 2009, Oracle. All rights reserved.

Example of webservice.xml File

Above is an example of webservice.xml deployment descriptor. There is a defined relationship
between the deployment descriptor elements and the @WebService annotations. Refer to section 5.3
in the WSEE 1.2 for more detailed information regarding the deployment descriptor elements and the
mapping to the @WebService annotation attributes.
The structure of the weblogic-webservices.xml file is similar to the structure of the
webservices.xml file. For more information about element hierarchy of weblogic-
webservices.xml, see Oracle® Fusion Middleware WebLogic Web services Reference for Oracle
WebLogic Server 11g Release 1.

SIB with @WebService annotation:

@WebService(wsdlLocation=”http://example.com/location/of/the/w
sdl/MyService.wsdl”)

webservices.xml deployment descriptor:

Oracle University and Egabi Solutions use only

<webservices>
<webservice-description>
<webservice-description-name>MyService</webservice-
description-name>
<wsdl-file>META-INF/wsdl/MyService.wsdl</wsdl-file>
…
</webservice-description>
</webservices>

Copyright © 2009, Oracle. All rights reserved.

Using webservice.xml to Override Annotations

In this example, the service implementation class for a JAX-WS Web service uses the
@WebService.wsdlLocation attribute to specify an absolute URL for the WSDL document.
The associated webservices.xml deployment descriptor specifies a different WSDL file. The
value that is specified in the deployment descriptor, META-INF/wsdl/MyService.wsdl, overrides the
@WebServiceRef.wsdlLocation attribute from the annotated code.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 19
Quiz

In JAX-WS, a deployment descriptor:

1. Augments existing annotations with new values
2. Replaces annotations, making them not required
3. Overrides existing annotations with replacement values
4. 1 and 3

Oracle University and Egabi Solutions use only

Answer: 4

• JDeveloper
• OEPE
• WebLogic Ant : jwsc, clientgen, schemagen, and
wldeploy
• Apache Ant: An open source tool creates packages in a

Oracle University and Egabi Solutions use only

portable manner.

Copyright © 2009, Oracle. All rights reserved.

Packaging and Deployment Tools

JDeveloper, OEPE and WebLogic Ant include packaging utilities to create and package a POJO or
EJB endpoint. They both include WebLogic specific deployment descriptors or add WebLogic-
specific features within the packaging. If you want WAR/EAR generation code that is portable across
platforms, you may want to use third-party, open source tools, such as Apache Ant or Apache
Maven.

JDeveloper allows you to:

• Deploy Web services to:
– The Integrated WebLogic Server
– Other WebLogic Servers
• Generate Web services that can be manually deployed to

Oracle University and Egabi Solutions use only

any containers that support the Sun JAX-WS Reference
implementation.

Copyright © 2009, Oracle. All rights reserved.

Deploying Web Services by Using JDeveloper

JDeveloper provides tools that help you create and deploy web services to Oracle WebLogic Server,
where they run within a Java EE container. You can:
• Run web services in JDeveloper’s Integrated WLS in order to test them.
• Deploy web services to other WebLogic Servers. JDeveloper allows you to add other server
instances, and bind your application to them. For more information on how to create a new
server instance, please see JDeveloper’s Online Help.
You can also generate web services that can be manually deployed to any containers that support the
Sun JAX-WS Reference Implementation.

With OEPE, you can:

• Define run times: Target
environments for Servers.
• Define servers: Target
environments for Web
services, and Web and

Oracle University and Egabi Solutions use only

enterprise applications.
• Deploy Web services to any
defined server.
• Package applications into
WAR/EAR files for later
deployment.

Copyright © 2009, Oracle. All rights reserved.

Deploying Web Services Using OEPE

Oracle Enterprise Pack for Eclipse is a layered framework based on Eclipse Ganymede, and provides
a variety of mechanisms for managing web applications, Web services, enterprise applications and
their associated artifacts simply and easily.
With OEPE you can:
• Define Runtimes: Runtimes represent the environment an application runs within and includes
definition of environment, libraries, JDK etc required by a server
• Define Servers: Servers represent a specific instance of WebLogic, Apache, WebSphere or
other target JEE server. Servers use a specific runtime to define required JDK components and
a tied to a specific domain, in the case of WebLogic Server, or other application server
requirement. Once defined, the servers’ lifecycle can completely be controlled within
OEPE/Eclipse. The Server, can be started, stopped, restarted etc, all within the IDE.
• Deploy applications to a specific Server: Once a server is defined OEPE can use it to target a
web service, web application or enterprise application. Applications can be temporarily targeted
to a server, and each time the application is deployed the developer is asked what server to
target. Or permanently targeted, and as such each deployment is to the same server.
• Package applications: Eclipse itself provides a rich set of tools for packaging applications
including full support for managing deployment descriptors, packaging into WAR, EAR or
JAR formats and exporting projects for later use.
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 23
Deploying a Web Service with a SIB

To deploy a Web service endpoint with only a SIB to the

integrated WebLogic Server instance:
1. Right-click the project containing the Web service.
2. Select Deploy > WebServices > to >
IntegratedWLSConnection.

Oracle University and Egabi Solutions use only

Deploying a Web Service with a SIB

You can deploy Web service generated in JDeveloper to the integrated WebLogic Server instance
easily. This slide lists the steps for deploying a Web service with only a SIB to the integrated
WebLogic Server instance.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 24
Steps for Deploying a Web Service with
an SIB and WSDL
Steps for supplying your own WSDL:
1. Right-click the class and select “Show WSDL for Web
Service Annotations.”
2. Use Tools > Copy WSDL Locally to place the WSDL either
under your project’s source or the public_html
directory.

Oracle University and Egabi Solutions use only

3. Edit the wsdlLocation attribute of the @WebService
annotation to point to this WSDL.

Copyright © 2009, Oracle. All rights reserved.

Steps for Deploying a Web Service with an SIB and WSDL

If you want to provide a WSDL file in the deployment archive:
1. Right-click the class and select “Show WSDL for Web Service Annotations.”
2. Use Tools >Copy WSDL Locally to place the WSDL either under the source or
public_html directory. The source directory is where your service class located.
3. Edit the wsdlLocation attribute of the @WebService annotation to point to this WSDL:
- If the WSDL file is saved under public_html directory, the syntax for referencing the file
is @WebService(wsdlLocation=“MyWsdl.wsdl”)
- If it is saved under the source, you need to provide the fully qualified name of the WSDL
file. For example, if the package prefix of the class is com.oracle.example, the syntax is
@WebService(wsdlLocation=“/com/oracle/example/MyWsdl.wsdl”)
This WSDL file will be used from now on, the JDeveloper will also tell you when the Java class and
WSDL are out of sync and offer to fix it for you.
The remaining steps for deploying the Web service with SIB and WSDL are the same as those with
only a SIB.

The jwsc Ant task:

• Takes one or more JWS files as input
• Generates all the artifacts you need to create a WebLogic
Web Service. The artifacts include:
– Web service class file

Oracle University and Egabi Solutions use only

– JAXB data-binding artifact class file
– All required deployment descriptors, including:
— Servlet-based Web Service deployment descriptor file: web.xml
— EAR deployment descriptor files: application.xml and
weblogic-application.xml
• Compiles, packages classes and artifacts, and creates an
Enterprise Application directory

Copyright © 2009, Oracle. All rights reserved.

Using jwsc Ant to Package Web Services

The jwsc Ant task takes as input a JWS file that contains JWS annotations and generates all the
artifacts you need to create a WebLogic Web Service. The JWS file can be either one you coded or
generated by the wsdlc Ant task. The jwsc-generated artifacts include:
• JSR-109 Web Service class file
• JAXB data binding artifact class file
• All required deployment descriptors, including:
- Servlet-based Web Service deployment descriptor file: web.xml
- EAR deployment descriptor files: application.xml and weblogic-
application.xml
After generating all the required artifacts, the jwsc Ant task compiles the Java files (including your
JWS file), packages the compiled classes and generated artifacts into a deployable JAR archive file,
and finally creates an exploded Enterprise Application directory that contains the JAR file.
Note: The wsdlc Ant task generates, from an existing WSDL file, a set of artifacts that together
provide a partial Java implementation of the Web Service described by the WSDL file.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 26
Updating the build.xml File for the jwsc Ant
Task
To run the jwsc Ant task, add the following taskdef and
build-service targets to the build.xml file:
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<target name="build-service">
<jwsc

Oracle University and Egabi Solutions use only

srcdir="src_directory"
destdir="ear_directory"
>
<jws file="JWS_file"
type="WebService_type"/>
</jwsc>
</target>

To actually run the jwsc task, use the command:

prompt> ant build-service

Copyright © 2009, Oracle. All rights reserved.

Updating the build.xml File for the jwsc Ant Task

To run the jwsc Ant task, you need to add taskdef and build-service targets to the
build.xml file. In the example code:
• src_directory refers to the top-level directory that contains subdirectories that correspond
to the package name of your JWS file.
• ear_directory refers to an Enterprise Application directory that will contain all the
generated artifacts.
• JWS_file refers to the full pathname of your JWS file, relative to the value of the
src_directory attribute.
• WebService_type specifies the type of Web Service. This value can be set to JAXWS or
JAXRPC.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 27
Using the wldeploy Ant Task to Deploy Web
Services
To use the wldeploy Ant task, add the following target to your
build.xml file:
<target name="deploy">
<wldeploy action="deploy"
name="DeploymentName"
source="Source" user="AdminUser"

Oracle University and Egabi Solutions use only

password="AdminPassword"
adminurl="AdminServerURL"
targets="ServerName"/>
</target>

To actually deploy the Web Service, execute the deploy target

at the command line:
prompt> ant deploy

Copyright © 2009, Oracle. All rights reserved.

Using the wldeploy Ant Task to Deploy Web Services

Because Web Services are packaged as Enterprise Applications, deploying a Web Service simply
means deploying the corresponding EAR file or exploded directory.
There are a variety of ways to deploy WebLogic applications, from using the Administration Console
to using the weblogic.Deployer Java utility. The easiest way to deploy a Web Service as part
of the iterative development process is to add a target that executes the wldeploy WebLogic Ant
task to the same build.xml file that contains the jwsc Ant task. You can add tasks to both deploy
and undeploy the Web service so that as you add more Java code and regenerate the service, you can
redeploy and test iteratively.
In the example code:
• DeploymentName refers to the deployment name of the Enterprise Application, or the name
that appears in the Administration Console under the list of deployments.
- Source refers to the name of the Enterprise Application EAR file or exploded directory
that is being deployed. By default, the jwsc Ant task generates an exploded Enterprise
Application directory.
- AdminUser refers to administrative username.
- AdminPassword refers to the administrative password.
• AdminServerURL refers to the URL of the Administration Server, typically ://localhost:7001.
• ServerName refers to the name of the WebLogic Server instance to which you are deploying
THESE eKIT the Web Service.
MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 28
Overview of WebLogic Web Services
Administration Tasks
• Basic administration of Web services is very similar to the
administration of Java EE applications and modules.
• Tasks specific to Web services are:
– Viewing the WSDL of the Web service
– Viewing the SOAP handlers associated with the Web service

Oracle University and Egabi Solutions use only

– Configuring the WS-Policy files associated with a Web
service endpoint or its operations
– Creating a Web service security configuration

Copyright © 2009, Oracle. All rights reserved.

Overview of WebLogic Web Services Administration Tasks

When you compile and package a WebLogic Web service, the task packages it as part of an
enterprise application. The Web service itself is packaged inside the enterprise application as a Web
application WAR file, by default. However, if your JWS file implements a session bean then the Web
service is packaged as an EJB JAR file. Therefore, basic administration of Web services is very
similar to basic administration of standard Java EE applications and modules. These standard tasks
include:
• Installing the Enterprise application that contains the Web service
• Starting and stopping the deployed Enterprise application
• Configuring the Enterprise application and the archive file which implements the actual Web
service. You can configure general characteristics of the Enterprise application, such as the
deployment order, or module-specific characteristics, such as session time-out for Web
applications or transaction type for EJBs
• Creating and updating the Enterprise application’s deployment plan
• Monitoring the Enterprise application
• Testing the Enterprise application
The following administrative tasks are specific to Web services:
• Viewing the WSDL of the Web service
• Viewing the SOAP handlers associated with the Web service
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 29
Overview of WebLogic Web Services Administration Tasks (continued)
• Configuring the WS-Policy files associated with a Web service endpoint or its operations
• Creating a Web service security configuration
SOAP handlers, WS-Policy and Web service security will be discussed in the following lessons.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 30
Basics of WebLogic Server Administration
Console
Administration Console is:
• Used to manage:
– A WebLogic Server domain
– One or more WebLogic Server instances
– Deployed applications, including Web services

Oracle University and Egabi Solutions use only

• Hosted on the Administration Server, a special instance of
WebLogic Server
• A Web application, which can be accessed from any
supported Web browsers
– The URL of the Administration Console is
http://hostname:port/console.

Copyright © 2009, Oracle. All rights reserved.

Basics of WebLogic Server Administration Console

There are a variety of ways to administer Java EE applications and Web services that run on
WebLogic Server, such as Administration Console, Oracle Enterprise Manager Fusion Middleware
Control, WebLogic Scripting Tool, WebLogic Ant Tasks, and so on. Use the tool that best fits your
needs. This section will focus on the WebLogic Administration Console.
Administration Console providing a Web browser-based, graphical user interface you use to manage
a WebLogic Server domain, one or more WebLogic Server instances, clusters, and applications,
including Web services, that are deployed to the server or cluster.
One instance of WebLogic Server in each domain is configured as an Administration Server. The
Administration Server provides a central point for managing a WebLogic Server domain. All other
WebLogic Server instances in a domain are called Managed Servers. The Administration Server
hosts the Administration Console, which is a Web application accessible from any supported Web
browser with network access to the Administration Server.
Note: In a domain with only a single WebLogic Server instance, that server functions both as
Administration Server and Managed Server.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 31
Basics of WebLogic Server Administration Console (continued)
To invoke the Administration Console in your browser, enter the following URL:
http://hostname:port/console where
• hostname t 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.

Oracle University and Egabi Solutions use only

Managing Web Services by Using the Administration Console

To view and update the configuration information about a Web Service using the Administration
Console, click on the Deployments node in the left pane, the Web services packaged in the Enterprise
application should display in Deployments table in the right pane. Expand the application by clicking
the + node, and click on the name of the Web Service to view or update its configuration.
This slides shows how the HelloWSService Web service, packaged inside the HelloWS Enterprise
application, is displayed in the Deployments table of the Administration Console.
Note: It is not required that a Web service be installed as part of an Enterprise application; it can be
installed as just the Web Application or EJB. However, Oracle recommends that users install the
Web service as part of an Enterprise application.

A variety of Web
service
characteristics
can be managed
via the console.

Oracle University and Egabi Solutions use only

Web Services Configuration

This figure shows the Web services settings where you can view and update configuration
information of Web services, test and monitor the Web services.

Policy can be
configured using the
Configuration > WS-
Policy tab.

Oracle University and Egabi Solutions use only

Choose the port, or a
method and then add
specific policy.

Copyright © 2009, Oracle. All rights reserved.

Configuring a Policy
Web Service policy can be configured using the console rather then applied directly to a Web service
via an annotation. To add policy to a web service. Select the web service, choose its configuration tab
and then using the WS Policy tab add specific policy.

Web Services can be

tested and WSDL
examined via the
Testing tab.

Oracle University and Egabi Solutions use only

Testing via the Console

Web Services can be tested via the console by navigating to the Web service, selecting the testing tab
and then choosing the web service client.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 36
Quiz

The WebLogic Console can be used to:

1. Specify the Web service policy
2. Test Web Services
3. Deploy and undeploy Web services
4. All of the above

Oracle University and Egabi Solutions use only

Answer: 4

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 37
Summary

In this lesson, you should have learned how to:

• Describe JAX-WS specifications for packaging and
deployment of Web services
• Package and deploy POJO endpoints
• Package and deploy EJB endpoints

Oracle University and Egabi Solutions use only

• Illustrate the deployment process in the WebLogic Server
container
• Deploy Web services without deployment descriptors
• Use deployment descriptors to override the annotations
• Manage Web services by using WLS Administration
Console

Copyright © 2009, Oracle. All rights reserved.

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 6 - 38
Practice 6 Overview:
Packaging and Deploying Web Services
This practice covers the following topics:
• Deploying a packaged Web Service
• Creating and deploying a Web Service via Ant

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Fault and Exception Handling in JAX-WS Web
Services

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe SOAP faults
• Describe how SOAP fault messages are handled in
JAX-WS
• Describe the SOAP fault message structure

Oracle University and Egabi Solutions use only

• Explain JAX-WS mapping of Java exceptions to WSDL
faults and WSDL faults to Java exceptions
• List the steps for creating modeled faults
• Use JAX-WS fault handling for throwing and catching
exceptions

Copyright © 2009, Oracle. All rights reserved.

• During the processing of a request, if an error occurs, a

Web service generates a SOAP fault.
• SOAP faults:
– May be generated based on business logic errors or
unexpected conditions
– May be returned to the sender (request/response

Oracle University and Egabi Solutions use only

messaging)
– Stored (one-way)
• The SOAP specification defines the standard structure of a
fault within a SOAP message:
– Location within the SOAP envelope
– The contained information

Copyright © 2009, Oracle. All rights reserved.

What Are SOAP Faults?

If an error occurs while a Web service is processing a message, the client may have to be notified. In
such cases, due to the fact that a client application may be written on a different platform or
language, there must exist a standard, platform-independent mechanism for describing the error. The
SOAP specification defines SOAP faults for such situation. The specification describes its format
within the SOAP envelope as well as its contents. The end result is that when an error occurs in a
Web service, no matter what language the service is written in, a SOAP message containing a SOAP
fault will be used to communicate the error to the client.
SOAP faults are generated by receivers of a message. The receiver needs to send a SOAP fault back
to the sender only if the Request/Response messaging mode is used. In One-Way mode, the receiver
should generate a fault and may store it somewhere, but it must not attempt to transmit it to the
sender.

In JAX-WS, you can map java.lang.Exception to the

SOAP fault.
Java exceptions:
• Mapped to wsdl:fault messages are referred to as
Modeled faults

Oracle University and Egabi Solutions use only

– Java Web services that throw exceptions, when deployed,
produce wsdl:fault definitions in their WSDL file.
• Raised by an application or on behalf of an application, but
not mapped, are referred to as Unmodeled faults
Note: Modeled versus Unmodeled are convenience terms and
not industry standards.

Copyright © 2009, Oracle. All rights reserved.

Java and SOAP Faults

The WSDL specification provides a tag (wsdl:fault) for specifying fault messages. If the Java
exceptions can be mapped to a wsdl:fault message, we call this modeled fault because the
wsdl:fault message is predefined. But there are scenarios, such as exceptions resulting from
unanticipated run-time errors, that will unlikely have a corresponding wsdl:fault message and
need to be returned as generic SOAP faults.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 4
Unmodeled Faults

• Unmodeled faults:
– They are generated by JAX-WS when no business logic fault
is defined in WSDL.
– SOAP Fault elements are created in the response.
• Typical client-side Java exceptions include:
Often referred to as
– SOAPFaultException

Oracle University and Egabi Solutions use only

implicit or undeclared
– WebServiceException faults because they
are not shown in
– ExecutionException WSDL

Copyright © 2009, Oracle. All rights reserved.

Un-modeled Faults
Unmodeled faults are faults generated by JAX-WS ,when no corresponding exception is defined in
WSDL, such as JAX-WS run-time exceptions, NullPointerException.
There are three types of exceptions:
• SOAPFaultException and its relatives, used when the client receives an un-modeled fault
• WebServiceException, used in the JAX-WS APIs
• ExecutionException, used in asynchronous client programs

• SOAPFaultException:When the service throws an

unmodeled fault, the client receives a
SOAPFaultException.
• WebServicesException:The general-purpose
exception for the JAX-WS APIs
•

Oracle University and Egabi Solutions use only

ExecutionException
– In Asynchronous operation case
– Not a JAX-WS–specific exceptions
– In JRE concurrent library
java.util.concurrent.ExecutionException

Copyright © 2009, Oracle. All rights reserved.

Common Unmodeled Faults

• SOAPFaultException
If an invocation of the Web service returns a SOAP fault message that does not map to
wsdl:fault, JAX-WS converts this SOAP fault message, containing the information
relevant to the problem in the faultcode and faultstring fields, to an instance of
javax.xml.ws.soap.SOAPFaultException. The SOAPFaultException is a
protocol-specific exception. It extends javax.xml.ws.ProtocolException.
• WebServicesException
javax.xml.ws.WebServiceException is the general-purpose exception for the JAX-
WS APIs. When calls to JAX-WS defined Java classes fail, such as Service,
BindingProvider, and Dispatch, WebServiceException will be thrown.
• ExecutionException
java.util.concurrent.ExecutionException is used by JAX-WS’s asynchronous
client. This exception is thrown when the client tries to get the response from an asynchronous
call.

The SOAP <Fault> element is used to carry error and status

information within a SOAP message.
• The SOAP fault element appears as a child of the body
element.
• There can be only one fault entry.

Oracle University and Egabi Solutions use only

SOAP Fault Structure

A SOAP message that contains a Fault element in the Body is called a fault message. When a fault
message is generated, the Body of the SOAP message must contain only a single Fault element and
nothing else.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 7
SOAP 1.1 Fault

The SOAP 1.1 Fault element has the following subelements:

• Faultcode: The standard code used by software to
process a fault
• Faultstring: The human-readable description
• Faultactor: Information regarding the node that caused

Oracle University and Egabi Solutions use only

the fault
• Detail: Application-specific information such as the
exception that was thrown

Copyright © 2009, Oracle. All rights reserved.

SOAP 1.1 Fault

In SOAP 1.1, the Fault element itself must contain a faultcode element and a faultstring
element, and optionally faultactor and detail elements.
• The <faultcode> element provides information about the fault in a form that can be
processed by software. SOAP defines a small set of SOAP fault codes covering basic SOAP
faults, and this set can be extended by applications.
• The <faultstring> element provides information about the fault in a form intended for a
human reader.
• The <faultactor> element contains information about who caused the fault. Recall that a
SOAP message can be passed between multiple nodes before arriving at its ultimate
destination. Any of these components can generate a SOAP fault.
• The <detail> element allows application-specific information to be passed. This can contain
such information as what base type of exception was generated in the service. It must be
present if the contents of the <Body> element could not be successfully processed. The
<detail> element must not be used to carry information about error information belonging
to header entries. Detailed error information belonging to header entries must be carried within
header entries.

There are four faultcode defined in the SOAP 1.1

specification:
• VersionMismatch: An invalid namespace found in a
SOAP Envelope element
• MustUnderstand: The SOAP header entry was not
understood by a processing party.

Oracle University and Egabi Solutions use only

• Client: The message was incorrectly formed by the client
for processing to be completed.
• Server: There was a problem with the server so the
message could not proceed.

Copyright © 2009, Oracle. All rights reserved.

SOAP 1.1 Standard Fault Codes

The SOAP 1.1 specification defines four standard faultcodes:
• VersionMismatch: The specification defines that for versioning, the message must have an
envelope element associated with the http://schemas.xmlsoap.org/soap/envelope namespace. If
a SOAP message is received in which the SOAP envelope is associated with a namespace other
than http://schemas.xmlsoap.org/soap/envelope, a VersionMismatch fault must be raised.
• MustUnderstand: A SOAP header element may be defined with a mustUnderstand attribute
set to 1 or 0. If the attribute is set to 1, any receiving application must be able to be recognized
by the SOAP processor; otherwise a MustUnderstand fault must be raised.
• Client: If a message is improperly formed or is missing information for a recipient to
complete processing, a fault can be raised with a Client faultcode. For example, the message
could lack the proper authentication or payment information. It is generally an indication that
the message is not to be resent without change.
• Server: If the recipient cannot complete processing due to reasons not attributable to the
client (the client’s message is properly formed and all necessary information is complete) the
recipient can raise a fault with a faultcode of Server.

<?xml version= 1.0 ?>

<soap:Envelope
xmlns:soap='http://schemas.xmlsoap.org/soap/envelope'>
<soap:body>
<soap:Fault>
<faultcode>soap:VersionMismatch</faultcode>
<faultstring xml:lang='en'>

Oracle University and Egabi Solutions use only

Message was not SOAP1.1 compliant
</faultstring>
<faultactor>
http://sample.org.com/jws/authnticator
</faultactor>
</soap:Fault>
</soap:Body>
</soap:Envelope>

Copyright © 2009, Oracle. All rights reserved.

SOAP 1.1 Fault Message Example

The above example shows a SOAP 1.1 receiver generates VersionMismatch fault when it
receives SOAP 1.2 message, as it doesn’t recognize the name namespace of the SOAP message’s
Envelope element.
In this example, an intermediary node in the message path, the authentication node, did not recognize
the name namespace of the SOAP message’s Envelope element, so it generates
VersionMismatch fault.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 10
SOAP 1.2 Faults

• The structure of a SOAP fault has changed in SOAP 1.2.

• All Fault elements are now namespace qualified.
• The mapping between SOAP 1.1 and SOAP 1.2 faults are:

SOAP 1.1 SOAP 1.2

Oracle University and Egabi Solutions use only

faultcode e:Code, e:Value,
e:Subcode
faultstring e:Reason

faultactor e:Node, e:Role

detail e:Detail

Copyright © 2009, Oracle. All rights reserved.

SOAP 1.2 Faults

The SOAP 1.2 faults are structured in a different manner compared to SOAP 1.1. All fault elements
are now namespace qualified; faultstring is renamed to Reason, faultactor is renamed to
Role and faultcode is renamed to Code. But this code element can contain a hierarchy of fault
codes. The fault elements may contain extra sub elements other than SOAP 1.1.
• Node specifies which SOAP node generated the fault message.
• Role specifies what role this node was playing when the fault occurred.
• Detail is free format XML structure to supply any detailed fault information.

The standard fault codes for SOAP 1.2 fault messages are:
• VersionMismatch
• MustUnderstand
• Sender: Renamed from SOAP 1.1 Client
• Receiver: Renamed from SOAP 1.1 Server

Oracle University and Egabi Solutions use only

• DataEncodingUnknown: Received message uses an
unrecognized value of the encoding style.

Copyright © 2009, Oracle. All rights reserved.

SOAP 1.2 Fault Codes

SOAP 1.2 provides a new fault code DataEncodingUnknown. You can mention encoding styles
for SOAP header blocks and child elements of the SOAP body. If the mentioned encoding style by
the client is not supported by the Web services server, then the server sends out this error. To fix this
error, you either remove the encoding style attribute or find out the encoding styles supported by the
Web services server you are talking to.

<env:Envelope xmlns:env= http://www.w3.org/2003/05/soap-envelope >

<env:Body>
<env:Fault>
<env:Code> (required)
<env:Value> (required)
env:VersionMismatch | env:MustUnderstand | Sender
| DataEncodingUnknown | Receiver
</env:Value>
<env:Subcode> (optional)
<env:Value>text</env:Value> (required)

Oracle University and Egabi Solutions use only

</env:Subcode>
</env:Code>
<env:Reason> (required)
<env:Text xml:lang= languageCode >text<env:Text> (required)
...
</env:Reason>
<env:Role>http://example.com/processingRole</env:Role> (optional)
<env:Detail ...> (optional)
... (any XML structure)
</env:Detail>
</env:Fault>
</env:Body>
</env:Envelope>

Copyright © 2009, Oracle. All rights reserved.

SOAP 1.2 Fault Message Structure

The above code shows the structure of SAOP1.2 fault message:
• Fault must be the only child element of Body.
• Code and Reason are required child elements. Role and Detail are optional child elements.
• Code, Reason, Role and Detail must appear in the predefined order.
• Code.Value is a required element. It must contain one of the five predefined values.
• Code.Subcode is an optional element.
• Subcode can have a recursive structure.
• The first Reason.Text element is required. Additional Reason.Text elements are
optional.
• Reason.Text[@xml:lang] is a required attribute, which specifies an XML standard
language code.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 13
SOAP 1.2 Fault Message Example
<?xml version='1.0' ?>
<env:Envelope xmlns:env= http://www.w3.org/2003/05/soap-envelope >
<env:Body>
<env:Fault>
<env:Code>
<env:Value>env:Sender</env:Value>
<env:Subcode>
<env:Value>rpc:BadArguments</env:Value>
</env:Subcode>
</env:Code>

Oracle University and Egabi Solutions use only

<env:Reason>
<env:Text xml:lang= en-US >Processing error</env:Text>
</env:Reason>
<env:Detail>
<e:myFaultDetails
xmlns:e= http://travelcompany.example.org/faults >
<e:message>Name does not match card number</e:message>
<e:errorcode>999</e:errorcode>
</e:myFaultDetails>
</env:Detail>
</env:Fault>
</env:Body>
</env:Envelope>

Copyright © 2009, Oracle. All rights reserved.

SOAP 1.2 Fault Message Example

Above is a SOAP 1.2 fault message, an example #6a from the SOAP 1.2 specification.

• Java exceptions are translated into a SOAP fault and then

sent to a client informing it that the Web method invocation
failed.
• JAX-WS handles SOAP fault processing during SOAP
protocol binding:

Oracle University and Egabi Solutions use only

SOAP Web
Protocol Service
SOAP Binding Java/
Request Endpoint SEI
XML
Servlet SOAP Fault Binding
client

Processing Other
classes
SOAP Business exceptions
Response translated to specific,
JAX-WS Runtime Services if possible, faults.

Copyright © 2009, Oracle. All rights reserved.

JAX-WS Fault Processing Infrastructure

Fault processing is important because any exception thrown by your Java code needs to get translated
into a SOAP fault that can be sent back to the client informing it of why the Web service invocation
failed. JAX-WS provides SOAP fault processing in the SOAP protocol binding.
JAX-WS specifies a SOAP binding for SOAP message processing. The SOAP binding maps handler
and service exceptions to SOAP fault messages. This feature saves you a lot of time and energy by
eliminating the need to write code that maps your service exceptions to SOAP faults. If you want to
customize the fault handling process, you can do so with JAX-WS handlers, which will be discussed
later in this course.
This section will show you how to leverage the JAX-WS fault processing infrastructure.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 15
Quiz

A Java exception that is not explicitly thrown by a method

generates a modeled SOAP fault.
1. True
2. False

Oracle University and Egabi Solutions use only

Answer: 2

Start from Java:

Client Server
MyService.wsdl
WSDL to Java tool MyService.java

Oracle University and Egabi Solutions use only

CustomException
SEI Fault related artifacts
MyException.java
FaultBean
Impl Class
MyService.wsdl
Exception …
PortClient <wsdl:fault ... />

Client artifacts

Copyright © 2009, Oracle. All rights reserved.

Creating Modeled Faults

WSDL files define SOAP faults with tag<wsdl:fault>. JAX-WS WSDL to Java mapping binds
wsdl:fault messages to generate subclasses of java.lang.Exception. When you generate
client artifacts from a WSDL, these mapped exception classes are also generated.
JAX-WS delegates the schema generation to JAXB. The data in a fault is defined in the schema, so
the JAXB generator generates the Java bean containing the exception's data.

SIB: HelloWorld.java
@WebService Results in modeled fault.
public class HelloWorld {

public String sayHello(String s) throws MissingName {

String result = "hello";

if ( s == null || s.isEmpty()) { // modeled fault
throw new MissingName();

Oracle University and Egabi Solutions use only

}
return result + " " + s; Thrown explicitly
}

Exception class: MissingName.java

public class MissingName extends Exception {
public MissingName() {
super("Your name is required.");
}

Copyright © 2009, Oracle. All rights reserved.

Web Service and Exception

The code examples in the slide show the Web service HelloWorld will throw a custom exception –
MissingName if the request message is empty.

HelloWorldService.wsdl
<?xml version="1.0" encoding="UTF-8"?> JAXB uses the type
<wsdl:definitions ...> definition in schema to
<wsdl:types> map create
<schema xmlns=...> MissingName.java
<xsd:complexType name="sayHello"> that has a “Message”
<xsd:sequence> property and extends
<xsd:element name="arg0" type="xsd:string"/>
exception.
</xsd:sequence>

Oracle University and Egabi Solutions use only

</xsd:complexType>
<xsd:element name="sayHello" type="tns:sayHello"/>
...
<xsd:complexType name="MissingName">
<xsd:sequence>
<xsd:element name="Message" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="MissingName" type="tns:MissingName"/>
</schema>
</wsdl:types>
...

Copyright © 2009, Oracle. All rights reserved.

Web Service WSDL with Fault Message

The code snippet shows the WSDL file generated from the annotated Web service. The
HelloWorld Web service uses the document/literal wrapped style of WSDL, so the element
MissingName defined here is the wrapper element that contains the parameters. The parameters
contained in the wrapper elements get mapped to method parameters in the SEI using the JAXB
XML Schema to Java mapping. In this case particularly, a class file named MissingName.java
is generated by the tool (JDeveloper). MissingName.java is a JavaBean that JAX-WS refers to
as a fault bean that has a Message property.

<wsdl:message name="MissingName">
<wsdl:part name="MissingName" element="tns:MissingName"/>
</wsdl:message>
<wsdl:portType name="HelloWorld"> Gets mapped to the
<wsdl:operation name="sayHello"> exception class:
<wsdl:input message="tns:sayHelloInput“ .../> MissingName.java
<wsdl:output message="tns:sayHelloOutput“ .../>
<wsdl:fault name="MissingName" message="tns:MissingName"/>
</wsdl:operation>
</wsdl:portType>

Oracle University and Egabi Solutions use only

<wsdl:binding name="HelloWorldSoapHttp" type="tns:HelloWorld">
<soap:binding style="document“
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="sayHello"> Gets mapped to the
<soap:operation soapAction=""/> "throws MissingName"
... clause of the sayHello
<wsdl:fault name="MissingName"> method declaration
<soap:fault name="MissingName" use="literal“
encodingStyle=""/>
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
...

Copyright © 2009, Oracle. All rights reserved.

Web Service WSDL with Fault Message (continued)

wsdl:fault is defined inside the wsdl:portType definition. Since the method signatures in
the SEI get mapped from the operations defined on the wsdl:portType, each wsdl:fault gets
mapped to a thrown exception. In this case, the single wsdl:fault maps to the "throws
MissingName" clause of the sayHello method declaration.
The wsdl:message referred to by a wsdl:fault gets mapped to a class that extends
java.lang.Exception. In this example, the wsdl:message named MissingName gets
mapped to the MissingName.java class. This is a wrapper exception class for the fault bean.

MissingName.java
package com.library.ws.mfclient.type

import...
@XmlAccessorType(XmlAccessType.FIELD) Used to contain the
@XmlType(name = "MissingName", propOrder = { “content” of the fault
"message" and used “inside” the
}) associated generated
public class MissingName { client-side exception.

Oracle University and Egabi Solutions use only

@XmlElement(name = "Message", required = true)
protected String message;

public String getMessage() {

return message;
}

public void setMessage(String value) {

this.message = value;
}
}

Copyright © 2009, Oracle. All rights reserved.

FaultBean Class (Generated JavaBean)

The above code is from MissingName.java. JAX-WS delegates the schema generation to JAXB, so
this file is the result of applying the JAXB XML Schema to Java mapping to the schemas defined in
the wsdl:types section. Note that the root package of this class file is
com.library.ws.mfclient.type, which is different from the exception class (see next
slide).

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 21
Exception Class

MissingName.java
Package com.library.ws.mfclient

import javax.xml.ws.WebFault;

@WebFault(faultBean="com.library.ws.mfclient.type.MissingName",
targetNamespace="http://ws.library.com/", name="MissingName")
public class MissingName
extends Exception {

Oracle University and Egabi Solutions use only

private com.library.ws.mfclient.type.MissingName faultInfo;

public MissingName(String message,

com.library.ws.mfclient.type.MissingName faultInfo){
super(message);
this.faultInfo = faultInfo;
This object contains
}
the exception
message Object.

Copyright © 2009, Oracle. All rights reserved.

Exception Class
JAX-WS uses the @WebFault annotation to identify this class as a exception. It is a wrapper class
for the fault bean.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 22
Exception Class

public MissingName(String message,

com.library.ws.mfclient.type.MissingName faultInfo,
Throwable t) {
super(message,t);
this.faultInfo = faultInfo;
}

public com.library.ws.mfclient.type.MissingName getFaultInfo() {

Oracle University and Egabi Solutions use only

return faultInfo;
}

public void setFaultInfo(com.library.ws.mfclient.type.MissingName

faultInfo) {
this.faultInfo = faultInfo;
}
}

Copyright © 2009, Oracle. All rights reserved.

HelloWorld.java (SEI)
@WebService(wsdlLocation="HelloWorldService.wsdl", ...)
@XmlSeeAlso(
{ com.library.ws.faultclient.ObjectFactory.class })
public interface HelloWorld
{
@WebMethod
...
public String sayHello(@WebParam(targetNamespace="", name="arg0")

Oracle University and Egabi Solutions use only

String arg0)
throws com.library.ws.faultclient.MissingName;
}

Copyright © 2009, Oracle. All rights reserved.

Client-Side Service Implementation

The code snippet is the SEI generated from the target WSDL. SEI is mapped from
wsdl:portType by using the JAX-WS WSDL to Java mapping.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 24
Client

HelloWorldPortClient.java
public class HelloWorldPortClient
{
@WebServiceRef
private static HelloWorldService helloWorldService;

public static void main(String [] args)

{
helloWorldService = new HelloWorldService();

Oracle University and Egabi Solutions use only

HelloWorld helloWorld = helloWorldService.getHelloWorldPort();
// Add your code to call the desired methods.
try {
String result = helloWorld.sayHello("");
System.out.println("Result: "+result);
} catch (MissingName e) {
System.err.println("MissingName: msg='"+e.getMessage()+ "',
code="+e.getFaultInfo().getCustomErrorCode());
e.printStackTrace();
}
}
}

Copyright © 2009, Oracle. All rights reserved.

Client
The above code from HelloWorldPortClient class is used to create a proxy instance, and
invoke the sayHello method of HelloWorld Web service. Note that the code that exercises the
sayHello method has catch blocks to handle any MissingName exceptions that might get
thrown.

On the server side:

1. Create a custom exception class.
2. Update the Web service to throw an exception.
3. Generate the Web service WSDL file.
On the client side:

Oracle University and Egabi Solutions use only

1. Import the Web service WSDL file.
2. Generate client artifacts by using a WSDL to the Java
mapping tool—for example, clientgen.
3. Provide implementation to access the method with
exceptions thrown by the remote Web service.
4. Package and deploy.

Copyright © 2009, Oracle. All rights reserved.

Creating Modeled Faults

This slide lists the steps for creating modeled faults starting from Java.

SIB: HelloWorld.java
@WebService
public class HelloWorld {

public String sayHello(String s) throws MissingName {

String result = "hello";

if ( s == null || s.isEmpty()) { // modeled fault
throw new MissingName();

Oracle University and Egabi Solutions use only

} else if (s.equalsIgnoreCase("abc")) { // unmodeled fault
throw new RuntimeException(“Please enter a name.");
}
return result + " " + s;
}

Copyright © 2009, Oracle. All rights reserved.

Implicit Fault Example on the Server Side

The code in the slide is the service endpoint implementation class. In addition to throwing a
MissingName exception (modeled fault) when user input is empty, it will throw a run-time
exception (unmodeled fault) when the input is “abc”.

HelloWorldPortClient.java
public class HelloWorldPortClient
{
@WebServiceRef
private static HelloWorldService helloWorldService;

public static void main(String [] args)

{
helloWorldService = new HelloWorldService();

Oracle University and Egabi Solutions use only

HelloWorld helloWorld = helloWorldService.getHelloWorldPort();

// Add your code to call the desired methods.

String result = helloWorld.sayHello("abc");

System.out.println("result is: "+result);
}
}

Copyright © 2009, Oracle. All rights reserved.

Implicit Fault Example on the Client Side

This slide shows the code implementation on the client to invoke the remote Web service that throws
an implicit exception.

Oracle University and Egabi Solutions use only

Exceptions in the Log File

Above screenshot is the log file showing the exceptions thrown when you invoke the Web service
from the client side. The client side sees the SOAPFaultException, which is caused by the
server-side’s RuntimeException.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 29
Quiz

Run-time exceptions are unmodeled and raised on the client

side via SOAPFaultException.
1. True
2. False

Oracle University and Egabi Solutions use only

Answer: 1

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 30
Summary

In this lesson, you should have learned how to:

• Describe what SOAP faults are
• Describe the SOAP fault message structure
• How SOAP fault messages get handled in JAX-WS
• Map Java exceptions to WSDL faults and WSDL faults to

Oracle University and Egabi Solutions use only

Java exceptions
• Create modeled faults
• Use JAX-WS fault handling for throwing and catching
exceptions

Copyright © 2009, Oracle. All rights reserved.

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 7 - 31
Practice 7 Overview:
Handling Web Service Exceptions
This practice covers the following topics:
• Working with exceptions: Services
• Working with exceptions: Client

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe the benefits of message-level security
• Illustrate the relationships of WS-Security specifications
• Explain how SAML is used with WS-Security to secure
messages

Oracle University and Egabi Solutions use only

• Describe WLS WS-Security features
• Use WLS prepackaged WS-Policy files with annotations to
enforce security
• List the steps for configuring a message-level security
• Invoke a message-secured Web service
• Describe how to secure WLS Web services by using
Oracle Web Services Manager WS-Security policies

Copyright © 2009, Oracle. All rights reserved.

Objectives
This lesson discusses how to use WS-Security and WS-Policy to enforce security on the message
level for the Web Services.

To secure your Web Service, you need to configure one or two

different types of security:
• Transport-level security: Secures connections between the
service consumer and the provider
• Access control security: Specifies which roles are allowed
to access what Web Services

Oracle University and Egabi Solutions use only

• Message-level security: Secure a message throughout its
journey between the sender and the intended recipient

Copyright © 2009, Oracle. All rights reserved.

Overview of Web Services Security

Web services security covers a lot of territory. It is usually divided into smaller, more manageable
chunks:
Transport-level security
Security begins at the transport or wire level. It allows the client and Web service to communicate
securely across network by providing secure connection.
Message-level security
Message level security is end-to-end security. It means that the message is secured throughout its
journey between sender and intended recipient. In Web service communication the message can
travel through various entities before it reached its intended recipient. The message will be secured
during this journey if message level security is applied.
Access control security
Web services provide clients with access to resources. If a resource is secured, then a client needs the
appropriate credentials to gain access. Access control security provides both authentication and
authorization.

• Transport-level security secures the connection between

the client and Web service with Secure Sockets Layer
(SSL).
• SSL is the most widely used transport-level data-
communication protocol providing:
– Authentication (the communication is established between

Oracle University and Egabi Solutions use only

two trusted parties)
– Confidentiality (the data exchanged is encrypted)
– Message integrity (the data is checked for possible
corruption)
• Limitations:
– Point-to-point, only secures the connection
– Cannot encrypt selected parts of the message

Copyright © 2009, Oracle. All rights reserved.

Transport-Level Security
Transport-level security uses SSL to secure the connection between a client application and the Web
Service. SSL provides secure connections by allowing two applications connecting over a network to
authenticate the other's identity and by encrypting the data exchanged between the applications.
Transport-level security, however, secures only the connection itself. This means that if there is an
intermediary between the client and server, such as a router or message queue, the intermediary gets
the SOAP message in plain text. When the intermediary sends the message to a second receiver, the
second receiver does not know who the original sender was and may not use SSL. Additionally, the
encryption used by SSL is "all or nothing": either the entire SOAP message is encrypted or it is not
encrypted at all. There is no way to specify that only selected parts of the message be encrypted.

• Message-level security:
– Specifies whether the SOAP messages between a client
application and the Web service should be:
— Digitally signed (to ensure data integrity)
— Encrypted (to ensure confidentiality)
– Assures authentication, by requiring username, X.509, or

Oracle University and Egabi Solutions use only

SAML tokens
• Security data built in to the XML message text
• Advantages:
– Is end-to-end security
– Allows specific parts of the message be signed and
encrypted

Copyright © 2009, Oracle. All rights reserved.

Message-Level Security
Message-level security specifies whether the SOAP messages between a client application and the
Web Service should be digitally signed or encrypted, or both. It also can specify a shared security
context between the Web Service and client in the event that they exchange multiple SOAP
messages. You can use message-level security to assure:
• Confidentiality, by encrypting message parts
• Integrity, by digital signatures
• Authentication, by requiring username, X.509, or SAML tokens
Security data are built in to the XML message text, usually as additional SOAP header fields.
Message-level security includes all the security benefits of SSL, but with additional flexibility and
features. Message-level security is end-to-end, which means that a SOAP message is secure even
when the transmission involves one or more intermediaries. The SOAP message itself is digitally
signed and encrypted, rather than just the connection. And finally, you can specify that only
individual parts or elements of the message be signed, encrypted, or required.

• The goal of Web Services Security (WS-Security) is to

provide comprehensive end-to-end security at SOAP
message level.
• WS-Security:
– Specifies rules to ensure:

Oracle University and Egabi Solutions use only

— Authentication, using security tokens
— Confidentiality, using XML Encryption specification
— Integrity, using XML Signature specification
– Supports multiple security tokens for authentication:
— Username/password
— X.509 certificate
— Kerberos ticket
— Security Assertion Markup Language (SAML)

Copyright © 2009, Oracle. All rights reserved.

WS-Security Overview
Web Services Security (WS-Security) specification specifies the Web services security at message
level. IBM and Microsoft defined the specification, which is OASIS approved, “Web Services
Security: SOAP Message Security”.
WS-Security is a collection of protocols that specify how different levels of security can be enforced
on messaging in SOAP-based web services. It is meant to provide comprehensive end-to-end
message content security and not just transport-level security. The security matters are not delegated
to the transport level but rather handled directly through an appropriate security API.
WS-Security defines SOAP extensions to implement client authentication, data integrity and data
confidentiality on the message level.
• Data confidentiality is to make sure that the data can't be read during transit, by means of
message encryption. WS-Security uses the XML Encryption specification to encrypt portions of
the SOAP messages. Any portions of SOAP messages, including headers and body blocks may
be encrypted.
• Data integrity ensures the recipient that the data that application receives has not been altered
during transit. It is implemented by XML Signature in WS-Security. XML Signature binds the
sender's identity (or "signing entity") to an XML document. Signing and signature verification
can be done using asymmetric or symmetric keys.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 6
WS-Security Overview (continued)
• Authentication can be done using security tokens. WS-Security allows you to use any security
token you choose to use. Explicitly defined are three different options:
- Username/password authentication in case of custom authentication
- Binary authentication tokens in the form of Kerberos tickets or X.509 certificates
- Security Assertion Markup Language (SAML)
WS-Security defines how to attach XML Signature and XML Encryption headers to SOAP
messages, as well as a way of associating security tokens with a message.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 7
What Is SAML?

Security Assertion Markup Language (SAML) is:

• An open framework for sharing security information on the
Internet through XML documents
• The dominant standard for federated Identity
• A protocol that does not define any new approaches to

Oracle University and Egabi Solutions use only

Authentication/Authorization; it just generates appropriate
tokens/assertions after the authentication occurs

Copyright © 2009, Oracle. All rights reserved.

What Is SAML?
With WS-Security you can use any security token you want. SAML is one of the most interesting
security tokens. It is an open framework for sharing security information on the Internet through
XML documents. It enables different security services systems to interoperate.
SAML is the dominant standard for Federated Identity. Federated Identity uses information from
multiple, independently administered sources to implement security services such as authentication
and authorization.
SAML specification defines a standard, XML-based approach for passing security tokens defining
authentication and authorization rights. Originally, SAML was targeted more toward distributed
authentication and single sign-on (SSO), but those concepts are also central to Web services security
now.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 8
SAML Architecture

SAML includes three parts:

• Assertions: How you define authentication and
authorization information
• Protocol: How you ask (SAML Request) and get (SAML
Response) the assertions you need

Oracle University and Egabi Solutions use only

• Bindings and Profiles: How SAML assertions ride “on”
(Bindings) and “in” (Profiles) industry-standard transport
and messaging frameworks

Copyright © 2009, Oracle. All rights reserved.

SAML Architecture
SAML includes three parts:
• SAML Assertion: A set of statements made by a SAML authority. It includes:
- Authentication statements
- Attribute statements
- Authorization statements
• SAML Protocol: SAML defines a request/response protocol for obtaining assertions
• SAML Bindings and Profiles: How SAML assertions ride “on” (Bindings) and “in”
• (Profiles) industry-standard transport and messaging frameworks.
- Bindings: A binding details how the SAML protocol maps onto transport and messaging
protocols.
- Profiles: Derived from use cases, they are technical descriptions of specific flows of
assertions and protocol messages.
The full SAML specification is used in browser-based federation cases. However, Web services
security systems only use SAML assertions. The protocol and bindings are taken care of by WS-
Security and the transport protocol, for example HTTP.

• WS-Security and SAML work together:

– WS-Security defines how you insert the information into a
SOAP envelope.
– SAML defines what the security information is.
• SAML Token Profile 1.1 specifies how SAML assertions
can be used for Web Services security:

Oracle University and Egabi Solutions use only

– WS-Security allows SAML assertions to be placed inside a
SOAP header.
– SAML Token Profile 1.1 is supported only through WS-
SecurityPolicy.

Copyright © 2009, Oracle. All rights reserved.

WS-Security and SAML

WS-Security allows SAML assertions to be placed inside a SOAP header, laying the foundations of
SSO for Web services.
SAML has already adopted WS-Security as the appropriate method for "binding" SAML assertions
into SOAP messages.
WS-Security is the messaging language; SAML is the security language.
SAML Token Profile 1.1 is part of the core set of WS-Security standards, and specifies how SAML
assertions can be used for Web Services security. SAML assertions and references to assertion
identifiers are contained in the WS-Security Header element, which in turn is included in the SOAP
envelope Header element (described in the WS-Security SAML Token Profile).

• WebLogic Server supports SAML Token Profile 1.1,

including support for SAML 2.0 and SAML 1.1 assertions.
• WebLogic Server allows you to use:
– SAML tokens server-to-server
– SAML tokens from a stand-alone client via WS-Trust
(supported under JAX-RPC only)

Oracle University and Egabi Solutions use only

WebLogic’s Support for SAML Token

In the preceding examples, users use username tokens to authenticate themselves. Because
WebLogic Server implements the SAML Token Profile 1.1 of the Web Services Security
specification, users can also use SAML tokens in the SOAP messages to authenticate themselves
when invoking a Web Service operation.
Use of SAML tokens works server-to-server. This means that the client application is running inside
of a WebLogic Server instance and then invokes a Web service running in another WebLogic Server
instance using SAML for identity. Because the client application is itself a Web Service, the Web
services security runtime takes care of all the SAML processing.
In addition to this server-to-server usage, you can also use SAML tokens from a standalone client via
WS-Trust. But for this release, this feature is only supported under JAX-RPC.
For more information about using SAML tokens to secure messages, see Configuring Message-Level
Security: Using Security Assertion Markup Language (SAML) Tokens For Identity of Oracle®
Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server 11g Release 1
(10.3.1)

Client WS-Security Server WS-Security

SOAP SOAP
message interceptor interceptor message

Check Check
Sign Encrypt Add auth Decrypt
auth signature
token
token

Oracle University and Egabi Solutions use only

Check Encrypt Sign
Decrypt
signature
SOAP SOAP
message message
Transport
HTTP, JMS

Copyright © 2009, Oracle. All rights reserved.

WS-Security Architecture
The slide displays the WS-Security architecture. The WS-Security architecture is segregated into two
parts: client WS-Security interceptor and server WS-Security interceptor. An interceptor is a prebuilt
JAX-WS handler that implements all the WS-Security features, such as digital signatures, encryption,
and authentication.
Whenever a client has to send a SOAP request message to the server, the SOAP request message is
intercepted by the client interceptor. The interceptor adds the authentication, signature, and
encryption elements to the SOAP message, and then forwards the message to the Web service.
On receiving the message from the client, the Web service invokes the server interceptor that verifies
the signatures of the incoming SOAP message. If the signature is valid, the interceptor decrypts and
authenticates the message and forwards it to the Web service endpoint implementation. After
processing the client’s request, the Web service generates a SOAP response message that includes
the WS-Security header with integrity and confidentiality information. The message is then sent back
to the client.
On receiving the SOAP response message from the server, the client interceptor interprets the header
and delivers it to the client application.

WS- WS-
WS-Secure Conversation
Federation Authorization

WS-Policy WS-Trust WS-Privacy

Oracle University and Egabi Solutions use only

WS-Security

SOAP Specification

Not supported in WLS Web Services and not adopted by the industry

Copyright © 2009, Oracle. All rights reserved.

WS-Security Stack
As shown above, the WS-Security is a family of specifications designed to augment transport-level
security by providing a unified, transport-neutral, end-to-end framework for higher levels of security
such as authorization. There are two layers above WS-Security: the first layer consists of WS-Policy,
WS-Trust, and WS-Privacy; the second layer of WS-Secure Conversation, WS-Federation, and WS-
Authorization builds upon this first layer.
First Layer
• WS-Policy: This specification describes general security capabilities, constraints, and policies.
For example, a WS-Policy assertion could stipulate that a message requires security tokens or
that a particular encryption algorithm be used.
• WS-Trust: This specification deals primarily with how security tokens are to be issued and
exchanged.
• WS-Privacy: Explains how services can enforce privacy policies. The specification also covers
how a service can determine whether a requester intends to follow such policies.
Second Layer
• WS-Secure Conversation: Secures web service conversations across different sites and,
therefore, across different security contexts and trust domains. The specification focuses on
how a security context is created and how security keys are derived and exchanged.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 13
WS-Security Stack (continued)
• WS-Federation: The specification addresses the challenge of managing security identities in a
heterogeneous security environment. It describes how to maintain a single, authenticated
identity across different platforms and organizations.
• WS-Authorization: Defines how Web services manage authorization data and policies.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 14
Quiz

Both transport-level and message-level securities provide:

1. Authentication
2. Data integrity
3. Single sign-on
4. Data encryption

Oracle University and Egabi Solutions use only

Answers: 1, 2, 4

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 15
Quiz

WS-Security is to provide security at:

1. Wire-level
2. Access control
3. Message-level

Oracle University and Egabi Solutions use only

Answer: 3

WS-Policy:
• Defines a framework for allowing Web Services to express
their constraints and requirements
• Provides a model and syntax for describing the policies of
a Web service.

Oracle University and Egabi Solutions use only

• Is broken up into several subsidiary specifications:
– WS-Policy: Defining a grammar that explains Web services
policies
– WS-PolicyAttachment: Associates policies to Web services
– WS-PolicyAssertions: Defines a set of general policy
assertions

Copyright © 2009, Oracle. All rights reserved.

WS-Policy Overview
WS Policy is used by Web services primarily to specify requirements that clients must satisfy in
order to use the Web service. The requirements cover security/encryption, transportation protocol
and so on. Basically, WS-policy provides the Web service an ability to specify requirements beyond
that normally definable by its WSDL specification. A policy consists of a set of rules written in XML
that are either incorporated directly into or referenced by the Web service's WSDL specification.
Web services Policy Framework, called as WS-Policy provides a model and syntax for describing the
policies of a web service.
WS-Policy includes the following specifications:
• WS-Policy - Defines a grammar which explains Web services policies
• WS-PolicyAttachment - Defines policy around using attachments
• WS-PolicyAssertions - Defines a set of general policy assertions
The constraints and requirements of Web services are expressed as policy assertions.
• WS-SecurityPolicy - Defines a set of security policy assertions for use with the WS-Policy
framework describing how messages are secured

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 17
Policy Assertion

• Policy assertion:
– Is a basic unit representing individual requirement in a policy
– Is domain specific (security, reliability)
• Service providers use a policy assertion to convey a
condition under which they offer a Web service.

Oracle University and Egabi Solutions use only

• An example of policy expression:
<Policy>
<wsp:TextEncoding Encoding="iso-8859-5" />
</Policy>

Copyright © 2009, Oracle. All rights reserved.

Policy Assertion
A policy assertion is a piece of service metadata representing an individual requirement, capability,
or other property of a behavior. Assertions are domain (security, reliability and transaction) specific
and the details are specified in separate specifications. Service providers use a policy assertion to
convey a condition under which they offer a Web service. A policy-aware client can recognize policy
assertions and engage these behaviors automatically.
The policy expression (XML form of the policy) in the above example consists of a Policy main
element and a child element wsp:TextEncoding. Child elements of the Policy element are
policy assertions. This example represents a specific policy assertion for text encoding. A policy-
aware client can recognize this policy assertion, engage text encoding automatically.
Note: The prefix wsp is used here to denote the Web Services Policy XML Namespace.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 18
Policy Operators

There are three policy operators for combining policy

assertions:
• All: All the behaviors represented by the assertions are
required.
• Policy: Is a synonym for All

Oracle University and Egabi Solutions use only

• ExactlyOne: Requires exactly one of the behaviors
represented by the assertions
<All>
<wsp:TextEncoding Encoding="iso-8859-5" />
<wsap:UsingAddressing />
<ExactlyOne>
<wsp:TransportBinding>...</wsp:TransportBinding>
<wsp:AsymmetricBinding>...</wsp:AsymmetricBinding >
</ExactlyOne>
</All>

Copyright © 2009, Oracle. All rights reserved.

Policy Operators
Policy assertions can be combined in different ways to express consistent combinations of behaviors
(capabilities and requirements). There are three policy operators for combining policy assertions:
Policy, All and ExactlyOne.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 19
Sample of a Policy File
<wsp:Policy xmlns:wsp=“http://schemas.xmlsoap.org/ws/2004/09/policy”
xmlns:wsap=“...” xmlns:ap=“...” >
<All>
<wsp:TextEncoding Encoding="iso-8859-5" />
<wsap:UsingAddressing />
<ExactlyOne>
<wsp:TransportBinding>
<Policy>
<sp:TransportToken>
<Policy>

Oracle University and Egabi Solutions use only

<sp:HttpsToken>
<Policy> <sp:HttpDigestAuthentication /> </Policy>
</sp:HttpsToken>
</Policy>
</sp:TransportToken>
<sp:AlgorithmSuite>
<Policy> <sp:Basic256Rsa15/> </Policy>
</sp:AlgorithmSuite>
</Policy>
</wsp:TransportBinding>
<wsp:AsymmetricBinding>...</wsp:AsymmetricBinding >
</ExactlyOne>
</All>
</wsp:Policy>

Copyright © 2009, Oracle. All rights reserved.

Sample of a Policy File

The above example use a nested policy expression to enumerate the dependent behaviors for a Web
Service interaction. The sp:TransportToken is a nested policy assertion of the
sp:TransportBinding policy assertion. The sp:TransportToken assertion requires the
use of a specific transport token and further qualifies the behavior of the sp:TransportBinding
policy assertion.

• WS-SecurityPolicy defines a set of security policy

assertions for use with the WS-Policy framework to
describe how messages are to be secured.
• Message-level security for a Web Service is configured by
attaching one or more policy files that contain security
policy statements.

Oracle University and Egabi Solutions use only

WS-SecurityPolicy
The WS-Policy specification defines a framework for allowing Web Services to express their
constraints and requirements. Such constraints and requirements are expressed as policy assertions.
WS-SecurityPolicy defines a set of security policy assertions for use with the WS-Policy framework
to describe how messages are to be secured in the context of WSS: SOAP Message Security, WS-
Trust and WS-SecureConversation.
You configure message-level security for a Web Service by attaching one or more policy files that
contain security policy statements, as specified by the WS-SecurityPolicy specification.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 21
Quiz

Which of these statements is not true concerning WS-Policy?

1. A set of specifications that describe the capabilities and
constraints of a Web service
2. Consists of a set of rules written in XML
3. Only used for security purpose

Oracle University and Egabi Solutions use only

4. Can be referenced by Web service’s WSDL file

Copyright © 2009, Oracle. All rights reserved.

Answer: 3

• WebLogic Server supports the followings under JAX-WS:

– WS-Security 1.1
– WS-Policy 1.2 and 1.5
– WS-SecurityPolicy 1.2
– SAML Token Profile 1.1

Oracle University and Egabi Solutions use only

– Configuration of policy via annotation/WSDL, Admin
Console, and descriptor
• Supported under JAX-RPC:
– WS-SecureConversation
– WS-Trust

Copyright © 2009, Oracle. All rights reserved.

WebLogic WS-Security Support

This slide lists the supported WS-Security features and specifications for JAX-WS Web services.
For maximum portability, Oracle recommends that you use WS-Policy 1.2 and OASIS WS-
SecurityPolicy 1.2 with JAX-WS.
WebLogic Server supports:
• WS-Policy 1.2 with namespace: http://schemas.xmlsoap.org/ws/2004/09/policy
• OASIS WS-SX TC Web Services SecurityPolicy with namespace: http://docs.oasis-
open.org/ws-sx/ws-securitypolicy/200702
In addition to this new version of the namespace, WebLogic Server continues to support Web
Services SecurityPolicy namespace: http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 23
Message-Level Security Configuration Using
Policy Files
• To configure the message-level security for WebLogic
Web services, you need to:
– Specify the details of message-level security with one or
more security policy files
– Use the @Policy and @Policies annotations in JWS file
to associate policy files with Web Service

Oracle University and Egabi Solutions use only

— Associate any number of policy files with a Web Service
— Specify a policy file at both the class and method level
• WebLogic Server provides some prepackaged policy files
that are recommended for most use cases.

Copyright © 2009, Oracle. All rights reserved.

Message-Level Security Configuration Using Policy Files

To configure message-level security for a WebLogic Web service, do the following:
• Specify the details of message-level security with one or more security policy files
- Security policy files describe whether and how the SOAP messages should be digitally
signed or encrypted.
- They can also specify that a client application authenticate itself using a username,
SAML, or X.509 token.
• Use the @weblogic.jws.Policy and @weblogic.jws.Policies annotations in
JWS file to associate policy files with Web Service. You can associate any number of WS-
Policy files with a Web service, although it is up to you to ensure that the assertions do not
contradict each other. You use @Policy to attach single policy, and @Policies to attach
multiple policies by grouping two or more @Policy annotations.
WebLogic Server provides some pre-packaged WS-Policy files that are recommended for most use
cases. However, if you use SAML tokens for authentication, or you want to specify that particular
parts of a SOAP message rather than the entire body be encrypted or digitally signed, you must
create your own WS-Policy files.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 24
Sample of Using @Policy and @Policies
Annotations
@WebService
@Policy(uri="policy:Wssp1.2-2007-Wss1.0-UsernameToken-Plain-
X509-Basic256.xml") Username token with
plain-text password is
public class SignAndEncrypt { Grouping of sent in the request for
policies Authentication.
@WebMethod
@Policies({
@Policy(uri="policy:Wssp1.2-2007-SignBody.xml"),

Oracle University and Egabi Solutions use only

@Policy(uri="policy:Wssp1.2-2007-EncryptBody.xml")})
public String getInfo(String s) {
return s; Sign and encrypt the
} body of both the request
and response
@WebMethod
messages.
@Policy(uri="policy:Wssp1.2-2007-SignBody.xml",
direction=Policy.Direction.inbound)
@Oneway
public void echoOneway(String s) { Sign the body of the
System.out.println("s = " + s); request SOAP message.
}
}

Copyright © 2009, Oracle. All rights reserved.

Sample of Using @Policy and @Policies Annotations

This code example shows the service authenticates the client with a username token, and signs and
encrypts (with X509 certificates) the response messages.
The policies used in this example are all pre-packaged with WebLogic Server. The uri attribute is
used to specify the location of the WS-Policy file. To specify the pre-packaged WLS policy files, use
the policy: prefix and the name of one of the WS-Policy files, as shown in the above example.
The direction attribute specifies whether the policy file should be applied to the request
(inbound) SOAP message, the response (outbound) SOAP message, or both (default if unspecified).

• Use the uri attribute to specify the location of the policy

file:
– Specify one of the prepackaged security policy files:
@Policy(uri="Wssp1.2-2007-SignBody.xml")
– Specify a user-created policy file with relative path:
@Policy(uri="../policies/MyPolicy.xml")

Oracle University and Egabi Solutions use only

– Specify a policy file that is located in a shared JEE library:
@Policy(uri="policy:MySharedPolicy.xml")
• Load a policy file from classpath:
– Start WebLogic Server with:
-Dweblogic.wsee.policy.LoadFromClassPathEnabled=true
– Copy the policy file to the root directory of your Web application.
– Reference it directly by its name:
@Policy(uri=”MyPolicy.xml”)

Copyright © 2009, Oracle. All rights reserved.

Specifying the Policy File Location

The preceding example shows how to reference pre-packaged security policy files from the @Policy
annotation.
To specify an user-created policy file:
1. Specify the policy annotation.
2. Use the uri attribute to name of the policy file. For example:
@Policy(uri="../policies/UserCreatedPolicy.xml")
If you want to reuse policy file in multiple Web services then you can package it in shared Java
EE library and specify the file using a uri similar to:
@Policy(uri="policy:MySharedPolicy.xml")
Here the WS-Policy file is assumed to be located in a shared Java EE library’s META-
INF/policies or WEB-INF/policies directory.
Load a policy file from CLASSPATH
The 10.x release of WebLogic Server includes a ‘load policy as resource from CLASSPATH’ feature
that allows you to copy a policy file to the root directory of your Web application and then reference
it directly by its name via an @Policy annotation. If you enable this feature, be aware that if the
policy file to the WEB-INF/policies directory, the same ‘mypolicy.xml’ reference in the @Policy
annotation will no longer work. You would need to add the policy prefix to the @Policy annotation;
for example, “policy:mypolicy.xml”.
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 26
WebLogic Prepackaged Policy Files

• Policy files are located in:

/WL_HOME/server/lib/weblogic.jar
• There are two sets of policies with different namespaces, but
perform the same functions:
– Prefix of “Wssp1.2-2007-”: Conforms to the OASIS WS-
SecurityPolicy 1.2 specification (recommended)

Oracle University and Egabi Solutions use only

– Prefix “Wssp1.2-”: Carries over from the WLS version 10.0
• The policy files are categorized as:
– Transport Level Policies
– Protection Assertion Policies
– WS-Security 1.0 Username and X509 Token Policies
– WS-Security 1.1 Username and X509 Token Policies
– SAML Token Profile Policies

Copyright © 2009, Oracle. All rights reserved.

WebLogic Prepackaged Policy Files

WebLogic Server includes a number of WS-Security Policy files you can use in most Web Services
applications. The policy files are located in /WL_HOME/server/lib/weblogic.jar. Within
weblogic.jar, the policy files are located in /weblogic/wsee/policy/runtime.
There are two sets of these policies. In most of the cases, they perform identical functions, but the
policy uses different namespace.
• The first set has a prefix of "Wssp1.2-2007-". These security policy files conform to the OASIS
WS-SecurityPolicy 1.2 specification and have the following namespace:
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy“
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws
securitypolicy/200702" >
• The second set carries over from WebLogic Server version 10.0 and has the prefix "Wssp1.2-":
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy“
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-
securitypolicy/200512" >

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 27
WebLogic Prepackaged Policy Files (continued)
Oracle recommends that you use the new policy namespace, as those are official namespaces from
OASIS standards and they will perform better when interoperating with other vendors. The old
policies having the prefix of "Wssp1.2-" are mainly for users who want to interoperate with existing
applications that already use this version of the policies.
The policy files are categorized as:
• Transport Level Policies: These policies require use of the https protocol to access WSDL and
invoke Web Services operations. The files include:
- Wssp1.2-2007-Https.xml
- Wssp1.2-2007-Https-BasicAuth.xml
- Wssp1.2-2007-Https-ClientCertReq.xml
- Wssp1.2-2007-Https-UsernameToken-Digest.xml

Oracle University and Egabi Solutions use only

- Wssp1.2-2007-Https-UsernameToken-Plain.xml
• Protection Assertion Policies: Protection assertions are used to identify what is being
protected and the level of protection provided. Protection assertion policies cannot be used
alone; they should be used only in combination with X.509 Token Policies. For example, you
might use Wssp1.2-2007-Wss1.1-X509-Basic256.xml together with Wssp1.2-
2007-SignBody.xml. The files include:
- Wssp1.2-2007-SignBody.xml
- Wssp1.2-2007-EncryptBody.xml
- Wssp1.2-2007-Sign-Wsa-Headers.xml
• WS-Security 1.0 Username and X509 Token Policies: Policies support the Username Token
or X.509 Token specifications of WS-Security 1.0. They include:
- Wssp1.2-2007-Wss1.0-X509-Basic256.xml
- Wssp1.2-2007-Wss1.0-UsernameToken-Digest-X509-Basic256.xml
- Wssp1.2-2007-Wss1.0-UsernameToken-Plain-X509-Basic256.xml
• WS-Security 1.1 Username and X509 Token Policies: Policies support the Username Token
or X.509 Token specifications of WS-Security 1.1. They include:
- Wssp1.2-2007-Wss1.1-X509-Basic256.xml
- Wssp1.2-2007-Wss1.1-UsernameToken-Digest-X509-Basic256.xml
- Wssp1.2-2007-Wss1.1-UsernameToken-Plain-X509-Basic256.xml
- Wssp1.2-2007-Wss1.1-EncryptedKey-X509-SignedEndorsing.xml
- Wssp1.2-2007-Wss1.1-UsernameToken-Digest-EncryptedKey.xml
- Wssp1.2-2007-Wss1.1-UsernameToken-Plain-EncryptedKey.xml
- Wssp1.2-2007-Wss1.1-DK-X509-SignedEndorsing.xml
- Wssp1.2-2007-Wss1.1-UsernameToken-Digest-DK.xml
- Wssp1.2-2007-Wss1.1-UsernameToken-Plain-DK.xml
• SAML Token Profile Policies: Policies implement WS-Security SAML Token Profile 1.0 and
1.1. (SAML will be discussed later in this lesson)
For more details of these pre-packaged WS-Policy files, see the Configuring Message-Level Security
of Oracle® Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server 11g
Release 1 (10.3.1)

Oracle University and Egabi Solutions use only

Associating Policy Files Using JDeveloper

The Web Service Properties wizard in JDeveloper can help you to configure a message-secured Web
Service (at class or method level) with the pre-packaged policy files.

Oracle University and Egabi Solutions use only

Associate
policy files
with the
operations

Copyright © 2009, Oracle. All rights reserved.

Associating Policy Files at Run Time Using Administration Console

You can associate policy files only at runtime using the Administration Console, or you can specify
some policy files using the annotations and then associate additional ones at runtime. However, once
you associate a policy file using the JWS annotations, you cannot change this association at runtime
using the Administration Console.
At runtime, the Administration Console allows you to associate as many policy files as you want
with a Web Service and its operations, even if the policy assertions in the files contradict each other
or contradict the assertions in policy files associated with the JWS annotations. It is up to you to
ensure that multiple associated policy files work together. If any contradictions do exist, WebLogic
Server returns a runtime error when a client application invokes the Web Service operation.
To use the Console to associate one or more WS-Policy files to a Web Service, the WS-Policy XML
files must be located in either the META-INF/policies or WEB-INF/policies directory of the EJB
JAR file or WAR file, respectively.

Oracle University and Egabi Solutions use only

Associating Policy Files at Run Time Using Administration Console (continued)

See Associate a WS-Policy file with a Web Service in the Oracle Fusion Middleware Oracle
WebLogic Server Administration Console Help for detailed instructions on using the Administration
Console to associate a policy file at runtime.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 31
Quiz

What tool can associate a policy file at run time?

1. JDeveloper
2. WLS Administration Console
3. OEPE
4. WebLogic Ant

Oracle University and Egabi Solutions use only

Answer: 3

Message Sender (MS) Message Receiver (MR)

Use receiver’s
MS public key public key to MR public key
encrypt a message
MS private key MR
MRprivate
privatekey
key
MR
MRpublic
publickey
key MS public key

Oracle University and Egabi Solutions use only

Encryption

Use sender’s
MS public key private key to
MR public key
sign a message
MS
MSprivate
privatekey
key MR private key

MR public key MS
MSpublic
publickey
key

Signing

Copyright © 2009, Oracle. All rights reserved.

Message Encryption and Signing Mechanisms

In production environments, the Web Services runtime typically uses its two private key and digital
certificate pairs, one for signing and one for encrypting SOAP messages.
This diagram illustrates how messages are encrypted with the key pairs. As shown here, the sender
and receiver both should have their own key pairs (public and private) and the public key of the other
party. These keys are stored in keystore.
When a sender sends an encrypted message, the sender uses the receiver’s public key to encrypt the
message so that only the designated receiver can use the appropriate private key to decrypt the
message.
When a sender needs to send a signed message, the sender uses his own private key to sign the
message, so for those who have sender’s public key can verify the signature.

The main steps for configuring message-level security are:

1. Add WebLogic-specific annotations to specify the policy files in
JWS file.
2. Deploy Web Service after compilation.
3. Create a custom keystore, and two private key and digital
certificate pairs on the server side.

Oracle University and Egabi Solutions use only

4. Create a keystore on the client side.
5. Create a private key and digital certificate pair, and load it into
the client keystore.
6. Create users for authentication by using Admin console.
7. Update your client application to invoke the message-secured
Web Service.

Copyright © 2009, Oracle. All rights reserved.

Configuring Message-Level Security

To configure message-level security for a WebLogic Server Web Service:
1. Update your JWS file adding WebLogic-specific @Policy and @Policies JWS annotations
to specify the pre-packaged policy files that are attached to either the entire Web Service or to
particular operations.
2. Recompile and redeploy your Web Service as part of the normal iterative development process.
3. Create, if one does not currently exist, a custom identity keystore for WebLogic Server, and
create private key and digital certificate pairs.
You can use the Cert Gen utility or Sun's keytool utility. This step includes multiple sub-steps
which will be discussed in later slides.
4. Create a keystore used by the client application. Oracle recommends that you create one client
keystore per application user.
5. Create a private key and digital certificate pair, and load it into the client keystore. The same
pair will be used to both digitally sign the client's SOAP request and encrypt the SOAP
responses from WebLogic Server.
6. Using the Administration Console, create users for authentication in your security realm.
7. Update your client application by adding the Java code to invoke the message-secured Web
Service.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 34
Configuring Message-Level Security (continued)
Note: keytool is a standard Java SE SDK utility for managing the generation of private keys and
corresponding digital certificates, and keystore of private keys and associated certificates. For more
information, see http://java.sun.com/javase/6/docs/tooldocs/solaris/keytool.html.

Oracle University and Egabi Solutions use only

• WebLogic Server provides a private key and X.509

certificate pair out-of-the-box for demo and testing
purposes.
• In production, usually two pairs of private key and digital
certificate need to be created for signing and encryption
respectively. The steps are:

Oracle University and Egabi Solutions use only

1. Create a custom identity keystore.
2. Create two private key and digital certificate pairs, and import them
into the server keystore.
3. Using the Administration Console, create the default Web service
security configuration, which must be named default_wss.
4. Update the default Web Services security configuration to use:
— One of the key pairs for digitally signing SOAP messages
— Second key pairs for encrypting SOAP messages

Copyright © 2009, Oracle. All rights reserved.

Creating Key Pairs, Keystore on the Server Side

Web Services runtime uses the private key and X.509 certificate pair that is provided out-of-the-box
with WebLogic Server; this same key pair is also used by the core security subsystem for SSL and is
provided mostly for demonstration and testing purposes. In this scenario, one key pair is used for
both encryption and digital signatures. In production environments, the Web Services runtime
typically uses its own two private key and digital certificate pairs, one for signing and one for
encrypting SOAP messages.
The default Web Service security configuration is used by all Web services in the domain unless they
have been explicitly defined to use a different configuration.

• The WLS Web service security configuration specifies

information such as whether to use:
– An X.509 certificate for identity
– Password digests
– keystore for encryption and digital signatures

Oracle University and Egabi Solutions use only

• The default Web service security configuration is called
default_wss.
• To associate a Web service with a security configuration
other than the default, use the
@weblogic.jws.security.WssConfiguration
annotation.
• Both default and custom security configurations need to be
explicitly created using the Administration Console.

Copyright © 2009, Oracle. All rights reserved.

Web Service Security Configuration

WebLogic Server has a default Web Service security configuration called default_wss. This
default security configuration must be explicitly created using the Administration Console. After you
create this configuration, it is applied to all Web Services. If the default behavior of the Web
Services security runtime is adequate then no additional configuration is needed. However, if a Web
Service requires different behavior from the default (such as using an X.509 certificate for identity,
rather than the default username/password token), then the Web Service must be associated with a
security configuration.
You specify the name of the associated security configuration using the value attribute of the
@WssConfiguration annotation; if you do not specify this attribute, then the service is
associated with the default security configuration. For example:
@WebService
...
@WssConfiguration(value="my_security_configuration")
public class WssConfigurationImpl {
...

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 37
Quiz

In a production environment, when configuring message-level

security on WLS, you need to create which of the following?
1. Two client-side private key and digital certificate pairs
2. Two server-side private key and digital certificate pairs
3. One client-side private key and digital certificate pair

Oracle University and Egabi Solutions use only

4. One server-side private key and digital certificate pair

Copyright © 2009, Oracle. All rights reserved.

Answers: 2, 3

• Depending on the requirement of the security policy of the

Web service being invoked, the client must:
– Read the private key and digital certificate pair
– Pass the following information to the Web service:
— Key and digital certificate pair
Username and password for user authentication

Oracle University and Egabi Solutions use only

—

• For encryption, clients can use a client-side copy of the

server’s certificate.

Copyright © 2009, Oracle. All rights reserved.

Invoking a Message-Secured Web Service

When you update your Java code to invoke a message-secured Web Service, you must load a private
key and digital certificate pair from the client's keystore and pass this information, along with a
username and password for user authentication if so required by the security policy, to the secure
WebLogic Web Service being invoked.
If the security policy file of the Web Service specifies that the SOAP request must be encrypted, then
the Web Services client application must use a client-side copy of the server’s certificate.

import weblogic.security.SSL.TrustManager;
import weblogic.xml.crypto.wss.provider.CredentialProvider;
...
public class SecureHelloWorldClient {
public static void main(String[] args) throws Throwable {
String username = args[0]; Username or
String password = args[1]; password for the
UsernameToken
String keyFile = args[2]; Client private key file

Oracle University and Egabi Solutions use only

String clientCertFile = args[3];
SecureHelloWorldService service = new Client
SecureHelloWorldService_Impl(); certificate
SecureHelloWorldPortType port = Create client-side
service.getSecureHelloWorldServicePort(); BinarySecurityToken
List credProviders = new ArrayList(); credential provider
CredentialProvider cp = new
ClientBSTCredentialProvider(clientCertFile, keyFile);
credProviders.add(cp); Create client-side
UsernameToken
credential provider
cp = new ClientUNTCredentialProvider(username, password);
credProviders.add(cp);

Copyright © 2009, Oracle. All rights reserved.

Sample Client Code

The example code above shows a Java client application that invokes the message-secured
WebLogic Web Service. The client application takes four arguments:
• Client username and password for client authentication
• Client private key file
• Client digital certificate
The security-specific code in the sample client application is shown in bold:
• Import API:
- Import the WebLogic security TrustManager API:
import weblogic.security.SSL.TrustManager;
- Import the following WebLogic Web Services security APIs to create the needed client-
side credential providers, as specified by the policy files that are associated with the Web
Service:
import weblogic.xml.crypto.wss.provider.CredentialProvider;
import weblogic.xml.crypto.wss.WSSecurityContext;
import
weblogic.wsee.security.bst.ClientBSTCredentialProvider;
import
weblogic.wsee.security.unt.ClientUNTCredentialProvider;

Set credential provider

Map<String, Object> rc = ((BindingProvider)
to request context
port).getRequestContext();
rc.put(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credProviders);

rc.put(WSSecurityContext.TRUST_MANAGER,
new TrustManager() {
public boolean certificateCallback(X509Certificate[] chain,
int validateErr) {

Oracle University and Egabi Solutions use only

return true;
}
}); Set TrustManager to
verify that the certificate
String response = port.sayHello("World"); used to encrypt the
System.out.println("response = " + response); SOAP request is valid
}
}

Copyright © 2009, Oracle. All rights reserved.

Sample Client Code (continued)

• Use the ClientBSTCredentialProvider WebLogic API to create a binary security
token credential provider from the client's certificate and private key.
• Use the ClientUNTCredentialProvider API to create a username token from the
client's username and password.
• Use the WSSecurityContext.CREDENTIAL_PROVIDER_LIST property to pass a List object
that contains the binary security and username token.
• Use the weblogic.security.SSL.TrustManager WebLogic security API to verify
that the certificate used to encrypt the SOAP request is valid. The Web Services client runtime
gets this certificate from the deployed WSDL of the Web Service, which in production
situations is not automatically trusted, so the client application must ensure that it is okay
before it uses it to encrypt the SOAP request.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 41
Invoking a Web Service from Within a WebLogic
Server Instance
• To invoke a Web service from one instance of WebLogic
Server to another, you must:
– Specify security using the Administration Console:
— Configure the required credential mapping providers of the core
security of the WebLogic Server instance.
— Create the actual credential mappings in the credential mapping

Oracle University and Egabi Solutions use only

providers.
— Configure the core WebLogic Server security framework to trust
the X.509 certificate of the invoked Web Service.
– Invoke the Web Service operation using the
@ServiceClient annotation from any EJB, JWS, or
servlet.

Copyright © 2009, Oracle. All rights reserved.

Invoking a Web Service from Within a WebLogic Server Instance

The preceding example shows a stand-alone client application invoking the message-secured Web
Service. Sometimes, however, the client is itself running in a WebLogic Server instance, as part of an
EJB, a servlet, or another Web Service. In this case, you can use the core WebLogic Server security
framework to configure the credential providers and trust manager so that your EJB, servlet, or JWS
code contains only the simple invoke of the secured operation and no other security-related API
usage.
The procedure above lists the high level steps you must perform to make use of the core WebLogic
Server security framework in this use case.
1. In your EJB, servlet, or JWS code, invoke the Web Service operation as regular service client.
Specifically, do not create a CredentialProvider object that contains username or X.509 tokens,
and do not use the TrustManager core security API to validate the certificate from the
WebLogic Server hosting the secure Web Service. The reason you should not use these APIs in
your client code is that the Web Services runtime will perform this work for you.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 42
Invoking a Web Service from Within a WebLogic Server Instance (continued)
2. Using the Administration Console, configure the required credential mapping providers of the
core security of the WebLogic Server instance that hosts your client application. The list of
required credential mapper providers depends on the policy file that is attached to the Web
Service you are invoking. Typically, you must configure the credential mapper providers for
both username/password and X.509 certificates.
3. Using the Administration Console, create the actual credential mappings in the credential
mapping providers you configured in the preceding step. You must map the user principal,
associated with the client running in the server, to the credentials that are valid for the Web
Service you are invoking. See Configuring a WebLogic Credential Mapping Provider in Oracle
Fusion Middleware Securing Oracle WebLogic Server.
4. Using the Administration Console, configure the core WebLogic Server security framework to
trust the X.509 certificate of the invoked Web Service. See Configuring the Certificate Lookup

Oracle University and Egabi Solutions use only

and Validation Framework in Oracle Fusion Middleware Securing Oracle WebLogic Server.
You are not required to configure the core WebLogic Server security framework, as described in this
procedure, if your client application does not want to use the out-of-the-box credential provider and
trust manager. Rather, you can override all of this configuration by using the same APIs in your EJB,
servlet, and JWS code as in the stand-alone Java code. However, using the core security framework
standardizes the WebLogic Server configuration and simplifies the Java code of the client application
that invokes the Web Service.

Oracle Web Services Manager (WSM) WS-Security policies are

an alternative to the WLS WS-Security policies for enforcing
security for Web services.
Use:
• Oracle WSM WS-Security policies if developing WLS JAX-
WS Web services or clients that interact with SOA

Oracle University and Egabi Solutions use only

Composite Services, ADF Components, or WebCenter
Services
• WLS WS-Security policies if developing only WLS native
Java JAX-WS Web services

Copyright © 2009, Oracle. All rights reserved.

Oracle WSM WS-Security Policies

Oracle Fusion Middleware 11g Release 1 products install a portability layer on top of WebLogic
Server that integrates Oracle Web Services Manager (WSM) WS-Security policies into the
WebLogic Server environment. This portability layer provides Oracle WSM WS-Security policies
that you can use to protect WebLogic Server JAX-WS Web services and Web service clients.
You can use the Oracle WSM policies as an alternative to the WebLogic Server WS-Security policies
for enforcing security for Web services. You can also create custom Oracle WSM WS-Security
policies and use them with WebLogic Web services.
You might want to use Oracle WSM WS-Security policies to protect JAX-WS Web services if you
already use SOA, ADF, or Web Center applications elsewhere in your environment and you want to
have a consistent security environment.
You should secure a WebLogic Server JAX-WS Web service with Oracle WSM WS-Security
policies to have consistent and interoperable Web service security when these Web services are used
in conjunction with Oracle Fusion Middleware applications. That is, you should secure WebLogic
Server JAX-WS Web services with Oracle WSM WS-Security policies for use with applications that
interact with Oracle Fusion Middleware applications, not with standalone WLS web service
applications.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 44
Adding Oracle WSM WS-Security Policies to a
Web Service
• The Oracle WSM WS-Security policy attachment model is similar
to that of the WebLogic Web service policies:
– Adding policy annotations at design time
— @SecurityPolicy (single policy)
— @SecurityPolicies (multiple policies)
– Using the Administration Console at run time

Oracle University and Egabi Solutions use only

• The annotations have similar syntax and semantics to the
existing @Policy and @Policies annotations used by the WLS
policies, with the following exceptions:
– @SecurityPolicy and @SecurityPolicies can be applied
only at the class level.
– “Direction” is not used.
• For example:
@SecurityPolicy(uri="policy:oracle/authorization_policy")

Copyright © 2009, Oracle. All rights reserved.

Adding Oracle WSM WS-Security Policies to a Web Service

You can attach only one type of security policy to a Web service, either WebLogic Server security
policies or Oracle WSM policies. You cannot attach both WebLogic Server security policies and
Oracle WSM policies to the same Web service, through either the annotation mechanism, the
Administration Console, or a combination of the two.
Attaching Oracle WSM policies to a deployed Web service at runtime in the Administration Console
is similar to attaching WebLogic Server policies.
Note: You can attach an Oracle WSM WS-Security policy only to a JAX-WS Web service; you
cannot attach this type of policy to a JAX-RPC Web service.

The following Oracle WSM WS-Security policies are not

currently supported with WebLogic Server JAX-WS:
• Log policies
• WS-Addressing Policies
• MTOM Policies

Oracle University and Egabi Solutions use only

• Reliable Message Policies
• HTTP-based authentication:
– oracle/wss_http_token_client_policy
– oracle/wss_http_token_service_policy
– oracle/wss_http_token_over_ssl_client_policy
– oracle/wss_http_token_over_ssl_service_policy

Copyright © 2009, Oracle. All rights reserved.

Nonsupported Oracle WSM WS-Security Policies

Not all Oracle WSM WS-Security policies are supported with WebLogic Server JAX-WS Web
services. The slide lists the policies that you can not use in the WLS JAX-WS Web services.
The Oracle WSM policies are documented in the Oracle Fusion Middleware Security and
Administrator's Guide for Web Services.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 46
Summary

In this lesson, you should have learned how to:

• Describe the benefits of message-level security
• Illustrate the relationships of WS-Security specifications
• Explain how SAML is used with WS-Security to secure
messages

Oracle University and Egabi Solutions use only

Copyright © 2009, Oracle. All rights reserved.

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 8 - 47
Practice 8 Overview:
Securing Web Services Using WS-Policy
This practice covers the following topics:
• Signing and encrypting Web services calls in services
• Creating secure Web service clients

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe the use of SOAP handlers in Web Service
processing
• Create SOAP message handlers
• Configure handler chains on the server side

Oracle University and Egabi Solutions use only

• Configure handler chains for client-side applications

Copyright © 2009, Oracle. All rights reserved.

Objectives
The goal of this lesson is to teach how to create and configure SOAP handlers to manipulate
SOAP messages that are sent and received by JAX-WS clients and service endpoints.

• Web Services and their clients may need to access the SOAP
message for additional processing of the message request or
response.
• SOAP message handlers:
– Provide a mechanism for intercepting the SOAP message in both
the request and response of the Web Service

Oracle University and Egabi Solutions use only

– Can be used on both the client side and the server side
– Are organized into an ordered list known as a handler chain and are
invoked in order
• Use cases:
– Capturing and logging information
– Adding security
– Improving the performance of your Web service

Copyright © 2009, Oracle. All rights reserved.

SOAP Message Handlers

Web Services and their clients may need to access the SOAP message for additional processing
of the message request or response. You can create SOAP message handlers to enable Web
Services and clients to perform this additional processing on the SOAP message.
A SOAP message handler provides a mechanism for intercepting the SOAP message in both the
request and response of the Web Service. Handlers allow an application to process SOAP
messages before the message is delivered to the Web service operation, and handlers on
outgoing messages are invoked after the Web service operation has completed. The Web service
itself is unaware of the presence of handlers.
A handler can be used to modify a SOAP request or response message on the client and the
server side.
You can use handlers for a variety of purposes such as capturing and logging information and
adding security or other information to a message. Usually, they are done by storing and
manipulating Web service-specific information in SOAP header and body. For example, a client
application can use a handler to post-process a request message, adding authentication headers,
before sends it to a target Web service. On the server side, a handler could be used to preprocess
the message, checking those authentication headers, before the message is dispatched to invoke
the target service.
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 3
SOAP Message Handlers (continued)
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.

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 4
Handler Types

JAX-WS supports two types of handlers:

• Logical Handlers
– Protocol-neutral
– Has access only to the message payload in the SOAP body
– Mainly used to process XML message, like transforming the

Oracle University and Egabi Solutions use only

message
• SOAP Handlers
– Protocol-specific, limited to SOAP-specific configurations
– Has access to the entire SOAP message, including any
optional headers and attachments
– Designed for processing related to the SOAP binding

Copyright © 2009, Oracle. All rights reserved.

Handler Types
JAX-WS supports two types of SOAP message handlers: logical handlers and SOAP handlers.
Logical handlers can access the payload of the message only, and cannot change any protocol-
specific information (like headers) in a message. SOAP handlers can access the entire SOAP
message, including the message headers and body.
SOAP Handler is a protocol specific handler. It can be used if we want to check the user
credentials, and then only allow to access the service. Logical Handler is a message oriented
interface. You can easily access messages and transform the messages in logical handler class.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 5
Handler Framework

JAX-WS provides a handler framework that allows Web

services to manipulate SOAP messages. A handler can be
injected into the framework in two steps:
• Create a handler class, which implements the Handler
interface in the javax.xml.ws.handler package.
• Place a handler within a handler chain.

Oracle University and Egabi Solutions use only

Handler Framework
JAX-WS provides a handler framework that allows application code to manipulate outgoing and
incoming SOAP messages. A handler can be injected into the framework in two steps:
• One step is to create a handler class, which implements the Handler interface in the
javax.xml.ws.handler package. JWS provides two Handler subinterfaces,
LogicalHandler and SOAPHandler.
• The other step is to place the handler within a handler chain. This is typically done through
a configuration file, although handlers also can be managed through code or
programmatically.

For each handler, you need to:

• Create a Java class that implements the SOAP message
handler interface
• Implement sufficient logic to detect the inbound or
outbound direction of the message

Oracle University and Egabi Solutions use only

Creating Massage Handlers

When you create a handler class by implementing the javax.xml.ws.handler.Handler
interface, you must configure the handlers for the server or client, and implement sufficient logic
within the methods to detect the inbound or outbound direction of the current message. This is
because the JAX-WS runtime makes no distinction between server-side and client-side handler
classes and does not distinguish between inbound or outbound flow when a method for a specific
handler is invoked.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 7
Quiz

Which of the following statements are true concerning handler?

1. A handler can be used to modify a SOAP request or
response message only on the server side.
2. A handler can access information only in the header part of
the SOAP message.

Oracle University and Egabi Solutions use only

3. JAX-WS run time is capable of invoking several handler
classes in a chain.
4. Logical handlers have access to the entire SOAP
message.
5. JAX-WS run time does not detect the inbound or outbound
direction of a message.

Copyright © 2009, Oracle. All rights reserved.

Answers: 3, 5

HandlerResolver Client side

getHandlerChain()

<<use>>

Handler

Oracle University and Egabi Solutions use only

handleMessage()
handleFault()
close()

SOAPHandler LogicalHandler
getHeaders()

Handler Interfaces
The diagram illustrates the relationship of the message handler interfaces and methods.
To create a message handler, you need to implement the Handler interface in the
javax.xml.ws.handler package. JWS provides two Handler subinterfaces:
LogicalHandler and SOAPHandler. The class that implements either the LogicalHandler or the
SOAPHandler interface needs to define three methods for either interface type, including
handleMessage, which gives the programmer access to the underlying message. The other
two shared methods are handleFault and close. The SOAPHandler interface requires the
implementation to define a fourth method, getHeaders.
The details of methods in Handler interface are:
• handleMessage(): Called automatically when a request or response is sent (either on
server or client)
• handleFault(): Called automatically when there is a fault present in request or
response (either on server or client)
• close(): Called after the completion of message processing by all handlers for each
Web service invocation. This can be useful to clean up any resources used during
processing the message.

To manage a handler's life cycle, you can annotate a method

with:
• @PostConstruct annotation: Called after the handler is
created in the run time
• @PreDestroy annotation: Called before the handler is
destroyed

Oracle University and Egabi Solutions use only

public class BaseHandler<T extends MessageContext> {
@PostConstruct
public void init() {
//...
}
@PreDestroy
public void destroy() {
//...
}
}

Handler Life Cycle

For applications or JAX-WS runtimes to manage the lifecycle, you can annotate a method in a
handler with the @PostConstruct annotation so it will be called after the handler is created
in the runtime. The @PreDestroy annotation allows the method to be called before the
handler is destroyed. All those annotated methods must return void and take no arguments.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 10
Message Context

• Message context:
– Is used by JAX-WS to to exchange information between
client, client handlers, service, service run time, and service
handlers
– Contains a set of properties that are set by JAX-WS run time
automatically

Oracle University and Egabi Solutions use only

— Properties allow the handlers to determine whether a message
is inbound or outbound and to share the processing state.
• Handlers are invoked with a message context that
provides methods to:
– Access and modify inbound and outbound messages
– Manage a set of properties

Message Context
Message context (javax.xml.ws.handler.MessageContext) is the information
carrier among client, client runtime, client handlers, and service, service runtime, and server-side
handlers. It contains information about the message and the context of the message exchange,
such as information related to the binding protocol. JAX-WS enables handlers, endpoints, and
clients to manipulate a message context that travels along with the XML request/response
messages. The message context is maintained throughout the process of request handler and
response handler.
While invoking handlers, message context is sent as input to handlers’ call back methods. So
handlers can access and modify inbound and outbound messages and manage a set of properties.

Map<String,Object>

MessageContext

enum Scope

Oracle University and Egabi Solutions use only

LogicalMessageContext SOAPMessageContext

getMessage() getHeaders()
getMessage()
getRoles()
setMessage()

MessageContext Interface
MessageContext extends java.util.Map interface. The Map interface defines a key and
value pair collection. For MessageContext, the key is String type, and the value is Object
type.
MessageContext contains a set of properties which are set by JAX-WS runtime
automatically. To retrieve the value of each property, use get() method.
Some of the message context properties are:
• MESSAGE_OUTBOUND_PROPERTY (Boolean): It tells the message direction, if the value
is true then it is outbound messages, false is inbound message. Handlers use this property
to determine if the processing is on a outbound or inbound message.
• INBOUND_MESSAGE_ATTACHMENTS (java.util.Map): Attachments to an inbound
message. These can be used to acquire the attachments in inbound message.
• OUTBOUND_MESSAGE_ATTACHMENTS (java.util.Map): Attachments to an outbound
message. A proxy can use these to send attachments not described through WSDL MIME
binding.
Some properties are specific to the HTTP protocol and are available only in HTTP-based
bindings.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 12
MessageContext Interface (continued)
MessageContext has an embedded class MessageContext.Scope, which is an enum
defining property scope. Properties scoped as APPLICATION are visible to handlers, client
applications, or service endpoint implementations; those scoped as HANDLER are only visible to
handlers.
LogicalMessageContext is the context sent to logicalhandler.
SoapMessageContext is the message context sent to SOAPHandler.
SoapMessageContext consists of special methods to retrieve SOAP headers and SOAP
body content.

Oracle University and Egabi Solutions use only

A service endpoint implementation may obtain the

MessageContext object through a WebServiceContext.
public class HelloWorldService {
@Resource
WebServiceContext wsContext;

Oracle University and Egabi Solutions use only

@WebMethod
public String echoHello(String message) {
MessageContext context = wsContext.getMessageContext();
Map requestHeaders =
(Map)context.get(MessageContext.HTTP_REQUEST_HEADERS);
...
}
}

MessageContext Injection in Web Services

A service endpoint implementation may obtain the MessageContext object through a
WebServiceContext:
• The service runtime will inject the WebServiceContext object on any field marked
with @Resource.
JAX-WS allows you to obtain javax.xml.ws.WebServiceContext inside of a
Web service implementation by using the @Resource annotation for dependency
injection. Dependency injection is used to acquire references to resources when an object
is created by the container.
• To get a MessageContext instance, you should call the WebServiceContext's
getMessageContext() method.

Method Signature Description

handleMessage() public boolean handleMessage Manages normal processing of

(C context) throws inbound and outbound
java.lang.RuntimeException, messages. A property in the
java.xml.ws.ProtocolException MessageContext object is used
{} to determine whether the
message is inbound or

Oracle University and Egabi Solutions use only

outbound.

handleFault() public boolean handleFault Manages fault processing of

(C context) throws inbound and outbound
java.lang.RuntimeException, messages
java.xml.ws.ProtocolException
{}

close() void close (MessageContext Concludes the message

context) {} exchange and cleans up
resources that were accessed
during processing

Handler Interface Methods

The methods in Handler interface are:
• handleMessage(C context): Called automatically when a request or response is
sent.
- C extends MessageContext. Its properties allow the handlers to determine if a
message is inbound or outbound and to share processing state.
- If the return value is true, continue handler processing, usually invoking the next
handler on the handler chain. If the return is false, block handler processing.
- 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.
• handleFault(C context): Implement this method to handle processing of any
SOAP faults generated by the handleMessage() method, as well as faults generated by the
back-end component.
If the return value is true, invoke the handleFault()method on the next handler in
the handler chain. If the return is false, block processing of the handler fault chain.
• close(MessageContext context): Called after the completion of message
processing by all handlers for each Web service invocation. This can be useful to clean up
any resources used during processing the message.
THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 15
Interfaces of Logical and SOAP Handlers

Logical Handler SOAP Handler

interface javax.xml.ws.handler. javax.xml.ws.handler.soap.

LogicalHandler SOAPHandler

message context javax.xml.ws.handler. javax.xml.ws.handler.soap.

Oracle University and Egabi Solutions use only

LogicalMessageContext SOAPMessageContext

getMessage() of javax.xml.ws.LogicalMessage javax.xml.soap.SOAPMessage

message context
returns

Interfaces of Logical and SOAP Handlers

The table above shows the differences between a logical handler and SOAP handler:
• SOAP handlers are defined using the
javax.xml.ws.handler.soap.SOAPHandler interface. They are invoked using
the javax.xml.ws.handler.soap.SOAPMessageContext which extends
javax.xml.ws.handler.MessageContext. The
SOAPMessageContext.getMessage() method returns a
javax.xml.soap.SOAPMessage.
• Logical handlers are defined using the
javax.xml.ws.handler.LogicalHandler interface (see
http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/LogicalHandler.html). They
are invoked using the javax.xml.ws.handler.LogicalMessageContext
which extends javax.xml.ws.handler.MessageContext. The
LogicalMessageContext.getMessage() method returns a
javax.xml.ws.LogicalMessage. The payload can be accessed either as a JAXB
object or as a javax.xml.transform.Source object.

public class Handler1 implements LogicalHandler<LogicalMessageContext> 1

{
public boolean handleMessage(LogicalMessageContext lmc)
{
Boolean outboundProperty = (Boolean) 2
lmc.get (MessageContext.MESSAGE_OUTBOUND_PROPERTY);
if (outboundProperty.booleanValue()) {
System.out.println("\nOutbound message:");
} else {
System.out.println("\nInbound message:");

Oracle University and Egabi Solutions use only

}
LogicalMessage message = lmc.getMessage(); 3
Source payload = message.getPayload(); 4

// Process Payload Source

printSource(payload);
// ....
}
public boolean handleFault(LogicalMessageContext msc) { 5
return true;
}
public void close(MessageContext smc) { } 6
}

A Simple Logical Handler Class

The above example illustrates a simple logical handler that returns whether the message is
inbound or outbound along with the message content.
To create logical handler class:
1. Implement javax.xml.ws.handler.LogicalHandler interface
2. Identify the message direction by checking the standard property
MESSAGE_OUTBOUND_PROPERTY on the SOAPMessageContext passed into
handleMessge()
3. Retrieve the message in exchange by calling the getMessage() method on
LogicalMessageContext, and it returns a LogicalMessage object
4. With LogicalMessage, you can work with both javax.xml.transform.Source
or a JAXBContext. In this case, LogicalMessage.getPayload() returns the
payload as Source. The type of source returned depends on the JAX-WS runtime.
5. Implement the Handler.handleFault() method, which will be called if any fault
occurs in service
6. Implement the Handler.close() method to release the resources

public class Handler1 implements SOAPHandler<SOAPMessageContext> {

public Set<QName> getHeaders(){
return Collections.emptySet();
}

public boolean handleMessage(SOAPMessageContext smc)

{
Boolean outboundProperty = (Boolean)
smc.get (MessageContext.MESSAGE_OUTBOUND_PROPERTY);

Oracle University and Egabi Solutions use only

if (outboundProperty.booleanValue()) {
System.out.println("\nOutbound message:");
} else {
System.out.println("\nInbound message:");
}
System.out.println("** Response: "+msc.getMessage().toString());
return true;
}
public boolean handleFault(SOAPMessageContext msc) {
return true;
}
public void close(MessageContext smc) { }
}

A Simple SOAP Handler Class

The above example illustrates a simple SOAP handler that returns whether the message is
inbound or outbound along with the message content. When creating a SOAP handler class, in
addition to implementing the handleMessge(), handleFault(), close() methods,
SOAPHandler also must implement the getHeaders() method, which returns header blocks'
QNames, with each QName representing the qualified name of the outermost element of one
header block.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 18
Quiz

Name the methods that all handlers in JAX-WS must

implement:
1. handleMessage()
2. getMessage()
3. handleFault()

Oracle University and Egabi Solutions use only

4. close()
5. getHeaders()

Answers: 1, 3, 4

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 19
Handler Chain

A handler chain is a chain of handlers in the form of an ordered

list. It has the following properties:
• You can configure multiple logical and SOAP handlers in a
single handler chain.
• Handler chains can be configured different ways:

Oracle University and Egabi Solutions use only

– Through metadata, using the @HandlerChain annotation
– Programmatically (client side only)
• Configuration files are required for the deployment of
handlers specified using the @HandlerChain annotation.
• Handler chains are defined at the port level.
• Handlers in the handler chain exchange information using
message context.

Handler Chain
Developing handlers is only the first step. To use them in a Web service application, you must
configure and deploy them into the client or service runtime. Typically, you organize multiple
handlers according to an ordered list into handler chains. Handler configuration and deployment
use handler chains as units.
Handler chains have following properties:
• You can configure multiple Logical and SOAP handlers in a single handler chain
• When multiple handlers are configured in single chain the order of processing is different
for inbound and outbound messages. It actually depends on whether the source of message
is sender or receiver.
• Handler chains can be configured using annotation (that is,
@javax.jws.HandlerChain). Alternatively, on the client side, handler chains can be
configured at runtime using the HandlerResolver interface.
• The deployment of handlers specified using the @HandlerChain annotation requires
configuration files, which are handler chains' descriptor. The @HandlerChain
annotation contains a file attribute that points to this handler chain configuration file that
you create. WSEE specifies the deployment model for handlers, including the use of these
configuration files.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 20
Handler Chain (continued)
• Handler chains are defined at the port level—so all methods defined by a SEI must use the
same handler chain.
• Handlers in the handler chain have read/write access to the XML message and the
message’s context.

Oracle University and Egabi Solutions use only

Handler1 Handler2 Handoler3

handleMessage() handleMessage() handleMessage()
inbound inbound inbound
2

Oracle University and Egabi Solutions use only

Web
Service

4
Handler1 Handler2 Handler3
handleMessage() handleMessage() handleMessage()
outbound outbound outbound

WebLogic Server-Side Handler Execution

When invoking a Web Service, WebLogic Server executes handlers as follows:
1. The inbound methods for handlers in the handler chain are all executed in the order
specified by the JWS annotation. Any of these inbound methods might change the SOAP
message request.
2. When 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 outbound methods of the
handlers in the handler chain are executed in the reverse order specified by the JWS
annotation. Any of these outbound methods might change the SOAP message response.
4. Upon the first handler in the handler chain completing execution, WebLogic Server returns
the final SOAP message response to the client application that invoked the Web Service.

Chain 1 Chain 2

Processing order on the client side: Processing order on the server side:

Logical SOAP SOAP Logical

Oracle University and Egabi Solutions use only

Handlers Handlers Handlers Handlers

outbound inbound
Client Service
JAX-WS JAX-WS
inbound outbound
Runtime Runtime

Soap handler Logical handler

Handler Chain Processing Order

In a handler chain configuration file, there may be multiple chains, and in each of them, logical
handlers and SOAP handlers can coexist. Because the execution order of handlers may affect
logics implemented in them, and their collaboration, developers should know what sequence are
handlers of different kinds, and in different chains, executed.
The behavior defined in the JAX-WS specification: Whether there are multiple handler chains or
just one, all logical handlers are executed before SOAP handlers on an outbound message, and
all SOAP handlers are executed before logical handlers on an inbound message.
The above figures show how logical and SOAP handlers are invoked during a request and
response on client and server sides. There are two handler chains. The chain 1 consists of two
SOAP handlers and one logical handler, and the chain 2 consists of one SOAP handler and two
logical handlers.
Note: In this example, we use a set of handlers for both client and service. This is possible, but
very rare. Rather, it’s more common to have an asymmetric handler chains.

Configure a handler chain for a Web service through metadata:

• Specify @HandlerChain on the service endpoint interface
or implementation class.
• Specify the location of the configuration file as an attribute
of annotation.

Oracle University and Egabi Solutions use only

– For example:
@HandlerChain(file=“handler-chain.xml”)
• Create the configuration XML file to specify handler chain
declaration.
• Add the configuration file in the classpath for the service
endpoint interface or implementation class.

Configuring Handler Chains on the Server Side

The @javax.jws.HandlerChain annotation enables you to configure a handler chain for a
Web service. 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.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 24
Sample Service Implementation Class with
Handler Chain Annotation
@WebService
@HandlerChain(file="handler-chain.xml")
public class HelloWorldWS
{ Handler chain annotation with
@WebMethod() file attribute specifying the
location of configuration file
public String sayHello(String name) {
return "Hello " + name;
}

Oracle University and Egabi Solutions use only

}

Sample Service Implementation Class with Handler Chain Annotation

The location of the handler chain configuration file supports two formats:
• A relative path from the class file. This example uses a relative path, and handler-
chain.xml is placed in the same location where the service implementation class is
present.
• An absolute path of the configuration XML file. For example,
http://example.com/myhandlerfile.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<jws:handler-chain name="MyHandlerChain1">
<jws:protocol-bindings>
##SOAP11_HTTP ##ANOTHER_BINDING
</jws:protocol-bindings>
<jws:port-name-pattern
xmlns:ns1="http://handler.ws.example.com/">ns1:MySampl*
</jws:port-name-pattern> First handler

Oracle University and Egabi Solutions use only

<jws:service-name-pattern chain declaration
xmlns:ns1="http:// handler.ws.example.com/">ns1:*
</jws:service-name-pattern>
<jws:handler>
<jws:handler-class>
com.example.handler.ws.LoggingHandler
</jws:handler-class>
</jws:handler>
</jws:handler-chain>

Sample Handler Chain Configuration File

The handler-chain.xml configuration file referenced in the annotation of previous slide is the
handler chains' descriptor. The configuration file uses XML to list one or more handler chains,
as shown in the above simple example. Each handler chain may contain one or more handlers
implemented with the class names specified with the <handler-class> element. In this
example, the first handler chain has one handler declared: LoggingHandler; the second
chain has 2 handlers declared: SecurityHandler and CrpytographyHandlers, which
handle some task like authentication and encryption and decryption.
The protocol-bindings, port-name-pattern, and service-name-pattern
elements are all filters that are used to restrict which services can apply the handlers. If none of
these elements are specified within the handler-chain element, the handlers specified in the
chain are applied to everything.

<jws:handler-chain name="MyHandlerChain2”>
<jws:handler>
<jws:handler-class>
com.example.ws.handler.SecurityHandler
</jws:handler-class> Second handler
</jws:handler> chain declaration
<jws:handler>
<jws:handler-class>
com.example.ws.handler.CryptographyHandler
</jws:handler-class>

Oracle University and Egabi Solutions use only

</jws:handler>
</jws:handler-chain>
</jws:handler-chains>

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 27
Quiz

In a handler chain, you can choose not to invoke the next

handler and send an immediate response to the client
application at any point.
1. True
2. False

Oracle University and Egabi Solutions use only

Answer: 1

JAX-WS supports configuring client-side handler chains in the

following ways:
• Through metadata
• Programmatically, providing customization
– Using HandlerResolver on a Service interface

Oracle University and Egabi Solutions use only

– Using Binding interface, configuring handler chains at a
more fine-grained level

Configuring Handler Chains on the Client Side

You can configure client-side 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 (by creating a Java class that implements the SOAP message handler
interface). 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.
You can configure the client-side handlers through metadata (using the @HandlerChain
annotation on client side and server side, they are very similar), or you can modify the handler
chain programmatically to control how the handler chain is built in the runtime. There are two
approaches you can take to programmatically configure handler chains:
• Implement a javax.xml.ws.handler.HandlerResolver on a Service
instance.
• Set a handler chain directly on the javax.xml.ws.BindingProvider, such as a
port proxy or javax.xml.ws.Dispatch object.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 29
Configuring Handler Chains on the Client Side (continued)
Configuring client-side handler chains through metadata, the runtime actually uses the
@HandlerChain annotation and the default implementation of HandlerResolver class to build
the handler chain. This approach configures the client application with the same set of handler
chains for all message exchanges.
With programmatic configuration, you can also configure, through the custom
HandlerResolver class, different handler chains at the client runtime for different services,
ports, and protocol bindings.

Oracle University and Egabi Solutions use only

With this approach, you need to:

• Implement a HandlerResolver interface on a Service
getHandlerChain() constructs a
interface handler chain based on the passed
PortInfo object.
public static class MyHandlerResolver implements HandlerResolver {
public List<Handler> getHandlerChain(PortInfo portInfo) {

Oracle University and Egabi Solutions use only

List<Handler> handlers = new ArrayList<Handler>();
// add handlers to list based on PortInfo information
...
return handlers;
}
}

• Register the HandlerResolver instance

test.setHandlerResolver(new MyHandlerResolver());

Implementing HandlerResolver Interface

A Web service client application needs to implement the HandlerResolver interface and
register a HandlerResolver instance with a Service instance. When the client creates
binding providers to interact with the Web service, the runtime knows its PortInfo, calls the
getHandlerChain() method of the currently registered handler resolver to create the handler
chains, and further uses those chains to configure the binding provider.
The getHandlerChain() method constructs a handler chain based on the passed PortInfo
object. This method returns a handler list which is equivalent to a handler chain. Since a
PortInfo instance carries information about the qualified names of the service, the port, and
the protocol binding, you can configure different handler chains at the client runtime for
different services, ports, and protocol bindings. For example:
if (serviceName.getNamespaceURI().equals(
"http://ws.example.com/service") &&
serviceName.getLocalPart().equalsIgnoreCase("CardService")) {
handlerChain.add(authn);
handlerChain.add(logging);
}

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 31
Implementing HandlerResolver Interface (continued)
A Web service client application should register a HandlerResolver instance with a Service
instance. To register a handler resolver to the Service instance, use the
setHandlerResolver() method. In this case, the port proxy or Dispatch object created
from the Service instance uses the HandlerResolver to determine the handler chain.

Oracle University and Egabi Solutions use only

...
import javax.xml.ws.handler.Handler;
import javax.xml.ws.Binding;
import javax.xml.ws.BindingProvider;

import com.examples.ws.Handler1;
import com.examples.ws.Handler2;

Oracle University and Egabi Solutions use only

public class Main {
public static void main(String[] args) {
HandlerWS test;
try {
test = new HandlerWS(new URL(args[0] + "?WSDL"), new
QName("http://ws.example.com", "HandlerWS") );
} catch (MalformedURLException murl) { throw new
RuntimeException(murl); }
HandlerWSPortType port = test.getHandlerWSPortTypePort();

Using a Binding Interface

The Binding interface in the JAX-WS provides a second approach to configure handler chains
at a more fine-grained level as the Binding interface allows the application of a specific set of
handler chains to a particular message exchange. The above code snippet shows how to work
with the Binding interface to configure handler chains.
Binding is an abstraction of a JAX-WS protocol binding. The handler chain initially
configured on a binding provider instance (port proxy or Dispatch) is a snapshot of the
applicable handlers configured on the service instance at the time of creation. A Binding
instance provides methods to manipulate the initially configured handler chains for the binding
provider.

Cast port as a BindingProvider

object.

...
Binding binding = ((BindingProvider)port).getBinding();
List<Handler> handlerList = binding.getHandlerChain();
handlerList.add(new Handler1());
handlerList.add(new Handler2());

Oracle University and Egabi Solutions use only

binding.setHandlerChain(handlerList);
String result = null;
result = port.sayHello("foo bar");
System.out.println( "Got result: " + result );
}
}

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 34
Quiz

Which of the following ways can you use to configure client-

side handler chain configuration:
1. Setting HandlerResolver on a PortType interface
2. Using a Binding interface to set a handler chain
3. Specifying the @HandlerChain annotation in the Web

Oracle University and Egabi Solutions use only

service client class

Answer: 2, 3

Steps to add SOAP message handlers to a Web service:

1. Design the handlers and handler chains.
2. For each handler in the handler chain, create a Java class
that implements the SOAP message handler interface.
3. Update your SEI adding annotations to configure the

Oracle University and Egabi Solutions use only

SOAP message handlers.
4. Create the handler chain configuration file.
5. Compile all handler classes in the handler chain and
rebuild your Web service.

Adding Server-Side Handlers

The above procedure describes the high-level steps to add SOAP message handlers to your Web
Service.
Note: Add the handler chain configuration XML file in the class path for the service endpoint
interface when configuring the server or client handlers using the @HandlerChain annotation.
You must also include the handler classes contained in the configuration XML file in your class
path.

Oracle University and Egabi Solutions use only

Creating a Configuration File by Using JDeveloper Wizard

Once you create the handler classes and add the annotation to the service endpoint interface or
service implementation class, you can manually create the handler chain configuration file or
use the wizard in JDeveloper. To use the Wizard, you:
1. Select the Web Service Properties of the SEI
2. In Java Web Service Editor window, select Provide Handler Details.
3. You can choose the port that you want to apply the handler details to.
4. Add new handlers by providing the name and a handler class.

Steps to add SOAP message handlers to a Web service client:

1. Design the handlers and handler chains.
2. For each handler in the handler chain, create a Java class
that implements the SOAP message handler interface.
3. Update your JWS file, adding annotations or

Oracle University and Egabi Solutions use only

programmatically to configure the SOAP message
handlers.
4. If using annotations, create the handler chain configuration
file.
5. Compile all handler classes in the handler chain and
rebuild your Web service.

Adding Client-Side Handlers

The above procedure describes the high-level steps to add client-side SOAP message handlers to
the client application that invokes a Web Service operation.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 38
Summary

In this lesson, you should have learned:

• The use of SOAP handlers in Web Service processing
• How to create SOAP message handlers
• How to configure handler chains on the server side
• How to configure handler chains for client-side applications

Oracle University and Egabi Solutions use only

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 9 - 39
Practice 9 Overview:
Creating Handlers for Web Services
This practice covers the following topics:
• Writing a server-side logical handler
• Creating a handler chain configuration file
• Specifying the handler for a Web service

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe the challenges of binary data transmission
• Describe how MTOM addresses the challenges
• Explain the relationships between SOAP with Attachment,
XOP, and MTOM

Oracle University and Egabi Solutions use only

• Enable MTOM optimization on the client side
• Enable MTOM optimization on the server side

Traditional approaches for transmitting binary data in XML

include:
• Embedding data in XML as text-encoded binary using
either base64 or hexadecimal text encoding
• Attaching binary data as external entities, and then
referencing to those entities via URIs in the XML

Oracle University and Egabi Solutions use only

documents
Each of these methods has benefits and drawbacks.

Challenges of Binary Data Transmission

When Web services users sometimes may want to send binary attachments, such as images, media
files, XML docs, and others, together with a SOAP message. Such data is often in a specific binary
formats. Two traditional approaches for handling the data are:
• Embedding data in XML as text-encoded binary: Since XML can't directly encode true 8-bit
binary data, a simple is to use the XML Schema xs:base64binary or xs:hexBinary
types and encode the data inside the XML. This approach bloats the size of the data. For UTF-8
underlying text encoding, base64 encoding increases the size of the binary data by a factor of
1.33x of the original size, while hexadecimal encoding expands data by a factor of 2x.
• Referring to the binary data with a URI in the XML document: There were several
specifications introduced in the Web services world to deal with this binary attachment using
this “by reference” technique. SOAP with Attachments(SwA) is one such example. In this
approach, the data is external to the XML document and isn't part of the message Infoset. This
breaks the web services model and brings interoperability issues because no standard model
governs how SOAP intermediaries process the referenced data.

POST /BookCatalog HTTP/1.1

Content-Length: 59876
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" ?>

<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:ns1="http://catalog.example.com/book">
<soap:Body>

Oracle University and Egabi Solutions use only

<ns1:book>
<title>Web Services Security</title>
<isbn>1_99874_65_0</isbn>
<coverImage>/8j/RgABAgAAAQABAAD/2wBDAAgGBgc...(base64 encoded
cover image data with the rest omitted)</coverImage>
<sample>
<name>Introducing Web Services Security</name>
<content>JVBERi0xLjQNJeLjz9MNC...(base64 encoded
sample content with the rest omitted)</content>
</sample>
</ns1:book>
</soap:Body>
</soap:Envelope>

SOAP Message with Text-Encoded Binary

This is an example of a traditional SOAP message with binary contents when transferred through
HTTP. The content are an image and a sample chapter (in PDF) embedded as text-encoded binary.

Communication
protocol envelope (HTTP)

MIME Package

SOAP Part

SOAP envelope

Oracle University and Egabi Solutions use only

Header

Body

Attachment part
SOAP attachment

SOAP with Attachment (SwA)

SOAP Messages with Attachments (SwA) provides a mechanism to attach binary data to a SOAP
message without converting binary data to ASCII characters using base64 encoding.
SwA is based on Multipurpose Internet Mail Extensions (MIME), which was originally designed for
the e-mail protocol SMTP. MIME defines a way of embedding many different kinds of non-text data
in an e-mail message.
As the diagram illustrates, SOAP message is actually part of the MIME package. SOAP is usually the
payload of HTTP protocol. HTTP supports the use of MIME packages, so SwA leverages the
existing infrastructure for MIME and simply embeds the SOAP message as a MIME part, along with
its related binary data. MIME package is the payload of the HTTP request, and that it contains both
the SOAP message and its attachments.
Using attachments, certain information sets can travel along with the SOAP envelope, as MIME-type
attachments, rather than embedded in the SOAP body as XML. This is a useful feature especially
when passing medium to large quantities of binary-encoded information.

SOAP employs MIME to transfer binary data.

MIME:
• Allows binary data to be embedded in the body of email
and placing it into a block called an attachment or MIME
part

Oracle University and Egabi Solutions use only

• Defines:
– The headers that describe the data type of each attachment
– The boundaries that separate one attachment from another

Using MIME with SOAP

MIME allows binary data to be embedded in the body of e-mail and placing it into a block called an
attachment or MIME part. MIME also defines the headers that describe the data type of each
attachment, as well the boundaries that separate one attachment from another.
SOAP with Attachments takes advantage of the MIME specification, for managing a broad range of
content types as attachments to messages.
• MIME defines a framework by which any type of content can be named, described, transmitted
and received.
• MIME types are named in a slash-separated path, such as text/plain, text/xml, and image/gif.

POST /BookCatalog HTTP/1.1

Content-Type: Multipart/Related; boundary=MIME_boundary;
type= text/xml;start="<QueryBook_1>"

--MIME_boundary Root MIME part

Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Identifier of the first part
Content-ID: <QueryBook_1>
of the MIME package
<?xml version="1.0" encoding="UTF-8"?>

Oracle University and Egabi Solutions use only

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:ns1="http://catalog.example.com/book">
<soap:Body>
<ns1:book>
<title>Web Services Security</title>
<coverImage href=:"cid:QueryBook_1_image"/>
<sample> Reference to two
<name>Introducing Web Services Security</name> attachments in
<content href=:"cid:QueryBook_1_sample"/> the text part
</sample>
</ns1:book>
</soap:Body>
</soap:Envelope>

SOAP Message in MIME Package

SwA uses the Multipart/Related content type. Multipart/Related allows the root
MIME part to refer to other MIME parts. This allows a SOAP message, as an XML instance, to refer
to non-XML (usually binary) data in the same payload.
When you use Multipart/Related MIME types, you must include one root MIME part that is
identified by the HTTP Content-Type header. The root is identified with the start parameter. In
this example, identifiers of the three parts of the MIME package: QueryBook_1,
QueryBook_1_image, and QueryBook_1_sample,and references to the two attachments in
the text part, are shown in bold.
SwA uses the HREF to insert a reference to the data in the SOAP message instead of directly
encoding it. More specifically, you use the content-id (CID) of the MIME part containing the data
you are interested in as the reference.

--MIME_boundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: < QueryBook_1_image>

...binary JPG image...

Identifiers of the
--MIME_boundary-—
two parts of the
Content-Type: application/pdf
MIME package
Content-Transfer-Encoding: binary

Oracle University and Egabi Solutions use only

Content-ID: < QueryBook_1_sample >

...binary PDF...
--MIME_boundary-—

SOAP Message in MIME Package (continued)

This slide code shows the two attachments of the MIME package.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 8
Message Transmission Optimization Mechanism
(MTOM) Addresses Challenges
MTOM:
• Is a specification that defines a way to optimize the
transmission of wire format of SOAP messages
• Works together with XML-binary Optimization Packaging
(XOP) to:

Oracle University and Egabi Solutions use only

– Send and receive binary data optimally without incurring the
cost of data encoding on the wire
– Ensure the data is included in the XML document

Message Transmission Optimization Mechanism (MTOM) Addresses Challenges

MTOM is a specification that focuses on solving the binary data attachment problem. MTOM
provides a compromise between the two approaches described previously. MTOM is actually a “by
reference” method. MTOM uses XML Binary Optimized Packaging (XOP) to optimize the
transmission of wire format of SOAP messages. The wire format of a MTOM optimized message is
the same as the SwA message. The most notable feature of MTOM is the use of the XOP:Include
element to reference the binary attachments of the message. With this element, the attached binary
content logically becomes inline (by value) with the SOAP document even though it is actually
attached separately. This merges the two realms by making it possible to work only with one data
model. MTOM address the performance and interoperability challenges of the traditional ways of
transmitting the binary data.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 9
XOP

XOP specifies the method for serializing a XML file with non-
XML attachments into MIME packages and works by:
• Extracting the binary data in an XML document
• Serializing the data into packages by using MIME
Multipart/Related packaging mechanism

Oracle University and Egabi Solutions use only

• Adding references to the MIME packages in the SOAP
envelope

XOP
XOP specifies the method for serializing a XML file with non-XML content into MIME packages.
XOP provides an alternate serialization that is fully compatible with a MIME package, including an
XML document as the root portion of the package.
XOP extracts all the binary data in an XML document and serializes the data into packages by using
the packaging mechanism MIME Multipart/Related. The new XML document marks the locations of
those binary data packages with special elements that contain URI identifying the corresponding
location.

• MTOM:
– Serializes a SOAP message into a MIME
Multipart/Related XOP package
– One body part (the root) that contains an XML representation
of the modified SOAP envelope
– Additional parts that contain the binary representation of

Oracle University and Egabi Solutions use only

each element of the xs:base64Binary type
• The essential features of MTOM for SOAP 1.1 and SOAP
1.2 are the same, the main difference is the start-info
parameter:
– SOAP 1.1: text/xml
– SOAP 1.2 : application/soap+xml

How MTOM/XOP Works

MTOM serializes a SOAP message into a MIME Multipart/Related XOP package with one body part
(the root) that contains an XML representation of the modified SOAP envelope and additional parts
that contain the binary representation of each element of the xs:base64Binary or
xs:hexBinary type
The essential features of MTOM for SOAP 1.1 and SOAP 1.2 are the basically same, the main
difference is the start-info parameter of the root part of the MIME Multipart/Related
package.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 11
MTOM/XOP Version of SOAP Message
POST /BookCatalog HTTP/1.1
Content-Type: Multipart/Related; boundary=MIME_boundary;
type=application/xop+xml;start-info="text/xml"
Media type Indicates SOAP 1.1 content type
--MIME_boundary
Content-Type: application/xop+xml; type="text/xml" charset=UTF-8
Content-Transfer-Encoding: 8bit

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

Oracle University and Egabi Solutions use only

xmlns:ns1="http://catalog.example.com/book“
xmlns:xop=“http://www.w3.org/2003/12/xop/include”>
<soap:Body>
<ns1:book>
<title>Web Services Security</title>
<coverImage>
<xop:Include href=:"cid:QueryBook_1_image"/>
</coverImage> Reference to the
<sample> two binary
<name>Introducing Web Services Security</name> attachments
<content>
<xop:Include href=:"cid:QueryBook_1_sample"/>
</content>
</sample>

MTOM/XOP Version of SOAP Message

The above code example shows the book query SOAP message serialized using the XOP format into
a MIME Multipart/Related package. It looks similar to the SOAP message shown previously. You
can identify MTOM in a SOAP message transmission over HTTP by the following attributes:
• The media type of the root part of the MIME Multipart/Related package is
application/xop+xml.
• The start-info parameter indicates a content type of application/soap+xml (SOAP
1.1) or text/xml (SOAP 1.2)
• The use of the xop:Include element to reference the binary attachments of the message.
With this element, the attached binary content logically becomes inline (by value) with the
SOAP document even though it is actually attached separately.

</ns1:book>
</soap:Body>
</soap:Envelope>

--MIME_boundary
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
Content-ID: < QueryBook_1_image>
Identifiers of the

Oracle University and Egabi Solutions use only

...binary JPG image... two attachments
--MIME_boundary-— of the MIME
Content-Type: application/octet-stream package
Content-Transfer-Encoding: binary
Content-ID: < QueryBook_1_sample >

...binary PDF...
--MIME_boundary-—

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 13
Quiz

Which of the following is not seen in a SOAP message

transmitted over HTTP when MTOM enabled?
1. A root MIME part
2. The use of the xop:Include element to reference the
binary attachments of the message

Oracle University and Egabi Solutions use only

3. The start-info parameter
4. Text-encoded binary attachments

Answer: 4

• The MTOM option is not enabled by default.

• MTOM/XOP support is standard in JAX-WS via the use of
JWS annotations.
• With JAX-WS, you can enable MTOM on the client side,
the server side, or both.

Oracle University and Egabi Solutions use only

Enabling MTOM for JAX-WS Web Services

MTOM is disabled by default, it should enabled at client side as well as server side. Once this is
enabled all the XML binary data and all elements of type xs:base64Binary and
xs:hexBianry are optimally transmitted. JAX-WS Web services require separate configuration of
the client and the server artifacts to enable MTOM support.

To use MTOM/XOP to send binary data:

1. Annotate the data types to use as an MTOM attachment
(optional).
2. Enable MTOM on the server side of the Web Service.
3. Enable MTOM on the client side.

Oracle University and Egabi Solutions use only

4. Optionally, set the attachment threshold.

Using MTOM/XOP to Send Binary Data

This list summarizes the steps required to use MTOM/XOP to send base64Binary attachments:
1. Annotate the data types that you are going to use as an MTOM attachment.
Depending on your programming model, you can annotate your Java class or WSDL to define
the content types that are used for sending binary data. This step is optional. By default, XML
binary types are mapped to Java byte[].
2. Enable MTOM on the server side of the Web Service
3. Enable MTOM on the client side
4. Optionally, set the attachment threshold.
JAX-WS allows the service and/or client to optimize only binary data that are larger than a
configured threshold.

MIME Type Java Type

image/gif java.awt.Image

image/jpeg java.awt.Image

Oracle University and Egabi Solutions use only

text/plain java.lang.String

text/xml or application/xml javax.xml.transform.Source

*/* javax.activation.DataHandler

MIME and Java Data Type Mappings

In the default way an element will be mapped to byte type. For example <element
name=“myImage" type="base64Binary"/> is mapped to byte[]
The above table shows the mapping of MIME content types to Java types. The first three mapping
are self explanatory.
• When the mime type is text/xml or application/xml, then it is mapped to
javax.xml.transform.Source. The Source here represents the objects of classes
which implement Source interface. It contains the information of application sources such as
DOMSource, SAXSource and StreamSource.
• A default MIME type-to-Java type mapping exists for the first four MIME types. If no default
exists, the MIME content types are mapped to javax.activation.DataHandler,
which represents data available in different forms.

Annotate the data types starting from Java:

• Annotate the field that holds the binary data using the
@XmlMimeType annotation.
• The field that contains the binary data must be of the
DataHandler type.

Oracle University and Egabi Solutions use only

@WebMethod
public void dataUpload(
@XmlMimeType("application/octet-stream") DataHandler data){
...
}

Annotating the Data Types: Start from Java

When starting from Java, to define the content types that are used for sending binary data, annotate
the field that holds the binary data using the @XmlMimeType annotation.
The field that contains the binary data must be of type DataHandler.
The above example shows how to annotate a field in the Java class that holds the binary data.

Annotate the WSDL element of the xs:base64Binary or

xs:hexBinary type using one of the following attributes:
• xmime:contentType: Defines the content type of the
element
• xmime:expectedContentType: Defines the range of
media types that are acceptable for the binary data

Oracle University and Egabi Solutions use only

Annotating the Data Types: Start from WSDL

In WSDL, schema elements of xs:bas64Binary or xs:hexBinary can be annotated using the
attribute xmime:contentType or xmime:expectedContentType. JAXB specification
provides a mapping between xmime:contentType or xmime:expectedContentType to
Java type.
The above example maps the image element of type base64binary to image/gif MIME type
(which maps to the java.awt.Image Java type).

With WLS, you can enable MTOM on the Web Service using an
annotation or WS-Policy file:
• Using annotation @MTOM
import javax.xml.ws.soap.MTOM;
...

Oracle University and Egabi Solutions use only

@MTOM
@WebService(name="MtomPortType",
serviceName="MtomService",
targetNamespace="http://example.org")
public class MTOMImpl {
@WebMethod
public String echoBinaryAsString(byte[] bytes) {
return new String(bytes);

}
}

Enabling MTOM on the Server Side: Annotation

To enable MTOM in the Web Service, specify the @java.xml.ws.soap.MTOM annotation on
the service endpoint implementation class, as illustrated in the above example.

Using the WS-Policy file:

• Use the prepackaged WS-Policy file Mtom.xml
• Associate the Mtom.xml file with a Web service at
development time using the @Policy annotation in your
JWS file

Oracle University and Egabi Solutions use only

– Specify the attachToWsdl=true attribute to ensure that
the dynamic WSDL includes the required reference to the
Mtom.xml file.
import weblogic.jws.Policy;
@WebService
@Policy(uri="policy:Mtom.xml", attachToWsdl=true)
public class MtomImpl {
@WebMethod
public String echoBinaryAsString(byte[] bytes) {
return new String(bytes);
}

Enabling MTOM on the Server Side: WS-Policy

In addition to the @MTOM annotation described in the previous section, WebLogic JAX-WS Web
Services support MTOM/XOP enablement using the pre-packaged WS-Policy file Mtom.xml. WS-
Policy files follow the WS-Policy specification, described at http://www.w3.org/TR/ws-policy; this
specification provides a general purpose model and XML syntax to describe and communicate the
policies of a Web Service, in this case the use of MTOM/XOP to send binary data.
When you deploy the compiled JWS file to WebLogic Server, the dynamic WSDL will automatically
contain the following snippet that references the MTOM WS-Policy file; the snippet indicates that
the Web Service uses MTOM/XOP:
<wsdl:binding name="BasicHttpBinding_IMtomTest“
type="i0:IMtomTest">
<wsp:PolicyReference URI="#myService_policy" />
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 21
Enabling MTOM on the Server Side: WS-Policy (continued)
You can associate the Mtom.xml WS-Policy file with a Web Service at development-time by
specifying the @Policy metadata annotation in your JWS file. Be sure you also specify the
attachToWsdl=true attribute to ensure that the dynamic WSDL includes the required reference
to the Mtom.xml file.
In addition, you can attach the file at runtime by using the Administration Console; for details, see
“Associate a WS-Policy file with a Web Service” in the Oracle Fusion Middleware Oracle
WebLogic Server Administration Console Help.

Oracle University and Egabi Solutions use only

Enabling MTOM by Using JDeveloper

In JDeveloper, you can use a feature of Web Services Properties wizard to enable MTOM for the
service endpoint. Once you select the SOAP HTTP binding version and enable the MTOM,
JDeveloper will add the appropriate annotations to the service endpoint implementation class:
• For SOAP 1.1, it adds the @MTOM annotation
• For SOAP 1.2, in addition to the @MTOM annotation, it also adds the
@javax.xml.ws.BindingType annotation on the class, specifying a value of
javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING, which is predefined
constant corresponding to the SOAP 1.2 HTTP binding identifier.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 23
Quiz

Which of the following statements is true concerning using

MTOM to send binary data?
1. Data type annotation is required.
2. You can enable MTOM on a Web service by using the WS-
Policy file.

Oracle University and Egabi Solutions use only

3. MTOM can be enabled only on the server side of Web
services.

Answer: 2

Enable MTOM on a Proxy client using Binding Provider:

Create a Binding
Provider from a proxy
port

Service svc = Service.create(serviceName);

MtomSample proxy = svc.getPort(portName, MtomSample.class);

Oracle University and Egabi Solutions use only

BindingProvider myBP = (BindingProvider) proxy;

//Enable MTOM
SOAPBinding binding = (SOAPBinding) myBP.getBinding();
binding.setMTOMEnabled(true);

Enable MTOM

Enabling MTOM on the Client Side

The above example shows how to enable MTOM on the dynamic proxy client by using the
javax.xml.ws.soap.SOAPBinding client-side API.

Enable MTOM on a Proxy client by passing MTOMFeature as

a parameter when creating the proxy:

import javax.xml.ws.soap.MTOMFeature;

public class Main {

public static void main(String[] args) {

Oracle University and Egabi Solutions use only

String FOO = "FOO";
MtomService service = new MtomService()
MtomPortType port = service.getMtomPortTypePort(new
MTOMFeature());
String result = null;
...
}

Enabling MTOM on the Client Side (continued)

You can also enable MTOM on the client of the Web Service by passing the
javax.xml.ws.soap.MTOMFeature as a parameter when creating the Web Service proxy or
dispatch, as illustrated in the above example. MTOMFeature is a subclass of
WebServiceFeature. A WebServiceFeature is used to represent a feature that can be
enabled or disabled for a Web service.

• You can set the attachment threshold to specify when the

binary data is sent inline or as an attachment.
• To set the attachment threshold:
– On the server side, pass the threshold attribute to the @MTOM
annotation. For example: @MTOM(threshold=3072)
– On the client side of the Web Service, pass the threshold

Oracle University and Egabi Solutions use only

value to javax.xml.ws.soap.MTOMFeature. For
example:
MtomPortType port =
service.getMtomPortTypePort(new
MTOMFeature(3072));

Setting the Attachment Threshold

MTOM allows to selectively encode portions of the message, which allows us to send
base64encoded data as well as externally attached raw binary data referenced by the XOP element to
be sent in a SOAP message. For optimum efficiency of MTOM, it is advised to send smaller binary
attachments using base64encoding (non-optimized) and larger attachments as optimized content.
By default, the attachment threshold is 0 bytes. All base64 data is sent as an attachment.
In each of the examples above, if a message is greater than or equal to 3 KB, it will be sent as an
attachment. Otherwise, the content will be sent inline, as part of the SOAP message body.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 27
Quiz

Identify the two ways to enable MTOM on the client side:

1. Using the Binding Provider of the proxy port
2. Using MTOMFeature when creating the proxy
3. Using the @MTOM annotation
4. Using the @Resource annotation

Oracle University and Egabi Solutions use only

Answers: 1, 2

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 28
Streaming MTOM

To increases the performance of Web services with large

SOAP messages, you can specify that a Web service use a
streaming API when reading inbound messages by using:
• MTOM
• javax.activation.DataHandler
•

Oracle University and Egabi Solutions use only

com.sun.xml.ws.developer.StreamingDataHandler

Streaming MTOM
Using MTOM and the javax.activation.DataHandler and
com.sun.xml.ws.developer.StreamingDataHandler APIs you can specify that a Web
Service use a streaming API when reading inbound SOAP messages that include attachments, rather
than the default behavior in which the service reads the entire message into memory. This feature
increases the performance of Web Services whose SOAP messages are particularly large.
The following several slides describe how to employ streaming SOAP attachments on the client and
server sides.
Note: The com.sun.xml.ws.developer.StreamingDataHandler API (see
https://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/developer/
StreamingAttachment.html) is supported as an extension to the JAX-WS RI, provided by Sun
Microsystems. Because this API is not provided as part of the WebLogic software, it is subject to
change.

@StreamingAttachment(parseEagerly=true, memoryThreshold=40000L)
@WebService
@MTOM Configure the streaming
public class Streaming { SOAP attachment.
public Streaming(){}
@Oneway Map the
@WebMethod DataHandler.
public void fileUpload(String fileName,
@XmlMimeType("application/octet-stream") DataHandler data) {

Oracle University and Egabi Solutions use only

try {
StreamingDataHandler dh = (StreamingDataHandler) data;
File file = new File(fileName);
dh.moveTo(file);
dh.close();
} catch (Exception e){
throw new WebServiceException(e); Store the
} attachment to
} a file.
@XmlMimeType("application/octet-stream")
@WebMethod
public DataHandler fileDownload(String filename){
return new DataHandler(new FileDataSource(filename));
}

Server-Side Implementation Code

Above code snippet shows the server-side implementation code. It demonstrates the following:
• The @StreamingAttachement annotation is used to configure the streaming SOAP
attachment.
• The @XmlMimeType annotation is used to map the DataHandler, as follows:
- If starting from WSDL, it is used to map the
xmime:expectedContentTypes="application/octet-stream" to
DataHandler in the generated SEI.
- If starting from Java, it is used to generate an appropriate schema type in the generated
WSDL.
• Cast the DataHandler to StreamingDataHandler and use the
StreamingDataHandler.moveTo(File) method to store the contents of the
attachment to a file.

public class Main { Enable MTOM on the client.

public static void main(String[] args) {
MtomStreamingService service = new MtomStreamingService();
MTOMFeature feature = new MTOMFeature();
MtomStreamingPortType port = service.getMtomStreamingPortTypePort(
feature);
Map<String, Object>
ctxt=((BindingProvider)port).getRequestContext();
ctxt.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 8192);

Oracle University and Egabi Solutions use only

DataHandler dh=new DataHandler(new
FileDataSource("/tmp/example.jar")); Configure HTTP
port.fileUpload("/tmp/tmp.jar",dh); streaming support.

DataHandler dhn = port.fileDownload("/tmp/tmp.jar");

StreamingDataHandler sdh = (StreamingDataHandler)dhn;
try{
File file = new File("/tmp/tmp.jar");
sdh.moveTo(file);
sdh.close();
}
catch(Exception e){ Store the
e.printStackTrace(); attachment to
}}} a file.

Client-Side Implementation Code

This code example employs streaming SOAP attachments on the client side.
• Enable MTOM on the Web service client, pass the javax.xml.ws.soap.MTOMFeature
as a parameter when creating the Web Service proxy or dispatch.
• Configure HTTP streaming support by enabling HTTP chunking on the MTOM streaming
client:
Map<String, Object> ctxt =
((BindingProvider)port).getRequestContext();
ctxt.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE,
8192);
• Call the port.fileUpload method.
• Cast the DataHandler to StreamingDataHandler and use the
StreamingDataHandler.moveTo() method to store the attachment.

You can configure streaming SOAP attachments on the client

and server sides to specify the following:
• Directory in which large attachments are stored
• Whether to parse the streaming attachments
• Maximum attachment size (bytes) that can be stored in

Oracle University and Egabi Solutions use only

memory
• Attachments that exceed the specified number of bytes be
written to a file

Configuring Streaming SOAP Attachments

Configuring Streaming SOAP Attachments on the Server
To configure streaming SOAP attachments on the server, add the @StreamingAttachment
annotation on the endpoint implementation. The example below specifies that streaming attachments
are to be parsed eagerly and sets the memory threshold to 4MB. Attachments under 4MB are stored
in memory.
import com.sun.xml.ws.developer.StreamingAttachment;
@StreamingAttachment(parseEagerly=true, memoryThreshold=4000000L)
@WebService
public class StreamingImpl {
...
}

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 32
Configuring Streaming SOAP Attachments (continued)
Configuring Streaming SOAP Attachments on the Client
To configure streaming SOAP attachments on the client, create a StreamingAttachmentFeature
object and pass this as an argument when creating the PortType stub implementation. The following
example sets the directory in which large attachments are stored to /tmp, specifies that streaming
attachments are to be parsed eagerly (immediately rather then on request) and sets the memory
threshold to 4MB. Attachments under 4MB are stored in memory.
import com.sun.xml.ws.developer.StreamingAttachmentFeature;
MTOMFeature mtom = new MTOMFeature();
StreamingAttachmentFeature stf = new
StreamingAttachmentFeature("/tmp", true, 4000000L); // true =

Oracle University and Egabi Solutions use only

parse eagerly.
MtomStreamingService service = new MtomStreamingService();
MtomStreamingPortType port =
service.getMtomStreamingPortTypePort(mtom, stf);

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 33
Summary

In this lesson, you should have learned how to:

• Describe the challenges of binary data transmission
• Describe how MTOM addresses the challenges
• Explain the relationships between SOAP with Attachment,
XOP, and MTOM

Oracle University and Egabi Solutions use only

• Enable MTOM optimization on the client side
• Enable MTOM optimization on the server side

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 10 - 34
Practice 10 Overview:
Enabling MTOM in JAX-WS Web Services
This practice covers the following topics:
• Enabling an existing Web service to support MTOM
• Extending an existing Web service Java client to use
MTOM

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
JAX-WS Binding Customization

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe JAXB and its relationship with JAX-WS
• Describe the JAXB data binding framework
• Describe how to use JAX-WS binding customization
• Use JAXB annotations to customize Java classes

Oracle University and Egabi Solutions use only

• Use the JAXB binding language to customize XML
schema

Objectives
This lesson focuses on describing how the JAXB runtime performs serialization and deserialization
based on the annotations, and how you can use your own annotations to customize the behavior of
the JAXB serialization and deserialization processes.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 2
JAX-WS and JAXB

JAX-WS:
• Binds Java method signatures and WSDL messages and
operations
– Method name is mapped to port type operation.
– Method parameters are mapped to message parts.

Oracle University and Egabi Solutions use only

• Delegates the mapping of Java types to and from XML
definitions to JAXB
– Allows you to customize the mapping while automatically
handling the run-time conversion
• Serializers are used to implement type mappings.

JAX-WS and JAXB

With the emergence of XML as the standard for exchanging data across disparate systems, Web
Service applications need a way to access data that are in XML format directly from the Java
application. Specifically, the XML content needs to be converted to a format that is readable by the
Java application. Data binding describes the conversion of data between its XML and Java
representations.
JAX-WS binds Java method signatures and WSDL messages and operations. However, the mapping
of the message parts to the method parameters is not defined in the WSDL. JAX-WS uses JAXB to
manage all of the data binding tasks. This makes it easy for you to incorporate XML data and
processing functions in applications based on Java technology without having to know much about
XML.
Serializers are used to implement type mappings. A serializer converts an instance of a type
mapping’s Java type into an instance of its XML Schema component. A deserializer does the reverse.

Custom JAXB
Binding Annotations
Declarations

Schema Derived
XML and Existing Java

Oracle University and Egabi Solutions use only

Schema Bind
classes

Unmarshal
HTTP SOAP XML Java Objects
Marshal

JAXB

Data Binding with JAXB

The XML schema file along with the annotated Java class files contain all the necessary information
that the JAXB runtime requires to parse the XML documents for marshaling and unmarshaling.
The main process tasks are:
• Bind: Binds XML schema to schema-derived JAXB Java classes, or value classes. Each value
class provides access to the content of its corresponding schema component using get/set
properties.
• Unmarshal:
- The process converts the XML document to create a tree of Java objects, the objects here
represents the content and organization of the XML that can be accessed by Java code.
- The values in the XML tree can be accessed using getters and setters methods of Java
class.
- Unmarshaling is managed by the JAXB binding framework.
• Marshal: Converts the Java objects back to XML content. In this case, the Java methods that
are deployed as WSDL operations determine the schema components in the wsdl:types
section. Marshaling is the reverse process of Unmarshaling. It is managed by the JAXB binding
framework as well.

• Mapping strategies are needed to tell how to implement

the type mappings.
• Mechanisms for implementing type mappings:
– Standard binding: The mappings are predefined by a
standard binding of Java classes to XML Schema or vice
versa.

Oracle University and Egabi Solutions use only

– Annotations: To customize the Java-to-XML mapping
– Custom binding declarations: To customize XML-to-Java
mapping

Type Mapping Mechanisms

The type mappings, from Java classes to target XML Schema components, are implemented by
mapping strategies. A mapping strategy associates a Java class, its target XML Schema type, and a
description of a serializer (or deserializer) that can transform instances of the class to instances of the
Schema type (or vice versa).
Different Web services platforms provide different mechanisms for specifying the mapping
strategies. WebLogic Server provides the following mechanisms:
• Standard binding: The mappings are predefined by a standard binding of Java classes to XML
Schema. The standard binding is specified in the JAXB and JAX-WS specifications.
• Annotations: JWS uses this approach to provide customizations on top of the standard binding.
Annotations in the source code of a target Java class modify the standard binding to specify
how the class maps to XML Schema components and how the WSDL description of the Web
service is shaped.
• Custom binding declarations: To control the XML-to-Java mapping, you can define custom
binding declarations within the WSDL or XML Schema, or in an external file.

• JAXB is a Java/XML binding tool, which maps each Java

element to a unique schema component.
• JAXB binding supports two scenarios:
– Start from XML Schema:
JAXB schema
compiler

Oracle University and Egabi Solutions use only

XML Java
binding
Schema Classes
– Start from Java:

JAXB schema
generator
XML Java
binding
Schema Classes

JAXB Binding Scenarios

Java/XML binding is when a Java/XML map sends each Java programming element to a unique
XML Schema component. JAXB 2.1 is best thought of as a Java/XML binding tool. That is because
the annotations on the Java classes used by JAXB define a binding. Each class maps to a unique
XML Schema component based on its annotations.
The binding provides this mechanism by associating a set of Java classes with an XML schema so
that schema instances are manipulated using Java methods. This makes it easy for Java programmers
to work with XML instances of the schema.
JAXB binding supports two scenarios:
• Start from XML Schema: In this scenario, the schema exists first and the Java classes in the
data binding are created using a JAXB schema compiler.
• Start from Java: In this scenario, the Java classes exist first and are used to generate an XML
schema via a JAXB schema generator. The classes need not be explicitly annotated, because
JAXB defines defaults to supply implied annotations wherever needed.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 6
Quiz

JAXB binding provides a mechanism to:

1. Associate a set of Java classes with XML instances
2. Convert an instance of a Java type into an instance of its
XML Schema component
3. Associate a set of Java classes with an XML schema

Oracle University and Egabi Solutions use only

4. Map Java class method name to port type operation in the
WSDL file

Answer: 3

• Java/ XML binding represents XML Schema components

as Java content.
• JAXB schema compiler generates JAXB schema-derived
Java elements from an XML schema:
– Simple types are mapped to Java primitives.

Oracle University and Egabi Solutions use only

– Complex types are mapped to Java value classes.
— The elements and attributes of a complex type are mapped to
properties of a Java value class.
– The basic structure of a value class is determined by its
source schema component.

Binding XML Schema to Java Representation

JAXB specification provides a standard Java/ XML binding that represents XML Schema
components (for example, elements, types, and attributes) as Java content (for example, classes and
bean properties). This binding maps the WSDL message parts to Java method parameters and return
types that are used during invocation of a Web service.
JAXB implementations provide a schema compiler that generates JAXB schema-derived Java
elements from an XML schema. Usually, the schema-derived program elements generated from
complex types are referred to as Java value classes. Each class provides access to the content via a set
of JavaBean-style access methods (that is, get and set). So, the elements and attributes of a
complex type are mapped to properties of a Java value class. In contrast to complex types, simple
types—and particularly the built-in XML Schema types like xs:string—are mapped to the
corresponding Java primitives, for example java.lang.String.

WSDL of the Web service

<wsdl:types>
<xs:schema version="1.0“ targetNamespace=“..." ComplexType
xmlns:xs="http://www.w3.org/2001/XMLSchema"> element named
<xs:complexType name="reservation"> reservation
<xs:sequence>
<xs:element name="bookId" type="xs:int"/>
<xs:element name="reservationId" type="xs:int"/>
<xs:element name="username" type="xs:string“

Oracle University and Egabi Solutions use only

minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:schema>

JavaBean Reservation.java JavaBean

public class Reservation { properties
...
public int getReservationId() { return reservationId; }
public int getBookId() { return bookId; }
public String getUsername() { return username; }
}

Example of XML Schema-to-Java Mapping

The example above shows how a complex type element, reservation, in XML schema is
mapped to the Java value class, Reservation.java.

• In “start from Java” approach, Java/XML binding provides

a standard map from Java classes to XML Schema.
• JAX-WS uses the standard mapping to generate WSDL
from a Java class.
• How it works:

Oracle University and Egabi Solutions use only

– The parameters and return type of a Java method determine
the schema components in the wsdl:types section.
– JAXB schema generator looks for JavaBeans style
properties and maps them to XML elements and attributes.

Mapping Java Types to XML Schema

The JAXB Java/XML binding also provides a standard map from Java classes to XML Schema.
JAX-WS uses this map to generate WSDL from a Java class deployed as a Web service. At run-time,
JAXB marshals the Java objects to generate the XML content which is then packaged in a SOAP
message and sent as a Web Service request or response.
In this “Start from Java” programming model, the parameters and return type of a Java method being
deployed as a wsdl:operation determine the schema components in the wsdl:types section.
JAXB provides a schema generator that creates schema from existing classes using the standard map.
The schema generator looks for JavaBeans style properties and maps them to elements and attributes.
If the class you start with doesn’t look like a JavaBean, not much XML Schema can be generated
from it.

• JAXB 2.1 (JSR 222) specifies a full set of built-in XML

Schema, Java, and SOAP types.
• WebLogic Web services support the data type mapping as
follows:
– Built-in data types

Oracle University and Egabi Solutions use only

— XML-to-Java Mapping for built-in data types
— Java-to-XML Mapping for built-in data types
– User-defined data types
— XML user-defined data types
— Java user-defined data types

Data Type Mapping

WebLogic Web services support a full set of built-in XML Schema, Java, and SOAP types, as
specified by the JAXB 2.1 (JSR 222) specification, that you can use in your Web service operations
without performing any additional programming steps. Built-in data types are those such as integer,
string, and time.
Additionally, you can use a variety of user-defined XML and Java data types as input parameters and
return values of your Web Service. User-defined data types are those that you create from XML
Schema or Java building blocks, such as <xsd:complexType> or JavaBeans. JDeveloper, OEPE,
or the WebLogic Web services Ant tasks, such as jwsc and clientgen, automatically generate
the data binding artifacts needed to convert the user-defined data types between their XML and Java
representations. The XML representation is used in the SOAP request and response messages, and
the Java representation is used in the JWS that implements the Web service.

XML Schema Data Type Java Data Type

base64Binary byte[]

boolean boolean

byte byte

date, time java.xml.datatype.XMLGregorianCalendar

Oracle University and Egabi Solutions use only

decimal java.math.BigDecimal

double double

float float

int int

integer java.math.BigInteger

long long

Qname javax.xml.namespace.QName

string java.lang.String

Built-in Data Types: XML-to-Java Mapping

The above table lists, in the alphabetical order, most of the supported XML Schema data types (target
namespace http://www.w3.org/2001/XMLSchema) and their corresponding Java data types.
For the complete list, please see Using JAXB Data Binding of Oracle® Fusion Middleware Getting
Started With JAX-WS Web Services for Oracle WebLogic Server 11g Release 1 (10.3.1)

Java Data Type XML Schema Data Type

javax.activation.DataHandler base64Binary

java.awt.Image base64Binary

java.lang.Object Any Type

java.net.URI string

Oracle University and Egabi Solutions use only

java.util.Calendar dateTime

java.util.Date dateTime

javax.xml.namespace.QName QName

javax.xml.transform.Source base64Binary

short short

Built-in Data Types: XML-to-Java Mapping (continued)

The above table lists, in the alphabetical order, some of the supported Java data types and their
equivalent XML Schema data types. For the complete list, please see Using JAXB Data Binding of
Oracle® Fusion Middleware Getting Started With JAX-WS Web Services for Oracle WebLogic
Server 11g Release 1 (10.3.1)

XML Schema Data Type Equivalent Java Data Type or Mapping

Mechanism

<xsd:complexType> JavaBean

<xsd:attribute> in <xsd:complexType> Property of a JavaBean

<xsd:list> Array of the list data type

Array derived from soapenc:Array by Array of Java equivalent

Oracle University and Egabi Solutions use only

restriction

Derivation of new simple types by Equivalent Java data type of simple type
restriction of an existing simple type

Facets used with restriction element Facets not enforced during serialization
and deserialization

<xsd:anyType> java.lang.Object

<xsd:any> javax.xml.soap.SOAPElement

<xsd:any[ ]> javax.xml.soap.SOAPElement[ ]

<xsi:nil> and <xsd:nillable> attribute Java null value

Supported User-Defined XML Schema Data Types

When using user-defined data types, then you must create the data binding artifacts that convert the
data between XML and Java. JDeveloper, WLS jwsc and wsdlc Ant tasks that can automatically
generate the data binding artifacts for most user-defined data types.
The above table lists the XML Schema data types supported by the WebLogic tooling and their
equivalent Java data type or mapping mechanism.

Java Data Type Equivalent XML Schema Data Type

JavaBean whose properties are any <xsd:complexType> whose content model
supported data type is an <xsd:sequence> of elements
corresponding to JavaBean properties

Array and multidimensional array of An element in an <xsd:complexType> with

any supported data type (when used the maxOccurs attribute set to unbounded
as a JavaBean property)

Oracle University and Egabi Solutions use only

java.lang.Object <xsd:anyType>

java.util.Collection Literal Array

java.util.List Literal Array

java.util.ArrayList Literal Array

java.util.LinkedList Literal Array

java.util.Stack Literal Array

java.util.Set Literal Array

java.util.TreeSet Literal Array

Supported Java User-Defined Data Types

The above table lists the Java user-defined data types supported by the jwsc and wsdlc Ant tasks
and their equivalent XML Schema data type.

• Annotations define a set of type mapping and serve as the

marshalling instructions for implementing the type
mapping.
• Mapping annotations are the mechanism used by JAXB
for:
– Customizing the standard Java/XML binding

Oracle University and Egabi Solutions use only

– Controlling a binary data encoding
• JAXB annotations are available with the
javax.xml.bind.annotation package.

Customizing Java-to-XML Using Annotations

Annotations enable the Java programmer to specify the type mappings and are used at runtime to
marshal JAXB classes to/from an XML infoset representation.
In the “Start from Java” approach, the schema generator requires two inputs: a set of classes and a set
of mapping annotations. The schema generator, however, assumes defaults for everything, so if there
are no annotations, the schema generated is based entirely on the default Java/XML binding.
Mapping annotations allow you to override those default binding rules for Java-to-XML Schema
mapping. Another use for mapping annotations is controlling a binary data encoding—for example,
how binary data such as images are encoded.
JAX–WS binding customizations are used to customize name space to package mapping, mapping
operation name in WSDL to service endpoint interface (SEI) method name and the parameter names
of generated SEI method. This provision would give us flexibility in defining custom names.

Annotation Description
@XmlAccessorType Specifies whether fields or properties are mapped by default.

@XmlElement Maps a property contained in a class to a local element in the XML

Schema complex type to which the containing class is mapped.

Oracle University and Egabi Solutions use only

@XMLMimeType Associates the MIME type that controls the XML representation of
the property with a textual representation, such as image/jpeg

@XmlRootElement Maps a top-level class to a global element in the XML Schema that
is used by the WSDL of the Web Service.

@XmlSeeAlso Binds other classes when binding the current class

@XmlType Maps a class or enum type to an XML Schema type

JAXB Mapping Annotations

If required, you can override the default binding rules for Java-to-XML Schema mapping using
JAXB annotations. The above table summarizes the JAXB mapping annotations that you can include
in your JWS file to control how the Java objects are mapped to XML. Each of these annotations are
available with the javax.xml.bind.annotation package, described at
http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/package-tree.html.
For detailed explanation of each annotation, please see Using JAXB Data Binding of Oracle®
Fusion Middleware Getting Started With JAX-WS Web Services for Oracle WebLogic Server 11g
Release 1 (10.3.1)

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "reservation", propOrder = {
"bookId",
"reservationId",
"username"
})

Oracle University and Egabi Solutions use only

public class Reservation {

@XmlElement(namespace = "http://ws.library.com/types”)
protected int bookId;
@XmlElement(namespace = "http://ws.library.com/types”)
protected int reservationId;
@XmlElement(namespace = "http://ws.library.com/types”)
protected String username;
...
}

Example of JAXB Annotations

• The @XmlAccessorType annotation specifies whether fields or properties are mapped by
default. The annotation can be specified for the Java program elements: package and top-level
class. The @XmlAccessorType can be specified with the @XmlType and
@XmlRootElement annotations.
• The @XmlType annotation tells the JAXB runtime which schema type to map a class to and
specifies some aspects of the mapping.
• The @XmlElement annotation tells the JAXB runtime that a particular property or field maps
to a schema element definition.
In the above code snippet, the @XmlAccessorType annotation tells JAXB to map the fields
(hence the value XmlAccessType.FIELD) to schema element definitions. For example, the
String field—username—gets mapped to an XML element named username. Likewise, the
@XmlType annotation tells JAXB to map the class Reservation to an XML schema complex
type. Finally, the @XmlElement annotations provide a namespace for the elements.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 18
Quiz

Which of the following annotations maps a Java class to an

XML schema complex type:
1. @XmlAccessorType
2. @XmlType
3. @XmlSeeAlso

Oracle University and Egabi Solutions use only

4. @XmlElement

Answer: 2

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 19
Customizing XML Schema-to-Java Mapping Using
Binding Declaration
• Binding declarations can be used to control:
– Specific features, such as asynchrony, wrapper style, and so
on
– JAXB data binding artifacts that are produced by customizing
the XML Schema
• Two ways to define binding declarations:

Oracle University and Egabi Solutions use only

– Create an external binding declaration file that contains all
binding declarations for a specific WSDL or XML Schema
document.
– Embed binding declarations within the WSDL or XML
Schema document.

Customizing XML Schema-to-Java Mapping Using Binding Declaration

Due to the distributed nature of a WSDL, you cannot always control or change its contents to meet
the requirements of your application. For example, the WSDL may not be owned by you or it may
already be in use by your partners, making changes impractical or impossible.
When directly editing/modifying WSDL is not an option, you can specify custom binding
declarations to customize XML-to-Java mapping.
Binding declarations can be used to control specific features, such as asynchrony, wrapper style, and
so on. Binding declarations can also control JAXB data binding artifacts that are produced by
customizing the XML Schema.
Two ways to define binding declarations.
• Create an external binding declaration file that contains all binding declarations for a specific
WSDL or XML Schema document.
• Embed binding declarations within the WSDL or XML Schema document.

Global scope

Schema scope

Definition scope

Oracle University and Egabi Solutions use only

Component scope

Scopes of Custom Binding Declarations

Binding Declarations have scope:
Global scope
Describes customization values with global scope. Specifically:
• For JAX-WS binding declarations, describes customization values that are defined as part of
the root element, as described in Specifying the Root Element.
• For JAXB annotations, describes customization values that are contained within the
<globalBindings> binding declaration. Global scope values apply to all of the schema
elements in the source schema as well as any schemas that are included or imported.
Schema scope
Describes JAXB customization values that are contained within the <schemaBindings> binding
declaration. Schema scope values apply to the elements in the target namespace of a schema.
Definition scope
Describes JAXB customization values that are defined in binding declarations of a type definition or
global declaration. Definition scope values apply to elements that reference the type definition or
global declaration.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 21
Scope of Custom Binding Declarations (continued)
Component scope
Describes customization values that apply to the WSDL or schema element that was annotated.
Scopes for custom binding declarations adhere to the following inheritance and overriding rules:
• Inheritance—Customization values are inherited from the top down. For example, a WSDL
element (JAX-WS) in a component scope inherits a customization value defined in global
scope. A schema element (JAXB) in a component scope inherits a customization value defined
in global, schema, and definition scopes.
• Overriding—Customization values are overridden from the bottom up. For example, a WSDL
element (JAX-WS) in a component scope overrides a customization value defined in global
scope. A schema element (JAXB) in a component scope overrides a customization value
defined in definition, schema, and global scopes.

Oracle University and Egabi Solutions use only

• You can create an external binding declaration file using:

– JAX-WS binding declarations
– JAXB binding declarations
• The main tasks are:
– Create an external binding declaration file that contains all

Oracle University and Egabi Solutions use only

binding declarations for a specific WSDL or XML Schema
document
– Pass the binding declaration file to the <binding> child
element of the wsdlc, jwsc, or clientgen Ant task

Creating an External Binding Declarations File

You can create a binding declaration file using either JAX-WS Binding Declarations or JAXB
Binding Declarations.
Unlike annotations, which are always inline with the Java source code, the binding declarations, can
be provided either inline with the XML schema (that is, an inline annotated schema) or in a separate
configuration file (that is, an external binding declaration).

Customization Description
Package name Use the jaxws:package binding declaration to define the
package name.

Wrapper-style rules Use the jaxws:enablesWrapperStyle binding

declaration to enable or disable the wrapper style rules that
control how the parameter types and return types of a
WSDL operation are generated.

Oracle University and Egabi Solutions use only

Class name Use the jaxws:class binding declaration to define the
class name. This binding declaration can be specified for
one of the following nodes:
wsdl:portType: Defines the interface class name.
wsdl:fault: Defines fault class names.
soap:headerfault: Defines exception class names.
wsdl:service: Defines the implementation class names.

Method name Use the jaxws:method binding declaration to customize

the generated Java method name of a service endpoint
interface or the port accessor method in the generated
Service class.

JAX-WS Custom Binding Declarations

For a complete list of JAX-WS custom binding declarations, see JAX-WS WSDL Customization at
https://jax-ws.dev.java.net/nonav/2.1.2/docs/customizations.html.

Customization Description
Java parameter name Use the jaxws:parameter binding declaration to
customize the parameter name of generated Java
methods. This declaration can be used to change the
method parameter of a wsdl:operation in a wsdl:portType.

Asynchrony Use the jaxws:enableAsycMapping binding

declaration to instruct the clientgen Ant task to

Oracle University and Egabi Solutions use only

generate asynchronous polling and callback operations
along with the normal synchronous methods when it
compiles a WSDL file.

Provider Use the jaxws:provider binding declaration to mark

the part as a provider interface. This binding declaration
can be specified as part of the wsdl:portType. This
binding declaration applies when you are developing a
service starting from a WSDL file.

Handler chain Use the javaee:handlerchain binding declaration to

customize or add handlers.

<jaxws:bindings
wsdlLocation="http://localhost:7001/simple/SimpleService?WS
DL"
xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" >
<package name="example.webservices.simple.simpleservice">

Oracle University and Egabi Solutions use only

<enableWrapperStyle>true</enableWrapperStyle>
<enableAsyncMapping>false</enableAsyncMapping>
</jaxws:bindings>

Example of JAX-WS Custom Binding Declarations

The above code snippet shows an example of the root binding element that defines the package
name, wrapper style, and asynchronous mapping customizations.
Specifying the Root Element
The jaxws:bindings declaration is the root of all other binding declarations and defines the
location of the WSDL file and the namespace to which the XML Schema conforms:
http://java.sun.com/xml/ns/jaxws.
The package, wrapper style, and asynchronous mapping customizations, defined in previous tables,
can be globally defined as part of the root binding declaration in the external customization file.
Global bindings apply to the entire scope of the wsdl:definition in the WSDL referenced by the
wsdlLocation attribute.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 26
Creating an External Binding Declarations File
Using JAXB Binding Declarations
• The JAXB binding declarations file is an XML document
that conforms to the XML Schema for the namespace:
http://java.sun.com/xml/ns/jaxb
• The format of the root declaration is as follows:
<jaxb:bindings schemaLocation="uri_of_schema">

Oracle University and Egabi Solutions use only

An example defines the package name as
examples.webservices.simple.simpleservice.
Root
<jaxb:bindings schemaLocation="simpleservice.xsd"> declaration
<jaxb:bindings node="//xs:simpleType[@name='value1']">
<jaxb:package
Child
name="examples.webservices.simple.simpleservice"/> element
</jaxb:bindings>
</jaxb:bindings>

Creating an External Binding Declarations File Using JAXB Binding Declarations

The JAXB binding declarations file is an XML document that conforms to the XML Schema for the
namespace: http://java.sun.com/xml/ns/jaxb. The jaxb:bindings declaration is
the root of all other binding declarations. The format of the root declaration is:
<jaxb:bindings schemaLocation="uri_of_schema">
The root jaxb:bindings element can contain child elements. You specify the schema node that
is being customized by passing an XPath expression in the node attribute. The above code example
shows how to specify the root and child elements of the JAXB binding declarations file.

Customization Description
Global bindings Use the <globalBindings> binding declaration to
define binding declarations with global scope.
You can specify attributes and elements to the
<globalBindings> binding declaration:
• collectionType attribute that specifies a type class
• generateIsSetMethod attribute to generate the
isSet() method corresponding to the getter and setter

Oracle University and Egabi Solutions use only

property methods
• javaType element to customize the binding of an XML
Schema atomic datatype to a Java datatype

Schema bindings Use the <schemaBindings> binding declaration to

define binding declarations with schema scope.

Package name Use the <package> element of the

<schemaBindings> binding declaration to define the
package name for the schema.

Class name Use the <class> binding declaration to define the class
name for a schema element.

JAXB Custom Binding Declarations

The above table lists the typical JAXB customizations. It only summarizes the JAXB custom
binding declarations, to help get you started. For a complete list and description of all JAXB custom
binding declarations, see the JAXB specification (http://jcp.org/en/jsr/detail?id=222) or
"Customizing JAXB Bindings" in the Sun Java EE 5 Tutorial.

Customization Description
Java property name Use the <property> binding declaration to define the
property name for a schema element.

Java datatype Use the <javaType> binding declaration to customize

the binding of an XML Schema atomic datatype to a Java
datatype (built-in or application-specific).

Oracle University and Egabi Solutions use only

Specifying Child Elements

<jaxb:bindings schemaLocation="simpleservice.xsd">
<jaxb:bindings node="//xs:simpleType[@name='value1']">
<jaxb:package
name="examples.webservices.simple.simpleservice"/>
</jaxb:bindings>

Oracle University and Egabi Solutions use only

</jaxb:bindings>

Example of JAXB Custom Binding Declarations

The root jaxb:bindings element can contain child elements. You specify the schema node that
is being customized by passing an XPath expression in the node attribute.
The above example defines the package name as
examples.webservices.simple.simpleservice.

You can also embed binding declarations in a WSDL file using

one of the following methods:
What How Where

Binding Declaration Used Element File

Oracle University and Egabi Solutions use only

JAX-WS or JAXB jaxws:bindings WSDL file
element
JAXB In <appinfo> element XML schema

Embedding Binding Declarations

You can embed binding declarations in a WSDL file using one of the following methods:
• Embed a JAX-WS or JAXB binding declaration in the WSDL file using the
jaxws:bindings element as a WSDL extension.
• Embed a JAXB binding declaration in the XML Schema as part of an <appinfo> element.

<wsdl:portType name="SimpleServiceImpl">
<jaxws:bindings
xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
<jaxws:class name="SimpleService"/>
</jaxws:bindings>
</wsdl:portType>

Oracle University and Egabi Solutions use only

Embedding JAX-WS or JAXB Binding Declarations in the WSDL File

You can embed a binding declaration in the WSDL file using the jaxws:bindings element as a
WSDL extension.
The above example defines the class name as SimpleService for the SimpleServiceImpl
service endpoint interface (or port).
If this binding declaration had not been specified, the class name of the service endpoint interface
would be set to the wsdl:portType name—SimpleServiceImpl—by default.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 32
Embedding JAXB Binding Declarations in the
XML Schema
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.w3.org/2001/XMLSchema"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
jaxb:version="2.0">
<annotation>
<appinfo>
<jaxb:schemaBindings>

Oracle University and Egabi Solutions use only

<jaxb:package
name="example.webservices.simple.simpleservice"/>
</jaxb:schemaBindings>
</appinfo>
</annotation>
</schema>

Embedding JAXB Binding Declarations in the XML Schema

The above example defines the package name in the schema.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 33
Quiz

You can define custom binding declarations by using:

1. External JAX-WS binding declaration file
2. External JAXB binding declaration file
3. Embedded JAX-WS binding declarations
4. Embedded JAXB binding declarations

Oracle University and Egabi Solutions use only

5. All of above

Answer: 5

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 34
Summary

In this lesson, you should have learned how to:

• Describe JAXB and its relationship with JAX-WS
• Describe the JAXB data binding framework
• Describe how to use JAX-WS binding customization
• Use JAXB annotations to customize Java classes

Oracle University and Egabi Solutions use only

• Use the JAXB binding language to customize XML
schema

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 11 - 35
Practice 11 Overview:
Customizing JAX-WS Web Services Data Binding
This practice covers the following topics:
• Using JAXB to generate a set of Java classes representing
the schema definition
• Using the schemagen tool to generate schema from
existing Java

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Objectives

After completing this lesson, you should be able to:

• Describe the differences between JAX-WS and JAX-RPC
• Implement JAX-RPC service endpoints
• Implement a JAX-RPC Web services client
• Describe data binding in JAX-RPC

Oracle University and Egabi Solutions use only

• Describe the requirement of packaging and deploying JAX-
RPC Web services

Objectives
JAX-WS is the next generation Web services programming model extending the foundation provided
by the JAX-RPC programming model. Both JAX-WS and JAX-RPC programming models and
applications are still supported in WebLogic Server. Note that some features only exist in one style
of Web Service versus the other.. This lesson focuses on the differences between JAX-WS and JAX-
RPC.

• JAX-RPC is the ancestor of JAX-WS. It includes:

– The original standard for Web services in Java
– J2EE 1.4 APIs based
– Mostly standard-based but uses a proprietary data mapping
and parsing model
• WebLogic Server supports both JAX-RPC and JAX-WS

Oracle University and Egabi Solutions use only

programming models.
• Note: Java EE 5 adds support for JAX-WS, but it also
retains support for JAX-RPC.

JAX-RPC Versus JAX-WS

JAX-RPC is a technology to support XML-based RPC standards in Java. It was created to promote
interoperability between Web services executing in heterogeneous platforms and developed in
different languages. JAX-RPC was a standards-based implementation, but the binding and parsing
layers underneath it were proprietary, and Web services runtime from data binding functionality were
intermingled in JAX-RPC. Additionally, JAX-RPC 1.1 does not completely cover schema
specification.
JAX-RPC later evolved into JAX-WS – mainly to reflect that Web Services are more than just RPC
and are about communicating XML documents.

JAX-RPC JAX-WS
SOAP version 1.1 1.1 and 1.2

Java version J2EE 1.4 Java EE 5.0

HTTP bindings No Yes

Oracle University and Egabi Solutions use only

WS-I BP 1.0 1.0 and 1.1

Data mapping model Built-in binding and JAXB and StAX

parsing

Asynchronous No Yes

MTOM * No Yes

Handler model Based on SAAJ 1.1 Based on SAAJ 1.2

Standards/Features Supported by JAX-RPC and JAX-WS

The above table shows the differences of the standards/features supported by JAX-RPC and JAX-
WS:
• JAX-RPC supports only SOAP 1.1, whereas JAX-WS supports both SOAP 1.1 and 1.2
versions.
• JAX-RPC maps to Java 1.4, whereas JAX-WS maps to Java 5.0. JAX-WS uses lot of features
which are new in Java 5.0 for example annotations.
• JAX-RPC doesn’t allow HTTP binding which is defined in WSDL 1.1. By HTTP binding we
can send XML messages over HTTP without SOAP. JAX-WS allows HTTP binding as it
implements WSDL 1.1.
• JAX-RPC supports WS-I’s BP (basic profile) version 1.0 whereas JAX-WS supports 1.1.
• JAX-RPC has its own data mapping model which covers almost 90% of the XML schema
where JAX-WS uses JAXB data mapping. JAXB covers mappings for all XML schema.
• JAX-WS introduces asynchronous functionality which is not included in JAX-RPC
• JAX-WS adds support for MTOM where as JAX-RPC doesn’t have MTOM support.
* However, WebLogic Server supports MTOM feature for JAX-RPC Web services.
• The handler model has changed a lot from JAX-RPC to JAX-WS. JAX-RPC handlers depends
on SAAJ 1.2 specifications where as JAX-WS depends on SAAJ 1.3
As shown here, some benefits of JAX-WS over JAX-RPC include support for newer standards,
improved data binding, better support for attachments using MTOM, support for EJB 3, and an
THESEimproved and easier
eKIT MATERIALS AREprogramming
FOR YOUR USE model using
IN THIS annotationsONLY.
CLASSROOM . COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 12 - 4
WebLogic’s Support for JAX-RPC

• WebLogic Server supports the JAX-RPC programming

model in the following ways:
– J2EE 1.4 APIs – javax.xml.rpc.***
– Java EE 5 – Annotations
• Standards/features supported under the JAX-RPC stack:

Oracle University and Egabi Solutions use only

– WS-Addressing
– WS-ReliableMessaging
– WS-SecureConversation
– WS-Trust
– Conversational Web services
– MTOM

WebLogic’s Support for JAX-RPC

WebLogic Server supports the full Java EE 5 specification. Java EE 5 is the successor to J2EE 1.4. It
adds support for JAX-WS, but still retains support for JAX-RPC. WebLogic Server allows you to
create a Web service using the traditional J2EE 1.4 APIs or the annotations which is introduced in
Java EE 5.

JAX-RPC supports two server-side programming models:

• JAX-RPC service endpoints (JSE) – POJO
– Runs inside the J2EE Servlet container
– Has access to the same resources and contexts as a
standard servlet

Oracle University and Egabi Solutions use only

• EJB endpoints – Stateless session beans
– Use only when you need to exploit the transactional qualities
of EJB

JAX-RPC Server-Side Programming Models

JAX-RPC defines two server-side programming models for creating J2EE Web service endpoints:
JAX-RPC service endpoints and EJB endpoints.
JSE is the simplest way to create a Web service in J2EE and will be the one you use the most. In
reality, a JSE is a full-fledged J2EE component, which runs inside the J2EE Servlet container. It has
access to the same resources and contexts as a standard servlet, but instead of exposing HTTP
streams, it marshals SOAP messages into method invocations defined by a remote interface.

JAX-RPC Web Container

Client

Oracle University and Egabi Solutions use only

1 2 Service
Stub SOAP/HTTP Servlet Java Endpoint
4 3

JAX-RPC Service Endpoints Run-Time Architecture

The diagram shows how a JAX-RPC client invokes an operation on JAX-RPC service endpoint
interface:
1. Stub runs in client side JAX-RPC runtime system or standalone and sends a SOAP request over
HTTP to server.
The stub is nothing but a service endpoint interface and also has the intelligence to convert
Java types to SOAP (requests) and SOAP to Java types (responses).
2. The servlet inside the run time system marshal the SOAP request to Java method call and
invokes the service endpoint.
When a JSE is deployed, it is embedded in a JAX-RPC servlet provided by the vendor.
3. The service endpoint process the request and returns the response Java objects to the servlet.
4. Response is converted back to SOAP message by the servlet and sent to the client over HTTP.

JSE is composed of two parts:

• An endpoint interface extends the java.rmi.Remote
interface.
public interface HelloWorld extends java.rmi.Remote {
public String sayHello(String s)
throws java.rmi.RemoteException;

Oracle University and Egabi Solutions use only

}

• An implementation class that implements the endpoint

methods.
public class HelloWorld_Impl implements HelloWorld {
public String sayHello(String s){
...
}
}

JAX-RPC Service Endpoints

To create a JSE, you need to define an endpoint interface and an implementation class. The endpoint
interface is required to extend the java.rmi.Remote interface. It defines the Web service
operations that will be publicly accessible—in other words, the operations that Web service clients
can access using SOAP. In addition to the endpoint interface you must define the class that
implements the endpoint methods.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 12 - 8
EJB Endpoints

Like JSE, EJB endpoint is composed of two parts:

• An endpoint interface extends the java.rmi.Remote
interface.
public interface HelloWorld extends java.rmi.Remote {
public String sayHello(String s)
throws java.rmi.RemoteException;

Oracle University and Egabi Solutions use only

}

• A stateless session bean implements the interface.

public class HelloWorld_Impl implements javax.ejb.SessionBean,

HelloWorld {
...
}

EJB Endpoints
The J2EE Web service specification defines a new Web service endpoint interface for stateless
session beans that is on a par with the remote and local interfaces already used by enterprise beans.
Unlike the remote and local interfaces already familiar to EJB developers, though, the endpoint
interface does not extend an EJB object type—that is, an EJBObject or EJBLocalObject. Instead, the
endpoint interface extends the javax.ejb.Remote interface directly, which is the same as JSE
endpoint interface. In addition to the endpoint interface, you'll need to define the stateless session
bean that implements the interface.

• WebLogic supports programming JAX-RPC Web services

by annotating Java classes or EJBs. For example:
@WebService
public class HelloWorld_Impl {
public String sayHello(String s){
...
}

Oracle University and Egabi Solutions use only

}
• Various tools can be used generate the endpoint interface.
• Additionally, WebLogic Server extends JAX-RPC with
custom annotations, such as:
weblogic.jws.WLHttpTransport.

Creating a Web Service Using Annotations

WebLogic Server supports developing JAX-RPC Web services by annotating a standard Java class or
EJB with JSR-181 annotations. JDeveloper, Eclipse w/OEPE, and WebLogic Ant tasks work to
generate the required descriptors and artifacts based on the annotations included in a JWS file.
In addition to standard JSP181 annotations, WebLogic Server define a set of JWS annotations that
can be used to specify various other behavior and features. For a complete list of the WebLogic-
specific annotations, please see JWS Annotation Reference of Oracle® Fusion Middleware
WebLogic Web Services Reference for Oracle WebLogic Server 11g Release 1 (10.3.1).

Oracle University and Egabi Solutions use only

Creating a JAX-RPC Web Service Using JDeveloper

Like JAX-WS Web service, JDeveloper has a wizard to help developers to create JAX-RPC Web
services. You create a generic service implementation class, the wizard will add annotations and
generate a service interface for the implementation class based on your selections.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 12 - 11
Quiz

Which of the following statements are not true concerning JAX-

RPC?
1. JAX-RPC is supported by both J2EE 1.4 and JEE 5.
2. JAX-RPC defines annotations to annotate Java class or
EJB as a Web service.

Oracle University and Egabi Solutions use only

3. JAX-RPC client relies on generated stubs to invoke the
Web service.
4. JAX-RPC endpoint interfaces always extend the
java.rmi.Remote interface.

Answer: 2

There are three specific types of JAX-RPC client-slide

programming models:
• Generated Stubs Model: Traditional model, which includes
generating:
– Remote interface

Oracle University and Egabi Solutions use only

– Client-side stub
– Service interface
• Dynamic Proxy Model: Created dynamically at run time
rather than generating statically from a remote interface
• Dynamic Invocation Interface, or DII, Model: An API for
invoking Web services endpoints

JAX-RPC Client-Side Programming Models

There are three types of JAX-RPC client side programming models:
• Generated Stubs: This is the most common way people use to invoke web services. Like the
JAX-WS programming model, for a client to use JAX-RPC to access a Web service endpoint,
the endpoint must publish a WSDL document. The JAX-RPC compiler, generates Java remote
interfaces and stubs that implement the endpoint operations described by the WSDL document.
• Dynamic Proxies: A dynamic proxy is used in the same way as a generated stub, except the
remote interface's stub implementation is generated dynamically, at runtime.
• Dynamic Invocation Interface ( DII ): JAX-RPC provides an API for invoking operation on
web service endpoint. DII can be used to invoke any service without mentioning WSDL file.
Where as dynamic proxies makes use of portType and binding names in WSDL. Covered in
later slides.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 12 - 13
Invoking Web Services Using a Generated Stubs
Model
Endpoint
Web Service
Interfaces
WSDL to Java
and Stubs
Mapping Tool
Service (clientgen) WSDL
Interface and Class

Oracle University and Egabi Solutions use only

SOAP
Response
Create a service instance
SOAP
get*Port(…) Request
Invoke
a method
Stub instance

Invoking Web Services Using a Generated Stubs Model

The generated stubs make Web service endpoints appear as local Java objects. A generated stub is
created by a JAX-RPC compiler. JAX-RPC compilers include: WebLogic’s clientgen, an Ant
task for compiling JWS files; and JDeveloper and Eclipse/OEPE GUI tools, both providing built-in
JAX-RPC compilers.
In general, JAX-RPC compilers read a WSDL document and generate endpoint interfaces, stub
classes, and a service interfaces. Specifically:
• Endpoint interface: An interface defining service operations . The same interface is present at
both service and client side.
• The Generated Stub: A class implementing both javax.xml.rpc.Stub and the service
endpoint interfaces, responsible for translating method calls to SOAP messages.
• Service Interface and Implementation: A J2EE component can use an instance of the service
interface, called a service, to obtain a reference to a specific generated stub. The service
interface defines an accessor for every port declared by the service definition. The compiler
generates interface which extends javax.xml.rpc.Service, and has a method which
returns the service endpoint interface.

WSDL PortType is
mapped to an interface.

public interface HelloWorld extends java.rmi.Remote {

public String sayHello(String s)
throws java.rmi.RemoteException; The operation in WSDL
portType is mapped to a

Oracle University and Egabi Solutions use only

}
method in the interface.

Endpoint Interface Generated from WSDL

A JAX-RPC compiler will take the portType and operation definitions in the WSDL document and
generate the endpoint interface as shown above.

public class HelloWorld_Stub extends weblogic.wsee.jaxrpc.StubImpl

implements com.library.ws.HelloWorld, java.io.Serializable {

public HelloWorld_Stub(weblogic.wsee.wsdl.WsdlPort port,

weblogic.wsee.jaxrpc.ServiceImpl service)
throws javax.xml.rpc.ServiceException {
super(port, com.library.ws.HelloWorld.class, service);
}

Oracle University and Egabi Solutions use only

public java.lang.String sayHello(java.lang.String s) throws
java.rmi.RemoteException {
java.util.ArrayList _args = new java.util.ArrayList();
_args.add(s);

try {
...
}
}
}

Generated Stub Class

JAX-RPC compilers also generate the stub classes that implements an endpoint interface. An
instance of the generated stub class is responsible for translating method calls into SOAP
communications with the Web service endpoint.
In addition to implementing the endpoint interface, the stub class also extends
weblogic.wsee.jaxrpc.StubImpl class, defining methods for reading and setting properties
relating to network communication and authentication.

public interface HelloWorldService extends

javax.xml.rpc.Service {

com.library.ws.HelloWorldPortType getHelloWorldPort() throws

javax.xml.rpc.ServiceException;

... Returns
} HelloWorldPort

Oracle University and Egabi Solutions use only

port in this service

Generated Service Interface and Implementation

JAX-RPC compiler generates an interface which extends javax.xml.rpc.Service and its
implementation:
• The generated Service interface is used to access web service from any java component .
• Service interface name is derived from service definition in WSDL .
• The port accessor method name will be derived from port definition name in WSDL
• Generated service acts as factory for the stub class

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 12 - 17
Using the Stub Interface to Access Run-Time
Information
• The javax.xml.rpc.Stub interface enables you to
dynamically configure the Stub instance of your Web
Service client.
• The method of the Stub interface:
– _getProperty()
– _getPropertyNames()

Oracle University and Egabi Solutions use only

– _setProperty()
• The property values that you can access from the Stub
instance:
– ENDPOINT_ADDRESS_PROPERTY
– PASSWORD_PROPERTY
– SESSION_MAINTAIN_PROPERTY
– USERNAME_PROPERTY

Using the Stub Interface to Access Run-Time Information

The javax.xml.rpc.Stub interface enables you to dynamically configure the Stub instance of your
Web Service client. For more information, see
http://java.sun.com/javaee/5/docs/api/javax/xml/rpc/Stub.html. For
example, you can set the target service endpoint dynamically for the port Stub instance, as follows:
ComplexService service=new ComplexService_Impl (args[0]+"?WSDL" );
ComplexPortType port = service.getComplexServicePort();
((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY,
"http://localhost:8010/MyContext/MyService");
The methods of the Stub interface that you can use in your JWS file to access runtime information
about the Web Service are:
• _getProperty(): Returns the value of the specified configuration property.
• _getPropertyNames(): Returns an Iterator of the names of the properties that can be
configured on the Stub instance.
• _setProperty(): Sets the name and value of a configuration property for the Stub instance.

• WebLogic Server provides a set of stub properties that you

can set in the JAX-RPC Stub.
• Most of the stub property names are defined in the
weblogic.wsee.jaxrpc.WebLogic Servertub
interface.
• The syntax of the method setting a property is:

Oracle University and Egabi Solutions use only

Stub._setProperty(String,Object)
For example:
((Stub)port)._setProperty(WebLogic
Servertub.VALIDATE_WEBSERVICE_RESPONSE,"true");

WebLogic Web Services Stub Properties

WebLogic Server provides a set of stub properties that you can set in the JAX-RPC Stub used to
invoke a WebLogic Web Service. Most of the stub properties are defined in the WebLogic
Servertub class.
In the above example, VALIDATE_WEBSERVICE_RESPONSE property is set to force the Web
service client to validate response coming from a Web service.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 12 - 19
Quiz

Name the interfaces the generated Stub class needs to

implement:
1. javax.xml.rpc.Stub
2. javax.xml.rpc.Service
3. java.rmi.Remote

Oracle University and Egabi Solutions use only

4. The service endpoint interface

Answers: 1, 4

• WebLogic Web Services support:

– A set of built-in XML Schema, Java, and SOAP types
specified by the JAX-RPC specification
– User-defined XML and Java data types
• For a complete list of the supported data types, please see
Oracle® Fusion Middleware Getting Started with JAX-RPC

Oracle University and Egabi Solutions use only

Web Services for Oracle WebLogic Server 11g Release 1.

JAX-RPC Data Binding

WebLogic Web Services support a full set of built-in XML Schema, Java, and SOAP types, as
specified by the JAX-RPC specification, that you can use in your Web Service operations without
performing any additional programming steps. Built-in data types are those such as integer, string,
and time.
Additionally, you can use a variety of user-defined XML and Java data types, including Apache
XmlBeans (in package org.apache.xmlbeans), as input parameters and return values of your Web
Service. User-defined data types are those that you create from XML Schema or Java building
blocks, such as <xsd:complexType> or JavaBeans. The WebLogic Web Services Ant tasks, such
as jwsc and clientgen, automatically generate the data binding artifacts needed to convert the user-
defined data types between their XML and Java representations.

Oracle University and Egabi Solutions use only

<element name="author" type="xsd:string" />
</sequence>
</complexType>
</types>
Complex type
<message name="BookQuote_getBookPrice"> declaration
<part name="bookId" type="mh:Book"/>
</message>
<message name="BookQuote_getBookPriceResponse">
<part name="result" type="xsd:float"/>
</message>

Mapping XML Schema Complex Types

The above WSDL snippet declares a complex type Book. The complex type is mapped to service
input message.
The tool will generate Book class type, which will be the input to endpoint interface method
getBookPrice().

public interface BookQuote extends java.rmi.Remote {

public float getBookPrice(Book book)
throws java.rmi.RemoteException;
}
Generated service
endpoint

Oracle University and Egabi Solutions use only

operation has
Book type as input.

Mapping XML Schema Complex Types: Generated Endpoint Interface

The slide shows generated interface with method getBookPrice which has Book class type as input
parameter.

• Packaging and deployment of JAX-RPC Web services is

similar to JAX-WS:
– JSEs are packaged into a WAR file.
– EJB endpoint is packaged into an EJB JAR file.
• JAX-RPC Web services differ from JAX-WS by requiring
deployment descriptors, including:

Oracle University and Egabi Solutions use only

– WAR: web.xml, webservices.xml, weblogic-
webservice.xml
– EJB JAR: ejb-jar.xml, webservices.xml,
weblogic-webservice.xml

Packaging and Deploying JAX-RPC Services

JSEs are packaged into a WAR file, because the JSE is built on top of the servlet programming
model. The EJB endpoint is packaged into an EJB JAR file, because an EJB endpoint is an Enterprise
JavaBean that happens to process SOAP messages.
As for this, JAX-RPC is very similar to JAX-WS Web service. However, deployment descriptors,
optional for JAX-WS Web services, are required to deploy JAX-RPC Web services that are
developed using Web Services for Java EE technology.
At deployment time the J2EE application server's deployment tools can examine the endpoint
interface, along with other information provided by deployment descriptors, and use it to generate the
portType and message definitions of the WSDL document.

• JDeveloper
• Oracle Enterprise Pack for Eclipse
• Apache Ant: An open tool for automating the software build
process using XML-based build definitions
• WebLogic Ant: jwsc and wldeploy Ant tasks

Oracle University and Egabi Solutions use only

Packaging and Deployment Tools

JDeveloper, OEPE and WebLogic Ant include packaging utilities to create and package JSEs or EJB
endpoints. Each includes WebLogic specific deployment descriptors and features used during the
packaging and deployment. For portable WAR/EAR generation you may want to consider third-
party, open source tools, such as Apache Ant.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 12 - 25
Summary

In this lesson, you should have learned how to:

• Describe the differences of JAX-WS and JAX-RPC
• Implement JAX-RPC service endpoints
• Implement a JAX-RPC Web services client
• Describe data binding in JAX-RPC

Oracle University and Egabi Solutions use only

• Describe the requirement of packaging and deploying JAX-
RPC Web services

Summary
This slide summarizes what you have learned in this lesson.

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED
Oracle Fusion Middleware 11g: Build Web Services 12 - 26
Practice 12 Overview:
Creating JAX-RPC Web Services
This practice covers the following topics:
• Creating a JAX-RPC-based Web service from an existing
Java class

Oracle University and Egabi Solutions use only

THESE eKIT MATERIALS ARE FOR YOUR USE IN THIS CLASSROOM ONLY. COPYING eKIT MATERIALS FROM THIS
COMPUTER IS STRICTLY PROHIBITED

Manisha Reddy
No ratings yet
Manisha Reddy
7 pages
0321146182
No ratings yet
0321146182
845 pages
Program: / Downserver - Java / Import Java - Rmi.
No ratings yet
Program: / Downserver - Java / Import Java - Rmi.
83 pages
Client - Server Architecture
No ratings yet
Client - Server Architecture
3 pages
Web Service Foundations: WSDL and SOAP
No ratings yet
Web Service Foundations: WSDL and SOAP
98 pages
U6 - M1 - L3 - SOAP, REST Web Services and Technology Trends - Annotated - Tagged
No ratings yet
U6 - M1 - L3 - SOAP, REST Web Services and Technology Trends - Annotated - Tagged
25 pages
Web Services in Java
No ratings yet
Web Services in Java
762 pages
24 Corba
No ratings yet
24 Corba
15 pages
SA Practical CS-701
No ratings yet
SA Practical CS-701
23 pages
Web Services I 533
No ratings yet
Web Services I 533
98 pages
Web Services
No ratings yet
Web Services
35 pages
HCIA Exercises
No ratings yet
HCIA Exercises
7 pages
What Is A Pattern ? Definitions of A Pattern:: Unit 7: Design Patterns - 1 - 1
No ratings yet
What Is A Pattern ? Definitions of A Pattern:: Unit 7: Design Patterns - 1 - 1
18 pages
01 Introduction To Hive
No ratings yet
01 Introduction To Hive
17 pages
Introduction To Web Services
No ratings yet
Introduction To Web Services
70 pages
An Exhuastive Guide On MEAN Stack Development
No ratings yet
An Exhuastive Guide On MEAN Stack Development
5 pages
AWS Terminologies
No ratings yet
AWS Terminologies
41 pages
Divya Shree: Professional
No ratings yet
Divya Shree: Professional
10 pages
Assignment-Question CT027-3-3 - EPDA - 3F2111
No ratings yet
Assignment-Question CT027-3-3 - EPDA - 3F2111
4 pages
Web Services
No ratings yet
Web Services
63 pages
SOA Using Java Web Services
No ratings yet
SOA Using Java Web Services
63 pages
Web Services
100% (1)
Web Services
33 pages
Network Computing: Professor Louise E. Moser Spring 2008
No ratings yet
Network Computing: Professor Louise E. Moser Spring 2008
23 pages
Unit 5
No ratings yet
Unit 5
13 pages
Jax WS PDF
No ratings yet
Jax WS PDF
19 pages
Web Services With JAX-RPC and Apache Axis
No ratings yet
Web Services With JAX-RPC and Apache Axis
38 pages
Chapter 8 JAX-WS Web Services
No ratings yet
Chapter 8 JAX-WS Web Services
65 pages
Web Services Architectures
No ratings yet
Web Services Architectures
15 pages
Getting Started On Developing Web Services
No ratings yet
Getting Started On Developing Web Services
39 pages
Oracle: Developer Day
No ratings yet
Oracle: Developer Day
16 pages
MD Hassan Java
No ratings yet
MD Hassan Java
4 pages
Java Web Services Training Outline
No ratings yet
Java Web Services Training Outline
4 pages
Java Web Services
No ratings yet
Java Web Services
61 pages
Web Services
No ratings yet
Web Services
17 pages
Unit 4 - JAXB
No ratings yet
Unit 4 - JAXB
29 pages
WebServices & SOA
No ratings yet
WebServices & SOA
54 pages
CV Vũ Hoài Nam - Java
No ratings yet
CV Vũ Hoài Nam - Java
2 pages
Web ServicesWeb Services and Service Oriented Architecture
No ratings yet
Web ServicesWeb Services and Service Oriented Architecture
54 pages
Websvcs
No ratings yet
Websvcs
97 pages
Web Services Development in Websphere V5: by Tapas Banerjee Ceo, Web Age Solutions Inc
No ratings yet
Web Services Development in Websphere V5: by Tapas Banerjee Ceo, Web Age Solutions Inc
34 pages
Ds Equinix Ibx and Xscale Data Centers Map en
No ratings yet
Ds Equinix Ibx and Xscale Data Centers Map en
4 pages
Web Services: Marlon Pierce Indiana University
No ratings yet
Web Services: Marlon Pierce Indiana University
23 pages
Web Services Documentation
100% (1)
Web Services Documentation
18 pages
Web Services Notes PDF
No ratings yet
Web Services Notes PDF
28 pages
Jordan Baker Resume 2023.11.05.pages
No ratings yet
Jordan Baker Resume 2023.11.05.pages
3 pages
Krafton Pubg - Loli
No ratings yet
Krafton Pubg - Loli
8 pages
Fernando de Figueiredo Mendes
No ratings yet
Fernando de Figueiredo Mendes
3 pages
Web Services and J2EE: Dan Harkey
No ratings yet
Web Services and J2EE: Dan Harkey
21 pages
T3TWS1.Introduction To SOA-R15
No ratings yet
T3TWS1.Introduction To SOA-R15
34 pages
Developing Java Web Services
No ratings yet
Developing Java Web Services
5 pages
Jax WS
No ratings yet
Jax WS
13 pages
Day 1 of AWS Journey
No ratings yet
Day 1 of AWS Journey
3 pages
JAX Ws
No ratings yet
JAX Ws
8 pages
Web Service Workshop
No ratings yet
Web Service Workshop
16 pages
Web Services Web Services
No ratings yet
Web Services Web Services
5 pages
1Z0 329
No ratings yet
1Z0 329
4 pages
Midas - All Placement Coures List
No ratings yet
Midas - All Placement Coures List
4 pages
Web Services Quick Guide
No ratings yet
Web Services Quick Guide
11 pages
Soap 2022
No ratings yet
Soap 2022
93 pages
1z0 329 Demo20160624122012 160624112233
No ratings yet
1z0 329 Demo20160624122012 160624112233
5 pages
Java WebServices Tutorial From JavaTpoint
No ratings yet
Java WebServices Tutorial From JavaTpoint
26 pages
Software Development Project Schedule
No ratings yet
Software Development Project Schedule
17 pages
Step 9 - Web - Services
No ratings yet
Step 9 - Web - Services
13 pages
Documentation Web Services
No ratings yet
Documentation Web Services
7 pages
Web Services
No ratings yet
Web Services
77 pages
Web Services.: What Is A Web Service?
No ratings yet
Web Services.: What Is A Web Service?
10 pages
Web Service Lectures
No ratings yet
Web Service Lectures
62 pages
Web Services Syllabus
No ratings yet
Web Services Syllabus
3 pages
Lec 14 - Web Services
No ratings yet
Lec 14 - Web Services
31 pages
Oracle Application Training
No ratings yet
Oracle Application Training
4 pages
Web Service
No ratings yet
Web Service
6 pages
A Web Services Details
No ratings yet
A Web Services Details
11 pages
Oracle Webservices FAQ
No ratings yet
Oracle Webservices FAQ
7 pages
Devops Shack k8 Cheat Sheet
No ratings yet
Devops Shack k8 Cheat Sheet
5 pages
Bigdata
No ratings yet
Bigdata
3 pages
Implementation of Webservices Ex - No:: D Aim
No ratings yet
Implementation of Webservices Ex - No:: D Aim
14 pages
Nischay HM Resume
No ratings yet
Nischay HM Resume
2 pages
BCS601 Model Set 1 Paper
No ratings yet
BCS601 Model Set 1 Paper
2 pages
DevOps Interview Questions
No ratings yet
DevOps Interview Questions
3 pages
OUM
No ratings yet
OUM
5 pages
Defining Key Flexfields: Every Time
No ratings yet
Defining Key Flexfields: Every Time
2 pages
Localization Saudi Arabia 3
No ratings yet
Localization Saudi Arabia 3
58 pages
Olmimplementationguidelines 150420061431 Conversion Gate02
No ratings yet
Olmimplementationguidelines 150420061431 Conversion Gate02
43 pages
Oracle R12 Ewemade
No ratings yet
Oracle R12 Ewemade
8 pages
1Z0 434 Demo
No ratings yet
1Z0 434 Demo
5 pages
CourseREG D47425GC10
No ratings yet
CourseREG D47425GC10
4 pages
Web Services
No ratings yet
Web Services
67 pages
JD Oracle HCM Func - Qatar
No ratings yet
JD Oracle HCM Func - Qatar
2 pages
1Z0-1050-21.pdf LAST ONE
No ratings yet
1Z0-1050-21.pdf LAST ONE
32 pages
EUI 2016 Financial - Report 2
No ratings yet
EUI 2016 Financial - Report 2
1 page
Ch-1 - Web Services Overview
No ratings yet
Ch-1 - Web Services Overview
23 pages
OTBI - Part 1
No ratings yet
OTBI - Part 1
17 pages
To Whom It May Concern: Inajob Thousand Emirates Dirham
No ratings yet
To Whom It May Concern: Inajob Thousand Emirates Dirham
2 pages
1 - Appendix (1) - Combine
No ratings yet
1 - Appendix (1) - Combine
27 pages
HCM Reports R13
No ratings yet
HCM Reports R13
194 pages
SOAP - XML Web Services Using Java
No ratings yet
SOAP - XML Web Services Using Java
19 pages
Web Service
No ratings yet
Web Service
35 pages
2-ORC Admin TS V1
No ratings yet
2-ORC Admin TS V1
15 pages
Chapter One Introduction
No ratings yet
Chapter One Introduction
5 pages
1Z0-1046-21.pdf LAST ONE
No ratings yet
1Z0-1046-21.pdf LAST ONE
53 pages
Rawabi MC 060 - V8 - Draft
No ratings yet
Rawabi MC 060 - V8 - Draft
64 pages
SOA 11g Foundation - A - B - Lifecycle of A Composite
No ratings yet
SOA 11g Foundation - A - B - Lifecycle of A Composite
18 pages
SOA 11g Foundation - 01.0 - Agenda Template-1
No ratings yet
SOA 11g Foundation - 01.0 - Agenda Template-1
11 pages
1309010996375out 1
No ratings yet
1309010996375out 1
5 pages
Teamcenter SOA - Introduction
No ratings yet
Teamcenter SOA - Introduction
3 pages
XML Commands
No ratings yet
XML Commands
3 pages
AMS Functional Specs Document V1.2
No ratings yet
AMS Functional Specs Document V1.2
38 pages
DOF Integration
No ratings yet
DOF Integration
1 page