Chapter

Chapter 1.
XML Web Service Standards
Given XML documents, schemas, and fragments determine whether their syntax and form are correct
(according to W3C schema) and whether they conform to the WS-I Basic Profile 1.1.
Basic Profile. SOAP Envelopes
An ENVELOPE MUST conform to the structure specified in SOAP 1.1 Section 4, "SOAP Envelope"
An ENVELOPE MUST have exactly zero or one child elements of the soap:Body element.
A RECEIVER MUST generate a fault if they encounter an envelope whose document element is not soap:Envelope.
The children of the soap:Body element in an ENVELOPE MUST be namespace qualified.
An ENVELOPE MUST NOT contain a Document Type Declaration.
An ENVELOPE MUST NOT contain Processing Instructions.
An ENVELOPE SHOULD NOT contain the namespace

declaration xmlns:xml="http://www.w3.org/XML/1998/namespace".
A DESCRIPTION SHOULD NOT contain the namespace

declaration xmlns:xml="http://www.w3.org/XML/1998/namespace".
An ENVELOPE MUST NOT have any element children of soap:Envelope following the soap:Body element.
CORRECT example:
<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >

<soap:Body>
<p:Process xmlns:p='http://example.org/Operations' >
<m:Data xmlns:m='http://example.org/information' >
Here is some data with the message
</m:Data>
</p:Process>
</soap:Body>
</soap:Envelope>
INCORRECT example:
<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >

<soap:Body>
<p:Process xmlns:p='http://example.org/Operations' />
</soap:Body>
<m:Data xmlns:m='http://example.org/information' >
Here is some data with the message
</m:Data>
</soap:Envelope>
soap:encodingStyle attributes on any of the elements whose namespace name

An ENVELOPE MUST NOT contain
is "http://schemas.xmlsoap.org/soap/envelope/".
An ENVELOPE MUST NOT contain soap:encodingStyle attributes on any element that is a child of soap:Body.
An ENVELOPE described in an rpc-literal binding MUST NOT contain soap:encodingStyle attribute on any element that is a
grandchild of soap:Body.
An ENVELOPE containing a soap:mustUnderstand attribute MUST only use the lexical forms "0" and "1".
A RECEIVER MUST NOT mandate the use of the xsi:type attribute in envelopes except as required in order to indicate a derived type
(see XML Schema Part 1: Structures, Section 2.6.1).
The soap:Envelope, soap:Header, and soap:Body elements in an ENVELOPE MUST NOT have attributes in the
namespace"http://schemas.xmlsoap.org/soap/envelope/".
Basic Profile. SOAP Processing Model
A RECEIVER MUST handle envelopes in such a way that it appears that all checking of mandatory header blocks is performed before any
actual processing.
"soap:MustUnderstand" fault when an envelope contains a mandatory header block (i.e., one
A RECEIVER MUST generate a
that has a soap:mustUnderstandattribute with the value "1") targeted at the receiver (via soap:actor) that the
receiver does not understand.
When a fault is generated by a RECEIVER, further processing SHOULD NOT be performed on the SOAP envelope aside from that which is
necessary to rollback, or compensate for, any effects of processing the envelope prior to the generation of the fault.
Where the normal outcome of processing a SOAP envelope would have resulted in the transmission of a SOAP response, but rather a fault is
generated instead, a RECEIVER MUST transmit a fault in place of the response.
A RECEIVER that generates a fault SHOULD notify the end user that a fault has been generated when practical, by whatever means is deemed
appropriate to the circumstance.
Basic Profile. SOAP Faults
A RECEIVER MUST interpret a SOAP message as a Fault when the soap:Body of the message has a single soap:Fault child.
soap:Fault element MUST NOT have element children other

When an ENVELOPE is a Fault, the
than faultcode, faultstring, faultactor and detail.
CORRECT example:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >

<faultcode>soap:Client</faultcode>
<faultstring>Invalid message format</faultstring>
<faultactor>http://example.org/someactor</faultactor>
<detail>
<m:msg xmlns:m='http://example.org/faults/exceptions'>
There were <b>lots</b> of elements in
the message that I did not understand
</m:msg>
<m:Exception xmlns:m='http://example.org/faults/exceptions'>
<m:ExceptionType>Severe</m:ExceptionType>
</m:Exception>
</detail>
</soap:Fault>
INCORRECT example:

<detail>
There were <b>lots</b> of elements in the message
that I did not understand
</detail>
<m:Exception xmlns:m='http://example.org/faults/exceptions' >
<m:ExceptionType>Severe</m:ExceptionType>
</m:Exception>
</soap:Fault>
When an ENVELOPE is a Fault, the element children of the soap:Fault element MUST be unqualified.
CORRECT example:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns='' >

<detail>
There were <b>lots</b> of elements in the message that
I did not understand
</m:msg>
</detail>
</soap:Fault>
INCORRECT example (children of the soap:Fault elements have namespace qualification):

<soap:faultcode>soap:Client</soap:faultcode>
<soap:faultstring>Invalid message format</soap:faultstring>
<soap:faultactor>http://example.org/someactor</soap:faultactor>
<soap:detail>
There were <b>lots</b> of elements in the message that
I did not understand
</m:msg>
</soap:detail>
</soap:Fault>
A RECEIVER MUST accept faults that have any number of elements, including zero, appearing as children of the detail element. Such
children can be qualified OR unqualified.
A RECEIVER MUST accept faults that have any number of qualified OR unqualified attributes, including zero, appearing on the detail
element. The namespace of qualified attributes can be anything other than "http://schemas.xmlsoap.org/soap/envelope/".
A RECEIVER MUST accept faults that carry an xml:lang attribute on the faultstring element.
When an ENVELOPE contains a faultcode element, the content of that element SHOULD be either one of the fault codes defined in
detail element), or a Qname whose namespace is controlled by the
SOAP 1.1 (supplying additional information if necessary in the
fault's specifying authority (in that order of preference).
NOTE: The set of faultcode values defined in SOAP 1.1 document

is: VersionMismatch, MustUnderstand, Client, Server.
When an ENVELOPE contains a faultcode element the content of that element SHOULD NOT use of the SOAP 1.1 "dot" notation to
refine the meaning of the fault.
CORRECT example:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
xmlns:c='http://example.org/faultcodes' >
<faultcode>c:ProcessingError</faultcode>
<faultstring>An error occured while processing the message</faultstring>
</soap:Fault>
CORRECT example:

<faultcode>soap:Server</faultcode>
<faultstring>An error occured while processing the message</faultstring>
</soap:Fault>
INCORRECT example:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
xmlns:c='http://example.org/faultcodes' >
<faultcode>soap:Server.ProcessingError</faultcode>
<faultstring>An error occurred while processing the message</faultstring>
</soap:Fault>
Basic Profile. Use of SOAP in HTTP
A MESSAGE MUST be sent using either HTTP/1.1 or HTTP/1.0.
A MESSAGE SHOULD be sent using HTTP/1.1.
A HTTP request MESSAGE MUST use the HTTP POST method.
A MESSAGE MUST NOT use the HTTP Extension Framework (RFC2774).
The value of the SOAPAction HTTP header field in a HTTP request MESSAGE MUST be a quoted string.
A RECEIVER MAY respond with a fault if the value of the SOAPAction HTTP header field in a message is not quoted.
A RECEIVER MUST NOT rely on the value of the SOAPAction HTTP header to correctly process the message.
CORRECT example #1:
A WSDL Description that has:
<soapbind:operation soapAction="foo" />
results in a message with a SOAPAction HTTP header field of:

SOAPAction: "foo"
CORRECT example #2:
A WSDL Description that has:
<soapbind:operation />
or
<soapbind:operation soapAction="" />
results in a message with a corresponding SOAPAction HTTP header field as follows:

SOAPAction: ""
An INSTANCE MUST use a 2xx HTTP status code on a response message that indicates the successful outcome of a HTTP request.
An INSTANCE SHOULD use a "200 OK" HTTP status code on a response message that contains an envelope that is not a fault.
Basic Profile. Service Description. Document Structure
A DESCRIPTION MUST only use the WSDL "import" statement to import another WSDL description.
In a DESCRIPTION, the namespace attribute of the wsdl:import MUST NOT be a relative URI.
To import XML Schema Definitions, a DESCRIPTION MUST use the XML Schema "import" statement.
A DESCRIPTION MUST use the XML Schema "import" statement only within the xsd:schema element of the types section.
In a DESCRIPTION the schemaLocation attribute of an xsd:import element MUST NOT resolve to any document whose
root element is not "schema" from the namespace "http://www.w3.org/2001/XMLSchema".
CORRECT description example:
<definitions name="StockQuote"
targetNamespace="http://example.com/stockquote/definitions"
...
xmlns="http://schemas.xmlsoap.org/wsdl/">
<import namespace="http://example.com/stockquote/definitions"
location="http://example.com/stockquote/stockquote.wsdl"/>
<message name="GetLastTradePriceInput">
<part name="body" element="..."/>
</message>
...
</definitions>
CORRECT description example:
targetNamespace="http://example.com/stockquote/"
xmlns:xsd1="http://example.com/stockquote/schemas"
...
<part name="body" element="xsd1:TradePriceRequest"/>
</message>
...
</definitions>
INCORRECT description example (imports not "wsdl" document):
targetNamespace="http://example.com/stockquote/definitions"
xmlns:xsd1="http://example.com/stockquote/schemas"
...
<import namespace="http://example.com/stockquote/schemas"
location="http://example.com/stockquote/stockquote.xsd"/>
</message>
...
</definitions>
A DESCRIPTION MUST specify a non-empty location attribute on the wsdl:import element.
wsdl:import elements MUST precede all other elements from the WSDL namespace
When they appear in a DESCRIPTION,
except wsdl:documentation.
wsdl:types elements MUST precede all other elements from the WSDL namespace
When they appear in a DESCRIPTION,
except wsdl:documentation andwsdl:import.
CORRECT example:
<definitions name="StockQuote" targetNamespace="http://example.com/stockquote/definitions">
<import namespace="http://example.com/stockquote/base"
<part name="body" element="..."/>
</message>
...
</definitions>
CORRECT example:
...
<types>
<schema targetNamespace="http://example.com/stockquote/schemas"
xmlns="http://www.w3.org/2001/XMLSchema">
.......
</schema>
</types>
<part name="body" element="tns:TradePriceRequest"/>
</message>
...
<service name="StockQuoteService">
<port name="StockQuotePort" binding="tns:StockQuoteSoap">
....
</port>
</service>
</definitions>
INCORRECT example ( wsdl:types elements MUST precede all other elements):
...
<part name="body" type="tns:TradePriceRequest"/>
</message>
...
<port name="StockQuotePort" binding="tns:StockQuoteSoap">
....
</port>
</service>
<types>
<schema targetNamespace="http://example.com/stockquote/schemas"
.......
</schema>
</types>
</definitions>
Basic Profile. Service Description. Types
A DESCRIPTION MUST NOT use QName references to WSDL components in namespaces that have been neither imported, nor defined in the
referring WSDL document.
A QName reference to a Schema component in a DESCRIPTION MUST use the namespace defined in
the targetNamespace attribute on the xsd:schemaelement, or to a namespace defined in the namespace attribute
on an xsd:import element within the xsd:schema element.
In a DESCRIPTION, declarations MUST NOT extend or restrict the soapenc:Array type.
In a DESCRIPTION, declarations MUST NOT use wsdl:arrayType attribute in the type declaration.
In a DESCRIPTION, elements SHOULD NOT be named using the convention ArrayOfXXX.
An ENVELOPE MUST NOT include the soapenc:arrayType attribute.
CORRECT example:
Given the WSDL Description:
<xsd:element name="MyArray1" type="tns:MyArray1Type"/>

<xsd:complexType name="MyArray1Type">
<xsd:sequence>
<xsd:element name="x" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
The envelope would serialize as (omitting namespace declarations for clarity):
<MyArray1>
<x>abcd</x>
<x>efgh</x>
</MyArray1>
INCORRECT example:

<xsd:complexType name="MyArray2Type"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" >
<xsd:complexContent>
<xsd:restriction base="soapenc:Array">
<xsd:sequence>
<xsd:element name="x" type="xsd:string"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute ref="soapenc:arrayType"
wsdl:arrayType="tns:MyArray2Type[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<MyArray2 soapenc:arrayType="tns:MyArray2Type[]" >

<x>abcd</x>
<x>efgh</x>
</MyArray2>
Describe the use of XML schema in Java EE Web services.
• [SCHEMA_PART_0] XML Schema Part 0: Primer Second Edition
• [SOAP_1.2_PART_2] SOAP Version 1.2 Part 2: Adjuncts
The W3C XML Schema Definition Language is a way of describing and constraining the content of XML documents.
The XML Schema specification consists of three parts. One part defines a set of simple datatypes, which can be associated with XML element
types and attributes; this allows XML software to do a better job of managing dates, numbers, and other special forms of information. The
second part of the specification proposes methods for describing the structure and constraining the contents of XML documents, and defines
the rules governing schema validation of documents. The third part is a primer that explains what schemas are, how they differ from DTDs,
and how one builds a schema.
XML Schema introduces new levels of flexibility that may accelerate the adoption of XML for significant industrial use. For example, a schema
author can build a schema that borrows from a previous schema, but overrides it where new unique features are needed. XML Schema allows
the author to determine which parts of a document may be validated, or identify parts of a document where a schema may apply. XML
Schema also provides a way for users of e-commerce systems to choose which XML Schema they use to validate elements in a given
namespace, thus providing better assurance in e-commerce transactions and greater security against unauthorized changes to validation
rules. Further, as XML Schema are XML documents themselves, they may be managed by XML authoring tools, or through XSLT.
Let's start from "Hello World!" example:
<?xml version="1.0" encoding="UTF-8" ?>
<greeting>
Hello World!
</greeting>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="greeting" type="xsd:string"/>
</xsd:schema>
Here is a simple data structure for a purchase order. The order example contains following elements: company name, product identifier, and
price.
<order_request>
<company_name>IBA JV</company_name>
<product_id>C-0YST</product_id>
<product_price>500.00</product_price>
</order_request>
This example represents pricing data as a floating-point number and company name and product identifier as strings. Agreement among
different programs about how to handle data is essential. XML solves data typing issues through the use of XML Schemas. The following
example shows how each element in the order request can be designated a specific data type:
<xsd:schema xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
<xsd:element name="order_request">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="company_name" type="xsd:string"/>
<xsd:element name="product_id" type="xsd:string"/>
<xsd:element name="product_price" type="xsd:double"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Another example of XML document for more complex purchase order:
<purchase_order order_date="2004-04-07">
<shipping_address country="US">
<name>Mikalai Zaikin</name>
<street>28th Street</street>
<city>Boulder</city>
<state>CO</state>
<zip>80301</zip>
</shipping_address>
<items>
<item part_number="008291">
<product_name>PRESARIO S5140</product_name>
<quantity>1</quantity>
<price>898.00</price>
</item>
<item part_number="005376">
<product_name>COMPAQ FP7317</product_name>
<quantity>1</quantity>
<price>398.00</price>
</item>
</items>
</purchase_order>
The XML Schema (one of many possible) for this document will be:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:element name="item">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="product_name" type="xsd:string" />
<xsd:element name="quantity">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxExclusive value="100"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="price" type="xsd:decimal" />
</xsd:sequence>
<xsd:attribute name="part_number" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="items">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1" ref="item" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="purchase_order">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="shipping_address" type="us_address" />
<xsd:element ref="items" />
</xsd:sequence>
<xsd:attribute name="order_date" type="xsd:date" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:complexType name="us_address">
<xsd:sequence>
<xsd:element name="name" type="xsd:string" />
<xsd:element name="street" type="xsd:string" />
<xsd:element name="city" type="xsd:string" />
<xsd:element name="state" type="xsd:string" />
<xsd:element name="zip" type="xsd:string" />
</xsd:sequence>
<xsd:attribute name="country" type="xsd:NMTOKEN" fixed="US" />
</xsd:complexType>
</xsd:schema>
NOTE: In SOAP 1.2 multireference values may be encoded in-place rather than as "top-level" elements (as in SOAP 1.1):
SOAP 1.1
<e:Books>
<e:Book>
<title>SCDJWS 1.4 Study Guide</title>
<author href="#mz" />
</e:Book>
<e:Book>
<title>SCWCD 1.4 Study Guide</title>
<author href="#mz" />
</e:Book>
</e:Books>
<author id="henryford">
</author>
SOAP 1.2
<e:Books>
<e:Book>
<author id="mz" >
</author>
</e:Book>
<e:Book>
<title>SCWCD 5.0 Study Guide</title>
<author ref="mz" />
</e:Book>
</e:Books>
The following code:
public class PersonName {

public String firstName;
public String lastName;
}
public class Person {

public PersonName name;
public float age;
public short height;
public static boolean compare(Person person1, Person person2);

}
The SOAP 1.2 message for Person.compare(...) call may look like this:
<soap:Envelope xmlns:soap='http://www.w3.org/2002/12/soap-envelope'
soap:encodingStyle='http://www.w3.org/2002/12/soap-encoding'>
<soap:Body xmlns:ns1='http://example'>
<ns1:compare>
<person id="mz">
<name>
<fistName>Mikalai</firstName>
<lastName>Zaikin</lastName>
</name>
<age>29</age>
<height>1.78</height>
<person>
<person ref="mz" />
</ns1:compare>
</soap:Body>
</soap:Envelope>
Default value of minOccurs is 1.
Default value of maxOccurs is 1.
XML Schema defines four main elements:
1. xsd:element declares an element and assigns it a type.

2. xsd:attribute declares an attribute and assigns it a type.
3. xsd:complexType defines a new complex type.
4. xsd:simpleType defines a new simple type.
Attribute values are always simple types. Attributes are unordered.
It does not matter whether complex type is defined before or after the element declaration as long as it is present in the schema document.
You can derive new simple types from existing types. An xsd:simpleType element defines the subtype. The name attribute
ofxsd:simpleType assigns a name to the new type, by which it can be referred to in xsd:element type attributes.
An xsd:restriction child element derives by restricting the legal values of the base type. An xsd:list child element
derives a type as a white space separated list of base type instances. An xsd:union child element derives by combining legal values
from multiple base types.
You can derive new simple types types from existing types by restricting the type to a subset of its normal values.
An xsd:simpleType element defines the restricted type. The name attribute of xsd:simpleType assigns a name to
xsd:restriction child element specifies what type is being restricted via its base attribute. Facet children
the new type. An
of xsd:restriction specify the constraints on the type. For example, this xsd:simpleType element defines
amyYear as any year from 1974 on:
<xsd:simpleType name="myYear">
<xsd:restriction base="xsd:gYear">
<xsd:minInclusive value="1974"/>
</xsd:restriction>
</xsd:simpleType>
Then you declare the year element like this:

<xsd:element name="year" type="myYear" />
Facets
include: length, minLength, maxLength, pattern, enumeration, whiteSpace, maxInclusiv
e, maxExclusive, minInclusive, minExclusive, totalDigits,fractionDigits. Not all
facets apply to all types.
For example, new string type must contain between 1 and 255 characters:
<?xml version="1.0"?>
<xsd:simpleType name="Str255">
<xsd:restriction base="xsd:string">
<xsd:minLength value="1"/>
<xsd:maxLength value="255"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
For example, the new year type must be between 1974 and 2100:
<xsd:simpleType name="myYear">
<xsd:restriction base="xsd:gYear">
<xsd:minInclusive value="1974"/>
<xsd:maxInclusive value="2100"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
The enumeration facet lists all allowed values. Applies to all simple types except boolean. For example, the computer brand
name must be one of the following : IBA JV, IBM, COMPAQ, DELL, HP.
<xsd:simpleType name="computerBrandName">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="IBA JV"/>
<xsd:enumeration value="IBM"/>
<xsd:enumeration value="COMPAQ"/>
<xsd:enumeration value="DELL"/>
<xsd:enumeration value="HP"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
Each element in the xsd:all group must occur zero or once; that is minOccurs and maxOccurs must each be 0 or 1.
The xsd:all xsd:all group may contain only individual element declarations;
group must be the top level element of its type. The
no choices or sequences. Example:
<xsd:complexType name="personName">
<xsd:all>
<xsd:element name="firstName" type="xsd:string"/>
<xsd:element name="lastName" type="xsd:string"/>
</xsd:all>
</xsd:complexType>
</xsd:schema>
xsd:choice requires exactly one of a group of specified elements to appear. The choice can
minOccurs and maxOccurs attributes that adjust this from zero to any given number. Example:
have
<xsd:complexType name="computer">
<xsd:sequence>
<xsd:element name="name" type="xsd:string"/>
<xsd:choice minOccurs="1" maxOccurs="1">
<xsd:element name="desktop" type="xsd:string"/>
<xsd:element name="notebook" type="xsd:string"/>
<xsd:element name="handheld" type="xsd:string"/>
</xsd:choice>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
hapter 2. SOAP 1.2 Web Service Standards
List and describe the encoding types used in a SOAP message.
• [SOAP_1.2_PART_2] SOAP Version 1.2 Part 2: Adjuncts
The SOAP encoding style is based on a simple type system that is a generalization of the common features found in type systems in
programming languages, databases and semi-structured data. A type either is a simple (scalar) type or is a compound type constructed as a
composite of several parts, each with a type. This is described in more detail below. This section defines rules for serialization of a graph of
typed objects. It operates on two levels. First, given a schema in any notation consistent with the type system described, a schema for an
XML grammar may be constructed. Second, given a type-system schema and a particular graph of values conforming to that schema, an XML
instance may be constructed. In reverse, given an XML instance produced in accordance with these rules, and given also the original schema,
a copy of the original value graph may be constructed.
There are following SOAP encoding types:
• Simple Types:
o Strings
o Enumerations
o Array of Bytes
• Compound Types:
o Arrays
o Structures
Simple Types
For simple types, SOAP adopts all the types found in the section "Built-in datatypes" of the "XML Schema Part 2: Datatypes" Specification,
both the value and lexical spaces. Examples
boolean (true, false, 0 or 1), byte, short, int, long, float, double, string (java.l
include:
ang.String), decimal(java.math.BigDecimal), date (java.util.GregorianCalendar
), dateTime (java.util.Date), SOAP-ENC:base64 (byte []).
The following examples are a SOAP representation of these primitive data types:
<element name="age" type="int"/>

<element name="height" type="float"/>
<element name="displacement" type="negativeInteger"/>
<element name="color">
<simpleType base="xsd:string">
<enumeration value="Green"/>
<enumeration value="Blue"/>
</simpleType>
</element>
<age>45</age>
<height>5.9</height>
<displacement>-450</displacement>
<color>Blue</color>
Strings
The datatype " string" is defined in "XML Schema Part 2: Datatypes" Specification. Note that this is not identical to the type called
"string" in many database or programming languages, and in particular may forbid some characters those languages would permit.
(Those values must be represented by using some datatype other than xsd:string.) A string MAY be encoded as a single-reference
or a multi-reference value. The containing element of the string value MAY have an "id" attribute. Additional accessor elements MAY then
have matching "href" attributes. For example, two accessors to the same string could appear, as follows:
<greeting id="String-0">Hello</greeting>
<salutation href="#String-0"/>
However, if the fact that both accessors reference the same instance of the string (or subtype of string) is immaterial, they may be encoded
as two single-reference values as follows:
<greeting>Hello</greeting>
<salutation>Hello</salutation>
Schema fragments for these examples could appear similar to the following:
<element name="greeting" type="SOAP-ENC:string"/>

<element name="salutation" type="SOAP-ENC:string"/>
SOAP-ENC:string is used as the element's type as a convenient way to declare an element whose
(In this example, the type
datatype is "xsd:string id href
" and which also allows an " " and " " attribute. See the SOAP Encoding schema for the exact
definition. Schemas MAY use these declarations from the SOAP Encoding schema but are not required to.)
Enumerations
Enumeration as a concept indicates a set of distinct names. A specific enumeration is a specific list of distinct values appropriate to the base
type. For example the set of color names ("Green", "Blue", "Brown") could be defined as an enumeration based on
thestring built-in type. The values ("1", "3", "5") are a possible enumeration based on integer, and so on. "XML Schema Part 2:
Datatypes" supports enumerations for all of the simple types except forboolean. The language of "XML Schema Part 1: Structures"
Specification can be used to define enumeration types. If a schema is generated from another notation in which no specific base type is
string". In the following schema example "EyeColor" is defined as a string with the possible values of
applicable, use "
" Green", "Blue", or "Brown" enumerated, and instance data is shown accordingly:
<element name="EyeColor" type="tns:EyeColor"/>
<simpleType name="EyeColor" base="xsd:string">

<enumeration value="Green"/>
<enumeration value="Blue"/>
<enumeration value="Brown"/>
</simpleType>
<Person>
<Name>Mikalai Zaikin</Name>
<Age>34</Age>
<EyeColor>Brown</EyeColor>
</Person>
Array of Bytes
An array of bytes MAY be encoded as a single-reference or a multi-reference value. The rules for an array of bytes are similar to those for a
string. In particular, the containing element of the array of bytes value MAY have an " id" attribute. Additional accessor elements MAY then
have matching " href " attributes. The recommended representation of an opaque array of bytes is the ' base64 ' encoding defined in
XML Schemas, which uses the base64 encoding algorithm. However, the line length restrictions that normally apply to base64 data in MIME
do not apply in SOAP. A "SOAP-ENC:base64" subtype is supplied for use with SOAP:
<picture xsi:type="SOAP-ENC:base64">
aG93IG5vDyBicm73biBjb3cNCg==
</picture>
Polymorphic Accessor
Many languages allow accessors that can polymorphically access values of several types, each type being available at run time. A polymorphic
xsi:type" attribute that describes the type of the actual value. For example, a polymorphic
accessor instance MUST contain an "
accessor named " cost" with a value of type "xsd:float" would be encoded as follows:
<cost xsi:type="xsd:float">29.95</cost>
as contrasted with a cost accessor whose value's type is invariant, as follows:
<cost>29.95</cost>
Compound types
A "struct" is a compound value in which accessor name is the only distinction among member values, and no accessor has the same name as
any other.
An "array" is a compound value in which ordinal position serves as the only distinction among member values.
Structures
The members of a Compound Value are encoded as accessor elements. When accessors are distinguished by their name (as for example in a
struct), the accessor name is used as the element name. Accessors whose names are local to their containing types have unqualified element
names; all others have qualified names. The following is an example of a struct of type " book":
<book>
<author>Mikalai Zaikin</author>
<intro>This is a certification guide</intro>
</book>
And this is a schema fragment describing the above structure:
<xsd:element name="book">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="author" type="xsd:string" />
<xsd:element name="title" type="xsd:string" />
<xsd:element name="intro" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
Arrays (SOAP 1.2)
Array encodings have been revised and simplified in the latest SOAP 1.2 specification.
ArrayType elements are derived from a generic nodeType element.
Now arrays have two attributes:
• itemType is the the type of the array (String, int, XML complex type).
• arraySize - The array's dimensions are represented by each item in the list of sizes (unspecified size in case of the
asterisk). The number of items in the list represents the number of dimensions in the array. The asterisk, if present, MUST only
appear in the first position in the list.
The default value of the arraySize attribute information item is "*", that is by default arrays are considered to have a
single dimension of unspecified size.
<xs:attribute name="arraySize" type="tns:arraySize" />
<xs:attribute name="itemType" type="xs:QName" />
<xs:attributeGroup name="arrayAttributes">
<xs:attribute ref="tns:arraySize" />
<xs:attribute ref="tns:itemType" />
</xs:attributeGroup>
SOAP 1.1 array:
<numbers enc:arrayType="xs:int[2]">
<number>3</number>
<number>4</number>
</numbers>
SOAP 1.2 array:
<numbers enc:itemType="xs:int" enc:arraySize="2">

<number>3</number>
<number>4</number>
</numbers>
Arrays (SOAP 1.1)
In SOAP 1.1 arrays are defined as having a type of " SOAP-ENC:Array " or a type derived there from. Arrays are represented as
element values, with no specific constraint on the name of the containing element (just as values generally do not constrain the name of their
containing element). Arrays can contain elements which themselves can be of any type, including nested arrays. New types formed by
SOAP-ENC:Array
restrictions of can also be created to represent, for example, arrays limited to integers or arrays of some user-
defined enumeration. The representation of the value of an array is an ordered sequence of elements constituting the items of the array.
Within an array value, element names are not significant for distinguishing accessors. Elements may have any name. In practice, elements
will frequently be named so that their declaration in a schema suggests or determines their type. As with compound types generally, if the
href"
value of an item in the array is a single-reference value, the item contains its value. Otherwise, the item references its value via an "
attribute. The following example is a schema fragment and an array containing integer array members:
<element name="myFavoriteNumbers" type="SOAP-ENC:Array"/>
<myFavoriteNumbers SOAP-ENC:arrayType="xsd:int[3]">
<number>1</number>
<number>2</number>
<number>3</number>
</myFavoriteNumbers>
In that example, the array "myFavoriteNumbers" contains several members each of which is a value of type xsd:int. This
SOAP-ENC:arrayType attribute. Note that the SOAP-ENC:Array type allows
can be determined by inspection of the
unqualified element names without restriction. These convey no type information, so when used they must either have
an xsi:type attribute or the containing element must have a SOAP-ENC:arrayType attribute. Naturally, types derived
from SOAP-ENC:Array SOAP-ENC
may declare local elements, with type information. As previously noted, the schema
contains declarations of elements with names corresponding to each simple type in the "XML Schema Part 2: Datatypes" Specification. It also
contains a declaration for "Array". Using these, we might write:
<SOAP-ENC:Array SOAP-ENC:arrayType="xsd:int[3]">
<SOAP-ENC:int>1</SOAP-ENC:int>
</SOAP-ENC:Array>
Arrays can contain instances of any subtype of the specifiedarrayType. That is, the members may be of any type that is substitutable
arrayType attribute, according to whatever substitutability rules are expressed in the schema. So, for
for the type specified in the
example, an array of integers can contain any type derived from integer (for example "int" or any user-defined derivation of integer).
Similarly, an array of "address" might contain a restricted or extended type such as "internationalAddress". Because
the supplied SOAP-ENC:Array type admits members of any type, arbitrary mixtures of types can be contained unless specifically
limited by use of the arrayType attribute.
Array values may be structs or other compound values. For example an array of "my:order" structs :
<SOAP-ENC:Array SOAP-ENC:arrayType="my:order[2]">
<order>
<product>Melon</product>
<price>0.99</price>
</order>
<order>
<product>Apple</product>
<price>1.49</price>
</order>
</SOAP-ENC:Array>
Arrays may have other arrays as member values. The following is an example of an array of two arrays, each of which is an array of strings:
<SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[][2]">
<item href="#array-1"/>
<item href="#array-2"/>
</SOAP-ENC:Array>
<SOAP-ENC:Array id="array-1" SOAP-ENC:arrayType="xsd:string[3]">

<item>row1column1</item>
</SOAP-ENC:Array>
<SOAP-ENC:Array id="array-2" SOAP-ENC:arrayType="xsd:string[2]">

</SOAP-ENC:Array>
Arrays may be multi-dimensional. In this case, more than one size will appear within the asize part of the arrayType attribute:
<SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[2,3]">
<item>row2ccolumn2</item>
</SOAP-ENC:Array>
soapenc:Array type for array declarations

NOTE: According to WS-I BP 1.1 you MUST NOT use
or soapenc:arrayType attribute in the type declarations (for both SOAP envelope and WSDL):
In a DESCRIPTION, declarations MUST NOT extend or restrict the soapenc:Array type.

In a DESCRIPTION, declarations MUST NOT use wsdl:arrayType attribute in the type declaration.
In a DESCRIPTION, elements SHOULD NOT be named using the convention ArrayOfXXX.
An ENVELOPE MUST NOT include the soapenc:arrayType attribute.
Mapping between XML Schema types and SOAP Java types
When a message part is defined using one of the XML Schema primitive types, the generated parameter's type is mapped to a corresponding
Java native type. The same pattern is used when mapping elements that are defined within the scope of a complex type. The resulting field is
of the corresponding Java native type.
The table below lists the mapping between XML Schema primitive types and Java native types:
Table 2.1. XML Schema Primitive Type to Java Native Type Mapping
XML Schema type SOAP Java type
xsd:string java.lang.String
xsd:integer java.math.BigInteger
xsd:int int
xsd:long long
xsd:short short
xsd:decimal java.math.BigDecimal
xsd:float float
xsd:double double
xsd:boolean boolean
xsd:byte byte
xsd:QName QName
xsd:dateTime XMLGregorianCalendar
xsd:base64Binary byte[]
xsd:hexBinary byte[]
xsd:unsignedInt long
xsd:unsignedShort int
xsd:unsignedByte short
xsd:time XMLGregorianCalendar
xsd:date XMLGregorianCalendar
xsd:g XMLGregorianCalendar
Wrapper Classes
Mapping XML Schema primitive types to Java primitive types does not work for all possible XML Schema constructs. Several cases require that
an XML Schema primitive type is mapped to the Java primitive type's corresponding wrapper type. These cases include:
1. An element element with its nillable attribute set to true as shown:
2.
3. <element name="count" type="xsd:int" nillable="true" />
4.
5. An element element with its minOccurs attribute set to 0 and its maxOccurs attribute set to 1, or
its maxOccurs attribute not specified, as shown:
6.
7. <element name="count" type="xsd:int" minOccurs="0" />
8.
9. An attribute element with its use attribute set to optional, or not specified, and having neither
its default attribute nor its fixed attribute specified, as shown:
10.
11. <element name="date">
12. <complexType>
13. <sequence/>
14. <attribute name="count" type="xsd:int" use="optional" />
15. </complexType>
16. </element>
17.
Table below shows how XML Schema primitive types are mapped into Java wrapper classes in these cases:
Table 2.2. Primitive Schema Type to Java Wrapper Class Mapping
XML Schema type SOAP Java type
xsd:int java.lang.Integer
xsd:long java.lang.Long
xsd:short java.lang.Short
xsd:float java.lang.Float
xsd:double java.lang.Double
xsd:boolean java.lang.Boolean
xsd:byte java.lang.Byte
xsd:unsignedByte java.lang.Short
xsd:unsignedShort java.lang.Integer
xsd:unsignedInt java.lang.Long
xsd:unsignedLong java.math.BigInteger
NOTE: Element that is nillable, meaning that the element CAN BE EMPTY without causing a validation error. For each of the XML schema built-
in types that map to a Java primitive, there is a corresponding Java primitive wrapper that can be used if
a nillable="true" attribute is specified.
Example of mapping XML Schema-Java class
XML Schema:
<schema>
<complexType name="Address">
<sequence>
<element name="street" nillable="true" type="xsd:string"/>
<element name="city" nillable="true" type="xsd:string"/>
<element name="state" nillable="true" type="xsd:string"/>
<element name="zip" type="xsd:int"/>
</sequence>
</complexType>
</schema>
Java class:
public class Address {
public String street;
public String city;
public String state;
public int zip;
}
NOTE: Since zip is not nillable, it can be primitive, otherwise it would be:
XML Schema:
<schema>
<complexType name="Address">
<sequence>
<element name="street" nillable="true" type="xsd:string"/>
<element name="city" nillable="true" type="xsd:string"/>
<element name="state" nillable="true" type="xsd:string"/>
<element name="zip" nillable="true" type="xsd:int"/>
</sequence>
</complexType>
</schema>
Java class:
public class Address {
public String street;
public String city;
public String state;
public Integer zip;
}
In XML Schema, we can use nillable attribute to indicate that whether the element's content could be nil, as
in <xsd:element name="birthDate" type="xsd:date" nillable="true"/>. If the content
of an element is nil, we can use xsi:nil attribute to signal the processor, as in <birthDate xsi:nil="true"
/> and this element must not contain any content.
More examples on nillable attribute. Consider following XML Schema:
<xsd:element name="rootElement" nillable="true">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="myElement" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
VALID:
<rootElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<myElement>I am valid</myElement>
</rootElement>
VALID:
<rootElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:nil="true" />
INVALID (when xsi:nil is true, the element MUST BE EMPTY):

<rootElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:nil="true">
<myElement>I am NOT valid</myElement>
</rootElement>
INVALID (element rootElement MUST have myElement child and xsi:nil has not been set to true):
<rootElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
Mapping arbitrary XML content to Java
The <xsd:any/> element is an element that represents arbitrary XML content within an XML document. It is what its name indicates:
any kind of XML. This lets you create complex type definitions in an XML Schema without describing what the exact structure of certain parts
of the complex type is. Here is an example that shows the definition of a type called Order. It contains two regular elements and
one <xsd:any/> element:
<schema elementFormDefault="qualified"
<complexType name="Order">
<sequence>
<element name="date" nillable="true" type="xsd:dateTime"/>
<element name="customer" nillable="true" type="xsd:string"/>
<xsd:any maxOccurs="unbounded"/>
</sequence>
</complexType>
</schema>
An instance of this type can contain any number of additional XML elements without violating the schema definition. You can add additional
information to anOrder element without defining its format in the schema. The JAX-RPC 1.1 specification defines
that <xsd:any/> element is mapped to the SAAJ'sjavax.xml.soap.SOAPElement interface. This means that the
Service Endpoint Interface [SEI] will contain a parameter or return value of typejavax.xml.soap.SOAPElement for each
place in the schema where <xsd:any/> was used and, respectively, javax.xml.soap.SOAPElement[] if
the maxOccursattribute is bigger than 1. Therefore, a JAX-RPC tool will generate the following class from the sample schema above:
public class Order implements java.io.Serializable {
private java.util.GregorianCalendar date;
private java.lang.String customer;
private javax.xml.soap.SOAPElement[] _any;
...
}
This approach can be usefule when your Web service uses some data that you don't want to be mapped into a Java class, but rather want to
let the JAX-RPC engine hand it to the implementation in its XML form. The implementation could then parse it or simply pass it on as XML for
further processing in the backend application. Similarly, you can create a client proxy that lets you pass in a SOAPElement rather
than a mapped Java object.
Describe the SOAP Processing and Extensibility Model.
• [SOAP_1.2_PART_1] SOAP Version 1.2 Part 1: Messaging Framework
SOAP Processing Model

SOAP provides a distributed processing model that assumes a SOAP message originates at an initial SOAP sender and is sent to an ultimate
SOAP receiver via zero or more SOAP intermediaries. Note that the SOAP distributed processing model can support many Message Exchange
Patterns (MEPs) including but not limited to one-way messages, request/response interactions, and peer-to-peer conversations.
The SOAP processing model specifies how a SOAP receiver processes a SOAP message. It applies to a single message only, in isolation from
any other SOAP message. The SOAP processing model itself does not maintain any state or perform any correlation or coordination between
messages, even, for example, when used in combination with a SOAP feature which involves sending multiple SOAP messages in sequence,
each subsequent message depending on the response to the previous message. It is the responsibility of each such feature to define any
combined processing.
SOAP Nodes
A SOAP node can be the initial SOAP sender, an ultimate SOAP receiver, or a SOAP intermediary. A SOAP node receiving a SOAP message
MUST perform processing according to the SOAP processing model as described in this section and in the remainder of this specification. A
SOAP node is identified by a URI.
SOAP Roles and SOAP Nodes
In processing a SOAP message, a SOAP node is said to act in one or more SOAP roles, each of which is identified by a URI known as
the SOAP role name. The roles assumed by a node MUST be invariant during the processing of an individual SOAP message. This
specification deals only with the processing of individual SOAP messages. No statement is made regarding the possibility that a given SOAP
node might or might not act in varying roles when processing more than one SOAP message.
Table below defines three role names which have special significance in a SOAP message:
Table 2.3. SOAP Roles defined by SOAP 1.2 specification
Short-name Name Description
Each SOAP
"http://www.w3.org/2003/05/soap- intermediary and the
next ultimate SOAP
envelope/role/next" receiver MUST act in
this role.
"http://www.w3.org/2003/05/soap- SOAP nodes MUST

none NOT act in this role.
envelope/role/none"
"http://www.w3.org/2003/05/soap- The ultimate

ultimateReceiver receiver MUST act in
envelope/role/ultimateReceiver" this role.
In addition to the SOAP role names defined in the table, other role names MAY be used as necessary to meet the needs of SOAP applications.
Targeting SOAP Header Blocks
A SOAP header block MAY carry a role attribute information item that is used to target the header block at SOAP nodes operating in the
role attribute information item as the SOAP role for the
specified role. SOAP 1.2 specification refers to the value of the SOAP
corresponding SOAP header block.
A SOAP header block is said to be targeted at a SOAP node if the SOAP role for the header block is the name of a role in which the SOAP node
operates. SOAP header blocks targeted at the special role "http://www.w3.org/2003/05/soap-
envelope/role/none" are never formally processed. Such SOAP header blocks MAY carry data that is required for processing
of other SOAP header blocks. Unless removed by the action of an intermediary, such blocks are relayed with the message to the ultimate
receiver.
Understanding SOAP Header Blocks
mustUnderstand attribute information item. When the value of such an attribute information
A SOAP header block MAY carry a
item is "true", the SOAP header block is said to be mandatory.
Mandatory SOAP header blocks are presumed to somehow modify the semantics of other SOAP header blocks or SOAP body elements.
Therefore, for every mandatory SOAP header block targeted to a node, that node MUST either process the header block or not process the
SOAP message at all, and instead generate a fault. Tagging SOAP header blocks as mandatory thus assures that such modifications will not
be silently (and, presumably, erroneously) ignored by a SOAP node to which the header block is targeted.
Processing SOAP Messages

Unless otherwise stated, processing of all generated SOAP messages, SOAP faults and application-level side effects MUST be semantically
equivalent to performing the following steps separately, and in the order given:
1. Determine the set of roles in which the node is to act. The contents of the SOAP envelope, including any SOAP header blocks and
the SOAP body, MAY be inspected in making such determination.
2. Identify all header blocks targeted at the node that are mandatory.
3. If one or more of the SOAP header blocks identified in the preceding step are not understood by the node then generate a single
SOAP fault with the Value of Code set to "env:MustUnderstand" . If such a fault is generated, any further
processing MUST NOT be done. Faults relating to the contents of the SOAP body MUST NOT be generated in this step.
4. Process all mandatory SOAP header blocks targeted at the node and, in the case of an ultimate SOAP receiver, the SOAP body. A
SOAP node MAY also choose to process non-mandatory SOAP header blocks targeted at it.
5. In the case of a SOAP intermediary, and where the SOAP message exchange pattern and results of processing (e.g., no fault
generated) require that the SOAP message be sent further along the SOAP message path, relay the message.
Relaying SOAP Messages
A SOAP header block MAY carry a relay attribute information item. When the value of such an attribute information item is "true",
the header block is said to be relayable.
Forwarding SOAP intermediaries MUST process the message according to the SOAP processing model defined in "Processing SOAP Messages".
In addition, when generating a SOAP message for the purpose of forwarding, they MUST:
1. Remove all processed SOAP header blocks.

2. Remove all non-relayable SOAP header blocks that were targeted at the forwarding node but ignored during processing.
3. Retain all relayable SOAP header blocks that were targeted at the forwarding node but ignored during processing.
SOAP Versioning Model
The version of a SOAP message is identified by the XML expanded name of the child element information item of the document information
item. A SOAP Version 1.2 message has a child element information item of the document information item with a [local name]
of Envelope and a [namespace name] of"http://www.w3.org/2003/05/soap-envelope".
Value of Code set

If a SOAP node receives a message whose version is not supported it MUST generate a fault with a
to"env:VersionMismatch". Any other malformation of the message construct MUST result in the generation of a fault with
a Value of Code set to "env:Sender".
The example below shows a version mismatch SOAP fault generated by a SOAP Version 1.2 node as a result of receiving a SOAP/1.1
message. The fault message is a SOAP/1.1 message with an Upgrade SOAP header block indicating support for SOAP Version 1.2:
<?xml version="1.0" ?>

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header>
<env:Upgrade>
<env:SupportedEnvelope qname="ns1:Envelope"
xmlns:ns1="http://www.w3.org/2003/05/soap-envelope"/>
</env:Upgrade>
</env:Header>
<env:Body>
<env:Fault>
<faultcode>env:VersionMismatch</faultcode>
<faultstring>Version Mismatch</faultstring>
</env:Fault>
</env:Body>
</env:Envelope>
Let's start by looking at a basic SOAP message and its nested elements.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header>
<pns:qualityOfService xmlns:pns="http://example.org/qos">
<pns:priority>3</pns:priority>
<pns:timestamp>2004-02-25T01:00:00-00:00</pns:timestamp>
<pns:persist>true</pns:persist>
</pns:appHeaderBlock>
</env:Header>
<env:Body>
<bmns:businessPO xmlns:env="http://example.org/po">
<bmns:description>Widgets</bmns:description>
<bmns:quantity>100</bmns:quantity>
<bmns:price>20.5</bmns:price>
</bmns:businessPO>
</env:Body>
</env:Envelope>
The outermost element is the env:Envelope that includes the namespace URL for SOAP. Enclosed within this are two subelements
that SOAP defines. These are the env:Header env:Bodyand elements. SOAP does not define their contents. The elements are
specific to the application that creates and processes the SOAP message. However, the SOAP specification does define how a SOAP node
processes these elements.
The env:Header element is OPTIONAL in SOAP, but it has been included in the sample to illustrate its use. The SOAP header is an
extension mechanism that provides a way for information to be passed within a SOAP message that is not part of the business message
payload. In the previous example, the env:Header includes an immediate child element that contains a set of quality of service
parameters. This immediate child is called a header block. A header can contain many header blocks. The header block has its own XML
namespace in which the priority timestamp
, , and persist elements appear. The SOAP specification allows header blocks
to be targeted at specific SOAP nodes for processing as the message travels along its message path. The SOAP headers control and process a
message as it moves along a message path. They include information that controls messaging qualities of service such as security, reliability,
and addressing. By specifying new headers, you can create interoperable protocols based on SOAP. These form the basis of the services
architecture.
The env:Body element within the SOAP message is MANDATORY. It contains the payload of the message, which is the information that
is being transferred from the initial SOAP sender to the ultimate SOAP receiver. The choice of what information goes into
the env:Header and what goes into the env:Body elements is a matter of business application and system design. In a typical
enterprise environment, middleware that supports a defined set of service policies mandates what headers are required in a SOAP message.
The env:Body is then used to contain necessary application-specific information, which is processed by the ultimate receiver of the
remote service implemention.
The "role" Attribute
When a SOAP node processes a SOAP message, the node is said to act in one of several roles. A SOAP role identifies how a SOAP node
should process a message. A URI identifies the SOAP role. It might be one of the three roles within the SOAP specification or one that
systems designers assign to meet the needs of some applications. It appears as an attribute on the parent header block element:
<env:Header>
<hb1:firstHeaderBlock xmlns:hb1="http://example.org/hb1"
env:role="http://example.org/Qos">
.....
</hb1:firstHeaderBlock>
<hb2:secondHeaderBlock xmlns:hb1="http://example.org/hb2"
env:role="http://www.w3.org/2003/05/soap-envelope/role/next">
.....
</hb2:secondHeaderBlock>
<hb3:thirdHeaderBlock xmlns:hb1="http://example.org/hb3">
.....
</hb3:thirdHeaderBlock>
</env:Header>
<env:Body>
.....
</env:Body>
</env:Envelope>
The hb1:firstHeaderBlock element has a role attribute set to a value of http://example.org/Qos . The
system designer assumes that the SOAP node that plays this role uses the information within the header block to manage message delivery
quality of service in some specified way. The second header block hb2:secondHeaderBlock has its role attribute set to one of
the roles defined within the SOAP 1.2 specification. The SOAP 1.2 specification defines three roles:
• http://www.w3.org/2003/05/soap-envelope/role/none
"none"
If a header block has a role set to the URI, no SOAP node should process the contents of the header block. Nodes
might need to examine the header contents if another header block references them, but they should not be processed.
• http://www.w3.org/2003/05/soap-envelope/role/next
"next" URI, because this is a
Every SOAP node must be capable of processing a header block with its role attribute set to the
"next" URI is one that the next SOAP node in the
role that every node should assume. A header block with a role set to the
message path should examine and possibly process. In the previous example, the hb2:secondHeaderBlock has
its role attribute set to "next".
• http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver
A SOAP node that assumes the role of an ultimate SOAP receiver processes a header block with its role attribute set to
the "ultimateReceiver" URI. A header block that has no role attribute is targeted at the SOAP node that is acting
hb3:thirdHeaderBlock is targeted at the ultimate SOAP
as an ultimate SOAP receiver. In the example, the
receiver because it doesn't have a role attribute.
NOTE: SOAP 1.1 has the actor attribute. In SOAP 1.2 this attribute is renamed to role. The semantics of the attribute are
unchanged.
The "mustUnderstand" Attribute
Sometimes a SOAP node MUST process a particular header completely if it is acting in that SOAP role. The SOAP specification signals this
condition by introducing a "mustUnderstand" attribute that can be added to a header block:
<env:Header>
<hb1:firstHeaderBlock exmlns:hb1="http://example.org/hb1"
env:role="http://example.org/Qos"
env:mustUnderstand="1">
.....
env:role="http://www.w3.org/2003/05/soap-envelope/role/next">
.....
.....
</env:Header>
<env:Body>
.....
</env:Body>
</env:Envelope>
In the example, the SOAP node that is targeted by the hb1:firstHeaderBlock element must process the header block
because a "mustUnderstand" 1
attribute is set to . This is commonly referred to as a mandatory header block. The SOAP
processing model states that processing of a SOAP message must not start until a SOAP node has identified all the mandatory header blocks
targeted at it and is prepared to process them in accordance with the specification for those header blocks. If a header block has
a "mustUnderstand" attribute set to 0, or there is no such attribute, a SOAP node might choose to ignore and not process the
"mustUnderstand"
header block, even though it might be targeted at it. If a header block has a attribute and is targeted at a
SOAP node, the SOAP node is obliged to generate and return a SOAP fault if it is unable to process the header block.
NOTE: According to Basic Profile Version 1.1:
An ENVELOPE containing a soap:mustUnderstand attribute MUST only use the lexical forms "0" and "1".
env:mustUnderstand="0|1"
The "relay" Attribute
The SOAP processing model states that a node that processes a header must remove it from the message before passing it to another node
along the message path. This is because the SOAP specification errs on the side of caution, making sure that an intermediary makes no
assumptions about what will happen to the message header it has processed later in the message path. The SOAP specification does,
however, allow a node to reinsert a header into an outbound message with its contents unchanged or altered in some way, but the default
behavior of the node is to remove the header after processing.
Sometimes, however, a systems designer wants a particular header to be targeted at any or all nodes within a message path. To allow this,
SOAP 1.2 introduces the "relay" attribute. If this attribute is set to true, a SOAP node that detects a header targeted at itself can
forward the header block to the next node if it chooses not to process it.
<env:Header>
<hb1:firstHeaderBlock xmlns:hb1="http://example.org/hb1"
env:role="http://example.org/Qos"
env:mustUnderstand="1">
.....
env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
env:relay="true">
.....
.....
</env:Header>
<env:Body>
.....
</env:Body>
</env:Envelope>
"next" node in the message path. It also has the "relay" attribute set
In the example, the second header block is targeted at the
to true. This means that a SOAP node that receives this message can process the header if it understands it. If it does so, the SOAP
processing rules must be obeyed and the header removed before forwarding the entire message. A "relay" attribute set
to true means that the node, if it chooses to, can ignore the header block and forward it to the next node. Remember that if a header
block also has the "mustUnderstand" attribute set to true, this over-rules a "relay", and the node must process the
header block if it understands its meaning.
NOTE: According to SOAP Version 1.2 Part 1: Messaging Framework:
"true" for the value "1", or "false" for "0". In addition, a

If relaying the message, a SOAP intermediary MAY substitute
SOAP intermediary MAY omit a SOAP mustUnderstand attribute information item if its value is "0".
SOAP Extensibility Model
SOAP provides a simple messaging framework whose core functionality is concerned with providing extensibility. The extensibility
mechanisms can be used to add capabilities found in richer messaging environments.
SOAP Features
A SOAP feature is an extension of the SOAP messaging framework. Although SOAP poses no constraints on the potential scope of such
features, example features may include "reliability", "security", "correlation", "routing", and message exchange patterns (MEPs) such as
request/response, one-way, and peer-to-peer conversations.
The SOAP extensibility model provides two mechanisms through which features can be expressed: the SOAP Processing Model (describes
the behavior of a single SOAP node with respect to the processing of an individual message) and the SOAP Protocol Binding
Framework (mediates the act of sending and receiving SOAP messages by a SOAP node via an underlying protocol).
SOAP Message Exchange Patterns (MEPs)
A Message Exchange Pattern (MEP) is a template that establishes a pattern for the exchange of messages between SOAP nodes. MEPs are a
type of feature, and unless otherwise stated, references in this specification to the term "feature" apply also to MEPs. The request-response
MEP specified in SOAP 1.2 Part 2 [SOAP Part 2] illustrates the specification of a MEP feature.
The specification of a message exchange pattern MUST:
1. Provide a URI to name the MEP.

2. Describe the life cycle of a message exchange conforming to the pattern.
3. Describe the temporal/causal relationships, if any, of multiple messages exchanged in conformance with the pattern (e.g.,
responses follow requests and are sent to the originator of the request.)
4. Describe the normal and abnormal termination of a message exchange conforming to the pattern.
SOAP Modules
The term "SOAP module" refers to the specification of the syntax and semantics of one or more SOAP header blocks. A SOAP module
realizes zero or more SOAP features. A module specification adheres to the following rules. It:
1. MUST identify itself with a URI. This enables the module to be unambiguously referenced in description languages or during
negotiation.
2. MUST declare the features provided by a module.
3. MUST clearly and completely specify the content and semantics of the SOAP header blocks used to implement the behavior in
question, including if appropriate any modifications to the SOAP processing model. The SOAP extensibility model does not limit
the extent to which SOAP can be extended. Nor does it prevent extensions from modifying the SOAP processing model.
4. MAY utilize the property conventions defined in SOAP 1.2 Part 2 [SOAP Part 2], section A Convention for Describing Features and
Bindings, in describing the functionality that the module provides. If these conventions are followed, the module specification
MUST clearly describe the relationship between the abstract properties and their representations in the SOAP envelope. Note that
it is possible to write a feature specification purely in terms of abstract properties, and then write a separate module specification
which implements that feature, mapping the properties defined in the feature specification to SOAP header blocks in the SOAP
module.
5. MUST clearly specify any known interactions with or changes to the interpretation of the SOAP body. Furthermore, it MUST clearly
specify any known interactions with or changes to the interpretation of other SOAP features and SOAP modules. For example, we
can imagine a module which encrypts and removes the SOAP body, inserting instead a SOAP header block containing a checksum
and an indication of the encryption mechanism used. The specification for such a module would indicate that the decryption
algorithm on the receiving side is to be run prior to any other modules which rely on the contents of the SOAP body.
Describe SOAP Message Construct and create a SOAP message that contains an attachment.
• [SOAP_1.2_PART_1] SOAP Version 1.2 Part 1: Messaging Framework
A SOAP message is an XML document that consists of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body.
The namespace identifier for the elements and attributes from SOAP message is
" http://www.w3.org/2003/05/soap-envelope". A SOAP message contains the following:
• The Envelope is the top element of the XML document representing the message.
• The Header is a generic mechanism for adding features to a SOAP message in a decentralized manner without prior
agreement between the communicating parties. SOAP defines a few attributes that can be used to indicate who should deal with a
Header element is OPTIONAL.
feature and whether it is optional or mandatory. NOTE:
• The Body is a container for mandatory information intended for the ultimate recipient of the message. SOAP defines one
element for the body, which is the Fault element used for reporting errors. NOTE: Body element is MANDATORY and MUST
be exactly 1 per message.
The grammar rules are as follows:
1. Envelope
• The element name is " Envelope".
• The element MUST be present in a SOAP message.
• One or two element information items in its [children] property in order as follows:
a. An optional Header element information item.
b. A mandatory Body element information item.
SOAP 1.2 Schema for Envelope:
<xs:complexType name="Envelope">
<xs:sequence>
<xs:element ref="tns:Header" minOccurs="0"/>
<xs:element ref="tns:Body" minOccurs="1"/>
</xs:sequence>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:complexType>
Example:
<env:Header>
<n:alertcontrol xmlns:n="http://example.org/alertcontrol">
<n:priority>1</n:priority>
<n:expires>2001-06-22T14:00:00-05:00</n:expires>
</n:alertcontrol>
</env:Header>
<env:Body>
<m:alert xmlns:m="http://example.org/alert">
<m:msg>Pick up Mary at school at 2pm</m:msg>
</m:alert>
</env:Body>
</env:Envelope>
NOTE: SOAP 1.1 allows additional elements to follow the SOAP Body element, SOAP 1.2 DISALLOWS these.
NOTE: According to WS-I BP 1.1:
An ENVELOPE MUST NOT have any element children of soap:Envelope following the soap:Body element.
2. Header
• The element name is " Header".
• The element MAY be present in a SOAP message. If present, the element MUST be the first immediate child element
of a SOAP Envelopeelement.
• The element MAY contain a set of header entries each being an immediate child element of the
SOAP Header element. All immediate child elements of the SOAP Header element MUST be namespace-
qualified.
NOTE: WS-I BP 1.0 requires all immediate children of Header element be namespace qualified.
3. SOAP 1.2 Schema for Header:

4.
5. <xs:complexType name="Header">
6. <xs:annotation>
7. <xs:documentation>
8. Elements replacing the wildcard MUST be namespace qualified, but can be in the
targetNamespace
9. </xs:documentation>
10. </xs:annotation>
11. <xs:sequence>
12. <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
13. </xs:sequence>
14. <xs:anyAttribute namespace="##other" processContents="lax"/>
15. </xs:complexType>
16.
17.
18. Example:
19.
20. <env:Header xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
21. <t:Transaction xmlns:t="http://example.org/2001/06/tx" env:mustUnderstand="1" >
22. 5
23. </t:Transaction>
24. </env:Header>
25.
26.
27. Body
• The element name is " Body".
• The element MUST be present in a SOAP message and MUST be an immediate child element of a
SOAP Envelope element. It MUST directly follow the SOAP Header element if present. Otherwise it MUST
be the first immediate child element of the SOAPEnvelope element.
• The element MAY contain a set of body entries each being an immediate child element of the SOAP Body element.
Immediate child elements of the SOAP Body element SHOULD be namespace-qualified.
SOAP defines one particular direct child of the SOAP body, the SOAP fault, which is used for reporting errors.
NOTE: WS-I BP 1.1 requires ALL immediate children of Body element be namespace qualified:
The children of the soap:Body element in an ENVELOPE MUST be namespace qualified.
28. SOAP 1.2 Schema for Body:

29.
30. <xs:complexType name="Body">
31. <xs:sequence>
32. <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
33. </xs:sequence>
34. <xs:anyAttribute namespace="##other" processContents="lax"/>
36.
37.
38. Example:
39.
40. <env:Body xmlns:env="http://www.w3.org/2003/05/soap-envelope">
41. <m:alert xmlns:m="http://example.org/alert">
42. <m:msg>Pick up Mary at school at 2pm</m:msg>
43. </m:alert>
44. </env:Body>
45.
46.
The SOAP Body element provides a simple mechanism for exchanging mandatory information intended for the ultimate recipient of the
message. Typical uses of the Body element include marshalling RPC calls and error reporting. The Body element is encoded as an
immediate child element of the SOAP Envelope XML element.
If aHeader element is present then the Body element MUST immediately follow the Header element, otherwise it MUST be the
Envelope element. All immediate child elements of the Body element are called body entries
first immediate child element of the
and each body entry is encoded as an independent element within the SOAP Body element. The encoding rules for body entries are as
follows:
1. WS-I BP 1.1: The children of the soap:Body element in an ENVELOPE MUST be namespace qualified.
WS-I BP 1.1: An ENVELOPE MUST NOT contain soap:encodingStyle attributes on any element that is a child
of soap:Body.
2. rpc-literal binding MUST NOT

WS-I BP 1.1: An ENVELOPE described in an
contain soap:encodingStyle attribute on any element that is a grandchild of soap:Body.
SOAP Fault
SOAP defines one body entry, which is the Fault entry used for reporting errors. Here is SOAP 1.2 Schema definition
of Fault element:
<xs:complexType name="Fault" final="extension">

<xs:annotation>
<xs:documentation>
Fault reporting structure
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="Code" type="tns:faultcode"/>
<xs:element name="Reason" type="tns:faultreason"/>
<xs:element name="Node" type="xs:anyURI" minOccurs="0"/>
<xs:element name="Role" type="xs:anyURI" minOccurs="0"/>
<xs:element name="Detail" type="tns:detail" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
Sample SOAP 1.2 fault is shown below:
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:flt="http://example.org/faults">

<env:Body>
<env:Fault>
<env:Code>
<env:Value>env:Receiver</env:Value>
<env:Subcode>
<env:Value>flt:BadValue</env:Value>
</env:Subcode>
</env:Code>
<env:Reason>
<env:Text>A Fault occurred</env:Text>
</env:Reason>
<env:Detail>
<flt:MyDetails>
<flt:Message>Something went wrong at the Receiver</flt:Message>
<flt:ErrorCode>1234</flt:ErrorCode>
</flt:MyDetails>
</env:Detail>
</env:Fault>
</env:Body>
</env:Envelope>
The SOAP Fault element is used to carry error and/or status information within a SOAP message. If present, the SOAP Fault element
MUST appear as a body entry and MUST NOT appear more than once within a Body element. The SOAP Fault element defines two or
more child element information items in its [children] property in order as follows:
1. A MANDATORY Code element.

2.
3. <xs:element name="Code" type="tns:faultcode"/>
4. ...
5. <xs:complexType name="faultcode">
6. <xs:sequence>
7. <xs:element name="Value" type="tns:faultcodeEnum"/>
8. <xs:element name="Subcode" type="tns:subcode" minOccurs="0"/>
9. </xs:sequence>
11.
12.
The Code element information item has:
• A [local name] of Code.

• One or two child element information items in its [children] property, in order, as follows:
a. A MANDATORY Value element information item.
The type of the Value element information item is env:faultCodeEnum. SOAP 1.2
defines a small set of SOAP fault codes covering high level SOAP faults:
<xs:element name="Value" type="tns:faultcodeEnum"/>

...
<xs:simpleType name="faultcodeEnum">
<xs:restriction base="xs:QName">
<xs:enumeration value="tns:DataEncodingUnknown"/>
<xs:enumeration value="tns:MustUnderstand"/>
<xs:enumeration value="tns:Receiver"/>
<xs:enumeration value="tns:Sender"/>
<xs:enumeration value="tns:VersionMismatch"/>
</xs:restriction>
</xs:simpleType>
b. An OPTIONAL Subcode element information item.

c.
d. <xs:element name="Subcode" type="tns:subcode" minOccurs="0"/>
e. ...
f. <xs:complexType name="subcode">
g. <xs:sequence>
h. <xs:element name="Value" type="xs:QName"/>
i. <xs:element name="Subcode" type="tns:subcode" minOccurs="0"/>
j. </xs:sequence>
k. </xs:complexType>
l.
The Subcode element information item has:
o A [local name] of Subcode.

o One or two child element information items in its [children] property, in order, as follows:
i. A MANDATORY Value element information item.
The type of the Value element information item is xs:QName. The value
of this element is an application defined subcategory of the value of
the Value child element information item of the Subcode element
information item's parent element information item.
ii. An optional Subcode element information item.

13. A MANDATORY Reason element information item.
The Reason element information item is intended to provide a human-readable explanation of the fault.
<xs:element name="Reason" type="tns:faultreason"/>

...
<xs:complexType name="faultreason">
<xs:sequence>
<xs:element name="Text" type="tns:reasontext" minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
The Reason element information item has:
• A [local name] ofReason.

• One or more Text element information item children.
Each child Text element information item MUST have a mandatory attribute information item with a [local name]
oflang and [namespace name] of "http://www.w3.org/XML/1998/namespace".
Note that the definition in of the lang attribute information item requires that the [prefix] is "xml"or any
capitalization thereof.
Each child Text element information item SHOULD have a different value for its xml:lang attribute
information item.
<xs:element name="Text" type="tns:reasontext" minOccurs="1" maxOccurs="unbounded"/>

...
<xs:complexType name="reasontext">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute ref="xml:lang" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
14. An OPTIONAL Node element information item.
The Node element information item is intended to provide information about which SOAP node on the SOAP message path
caused the fault to happen.
The type of the Node element information item is xs:anyURI.
<xs:element name="Node" type="xs:anyURI" minOccurs="0"/>
Each SOAP node is identified by a URI. The value of the Node element information item is the URI that identifies the SOAP
node that generated the fault. SOAP nodes that do not act as the ultimate SOAP receiver MUST include this element information
item. An ultimate SOAP receiver MAY include this element information item to indicate explicitly that it generated the fault.
15. An OPTIONAL Role element information item.
The Role element information item identifies the role the node was operating in at the point the fault occurred.
The type of the Role element information item is xs:anyURI.
<xs:element name="Role" type="xs:anyURI" minOccurs="0"/>
The value of the Role element information item MUST be one of the roles assumed by the node during processing of the
message.
16. An OPTIONAL Detail element information item.
The Detail element information item is intended for carrying application specific error information.
<xs:element name="Detail" type="tns:detail" minOccurs="0"/>

...
<xs:complexType name="detail">
<xs:sequence>
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:complexType>
The Detail element information item MAY have any number of character information item children. The character code of
each such character information item MUST be amongst the white space characters as defined by XML 1.0. These are considered
significant.
The Detail element information item MAY be present in a SOAP fault in which case it carries additional information relative
Detail element information item might contain information
to the SOAP fault codes describing the fault. For example, the
about a message not containing the proper credentials, a timeout, etc. The presence of the Detail element information item
has no significance as to which parts of the faulty SOAP message were processed.
SOAP 1.1 allows extension of fault codes using a "dot" notation, SOAP 1.2 disallows this and provides a more XML-like representation instead.
SOAP 1.1 fault:

<e:Fault>
<faultcode>e:Server.Memory</faultcode>
<faultstring>Out of memory</faultstring>
</e:Fault>
SOAP 1.2 fault:
<e:Fault>
<e:Code>
<e:Value>e:Receiver</e:Value>
<e:Subcode>
<e:Value>p:Memory</e:Value>
</e:Subcode>
</e:Code>
<e:Reason>Out of memory</e:Reason>
</e:Fault>
SOAP Fault Codes
SOAP fault codes are XML expanded names, and are intended to provide a means by which faults are classified. A hierarchical list of SOAP
codes and associated supporting information is included in every SOAP fault message, with each such code identifying the fault category at an
increasing level of detail.
Value child element information item of the Code element information item are RESTRICTED to those defined by
The values of the
theenv:faultCodeEnumtype (see the table below). Additional fault subcodes MAY be created for use by applications or features.
Such subcodes are carried in the Value child element information item of the Subcode element information item.
Detail element information item in the sense that they

SOAP fault codes are to be interpreted as modifiers of the contents of the
provide the context for theDetail element information item. A SOAP node MUST understand all SOAP fault codes in a SOAP fault
message in order to be able to interpret theDetail element information item in a SOAP fault.
Detail element information item is to be interpreted in the context of

Sample SOAP fault where the
the "env:Sender" and "m:MessageTimeout" fault codes:
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:m="http://www.example.org/timeouts"
xmlns:xml="http://www.w3.org/XML/1998/namespace">
<env:Body>
<env:Fault>
<env:Code>
<env:Value>env:Sender</env:Value>
<env:Subcode>
<env:Value>m:MessageTimeout</env:Value>
</env:Subcode>
</env:Code>
<env:Reason>
<env:Text xml:lang="en">Sender Timeout</env:Text>
</env:Reason>
<env:Detail>
<m:MaxTime>P5M</m:MaxTime>
</env:Detail>
</env:Fault>
</env:Body>
</env:Envelope>
NOTE: WS-I BP 1.1 PROHIBITS the use of "dot" notation of fault code (e.g. Server.Memory, or Sender.Memory).
The set of predefined fault code values is:
Table 2.4. SOAP Fault Codes

Local Name Meaning
The faulting node found an invalid element information item instead of the
VersionMismatch expected Envelope element information item. The namespace, local name or both did
not match theEnvelope element information item required by this recommendation.
An immediate child element information item of the SOAP Header element information
MustUnderstand item targeted at the faulting node that was not understood by the faulting node contained a
SOAP mustUnderstand attribute information item with a value of "1".
A SOAP header block or SOAP body child element information item targeted at the faulting
SOAP node is scoped with a data encoding that the faulting node does not support.
DataEncodingUnknown
DataEncodingUnknown generated when a received message uses an
unrecognised value of the encodingStyleattribute.
The message was incorrectly formed or did not contain the appropriate information in order to
succeed. 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.
Sender
NOTE: The SOAP 1.1 " Client" fault code is renamed "Sender" in SOAP 1.2.
The message could not be processed for reasons attributable to the processing of the message
rather than to the contents of the message itself. For example, processing could include
communicating with an upstream SOAP node, which did not respond. The message could
succeed if resent at a later point in time.
Receiver
NOTE: The SOAP 1.1 " Server" fault code is renamed "Receiver" in SOAP 1.2.
Create a SOAP message that contains an attachment.
The SOAP with Attachments API for Java (SAAJ) provides a standard way to send XML documents over the Internet from the Java platform. It
is based on the SOAP 1.1 and SOAP with Attachments specifications, which define a basic framework for exchanging XML messages.
The process of creation and sending SOAP message includes following steps:
• Creating a SOAP connection.

• Creating a SOAP message.
• Populating the message.
• Sending the message.
• Retrieving the reply.
A SAAJ client is a standalone client. That is, it sends point-to-point messages directly to a Web Service that is implemented for request-
response messaging. Request-response messaging is synchronous, meaning that a request is sent and its response is received in the same
operation. A request-response message is sent over a SOAPConnection object via the
method SOAPConnection.call , which sends the message and blocks until it receives a response. A standalone client can
operate only in a client role, that is, it can only send requests and receive their responses.
ASOAPMessage object represents an XML document that is a SOAP message. A SOAPMessage object always has a required
SOAPEnvelope object, which
SOAP part, and it may also have one or more attachment parts. The SOAP part must always have a
must in turn always contain a SOAPBody object. TheSOAPEnvelope object may also contain a SOAPHeader object, to
which one or more headers can be added.
The SOAPBody object can hold XML fragments as the content of the message being sent. If you want to send content that is not in XML
format or that is an entire XML document, your message will need to contain an attachment part in addition to the SOAP part. There is no
limitation on the content in the attachment part, so it can include images or any other kind of content, including XML fragments and
documents. Common types of attachment include sound, picture, and movie data: .mp3, .jpg, and .mpg files.
SOAPConnection object.
The first thing a SAAJ client needs to do is get a connection in the form of a
A SOAPConnection object is a point-to-point connection that goes directly from the sender to the recipient. The connection is
created by a SOAPConnectionFactory object. A client obtains the default implementation
for SOAPConnectionFactory by calling the following line of code:
SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance();
The client can use factory to create a SOAPConnection object.

SOAPConnection connection = factory.createConnection();
MessageFactory object, you get an instance of the default

Messages, like connections, are created by a factory. To obtain a
implementation for the MessageFactory class. This instance can then be used to create a SOAPMessage object:
MessageFactory messageFactory = MessageFactory.newInstance();

SOAPMessage message = messageFactory.createMessage();
All of theSOAPMessage objects that messageFactory creates, including message in the previous line of code, will be SOAP
SOAPMessage object message automatically contains the
messages. This means that they will have no pre-defined headers. The new
required elements SOAPPart, SOAPEnvelope, and SOAPBody, plus the optional element SOAPHeader (which is
included for convenience). The SOAPHeader and SOAPBody objects are initially empty, and the code below will illustrate some of
the typical ways to add content. Content can be added to the SOAPPart object, to one or more AttachmentPart objects, or
to both parts of a message.
package javax.xml.soap;
public abstract class SOAPPart implements org.w3c.dom.Document {

public abstract SOAPEnvelope getEnvelope() throws SOAPException;
...
}
SOAPPart object, which has a SOAPEnvelope object containing

As stated earlier, all messages have a
a SOAPHeader object and a SOAPBody object.
package javax.xml.soap;
public interface SOAPEnvelope extends SOAPElement {

public abstract Name createName(String localName, String prefix, String uri)
throws SOAPException;
public abstract Name createName(String localName) throws SOAPException;
public abstract SOAPHeader getHeader() throws SOAPException;
public abstract SOAPHeader addHeader() throws SOAPException;
public abstract SOAPBody getBody() throws SOAPException;
public abstract SOAPBody addBody() throws SOAPException;
}
SOAPHeaderElement object or
One way to add content to the SOAP part of a message is to create a
a SOAPBodyElement object and add an XML fragment that you build with the
method SOAPElement.addTextNode. The first three lines of the following code fragment access the SOAPBody object
body, which is used to create a new SOAPBodyElement object and add it to body. The argument passed to
the createName method is a Name object identifying the SOAPBodyElementbeing added. The last line adds the XML
string passed to the method addTextNode:
SOAPPart soapPart = message.getSOAPPart();

SOAPEnvelope envelope = soapPart.getEnvelope();
SOAPBody body = envelope.getBody();
Name bodyName = envelope.createName("text", "i",
"http://hotitems.com");
SOAPBodyElement bodyElement = body.addBodyElement(bodyName);
bodyElement.addTextNode("some-xml-text");
The content that you have just added to your SOAPBody object will look like the following when it is sent over the wire:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<i:text xmlns:i="http://hotitems.com">
some-xml-text
</i:text>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Another way is to add content to theSOAPPart object by passing it a javax.xml.transform.Source object, which
may be a SAXSource, DOMSource, orStreamSource object. The Source object contains content for the SOAP part
of the message and also the information needed for it to act as source input. AStreamSource object will contain the content as an
XML document; the SAXSource or DOMSource object will contain content and instructions for transforming it into an XML
document.
DOMSource object. The first step is to get the SOAPPart object from
The following code fragments illustrates adding content as a
the SOAPMessage object. Next the code uses methods from the JAXP API to build the XML document to be added. It uses
a DocumentBuilderFactory object to get a DocumentBuilderobject. Then it parses the given file to produce the
document that will be used to initialize a new DOMSource object. Finally, the code passes
the DOMSourceobject domSource to the method SOAPPart.setContent:
SOAPPart soapPart = message.getSOAPPart();

DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance();
DocumentBuilder builder = dbFactory.newDocumentBuilder();
Document document = builder.parse("file:///foo.bar/soap.xml");
DOMSource domSource = new DOMSource(document);
soapPart.setContent(domSource);
This code would work equally well with a SAXSource or a StreamSource object.
You use the setContent method when you want to send an existing SOAP message. If you have an XML document that you want to
addDocument method on the body of the message:
send as the content of a SOAP message, you use the
SOAPBodyElement docElement = body.addDocument(document);
This allows you to keep your application data in a document that is separate from the SOAP envelope unless and until it is time to send that
data as a message.
A SOAPMessage object may have no attachment parts, but if it is to contain anything that is not in XML format, that content must be
contained in an attachment part. There may be any number of attachment parts, and they may contain anything from plain text to image
files. In the following code fragment, the content is an image in a JPEG file, whose URL is used to initialize
the javax.activation.DataHandler object handler. The Message object message creates
the AttachmentPart object attachPart, which is initialized with the data handler containing the URL for the image.
Finally, the messageadds attachPart to itself:
URL url = new URL("http://foo.bar/img.jpg");

DataHandler handler = new DataHandler(url);
AttachmentPart attachPart = message.createAttachmentPart(handler);
message.addAttachmentPart(attachPart);
A SOAPMessage object can also give content to an AttachmentPart object by passing an Object and its content type
createAttachmentPart:
to the method
AttachmentPart attachPart = message.createAttachmentPart(

"content-string", "text/plain");
message.addAttachmentPart(attachPart);
Once you have populated a SOAPMessage object, you are ready to send it. A client uses
the SOAPConnection method call to send a message. This method sends the message and then blocks until it gets back a
response. The arguments to the method call are the message being sent and a URL object that contains the URL specifying the endpoint
of the receiver.
SOAPMessage response = soapConnection.call(message, endpoint);
The following example shows a SOAP 1.1 message with an attached facsimile image of the signed claim form ( claim.tiff), also it
illustrates the use of the cid reference in the body of the SOAP 1.1 message:
MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
start="<claim.xml@claiming-it.com>"
Content-Description: This is the optional message description.
--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <claim.xml@claiming-it.com>
<?xml version='1.0' ?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
..
<theSignedForm href="cid:claim.tiff@claiming-it.com"/>
..
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
--MIME_boundary
Content-Type: image/tiff
Content-Transfer-Encoding: binary
Content-ID: <claim.tiff@claiming-it.com>
d3d3Lm1hcmNoYWwuY29taesgfSEVFES45345sdvgfszd==
--MIME_boundary--
NOTE: In this example the " Content-Type " header line has been continued across two lines so the example prints easily. SOAP
message senders should send headers on a single long line.
NOTE: Associate the attachment to theSignedForm element by adding an href attribute. The attachment is referred to through
a cid (Content-ID) URL:
...
<myElement href="cid:xxxx" />
...
--MIME_boundary
Content-Type: image/tiff
Content-ID: <xxxx>
...
#
NOTE: Unlike SOAP 1.1 XML references, do not use ' ' (pound sign) in href attribute value when you refer to attachment, also when you
refer to attachment you must prepend unique identifier with prefix ' cid:'.
The following listing illustrates the creation of the SOAP request. The request asks a server to resize an image. The procedure is as follows:
1. Create SOAP connection and SOAP message objects through factories.

2. Retrieve the message body from the message object (intermediary steps: retrieve the SOAP part and envelope).
3. Create a new XML element to represent the request.
4. DataHandler object.
Create the attachment and initialize it with a
5. Create more elements to represent the two parameters ( source and percent).
6. Associate the attachment to the first parameter by adding an href attribute. The attachment is referred to through
a cid (Content-ID) URI.
7. Set the value of the second parameter directly as text and call the service.
The service replies with the resized image, again as an attachment. To retrieve it, you can test for a SOAP fault (which indicates an error). If
there are no faults, retrieve the attachment as a file and process it. Using SAAJ API:
// Using SAAJ
public File resize(String endPoint,File file) {

SOAPConnection connection = SOAPConnectionFactory.newInstance().createConnection();
SOAPMessage message = MessageFactory.newInstance().createMessage();
SOAPPart part = message.getSOAPPart();
SOAPEnvelope envelope = part.getEnvelope();
SOAPBody body = envelope.getBody();
SOAPBodyElement operation = body.addBodyElement(
envelope.createName("resize", "ps", "http://example.com"));
DataHandler dh = new DataHandler(new FileDataSource(file));
AttachmentPart attachment = message.createAttachmentPart(dh);
SOAPElement source = operation.addChildElement("source",""),
SOAPElement percent = operation.addChildElement("percent","");
message.addAttachmentPart(attachment);
source.addAttribute(envelope.createName("href"), "cid:" + attachment.getContentId());
percent.addTextNode("20");
SOAPMessage result = connection.call(message,endPoint);

part = result.getSOAPPart();
envelope = part.getEnvelope();
body = envelope.getBody();
if(!body.hasFault()) {
Iterator iterator = result.getAttachments();
if(iterator.hasNext()) {
dh = ((AttachmentPart)iterator.next()).getDataHandler();
String fname = dh.getName();
if (null != fname) return new File(fname);
}
}
return null;
}
The code above will produce following SOAP 1.1 message with attachment:
POST /ws/resize HTTP/1.0

Content-Type: multipart/related; type="text/xml";
start="<EB6FC7EDE9EF4E510F641C481A9FF1F3>";
boundary="----=_Part_0_7145370.1075485514903"
Accept: application/soap+xml, multipart/related, text/*
Host: example.com:8080
SOAPAction: ""
Content-Length: 1506005
------=_Part_0_7145370.1075485514903
Content-Type: text/xml; charset=UTF-8
Content-Id: <EB6FC7EDE9EF4E510F641C481A9FF1F3>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<ps:resize xmlns:ps="http://example.com">
<source href="cid:E1A97E9D40359F85CA19D1B8A7C52AA3"/>
<percent>20</percent>
</ps:resize>
</soapenv:Body>
</soapenv:Envelope>
------=_Part_0_7145370.1075485514903
Content-Type: image/jpeg
Content-Id: <E1A97E9D40359F85CA19D1B8A7C52AA3>
d3d3Lm1hcmNoYWwuY29taesgfSEVFES45345sdvgfszd==
------=_Part_0_7145370.1075485514903--
Chapter 3. Describing and Publishing (WSDL and UDDI)
Explain the use of WSDL in Web services, including a description of WSDL's basic elements, binding
mechanisms and the basic WSDL operation types as limited by the WS-I Basic Profile 1.1.
• [WS-I_BP_1.1] Basic Profile Version 1.1
Warning
While SCDJWS 5.0 objectives specify WSDL 2.0 specification version, the exam questions are still based on the WSDL 1.1
specification.
WSDL is an XML-based language that allows formal XML desriptions of the interfaces of Web services:
• Interface information describing all publicly available functions.

• Data type information for all message requests and message responses.
• Binding information about the transport protocol to be used.
• Address information for locating the specified service.
WSDL benefits:
• It is an interface description is a contract between the server developers and the client developers (like Java interface represents
a contract between client code and the actual Java object).
• It has formal descriptions which allows tool support, e.g. code template generators, integrate new services with little or no
manual code.
WSDL language can be described as having two layers:
1. The service definition layer describes abstract properties:

• data types
• message types
• operations
• services
2. The binding layer describes concrete properties:
• protocols
• data formats
The definitions element MUST be the root element of all WSDL documents. It defines the name of the web service, declares
definitions of
multiple namespaces used throughout the remainder of the document. An actual WSDL document consists of a set of
the following kinds:
• types - Contains XML Schema element and type definitions. The types element describes all the data types used between
the client and server. WSDL is not tied exclusively to a specific typing system, but it uses the W3C XML Schema specification as
its default choice. If the service uses only XML Schema built-in simple types, such as strings and integers, the types element
is not required.
The types element encloses data type definitions that are relevant for the exchanged messages. For maximum
interoperability and platform neutrality, WSDL prefers the use of XSD as the canonical type system, and treats it as the intrinsic
type system.
<definitions .... >

<types>
<xsd:schema .... />*
</types>
</definitions>
The XSD type system can be used to define the types in a message regardless of whether or not the resulting wire format is
actually XML, or whether the resulting XSD schema validates the particular wire format. This is especially interesting if there will
be multiple bindings for the same message, or if there is only one binding but that binding type does not already have a type
system in widespread use.
WS-I BP 1.1: A DESCRIPTION MUST NOT use QName references to WSDL components in namespaces that have been neither
imported, nor defined in the referring WSDL document.
WS-I BP 1.1: A QName reference to a Schema component in a DESCRIPTION MUST use the namespace defined in
the targetNamespace attribute on the xsd:schema element, or to a namespace defined in
the namespace attribute on an xsd:import element within the xsd:schema element.
xsd:schema elements contained in a wsdl:types element of a DESCRIPTION MUST have

WS-I BP 1.1: All
a targetNamespace attribute with a valid and non-null value, UNLESS the xsd:schema element
has xsd:import and/or xsd:annotation as its only child element(s).
WS-I BP 1.1: In a DESCRIPTION, declarations MUST NOT extend or restrict the soapenc:Array type.
WS-I BP 1.1: In a DESCRIPTION, declarations MUST NOT use wsdl:arrayType attribute in the type declaration.
WS-I BP 1.1: In a DESCRIPTION, elements SHOULD NOT be named using the convention ArrayOfXXX.
WS-I BP 1.1: An ENVELOPE MUST NOT include the soapenc:arrayType attribute.
CORRECT:

<xsd:complexType name="MyArray1Type">
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
<MyArray1>
<x>abcd</x>
<x>efgh</x>
</MyArray1>
INCORRECT (uses soapenc:arrayType attribute and soapenc:Array type):

<xsd:complexType name="MyArray2Type"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" >
<xsd:complexContent>
<xsd:restriction base="soapenc:Array">
<xsd:sequence>
</xsd:sequence>
<xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="tns:MyArray2Type[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<MyArray2 soapenc:arrayType="tns:MyArray2Type[]" >

<x>abcd</x>
<x>efgh</x>
</MyArray2>
• message - Consists of either a number of named parts typed by XML Schema elements, or a single part typed by a
XML Schema type. The messageelement describes a one-way message, whether it is a single message request or a single
message response. It defines the name of the message and contains zero or more message part elements, which can refer to
message parameters or message return values.
• portType - describing a set of operations, each being either:
o one-way: The endpoint receives an input message. (NOTE: The WS-I BP 1.1 restricts the
valid wsdl:operations to one-way and request-response operations):
Solicit-Response and Notification type operations in

A DESCRIPTION MUST NOT use
a wsdl:portType definition.
<wsdl:definitions .... >

<wsdl:portType .... > *
<wsdl:operation name="nmtoken">
<wsdl:input name="nmtoken"? message="qname"/>
</wsdl:operation>
</wsdl:portType >
</wsdl:definitions>
o request-response: The endpoint receives an input message and then responds with an output message (like
wsdl:operations to one-way
RPC - Remote Procedure Call). (NOTE: The WS-I BP 1.1 restricts the valid
and request-response operations).
o
o <wsdl:definitions .... >
o <wsdl:portType .... > *
o <wsdl:operation name="nmtoken" parameterOrder="nmtokens">
o <wsdl:input name="nmtoken"? message="qname"/>
o <wsdl:output name="nmtoken"? message="qname"/>
o <wsdl:fault name="nmtoken" message="qname"/>*
o </wsdl:operation>
o </wsdl:portType >
o </wsdl:definitions>
o
o output message and then receives an input message (NOTE: A

solicit-response: The endpoint sends an
DESCRIPTION MUST NOT use Solicit-Response and Notification type operations in
a wsdl:portType definition - R2303 - BP 1.1).
o
o <wsdl:input name="nmtoken"? message="qname"/>
o <wsdl:fault name="nmtoken" message="qname"/>*
o </wsdl:operation>
o </wsdl:portType >
o
o output message (NOTE: A DESCRIPTION MUST NOT use Solicit-

notification: The endpoint sends an
Response and Notification type operations in a wsdl:portType definition - R2303 - BP
1.1).
o
o </wsdl:operation>
o </wsdl:portType >
o
• The portType element combines multiple message elements to form a complete one-way or round-trip operation. For
example, aportType can combine one request and one response message into a single request/response operation, most
commonly used in SOAP services. Note that a portType can (and frequently does) define multiple operations.
• binding - Selects communication protocol and data formats for each operation and message.
The binding element describes the concrete specifics of how the service will be implemented on the wire. WSDL includes
built-in extensions for defining SOAP services, and SOAP-specific information therefore goes here.
NOTE: For interoperability the WS-I BP 1.1 requires that all messages must be sent using the SOAP 1.1 protocol over an HTTP
transport:
WS-I BP 1.1: A wsdl:binding element in a DESCRIPTION MUST use WSDL SOAP Binding as defined in WSDL 1.1
Section 3.
wsdl:binding element in a DESCRIPTION MUST specify the HTTP transport protocol with SOAP binding.
WS-I BP 1.1: A
transportattribute of its soapbind:binding child MUST have the
Specifically, the
value "http://schemas.xmlsoap.org/soap/http".
The SOAP messages must be in either "document-literal" or "rpc-literal" form:
WS-I BP 1.1: A wsdl:binding in a DESCRIPTION MUST either be a rpc- literal binding or a document-literal binding.
wsdl:binding and its wsdl:portType have the same list

The WS-I BP 1.1 requires that a
of wsdl:operations. A perfect matching between the two lists is established through a 1-1 and onto relation from
the wsdl:binding to the wsdl:portType. The wsdl:binding should completely bind all operations
within a wsdl:portType:
wsdl:binding in a DESCRIPTION MUST have the same set of wsdl:operations as

WS-I BP 1.1: A
the wsdl:portType to which it refers.
• service - Describes a collection of named ports, each associated with a binding and a network address.
service
The element defines the address for invoking the specified service. Most commonly, this includes a URL for invoking
the SOAP service.
The simplified structure of a WSDL document is:
<definitions> 
<types>

</types>
<message>

</message>
<portType>

</portType>
<binding>

</binding>
<service>

</service>
</definitions>
WSDL document grammar:
<wsdl:definitions name="nmtoken"? targetNamespace="uri"?>
<import namespace="uri" location="uri"/>*
<wsdl:documentation .... /> ?
<wsdl:types> ?
<wsdl:documentation .... />?
<xsd:schema .... />*
<-- extensibility element --> *
</wsdl:types>
<wsdl:message name="nmtoken"> *
<part name="nmtoken" element="qname"? type="qname"?/> *
</wsdl:message>
<wsdl:portType name="nmtoken">*
<wsdl:operation name="nmtoken">*
<wsdl:input name="nmtoken"? message="qname">?
</wsdl:input>
<wsdl:output name="nmtoken"? message="qname">?
</wsdl:output>
<wsdl:fault name="nmtoken" message="qname"> *
</wsdl:fault>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="nmtoken" type="qname">*

<wsdl:operation name="nmtoken">*
<wsdl:input> ?
<-- extensibility element -->
</wsdl:input>
<wsdl:output> ?
</wsdl:output>
<wsdl:fault name="nmtoken"> *
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="nmtoken"> *
<wsdl:port name="nmtoken" binding="qname"> *
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Example of simple WSDL (SOAP 1.1 Request-Response via HTTP):
targetNamespace="http://example.com/stockquote.wsdl"
xmlns:tns="http://example.com/stockquote.wsdl"
xmlns:xsd1="http://example.com/stockquote.xsd"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
<types>
<schema targetNamespace="http://example.com/stockquote.xsd"
xmlns="http://www.w3.org/2000/10/XMLSchema">
<element name="TradePriceRequest">
<complexType>
<all>
<element name="tickerSymbol" type="string"/>
</all>
</complexType>
</element>
<element name="TradePrice">
<complexType>
<all>
<element name="price" type="float"/>
</all>
</complexType>
</element>
</schema>
</types>
</message>
<message name="GetLastTradePriceOutput">
<part name="body" element="xsd1:TradePrice"/>
</message>
<portType name="StockQuotePortType">
<operation name="GetLastTradePrice">
<input message="tns:GetLastTradePriceInput"/>
<output message="tns:GetLastTradePriceOutput"/>
</operation>
</portType>
<binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">

<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="GetLastTradePrice">
<soap:operation soapAction="http://example.com/GetLastTradePrice"/>
<input>
<soap:body use="literal"/>
</input>
<output>
</output>
</operation>
</binding>
<documentation>My first service</documentation>
<port name="StockQuotePort" binding="tns:StockQuoteBinding">
<soap:address location="http://example.com/stockquote"/>
</port>
</service>
</definitions>
Describe how WSDL enables one to separate the description of the abstract functionality offered by a
service from concrete details of a service description such as "how" and "where" that functionality is
offered.
• [WS-I_BP_1.1] Basic Profile Version 1.1
Warning
While SCDJWS 5.0 objectives specify WSDL 2.0 specification version, the exam questions are still based on the WSDL 1.1
specification.
A WSDL document defines services as collections of network endpoints, or ports. In WSDL, the abstract definitions of endpoints and messages
are separated from their concrete network deployment or data format bindings. This separation supports the reuse of abstract definitions:
messages, which are abstract descriptions of exchanged data, and port types, which are abstract collections of operations. The concrete
protocol and data format specifications for a particular port type constitutes a reusable binding. A port is defined by associating a network
address with a reusable binding, and a collection of ports defines a service. Therefore, a WSDL document is composed of several elements.
The following is the structure of the information in a WSDL file:

A WSDL file contains the following parts:
• Web service interface definition (Abstract part)
This part contains the elements and the namespaces.
Describes the messages it sends and receives.
Describes the operation associates a message exchange pattern with one or more messages.
• Web service implementation (Concrete part)
This part contains the definition of the service and ports.
Specifies transport and wire format details for one or more interfaces.
Specifies a port (an endpoint) associates a network address with a binding.
Specifies a service which groups together endpoints that implement a common interface.
A WSDL file describes a Web Service with the following elements:
• portType
The description of the operations and associated messages (interface). The portType element defines abstract operations:
o One-way
The operation can receive a message but will not return a response.
o Request-response
The operation can receive a request and will return a response.
o Solicit-response
The operation can send a request and will wait for a response.
o Notification
The operation can send a message but will not wait for a response.
<portType name="procurementPortType">
<operation name="orderGoods">
<input message = "OrderMsg"/>
</operation>
</portType>
• message
The description of input and output parameters and return values.

<message name="OrderMsg">
<part name="productName" type="xs:string"/>
<part name="quantity" type="xs:integer"/>
</message>
• types
The schema for describing XML types used in the messages.
• binding
The bindings describe the protocol that is used to access a portType, as well as the data formats for the messages that are
portType element.
defined by a particular
binding attributes are:
o name any name

o type - points to the port type defined in the abstract part
soap:binding attributes are:
o style - "rpc" | "document"

o transport - Communication protocol : SOAP, Transport protocol : HTTP/SMTP
operation element:
o defines each operation that the port exposes.

o must also specify how the input and output are encoded : literal | encoded
<binding name="ProcurementSoapBinding" type="tns:procurementPortType">

<operation name="orderGoods">
<soap:operation soapAction="http://example.com/orderGoods"/>
<input>
</input>
<output>
</output>
</operation>
</binding>
• service
The services and ports define the location of the Web Service.
The service contains the Web Service name and a list of ports.
<service name="ProcurementService">
<port name="ProcurementPort" binding="tns:ProcurementSoapBinding">
<soap:address location="http://example.com/procurement"/>
</port>
</service>
• port
The port contain the location of the Web Service and the binding used for service access.
<port name="ProcurementPort" binding="tns:ProcurementSoapBinding">

<soap:address location="http://example.com/procurement"/>
</port>
Describe the Component Model of WSDL including Descriptions, Interfaces, Bindings, Services and
Endpoints.
• [NONE] blah
WSDL 2.0 Conceptual Model
The description of a web service can be modeled in two parts. In the abstract part, WSDL describes a web service in terms of messages it
sends and receives through a type system, typically W3C XML Schema. Message exchange patterns define the sequence and cardinality of
messages. An operation associates message exchange patterns with one or more messages. An interface groups these
operations in a transport and wire independent manner.
In the concrete part of the description, bindings specify the transport and wire format for interfaces. A
service endpoint service groups the endpoints that implement a common
associates network address with a binding. Finally, a
interface. Figure below shows the conceptual WSDL component model:
Description
This component serves as the root container for other components, most notably interfaces, bindings, and services. Abstract and concrete
components are distinctly identified and separated. The service interfaces compose the abstract elements of the document with their
respective messages and operations. The binding, service, and endpoints compose the concrete elements of the document.
Interface
This component serves as a container for operations, which in turn serves as a container for messages. The importance of this feature arises
from the inclusion of Message Exchange Patterns (MEPs), since an operation can consist of more than simple request and response messages.
One of the most discussed features of WSDL 2.0 in the industry is the ability for interfaces to extend one another. This inclusion as a feature,
along with the ability to include and import WSDL, certainly makes the job of tool developers more difficult. Yet interface inheritance should
increase the reusability of interfaces across an organization.
An interface element encloses a named set of abstract operations and the abstract messages. It can optionally extend one or more
QName
other interfaces. Interfaces are referred to by operation
in other components such as bindings. The interface element has
name and pattern as required attributes, while style is an optional attribute. Features defines functionalities associated with the message
exchanges between communicating parties, which might include reliability, security, correlation, and routing. Property is used to control the
behavior of a feature. It has a set of possible and permissible values specified by references to a schema description. These values can be
shared among features.
Binding
This component represents the detailed information required to access an endpoint. The binding provides the glue the makes the whole
system work and provides mechanisms for defining concrete formats for faults and messages and protocol interactions for interface
operations.
The binding element defines the underlying transport and wire format for messages. Each binding in the WSDL references to
an interface . All operations defined within the interface must be bound in the binding. An endpoint in the service component
references a binding. Both endpoints and bindings are modeled to support flexibility and location transparency. Multiple endpoints with
different network address can still share the same protocol binding. WSDL 2.0 Bindings specification defines binding extensions for protocols
and message formats such as SOAP, HTTP and MIME.
Service
This component represents the collection of endpoints where the service may be invoked.
Initial thoughts may envision that the Service component contains the bulk of the specification. However, it mainly serves to tie the service
interface to one or many endpoints implementing that interface.
A service element describes a set of endpoints which refer to a single network address for a binding. All other protocol specific
QName. service element has
information is contained in the binding. Service can be referred by
a name and interface which are required attributes.
Endpoint
This component represents a collection of information for a given service implementation. The endpoint ties a specific binding to the specific
address so the service can be invoked.
Describe the basic functions provided by the UDDI Publish and Inquiry APIs to interact with a UDDI
business registry.
Two types of UDDI APIs are defined. A publisher's API is provided for interactions between programs and the UDDI registry for the purpose of
storing or changing data in the registry. An inquiry API is provided for programs that want to access the registry to read information from the
registry.
Authenticated access is required to use the publishers API. Each Operator Site is responsible for selecting and implementing an authentication
protocol that is compatible with the publishers API, as well as providing a new user sign-up mechanism. Before using any of the publisher API
functions, the caller is responsible for signing up with one or more Operator Sites or compatible registries and establishing user credentials.
The Inquiry and Publishers API functions are exposed as SOAP messages over HTTP. HTTPS (specifically SSL 3.0) is used for all publisher API
calls in order to assure wire privacy. No authentication is required to make use of the Inquiry API functions.
SOAP is a method for using Extensible Markup Language (XML) in message and remote procedure call (RPC) based protocols. SOAP has been
jointly defined and submitted to the World Wide Web consortium (W3C) as a note.
UDDI uses SOAP in conjunction with HTTP to provide a simple mechanism for passing XML messages to Operator Sites using a standard
HTTP-POST protocol. Unless specified, all responses will be returned in the normal HTTP response document.
The general structure of a UDDI SOAP message:
POST /someVerbHere HTTP/1.1

Host: www.someoperator.org
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: ""

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<xxx_xxx_xxx generic="2.0" xmlns="urn:uddi-org:api_v2">
...
</xxx_xxx_xxx>
</Body>
</Envelope>
Inquiry API functions
The messages in this section represent inquiries that anyone can make of any UDDI Operator Site at any time. These messages all behave
synchronously and are required to be exposed via HTTP-POST only. Other synchronous or asynchronous mechanisms may be provided at the
discretion of the individual UDDI Operator Site or UDDI compatible registry.
The publicly accessible queries are:

• find_binding: Used to locate specific bindings within a registered businessService. Returns
abindingDetail message.
• find_business: Used to locate information about one or more businesses. Returns a businessList message.
• find_relatedBusinesses: Used to locate information about businessEntity registrations that are
related to a specific business entity whose key is passed in the inquiry. The Related Businesses feature is used to manage
registration of business units and subsequently relate them based on organizational hierarchies or business partner relationships.
Returns a relatedBusinessesList message.
• find_service: Used to locate specific services within a registered businessEntity. Returns
a serviceList message.
• find_tModel: Used to locate one or more tModel information structures. Returns a tModelList structure.
• get_bindingDetail: Used to get full bindingTemplate information suitable for making one or more
service requests. Returns a bindingDetailmessage.
• get_businessDetail: Used to get the full businessEntity information for one or more businesses or
organizations. Returns a businessDetailmessage.
• get_businessDetailExt: Used to get extended businessEntity information. Returns

a businessDetailExt message.
• get_serviceDetail: Used to get full details for a given set of registered businessService data.
Returns a serviceDetail message.
• get_tModelDetail: Used to get full details for a given set of registered tModel data. Returns
a tModelDetail message.
Publish API functions
The messages in this section represent commands that require authenticated access to an UDDI Operator Site, and are used to publish and
update information contained in a UDDI compatible registry. Each business should initially select one Operator Site to host their information.
Once chosen, information can only be updated at the site originally selected. UDDI provides no automated means to reconcile multiple or
duplicate registrations.
The messages defined in this section all behave synchronously and are callable via HTTP-POST only. HTTPS is used exclusively for all of the
calls defined in this publisher's API. The publishing API calls defined that UDDI operators support are:
• add_publisherAssertions: Used to add relationship assertions to the existing set of assertions.

• delete_binding: Used to remove an existing bindingTemplate from
the bindingTemplates collection that is part of a specified businessServicestructure.
• delete_business: Used to delete registered businessEntity information from the registry.

• delete_publisherAssertions: Used to delete specific publisher assertions from the assertion collection
controlled by a particular publisher account. Deleting assertions from the assertion collection will affect the visibility of business
relationships. Deleting an assertion will cause any relationships based on that assertion to be invalidated.
• delete_service: Used to delete an existing businessService from
the businessServices collection that is part of a specified businessEntity.
• delete_tModel: Used to hide registered information about a tModel. Any tModel hidden in this way is still
usable for reference purposes and accessible via the get_tModelDetail message, but is simply hidden
from find_tModel result sets. There is no way to actually cause a tModel to be deleted, except by administrative
petition.
• discard_authToken: Used to inform an Operator Site that a previously provided authentication token is no longer
authToken value is
valid and should be considered invalid if used after this message is received and until such time as an
recycled or reactivated at an operator's discretion. Seeget_authToken.
• get_assertionStatusReport: Used to get a status report containing publisher assertions and status
information. This report is useful to help an administrator manage active and tentative publisher assertions. Publisher assertions
are used in UDDI to manage publicly visible relationships between businessEntity structures. Relationships are a
feature introduced in generic 2.0 that help manage complex business structures that require more than
one businessEntity or more than one publisher account to manage parts of a businessEntity. Returns
an assertionStatusReport that includes the status of all assertions made involving
any businessEntity controlled by the requesting publisher account.
• get_authToken: Used to request an authentication token from an Operator Site. Authentication tokens are required
when using all other API's defined in the publishers API. This function serves as the program's equivalent of a login request.
• get_publisherAssertions: Used to get a list of active publisher assertions that are controlled by an individual
publisherAssertions
publisher account. Returns a message containing all publisher assertions associated with a
specific publisher account. Publisher assertions are used to control publicly visible business relationships.
• get_registeredInfo: Used to request an abbreviated synopsis of all information currently managed by a given
individual.
• save_binding: Used to register new bindingTemplate information or update
bindingTemplate information. Use this to control information about technical capabilities exposed by a
existing
registered business.
• save_business: Used to register new businessEntity information or update
existing businessEntity information. Use this to control the overall information about the entire business. Of
the save_xx API's this one has the broadest effect. In UDDI V2, a feature is introduced where save_businesscan
be used to reference a businessService that is parented by another businessEntity.
• save_service: Used to register or update complete information about a businessService exposed by a

specified businessEntity.
• save_tModel: Used to register or update complete information about a tModel.

• set_publisherAssertions: used to save the complete set of publisher assertions for an individual publisher
account. Replaces any existing assertions, and causes any old assertions that are not reasserted to be removed from the registry.
Publisher assertions are used to control publicly visible business relationships.
Chapter 4. JAX-WS
Explain JAX-WS technology for building web services and client that communicate using XML.
• [NONE] blah
Java API for XML-Based Web Services (JAX-WS) is the next generation Web services programming model complimenting the foundation
provided by the Java API for XML-based RPC (JAX-RPC) programming model. Using JAX-WS, development of Web services and clients is
simplified with more platform independence for Java applications by the use of dynamic proxies and Java annotations.
JAX-WS is a programming model that simplifies application development through support of a standard, annotation-based model to develop
Web Service applications and clients. The JAX-WS technology strategically aligns itself with the current industry trend towards a more
document-centric messaging model and replaces the remote procedure call programming model as defined by JAX-RPC. JAX-RPC has
limitations and does not support various complex document-centric services. JAX-WS is the strategic programming model for developing Web
services and is a required part of the Java Platform, Enterprise Edition 5 (Java EE 5). JAX-WS is also known as JSR 224.
The implementation of the JAX-WS programming standard provides the following enhancements for developing Web services and clients:
• Better platform independence for Java applications
Using JAX-WS APIs, development of Web services and clients is simplified with better platform independence for Java applications.
JAX-WS takes advantage of the dynamic proxy mechanism to provide a formal delegation model with a pluggable provider. This is
an enhancement over JAX-RPC, which relies on the generation of vendor-specific stubs for invocation.
• Annotations
JAX-WS introduces support for annotating Java classes with metadata to indicate that the Java class is a Web service. JAX-WS
supports the use of annotations based on the Metadata Facility for the Java Programming Language (JSR 175) specification, the
Web Services Metadata for the Java Platform (JSR 181) specification and annotations defined by the JAX-WS 2.1 specification.
Using annotations within the Java source and within the Java class simplifies development of Web services. Use annotations to
define information that is typically specified in deployment descriptor files, WSDL files, or mapping metadata from XML and WSDL
files into the source artifacts.
For example, you can embed a simple @WebService tag in the Java source to expose the bean as a Web service:
@WebService
public class QuoteBean implements StockQuote {
public float getQuote(String sym) {
...
}
}
The @WebService annotation tells the server runtime environment to expose all public methods on that bean as a Web
service. Additional levels of granularity can be controlled by adding additional annotations on individual methods or parameters.
Using annotations makes it much easier to expose Java artifacts as Web services. In addition, as artifacts are created from using
some of the top-down mapping tools starting from a WSDL file, annotations are included within the source and Java classes as a
way of capturing the metadata along with the source files.
Using annotations also improves the development of Web services within a team structure because you do not need to define
every Web service in a single or common deployment descriptor as required with JAX-RPC Web services. Taking advantage of
annotations with JAX-WS Web services enables parallel development of the service and the required metadata.
For JAX-WS Web services, the use of the webservices.xml deployment descriptor is optional because you can use
annotations to specify all of the information that is contained within the deployment descriptor file. You can use the deployment
descriptor file to augment or override existing JAX-WS annotations. Any information that you define in
the webservices.xml deployment descriptor overrides any corresponding information that is specified by annotations.
For example, if your service implementation class for your JAX-WS Web service includes the following:
o the @WebService annotation:

o @WebService(wsdlLocation="http://myhost.com/ExampleService.wsdl")
o the webservices.xml file specifies a different file name for the WSDL document as follows:
o
o <webservices>
o <webservice-description>
o <webservice-description-name>ExampleService</webservice-description-name>
o <wsdl-file>META-INF/wsdl/ExampleService.wsdl</wsdl-file>
o ....
o </webservice-description>
o </webservices>
o
META-
In this case, the value that is specified in the deployment descriptor,
INF/wsdl/ExampleService.wsdl overrides the annotation value.
• Invoking Web services asynchronously
With JAX-WS, Web services are called both synchronously and asynchronously. JAX-WS adds support for both a polling and
callback mechanism when calling Web services asynchronously. Using a polling model, a client can issue a request, get a response
object back, which is polled to determine if the server has responded. When the server responds, the actual response is retrieved.
Using the callback model, the client provides a callback handler to accept and process the inbound response object. Both the
polling and callback models enable the client to focus on continuing to process work without waiting for a response to return,
while providing for a more dynamic and efficient model to invoke Web services.
For example, a Web service interface might have methods for both synchronous and asynchronous requests. Asynchronous
requests are identified in the following example:
@WebService
public interface CreditRatingService {
// sync operation
Score getCreditScore(Customer customer);
// async operation with polling

Response<Score> getCreditScoreAsync(Customer customer);
// async operation with callback
Future<?> getCreditScoreAsync(Customer customer, AsyncHandler<Score> handler);
The asynchronous invocation that uses the callback mechanism requires an additional input by the client programmer. The
callback is an object that contains the application code that is run when an asynchronous response is received. Use the following
code example to invoke an asynchronous callback handler:
CreditRatingService svc = ...;
Future<?> invocation = svc.getCreditScoreAsync(customer,

new AsyncHandler<Score>() {
public void handleResponse (Response<Score> response) {
Score score = response.get();
// do work here...
}
}
);
Use the following code example to invoke an asynchronous polling client:
CreditRatingService svc = ...;
Response<Score> response = svc.getCreditScoreAsync(customer);
while (!response.isDone()) {
// Complete an action while we wait.
}
// No cast needed, because of generics.

Score score = response.get();
• Using resource injection
JAX-WS supports resource injection to further simplify development of Web services. JAX-WS uses this key feature of Java EE 5 to
shift the burden of creating and initializing common resources in a Java runtime environment from your Web service application to
the application container environment, itself. JAX-WS provides support for a subset of annotations that are defined in JSR-250 for
resource injection and application life cycle in its runtime environment.
The application server also supports the usage of the@Resource or@WebServiceRef annotation to declare JAX-
WS managed clients and to request injection of JAX-WS services and ports. When either of these annotations are used on a field
or method, they result in injection of a JAX-WS service or port instance. The usage of these annotations also results in the type
specified by the annotation being bound into the JNDI namespace.
The @Resource annotation is defined by the JSR-250, Common Annotations specification that is included in Java Platform,
@Resource annotation on a variable of
Enterprise Edition 5 (Java EE 5). By placing the
type javax.xml.ws.WebServiceContext within a service endpoint implementation class, you can request
a resource injection and collect the javax.xml.ws.WebServiceContext interface related to that particular
endpoint invocation. From theWebServiceContext interface, you can collect the MessageContext for the
request associated with the particular method call using thegetMessageContext() method.
The @WebServiceRef annotation is defined by the JAX-WS specification.
The following example illustrates using the @Resource and @WebServiceRef annotations for resource injection:
@WebService
public class MyService {
@Resource
private WebServiceContext ctx;
@Resource
private SampleService svc;
@WebServiceRef
private SamplePort port;
public String echo (String input) {

...
}
}
• Data binding with JAXB 2.1
JAX-WS leverages the Java Architecture for XML Binding (JAXB) 2.1 API and tools as the binding technology for mappings
between Java objects and XML documents. JAX-WS tooling relies on JAXB tooling for default data binding for two-way mappings
between Java objects and XML documents. JAXB data binding replaces the data binding described by the JAX-RPC specification.
The JAXB 2.1 specification provides enhancements such as improved compilation support and introduces support for
the @XMLSeeAlso annotation. With the improved compilation support, you now have the flexibility to control the whether
schemagen
a new schema file is generated when using the xjc schema
schema generator and you can configure the
compiler so that it does not automatically generate new classes for a particular schema. You can use
the @XMLSeeAlso annotation to ensure that JAXB is aware of all the classes included in an inheritance hierarchy for a
service endpoint interface.
• Dynamic and static clients
The dynamic client API for JAX-WS is called the dispatch client (javax.xml.ws.Dispatch). The dispatch client is
an XML messaging oriented client. The data is sent in either PAYLOAD or MESSAGE mode.
PAYLOAD mode, the dispatch client is only responsible for providing the contents of
When using the
the soap:Body and JAX-WS adds the soap:Envelopeand soap:Header elements.
MESSAGE mode, the dispatch client is responsible for providing the entire SOAP envelope including
When using the
the soap:Envelope, soap:Header, and soap:Body elements. JAX-WS does not add anything additional
to the message.
The dispatch client supports asynchronous invocations using a callback or polling mechanism.
The static client programming model for JAX-WS is the called the proxy client. The proxy client invokes a Web service based on a
Service Endpoint interface (SEI), which must be provided.
• Support for MTOM
Using JAX-WS, you can send binary attachments such as images or files along with Web services requests. JAX-WS adds support
for optimized transmission of binary data as specified by Message Transmission Optimization Mechanism (MTOM).
• Multiple data binding technologies
JAX-WS exposes the following binding technologies to the end user: XML Source, SOAP Attachments API for Java (SAAJ) 1.3, and
Java Architecture for XML Binding (JAXB) 2.1.
javax.xml.transform.Source into the runtime environment which

XML Source enables a user to pass a
represents the data in a Source object to be processed.
SAAJ 1.3 now has the ability to pass an entire SOAP document across the interface rather than just the payload itself. This action
is done by the client passing the SAAJ SOAPMessage object across the interface.
JAX-WS leverages the JAXB 2.1 support as the data binding technology of choice between Java and XML.
• Support for SOAP 1.2
Support for SOAP 1.2 has been added to JAX-WS 2.0.
JAX-WS supports both SOAP 1.1 and SOAP 1.2 so that you can send binary attachments such as images or files along with Web
services requests. JAX-WS adds support for optimized transmission of binary data as specified by MTOM.
• Development tools
JAX-WS provides the wsgen and wsimport command-line tools for generating portable artifacts for JAX-WS Web
services. When creating JAX-WS Web services, you can start with either a WSDL file or an implementation bean class.
If you start with an implementation bean class, use the wsgen command-line tool to generate all the Web services server
artifacts, including a WSDL file if requested.
If you start with a WSDL file, use thewsimport command-line tool to generate all the Web services artifacts for either the
server or the client. The wsimport command-line tool processes the WSDL file with schema definitions to generate the portable
artifacts, which include the service class, the service endpoint interface class, and the JAXB 2.1 classes for the corresponding XML
schema.
• Support for WS-Addressing (JAX-WS 2.1)
JAX-WS 2.1 integrates support for the WS-Addressing standard in to the API. The new API enables you to create, transmit and
use endpoint references to target a specific Web service endpoint. You can also explicitly specify the action URIs associated with
the Web Services Description Language (WSDL) operations of your Web service.
• Support for JAX-WS 2.1 features
JAX-WS 2.1 introduces the concept of features as a way to programmatically control certain functions or behaviors. There are
AddressingFeature, the MTOMFeature, and
three standard features: the
the RespectBindingFeature.
The AddressingFeature is used to enable or disable support for the WS-Addressing Version 1.0 specification.
The MTOMFeature is used to enable or disable support for Message Transmission Optimized Mechanism (MTOM) when sending
binary attachments.
The RespectBindingFeature is used to enable or disable support for wsdl:binding extensions. The application server
supports an additional feature, the SubmissionAddressingFeature, which is used to enable or disable support for WS-Addressing
Member Submission specification (prior to the WS-Addressing Version 1.0 level of specification).
Describe the Integrated Stack (I-Stack) which consist of JAX-WS, JAXB, StAX, SAAJ.
JAX-WS
JAX-WS stands for Java API for XML Web Services. JAX-WS is a technology for building web services and clients that communicate using XML.
JAX-WS allows developers to write message-oriented as well as RPC-oriented web services.
In JAX-WS, a web service operation invocation is represented by an XML-based protocol such as SOAP. The SOAP specification defines the
envelope structure, encoding rules, and conventions for representing web service invocations and responses. These calls and responses are
transmitted as SOAP messages (XML files) over HTTP.
Although SOAP messages are complex, the JAX-WS API hides this complexity from the application developer. On the server side, the
developer specifies the web service operations by defining methods in an interface written in the Java programming language. The developer
also codes one or more classes that implement those methods. Client programs are also easy to code. A client creates a proxy (a local object
representing the service) and then simply invokes methods on the proxy. With JAX-WS, the developer does not generate or parse SOAP
messages. It is the JAX-WS runtime system that converts the API calls and responses to and from SOAP messages.
With JAX-WS, clients and web services have a big advantage: the platform independence of the Java programming language. In addition,
JAX-WS is not restrictive: a JAX-WS client can access a web service that is not running on the Java platform, and vice versa. This flexibility is
possible because JAX-WS uses technologies defined by the World Wide Web Consortium (W3C): HTTP, SOAP, and the Web Service Description
Language (WSDL). WSDL specifies an XML format for describing a service as a set of endpoints operating on messages.
Describe and compare JAX-WS development approaches.

Prev Chapter 4. JAX-WS Next
Describe and compare JAX-WS development approaches.
• [JAVA_EE_5_TUTORIAL] The Java EE 5 Tutorial
Empty
Class
A Java class (not an interface) annotated with a javax.jws.WebService annotation can be used to define a Web service.
In order to allow for a separation between Web service interface and implementation, if the WebService annotation on the
class under consideration has aendpointInterface element, then the interface referred by this element is for all purposes the
SEI associated with the class.
Otherwise, the class implicitly defines a service endpoint interface (SEI) which comprises all of the public methods that satisfy
one of the following conditions:
1. They are annotated with the javax.jws.WebMethod annotation with the exclude element set to false or missing
(since false is the default for this annotation element).
2. They are NOT annotated with the javax.jws.WebMethod annotation but their declaring class has
a javax.jws.WebService annotation.
For mapping purposes, this implicit SEI and its methods are considered to be annotated with the same Web service-related
annotations that the original class and its methods have.
In pratice, in order to exclude a public method of a class annotated with WebService and not directly specifying
a endpointInterface from the implicitly defined SEI, it is necessary to annotate the method with a WebMethod annotation with
the exclude element set to true.
For mapping purposes, this class must be a top level class or a static inner class. As defined by JSR 181, a class annotated
with javax.jws.WebService MUST HAVE a default public constructor.
Interface
A Java service endpoint interface (SEI) is mapped to a wsdl:portType element. The wsdl:portType element acts as a container
for other WSDL elements that together form the WSDL description of the methods in the corresponding Java SEI. An SEI is a
Java interface that meets all of the following criteria:
1. It MUST carry a javax.jws.WebService annotation

2. Any of its methods MAY carry a javax.jws.WebMethod annotation
3. javax.jws.WebMethod if used, MUST NOT have the exclude element set to true.
4. All method parameters and return types are compatible with the JAXB 2.0 Java to XML Schema mapping definition
Method
Each public method in a Java SEI is mapped to a wsdl:operation element in the corresponding wsdl:portType plus one or
more wsdl:message elements.
Comparing JAX-WS and JAX-RPC SEI mapping
WSDL for a simple HelloWorld Web service:

<wsdl:definitions xmlns:tns="urn:helloWorld/sample/ibm/com" ...>
<wsdl:types>
<xsd:schema ...>
<xsd:element name="hello">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" nillable="true" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="helloResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="response" nillable="true" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</wsdl:types>
<wsdl:message name="helloRequestMsg">
<wsdl:part element="tns:hello" name="helloParameters" />
</wsdl:message>
<wsdl:message name="helloResponseMsg">
<wsdl:part element="tns:helloResponse" name="helloResult" />
</wsdl:message>
<wsdl:portType name="HelloWorld">
<wsdl:operation name="hello">
<wsdl:input message="tns:helloRequestMsg" name="helloRequest" />
<wsdl:output message="tns:helloResponseMsg" name="helloResponse" />
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="HelloWorldBinding" type="tns:HelloWorld">

<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="hello">
<soap:operation soapAction="urn:helloWorld/sample/ibm/com/hello" />
<wsdl:input name="helloRequest">
<soap:body use="literal" />
</wsdl:input>
<wsdl:output name="helloResponse">
<soap:body use="literal" />
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="HelloWorldService">
<wsdl:port name="port" binding="tns:HelloWorldBinding">
<soap:address location="http://server.org/" />
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
JAX-RPC HelloWorld SEI:
package com.ibm.samples;
public interface HelloWorld extends java.rmi.Remote {

...
}
JAX-WS HelloWorld SEI:
package com.ibm.samples.helloworld;
import javax.jws.WebService;
@WebService(name = "HelloWorld", targetNamespace = "urn:samples.ibm.com/HelloWorld")

public interface HelloWorld {
...
}
There are three differences here:
• Package: The target namespace is "urn:helloWorld/sample/ibm/com". Both mappings take the domain name-like
string and reverse the order of the elements. JAX-RPC's mapping stops at the first slash. JAX-WS's mapping
continues with the string, adding the information after the first slash. Both specifications allow for custom
namespace-to-package mappings.
• Annotations: JAX-WS requires that all SEIs include the @WebService annotation. JAX-WS includes support for the
annotations defined in JSR-181 Web Services Metadata.
• java.rmi.Remote: The JAX-RPC SEI extends the java.rmi.Remote interface. JAX-WS no longer requires this.
Although JAX-WS provides support for Web services that have an SEI, this is not mandatory for all services. With JAX-WS, a
JavaBean can be deployed on its own as a Web service implementation, as opposed to JAX-RPC where the bean must include
an SEI. JAX-WS services deployed without an SEI are considered to have an implicit SEI.
Comparing JAX-WS and JAX-RPC operation mapping
• Exploring the document/literal wrapped pattern
JAX-RPC complete HelloWorld SEI:
package com.ibm.samples;

public java.lang.String hello(java.lang.String name) throws java.rmi.RemoteException;
}
JAX-WS complete HelloWorld SEI:
package com.ibm.samples.helloworld;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.xml.ws.RequestWrapper;
import javax.xml.ws.ResponseWrapper;
@WebService(name = "HelloWorld", targetNamespace = "urn:samples.ibm.com/HelloWorld")

@WebMethod(action = "urn:samples.ibm.com/HelloWorld/hello")
@WebResult(name = "response", targetNamespace = "")
@RequestWrapper(localName = "hello",
targetNamespace = "urn:samples.ibm.com/HelloWorld",
className = "com.ibm.samples.helloworld.Hello")
@ResponseWrapper(localName = "helloResponse",
className = "com.ibm.samples.helloworld.HelloResponse")
public String hello(
@WebParam(name = "name", targetNamespace = "")
String name
);
}
As you can see, the JAX-WS mapping again has a lot of annotations. Another difference is that the JAX-RPC method
can throwjava.rmi.RemoteException while the JAX-WS method is not defined to do so.
• Exploring document/literal pattern
Both JAX-RPC and JAX-WS support mapping operations that are document/literal, but are not wrapped. To
accomplish this with the HelloWorldsample, you would need to remove the wrapper elements that represent the
operation name.
Document/literal WSDL:
<wsdl:types>
<xsd:schema targetNamespace="urn:helloWorld/sample/ibm/com"
xmlns:tns="urn:helloWorld/sample/ibm/com" ... >
<xsd:element name="hello" type="xsd:string"/>
<xsd:element name="helloResponse" type="xsd:string"/>
</xsd:schema>
</wsdl:types>
<wsdl:part element="tns:hello" name="helloParameters" />
</wsdl:message>
<wsdl:part element="tns:helloResponse" name="helloResult" />
</wsdl:message>
The only difference is the parameter name. As with the previous case, putting the annotations aside, there is no real
difference between the JAX-RPC mapping and the JAX-WS mapping.
JAX-RPC document/literal mapping:

public java.lang.String hello(java.lang.String helloParameters) throws java.rmi.RemoteException;
}
JAX-WS document/literal mapping:
@WebService(name = "HelloWorld", targetNamespace = "urn:helloWorld/sample/ibm/com")

@SOAPBinding(parameterStyle = ParameterStyle.BARE)
@WebMethod(action = "urn:helloWorld/sample/ibm/com/hello")
@WebResult(name = "helloResponse", targetNamespace = "urn:helloWorld/sample/ibm/com",
partName = "helloResult")
@WebParam(name = "hello", targetNamespace = "urn:helloWorld/sample/ibm/com",
partName = "helloParameters")
String helloParameters
);
}
Notice that for JAX-WS, you no longer see the @RequestWrapper and @ResponseWrapper annotations. Also note
that a new annotation appears at the interface level as well, @SOAPBinding. This annotation provides information
about the parameter style. If absent, the default value for theparameterStyle attribute is wrapped.
• Exploring the RPC/literal patterns
With an RPC/literal style WSDL, the parts are defined in terms of types rather than elements. Listing below contains
the relevant WSDL differences.
RPC/literal WSDL changes:
<wsdl:types/>
<wsdl:part name="helloParameters" type="xsd:string"/>
</wsdl:message>
<wsdl:part name="helloResult" type="xsd:string"/>
</wsdl:message>
JAX-RPC RPC/literal mapping:

public java.lang.String hello(java.lang.String helloParameters) throws java.rmi.RemoteException;
}
JAX-WS RPC/Literal mapping:

@SOAPBinding(style = Style.RPC)
@WebResult(name = "helloResult", partName = "helloResult")
@WebParam(name = "helloParameters", partName = "helloParameters")
String helloParameters
);
}
Comparing this JAX-WS interface to the previous, you see that the @SOAPBinding annotation remains, but now it is
not used for the parameter style, but rather the WSDL style.
• Exploring the RPC/encoded patterns
There is no comparison for RPC/encoded style operations that can be made. JAX-WS does not support any mappings
for WSDL documents that contain an encoded representation for the data. This comes from JAX-WS's compliance
with WS-I's Basic Profile 1.1, which does not allow usage of encoded WSDL documents. There are good reasons to
build an RPC/encoded Web service, in which case you should stick with the JAX-RPC mappings, but if you want to
write interoperable Web services, you should not use RPC/encoded.
Considering other JAX-WS and JAX-RPC differences
A major difference in operation mapping for JAX-WS over JAX-RPC is the introduction of asynchronous operations. Any WSDL
operation with a two-way message flow, or one where the client expects to receive a response, can be mapped to an
asynchronous Java representation. There are two different mechanisms, asynchronous with a callback and asynchronous
polling, that require two different mappings.
JAX-WS asynchronous callback:
public Future<?> helloAsync(
String name,
@WebParam(name = "asyncHandler", targetNamespace = "")
AsyncHandler<String> asyncHandler
);
JAX-WS asynchronous polling:
public Response<String> helloAsync(
String name
);
There is no asynchronous mapping for WSDL operations in JAX-RPC, so you do not have anything to make a comparison to
here. One important note, however, is that the asynchronous mappings only apply to the client side. No such asynchronous
mappings exist for service endpoints, only for clients.
Comparing IN/OUT parameters for JAX-WS and JAX-RPC
Both JAX-RPC and JAX-WS support parameters known as IN/OUT parameters. In this scenario, both JAX-RPC and JAX-WS map
that parameter to a holder parameter, but the impact this has is different for each mapping.
A WSDL with an IN/OUT parameter:
<xsd:element name="hello">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" nillable="true" type="xsd:string" />
<xsd:element name="inout" nillable="true" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="helloResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="response" nillable="true" type="xsd:string" />
<xsd:element name="inout" nillable="true" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
JAX-RPC SEI with IN/OUT parameters:

public java.lang.String hello(
java.lang.String name,
javax.xml.rpc.holders.StringHolder inout
) throws java.rmi.RemoteException;
}
JAX-WS SEI with IN/OUT parameters:

targetNamespace = "urn:helloWorld/sample/ibm/com",
className = "helloworld.sample.ibm.com.Hello")
targetNamespace = "urn:helloWorld/sample/ibm/com",
className = "helloworld.sample.ibm.com.HelloResponse")
public void hello(
String name,
@WebParam(name = "inout", targetNamespace = "", mode = Mode.INOUT)
Holder<String> inout,
@WebParam(name = "response", targetNamespace = "", mode = Mode.OUT)
Holder<String> response
);
}
For JAX-RPC, there are a set of classes defined by the specification as holder classes for known types. These include types
like java.lang.String and other primitive types. For user defined types, JAX-RPC requires that custom holder classes be
generated that can handle the user-defined types. JAX-WS, on the other hand, makes use of the Generics feature in Java 5 to
provide a single class that can work for all types, including user-defined types.
Another interesting thing to note here is the difference in return types. Rather than keeping the return type as JAX-RPC does,
JAX-WS makes the methodvoid and makes use of the holder for what was the return value. By rule in JAX-WS, when there is
more than one parameter that can be considered an OUT parameter for an operation, the return type must be void, and all OUT
parameters are mapped to holder types.
Describe the features of JAX-WS including the usage of Java Annotations.
• [JAX-WS_2.0_RI] JAX-WS Reference Implementation Project
Java API for XML-Based Web Services (JAX-WS) relies on the use of annotations to specify metadata associated with Web services
implementations and to simplify the development of Web services. Annotations describe how a server-side service implementation is accessed
as a Web service or how a client-side Java class accesses Web services.
The JAX-WS programming standard introduces support for annotating Java classes with metadata that is used to define a service endpoint
application as a Web service and how a client can access the Web service. JAX-WS supports the use of annotations based on the Metadata
Facility for the Java Programming Language (JSR 175) specification, the Web Services Metadata for the Java Platform (JSR 181) specification
and annotations defined by the JAX-WS 2.0 and later (JSR 224) specification which includes JAXB annotations. Using annotations from the
JSR 181 standard, you can simply annotate the service implementation class or the service interface and now the application is enabled as a
Web service. Using annotations within the Java source simplifies development and deployment of Web services by defining some of the
additional information that is typically obtained from deployment descriptor files, WSDL files, or mapping metadata from XML and WSDL into
the source artifacts.
Use annotations to configure bindings, handler chains, set names of portType, service and other WSDL parameters. Annotations are used in
mapping Java to WSDL and schema, and at runtime to control how the JAX-WS runtime processes and responds to Web service invocations.
For JAX-WS Web services, the use of the webservices.xml deployment descriptor is OPTIONAL because you can use annotations
to specify all of the information that is contained within the deployment descriptor file. You can use the deployment descriptor file to augment
or override existing JAX-WS annotations. Any information that you define in the webservices.xml deployment descriptor
overrides any corresponding information that is specified by annotations.
JSR 181 (Web Services Metadata) Annotations
• javax.jws.WebService
The purpose of this annotation is to mark a endpoint implementation as implementing a web service or to mark that a service
endpoint interface as defining a web service interface. All endpoint implementation classes MUST have
a WebService annotation and must meet the requirements of section 3.3 of the JAX-WS 2.0 specification.
Table 4.1. javax.jws.WebService
Property Description Default
The name of
name the wsdl:portType The unqualified name of the Java class or interface
The XML namespace of the the WSDL and

some of the XML elements generated from The namespace mapped from the package name
targetNamespace this web service. Most of the XML containing the web service according to section 3.2
elements will be in the namespace of the JAX-WS 2.0 specification.
according to the JAXB mapping rules.
The Service name of the web The unqualified name of the Java class or interface
serviceName service: wsdl:service + "Service"
The qualified name of the service endpoint
interface. This annotation allows the
separation of interface contract from
implementation. If this property is
specified, all
other WebService properties are None – If not specified, the endpoint implementation
class is used to generate the web service contract.
endpointInterface ignored as are all other 181 annotations.
In this case, a service endpoint interface is not
Only the annotations on the service
required.
endpoint interface will be taken into
consideration. The endpoint
implementation class is not required to
implement
the endpointInterface.
portName The wsdl:portName The WebService.name + "Port"

Specifies the Web address of the WSDL

wsdlLocation document defining the Web service. The -
Web address is either relative or absolute.
Example 1:
@WebService(name="AddNumbers", targetNamespace="http://duke.example.org", name="AddNumbers")

public class AddNumbersImpl {
public int addNumbers(int number1, int number2) {

return number1 + number2;
}
}
You can notice that the AddNumbersImpl implementation class does not implement a service endpoint interface. In
JAX-WS 2.0 service endpoint interface is no longer required. If a service endpoint interfaces is desired, then
the@WebService annotation on the endpoint implementation is modified to specify the endpoint interface and the actual
@WebService annotation. The following is the
service endpoint interface must also have a
above AddNumbersImpl modified to use a service endpoint interface.
Example 2:
@WebService(endpointInterface = "com.example.AddNumbersIF")

}
}
@WebService(targetNamespace="http://duke.example.org", name="AddNumbers")
public interface AddNumbersIF {
public int addNumbers(int number1, int number2);
}
NOTE: The following rules apply for methods on classes annotated with the @WebService annotation:
o If the @WebService annotation of an implementation class references an Service Endpoint Interface (SEI), the
@WebMethod annotations.
implementation class MUST NOT have any
o ALL public methods for an SEI are considered exposed methods regardless of whether
the @WebMethod annotation is specified or not. It is incorrect to have an @WebMethod annotation on an
exclude attribute.
SEI that contains the
o For an implementation class that DOES NOT reference an SEI, if the @WebMethod annotation is specified with a
value of exclude=true, that method is NOT exposed. If the @WebMethod annotation is not specified,
all public methods are exposed including the inherited methods with the exception of methods inherited
from java.lang.Object.
• javax.jws.WebMethod
The purpose of this annotation is to expose a method as a web service operation. The method must meet all the requirements of
section 3.4 of the JAX-WS 2.0 specification.
Table 4.2. javax.jws.WebMethod
The name
operationName The name of the wsdl:operation matching this method. For operations using the mode of the
defined Java
method
bySOAPBinding.Style.DOCUMENT,SOAPBinding.Use.LITERAL,
andSOAPBinding.ParameterStyle.BARE, this name is also used for the global
XML element representing the operations body element. The namespace of this name is taken from the
value WebService.targetNamespace or its default value.
The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most
action of the XML elements will be in the namespace according to the JAXB mapping rules.
""
exclude Used to exclude a method from the WebService. false
Example:
@WebMethod(operationName="add", action="urn:addNumbers")
public int addNumbers(int number1, int number2);
}
NOTE: Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint
implementation class.
NOTE: The @WebMethod annotation is only supported on classes that are annotated with
the @WebService annotation.
• javax.jws.OneWay
The purpose of this annotation is to mark a method as a web service one-way operation. The method must meet all the
requirements of section 3.4.1 of the JSR 224 spec.
Example:
@WebService(name="CheckIn")
public interface CheckInIF {
@WebMethod
@OneWay
public void checkIn(String name);
}
• javax.jws.WebParam
This annotation is used to customize the mapping of a single parameter to a message part or element.
Table 4.3. javax.jws.WebParam
Name of the parameter.
If the operation is rpc style @WebMethod.operationName,

and @WebParam.partNamehas not been document style and the
if the operation is
parameter style is BARE. Otherwise, the default

name specified, this is name of the wsdl:partrepresenting
the parameter. is argN, where N represents the index of the
parameter in the method signature (starting
at arg0).
@WebMethod.operationName, if the
operation isdocument style and the parameter style
is BARE.
document
If the operation is style or the parameter
maps to a header, this is the local name of the XML element
representing the parameter.
A name MUST be specified if the operation

is documentstyle, the parameter style is BARE, and
OUTor INOUT.
the mode is
targetNamespace - -
Represents the direction the parameter flows for this method.

Possible values
are IN, INOUT and OUT. INOUTand OUT modes
mode can only be used with parameters that meet the requirements IN for non-holder parameters INOUT for
for a holder as classified by section 3.5 of the JAX-WS 2.0 holder parameters.
OUT andINOUT parameters can be used
specification.
by all RPC and DOCUMENTbindings.
header - FALSE
partName for the parameter

Used to specify the
partName @WebParam.name
with RPCor DOCUMENT/BARE operations.
Example 1:
@WebResult(name="return")
public int addNumbers(
@WebParam(name="num1")int number1,
@WebParam(name="num2")int number2
);
}
Example 2:
public void addNumbers(
@WebParam(name="result" mode=WebParam.Mode.OUT) Holder<Integer> result)
throws AddNumbersException;
}
• javax.jws.WebResult
This annotation is used to customize the mapping of the method return value to a WSDL part or XML element.
Table 4.4. javax.jws.WebResult

The name of the return value in the WSDL and on the

"return" for RPC
wire. For RPC bindings this is the part name of the and DOCUMENT/WRAPPED bindings.
name return value in the response message.
For DOCUMENT bindings this is the local name Method name
of the XML element representing the return value.
+ "Response for DOCUMENT/BARE bindings.
targetNamespace - -
header - FALSE
partName for the result

Used to specify the
partName @WebResult.name
with RPC orDOCUMENT/BARE operations.
Example:
);
}
• javax.jws.HandlerChain
This annotation is used to specified an externally defined handler chain.
Table 4.5. javax.jws.HandlerChain
Location of the file containing the handler chain definition. The location can be relative or absolute with in a
file classpath system. If the location is relative, it is relative to the package of the web service. If it is absolute, it is none
absolute from some path on the classpath.
name DEPRECATED: The handler chain name from within the handler chain file. ""
Example:
@WebService
@HandlerChain(file="handlers.xml")

}
}
handlers.xml:
<jws:handler-config xmlns:jws="http://java.sun.com/xml/ns/javaee">
<jws:handler-chains>
<jws:handler-chain>
<jws:handler>
<jws:handler-class>handler.common.LoggingHandler</jws:handler-class>
</jws:handler>
</jws:handler-chain>
</jws:handler-chains>
</jws:handler-config>
You can only configure the server side handler by using the @HandlerChain annotation on the Service Endpoint
Interface (SEI) or the server endpoint implementation class.
Use one of several ways to configure a client side handler. You can configure a client side handler by using
the @HandlerChain annotation on the generated service class or SEI. Additionally, you can programmatically register
HandlerResolver interface on theService, or programmatically set the handler
your own implementation of the
chain on the Binding object.
• javax.jws.soap.SOAPBinding
JSR 181 also allows you to specify a SOAPBinding annotation on a endpoint implementation or service endpoint interface.
This annotation lets the developer choose between document/literal wrapped, document/literal bare, rpc/literal and rpc/encoded
endpoints with the default being document/literal wrapped. JAX-WS 2.1 does not support rpc/encoded.
The main difference between document/literal bare and document/literal wrapped is that methods on a document/literal wrapped
endpoint can have multiple parameters bound to the body of a SOAP message, while a document/literal bare can only have one
such parameter.
The main difference between document/literal wrapped and rpc/literal is that a document/literal invocation can be fully validated
by a standard validating XML parser, while an rpc/literal invocation cannot because of the implied wrapper element around the
invocation body.
Table 4.6. javax.jws.HandlerChain
Defines the style for messages used in a web service. The value can be
style either DOCUMENT or RPC. DOCUMENT
Defines the encoding used for messages used in web service. Can only
use be LITERAL for JAX-WS 2.1 LITERAL
Determines if the method's parameters represent the entire message body or

whether the parameters are wrapped in a body element named after the operation.
parameterStyle WRAPPED or BARE. BARE can only be used
Choice of WRAPPED
with DOCUMENT style bindings.
Example:
@SOAPBinding(style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.LITERAL)
);
}
JSR 224 (JAX-WS) Annotations
• javax.xml.ws.BindingType
The BindingType annotation is used to specify the binding to use for a web service endpoint implementation class. As
well as specify additional features that may be enabled.
This annotation may be overriden programmatically or via deployment descriptors, depending on the platform in use.
Example 1: Given the web service defined, the deployed endpoint would use the SOAP1.2 over HTTP binding:
@WebService
@BindingType(value="http://www.w3.org/2003/05/soap/bindings/HTTP/")
}
}
BindingType annotation that specifies use of the SOAP1.1/HTTP binding, it

Example 2: Here is another sample use of the
AddressingFeature and the MTOMFeature and also sets the threshold feature parameter
enables both the
on the MTOMFeature:
@WebService
@BindingType(value=SOAPBinding.SOAP11HTTP_BINDING,
features={
@Feature(AddressingFeature.ID),
@Feature(value=MTOMFeature.ID,
parameters={@FeatureParameter(name=MTOMFeature.THRESHOLD, value="1000")})
}
)
public class MyWebService {
...
}
NOTE: You can use the @BindingType annotation on the JavaBeans endpoint implementation class to enable MTOM by
specifying
eitherjavax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING or javax.xm
l.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING as the value for the annotation.
• javax.xml.ws.RequestWrapper
This annotation annotates methods in the Service Endpoint Interface with the request wrapper bean to be used at runtime.
When starting from Java this annotation is used resolve overloading conflicts in document literal mode. Only
the className is required in this case.
Example:
public interface AddNumbersImpl {

@WebMethod
@WebResult(targetNamespace = "")
@RequestWrapper(localName="addNumbers",
targetNamespace="http://server.fromjava/",
className="fromjava.client.AddNumbers")
@ResponseWrapper(localName="addNumbersResponse",
className="fromjava.client.AddNumbersResponse")
@WebParam(name = "arg0", targetNamespace = "")
int arg0,
int arg1);
}
• javax.xml.ws.ResponseWrapper
This annotation annotates methods in the Service Endpoint Interface with the response wrapper bean to be used at runtime.
When starting from Java this annotation is used resolve overloading conflicts in document literal mode. Only
the className is required in this case.
Example:
public interface AddNumbersImpl {

@WebMethod
@WebResult(targetNamespace="")
@RequestWrapper(localName="addNumbers",
className="fromjava.client.AddNumbers")
@ResponseWrapper(localName="addNumbersResponse",
className="fromjava.client.AddNumbersResponse")
int arg0,
int arg1);
}
• javax.xml.ws.ServiceMode
This annotation allows theProvider developer to indicate whether a Provider implementation wishes to work with
entire protocol messages or just with protocol message payloads.
Example:
@WebServiceProvider(wsdlLocation="WEB-INF/wsdl/AddNumbers.wsdl")
@ServiceMode(value=Service.Mode.PAYLOAD)
public class AddNumbersImpl implements Provider<Source> {
public Source invoke(Source source) throws RemoteException {

try {
DOMResult dom = new DOMResult();
Transformer trans = TransformerFactory.newInstance().newTransformer();
trans.transform(source, dom);
Node node = dom.getNode();
Node root = node.getFirstChild();
Node first = root.getFirstChild();
int number1 = Integer.decode(first.getFirstChild().getNodeValue());
Node second = first.getNextSibling();
int number2 = Integer.decode(second.getFirstChild().getNodeValue());
return sendSource(number1, number2);
} catch(Exception e) {
e.printStackTrace();
throw new RemoteException("Error in provider endpoint");
}
}
private Source sendSource(int number1, int number2) {

int sum = number1+number2;
String body =
"<ns:addNumbersResponse xmlns:ns=\"http://duke.example.org\"><return>"
+sum
+"</return></ns:addNumbersResponse>";
Source source = new StreamSource(
new ByteArrayInputStream(body.getBytes()));
return source;
}
NOTE: The @ServiceMode annotation is only supported on classes that are annotated with
the @WebServiceProvider annotation.
• javax.xml.ws.WebEndpoint
Used to annotate the get PortName() methods of a generated service interface.
The information specified in this annotation is sufficient to uniquely identify a wsdl:port element inside
a wsdl:service . The latter is determined based on the value of the @WebServiceClient annotation on the
generated service interface itself.
Example:
@WebServiceClient(name="AddNumbersImplService",
wsdlLocation="http://localhost:8080/jaxws-fromjava/addnumbers?wsdl")
public class AddNumbersImplService extends Service {
private final static URL WSDL_LOCATION;
private final static QName ADDNUMBERSIMPLSERVICE =
new QName("http://server.fromjava/", "AddNumbersImplService");
private final static QName ADDNUMBERSIMPLPORT =

new QName("http://server.fromjava/", "AddNumbersImplPort");
static {
URL url = null;
try {
url = new URL("http://localhost:8080/jaxws-fromjava/addnumbers?wsdl");
} catch (MalformedURLException e) {
}
WSDL_LOCATION = url;
}
public AddNumbersImplService(URL wsdlLocation, QName serviceName) {

super(wsdlLocation, serviceName);
}
public AddNumbersImplService() {
super(WSDL_LOCATION, ADDNUMBERSIMPLSERVICE);
}
/**
*
* @return
* returns AddNumbersImpl
*/
@WebEndpoint(name = "AddNumbersImplPort")
public AddNumbersImpl getAddNumbersImplPort() {
return (AddNumbersImpl)super.getPort(ADDNUMBERSIMPLPORT, AddNumbersImpl.class);
}
}
• javax.xml.ws.WebFault
This annotation is generated by the JAX-WS tools into service specific exception classes generated from a WSDL to customize to
the local and namespace name of the fault element and the name of the fault bean and to mark the service specific exception as
one generated from WSDL. Developers should not use this annotation themselves. The reason that the JAX-WS needs to know if a
service specific exception is generated from a WSDL or not is because these exceptions will already have a fault bean generated
for them. The name of this fault bean is not the same name as on generated from a Java service specific exception class. For
more information on this topic, please refer to section 3.6 of the JAX-WS 2.0 specification.
Example:
@javax.xml.ws.WebFault(name="AddNumbersException",
targetNamespace="http://server.fromjava/jaxws")
public class AddNumbersException_Exception extends Exception {
private fromjava.client.AddNumbersException faultInfo;
public AddNumbersException_Exception(String message, AddNumbersException faultInfo) {

super(message);
this.faultInfo = faultInfo;
}
public AddNumbersException_Exception(String message, AddNumbersException faultInfo, Throwable

cause) {
super(message, cause);
this.faultInfo = faultInfo;
}
public fromjava.client.AddNumbersException getFaultInfo() {

return faultInfo;
}
}
This annotation can only be applied to a fault implementation class on the client or server.
• javax.xml.ws.WebServiceClient
wsdl:service element inside a WSDL

The information specified in this annotation is sufficient to uniquely identify a
document. This wsdl:serviceelement represents the Web service for which the generated service interface provides a
client view.
Example:
@WebServiceClient(name="AddNumbersImplService",
wsdlLocation="http://localhost:8080/jaxws-fromjava/addnumbers?wsdl")
public class AddNumbersImplService extends Service {
private final static URL WSDL_LOCATION;
private final static QName ADDNUMBERSIMPLSERVICE =
new QName("http://server.fromjava/", "AddNumbersImplService");
private final static QName ADDNUMBERSIMPLPORT =

new QName("http://server.fromjava/", "AddNumbersImplPort");
static {
URL url = null;
try {
url = new URL("http://localhost:8080/jaxws-fromjava/addnumbers?wsdl");
} catch (MalformedURLException e) {
}
WSDL_LOCATION = url;
}
public AddNumbersImplService(URL wsdlLocation, QName serviceName) {

super(wsdlLocation, serviceName);
}
public AddNumbersImplService() {
super(WSDL_LOCATION, ADDNUMBERSIMPLSERVICE);
}
/**
*
* @return
* returns AddNumbersImpl
*/
@WebEndpoint(name = "AddNumbersImplPort")
public AddNumbersImpl getAddNumbersImplPort() {
return (AddNumbersImpl)super.getPort(ADDNUMBERSIMPLPORT, AddNumbersImpl.class);
}
}
• javax.xml.ws.WebServiceProvider
Annotation used to annotate a Provider implementation class.
Example:
@ServiceMode(value=Service.Mode.PAYLOAD)
@WebServiceProvider(wsdlLocation="WEB-INF/wsdl/AddNumbers.wsdl")
public class AddNumbersImpl implements Provider {
public Source invoke(Source source) {

try {
DOMResult dom = new DOMResult();
Transformer trans = TransformerFactory.newInstance().newTransformer();
trans.transform(source, dom);
Node node = dom.getNode();
Node root = node.getFirstChild();
Node first = root.getFirstChild();
int number1 = Integer.decode(first.getFirstChild().getNodeValue());
Node second = first.getNextSibling();
int number2 = Integer.decode(second.getFirstChild().getNodeValue());
return sendSource(number1, number2);
throw new RuntimeException("Error in provider endpoint", e);
}
}
private Source sendSource(int number1, int number2) {

int sum = number1+number2;
String body = "" + sum + "";
Source source = new StreamSource(new ByteArrayInputStream(body.getBytes()));
return source;
}
}
NOTE:
o A Java class that implements a Web service must specify either

the @WebService or @WebServiceProvider annotation. Both annotations cannot be present.
o The @WebServiceProvider annotation is only supported on the service implementation class.
o Any class with the @WebServiceProvider annotation must implement
the javax.xml.ws.Provider interface.
• javax.xml.ws.WebServiceRef
The @WebServiceRef annotation is used to define a reference to a web service and (optionally) an injection target for
it. Web service references are resources in the Java EE 5 sense.
Example:
import javax.xml.ws.WebServiceRef;
import com.techtip.jaxws.sample.CalculatorService;
import com.techtip.jaxws.sample.Calculator;
public class JAXWSClient {

@WebServiceRef(wsdlLocation="http://localhost:8080/CalculatorService?WSDL")
static CalculatorService service;
public void doTest() {

try {
Calculator port = service.getCalculatorPort();
int ret = port.add(2, 2);
}
}
}
NOTE: The @WebServiceRef annotation can be used to inject instances of JAX-WS services and ports.
NOTE: The @WebServiceRef annotation is only supported in certain class types. Examples are JAX-WS endpoint
implementation classes, JAX-WS handler classes, Enterprise JavaBeans classes, and servlet classes. This annotation is supported
in the same class types as the @Resourceannotation. See the Java Platform, Enterprise Edition (Java EE) 5 specification for
a complete list of supported class types.
• javax.xml.ws.Feature
The @Feature annotation is used to enable/disable a feature to use for a web service endpoint implementation class. This
@BindingType annotation.
annotation is used with
@BindingType annotation that specifies use of the SOAP1.1/HTTP binding, it enables both
Here is a sample use of the
the AddressingFeature and theMTOMFeature and also sets the threshold feature parameter on
the MTOMFeature:
@BindingType(
value=SOAPBinding.SOAP11HTTP_BINDING,
features={
@Feature(AddressingFeature.ID),
@Feature(value=MTOMFeature.ID,
parameters={@FeatureParameter(name=MTOMFeature.THRESHOLD, value="1000")})
}
)
public class MyWebService {
...
}
• javax.xml.ws.FeatureParameter
The @FeatureParameter annotation is used to specify paramaters for a feature. This annotation is used
with @Feature.
• javax.xml.ws.Action
The @Action annotation allows explicit association of Action message addressing property with input, output, and fault
messages of the mapped WSDL operation.
This annotation can be specified on each method of a service endpoint interface or implementation. For such a method, the
mapped operation in the generated WSDL contains explicit wsaw:Action attribute on the WSDL input, output and fault
messages of the WSDL operation based upon which attributes of the Action annotation have been specified.
Example: Specify explicit values for Action message addressing property for input and output messages:
@javax.jws.WebService
@javax.xml.ws.Action(
input="http://example.com/inputAction",
output="http://example.com/outputAction")
}
}
The generated WSDL looks like:
<definitions targetNamespace="http://example.com/numbers" ...>

...
<portType name="AddNumbersPortType">
<operation name="AddNumbers">
<input message="tns:AddNumbersInput" name="Parameters"
wsaw:Action="http://example.com/inputAction"/>
<output message="tns:AddNumbersOutput" name="Result"
wsaw:Action="http://example.com/outputAction"/>
</operation>
<portType>
...
<definitions>
• javax.xml.ws.FaultAction
The @FaultAction annotation is used inside an @Action annotation to allow an explicit association
of Action message addressing property with the fault messages of the WSDL operation mapped from the exception class.
The fault message in the generated WSDL operation mapped for className class contains
explicit wsaw:Action attribute.
Action
Example: Specify explicit values for message addressing property for the input, output and fault message if the Java
method throws only one service specific exception:
@javax.jws.WebService
@javax.xml.ws.Action(
input="http://example.com/inputAction",
output="http://example.com/outputAction",
fault = {@javax.xml.ws.FaultAction(className=AddNumbersException.class,
value="http://example.com/faultAction")}
)
public int addNumbers(int number1, int number2) throws AddNumbersException {
}
}
The generated WSDL looks like:
<definitions targetNamespace="http://example.com/numbers" ...>

...
<portType name="AddNumbersPortType">
<operation name="AddNumbers">
<input message="tns:AddNumbersInput" name="Parameters"
wsaw:Action="http://example.com/inputAction"/>
<output message="tns:AddNumbersOutput" name="Result"
wsaw:Action="http://example.com/outputAction"/>
<fault message="tns:AddNumbersException" name="AddNumbersException"
wsaw:Action="http://example.com/faultAction"/>
</operation>
<portType>
...
<definitions>
Describe the architecture of JAX-WS including the Tools SPI that define the contract between JAX-WS
tools and Java EE.
• [NONE] blah
The JAX-WS RI consists of the following major modules:
• Runtime
Runtime module is available at application runtime and provide the actual core Web Services framework.
JAX-WS is the aggregating component of what is called the integrated Stack (I-Stack). The I-Stack consists of JAX-WS, JAXB,
StAX, SAAJ and Fast Infoset. JAXB is the databinding component of the stack. StAX is the Streaming XML parser used by the
stack. SAAJ is used for its attachment support with SOAP messages and to allow handler developers to gain access to the SOAP
message via a standard interface. Fast Infoset is a binary encoding of XML that can improve performance.
• Tools
Tools for converting WSDLs and Java source/class files to Web Services.
o APT
A Java SE tool and framework for processing annotations. APT will invoke a JAX-
WS AnnotationProcossor for processing Java source files with javax.jws.* annotations and
making them web services. APT will compile the Java source files and generate any additional classes needed to make
an javax.jws.WebService annotated class a Web service.
o WsGen
Tool to process a compiled javax.jws.WebService annotated class and to generate the necessary
classes to make it a Web service.
o WsImport
Tool to import a WSDL and to generate an SEI (a javax.jws.WebService ) interface that can be either
implemented on the server to build a web service, or can be used on the client to invoke the web service.
• APT
A Java SE tool and framework for processing annotations.
apt [-classpath classpath] [-sourcepath sourcepath] [-d directory] [-s directory]

[-factorypath path] [-factory class] [-print] [-nocompile] [-Akey[=val] ...]
[javac option] sourcefiles [@files]
-s dir
Specify the directory root under which processor-generated source files will be placed;
files are placed in subdirectories based on package namespace.
-nocompile
Do not compile source files to class files.
-print
Print out textual representation of specified types; perform no annotation processing
or compilation.
-A[key[=val]]
Options to pass to annotation processors -- these are not interpreted by apt directly,
but are made available for use by individual processors
-factorypath path
Specify where to find annotation processor factories; if this option is used, the
classpath is not searched for factories.
-factory classname
Name of annotation processor factory to use; bypasses default discovery process
-d dir
Specify where to place processor and javac generated class files
-cp path or -classpath path

Specify where to find user class files and annotation processor factories.
If -factorypath is given, the classpath is not searched for factories.
The tool apt, annotation processing tool, includes a set of new reflective APIs and supporting infrastructure to process program
annotations. The aptreflective APIs provide a build-time, source-based, read-only view of program structure. These reflective
APIs are designed to cleanly model the Java programming language's type system after the addition of generics. First, apt runs
annotation processors that can produce new source code and other files. Next, apt can cause compilation of both original and
generated source files, easing development. The reflective APIs and other APIs used to interact with the tool are subpackages
of com.sun.mirror.
• Annotation Processor
An APT AnnotationProcessor for processing Java source files with javax.jws.* annotations and making
them web services.
• Runtime SPI
A part of JAX-WS that defines the contract between the JAX-WS RI runtime and Java EE.
• Tools SPI
A part of JAX-WS that defines the contract between the JAX-WS RI tools and Java EE.
• JAXB XJC-API
The schema compiler.
• JAXB runtime-API
A part of the JAXB runtime that defines the contract between the JAXB RI and the JAX-WS RI.
Describe creating a Web Service using JAX-WS.

• [JAVA_EE_5_TUTORIAL] The Java EE 5 Tutorial
The starting point for developing a JAX-WS web service is a Java class annotated with the javax.jws.WebService annotation.
The @WebService annotation defines the class as a web service endpoint.
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. An interface is not required when building a JAX-WS endpoint. The web service implementation class
implicitly defines an SEI.
You may specify an explicit interface by adding the endpointInterface element to the @WebService annotation in the
implementation class. You must then provide an interface that defines the public methods made available in the endpoint implementation
class.
You use the endpoint implementation class and the wsgen tool to generate the web service artifacts that connect a web service client to
the JAX-WS runtime.
Together, the wsgen tool and the Application Server provide the Application Server's implementation of JAX-WS.
These are the basic steps for creating the web service and client:
1. Code the implementation class.

2. Compile the implementation class.
3. Use wsgen to generate the artifacts required to deploy the service.
4. Package the files into a WAR file.
5. Deploy the WAR file. The web service artifacts (which are used to communicate with clients) are generated by the Application
Server during deployment.
6. Code the client class.
7. Use wsimport to generate and compile the web service artifacts needed to connect to the service.
8. Compile the client class.
9. Run the client.
Requirements of a JAX-WS Endpoint
JAX-WS endpoints must follow these requirements:
• The implementing class must be annotated with either

the javax.jws.WebService or javax.jws.WebServiceProvider annotation.
• The implementing class may explicitly reference an SEI through theendpointInterface element of
the @WebService annotation, but is not required to do so. If no endpointInterface is specified
in @WebService, an SEI is implicitly defined for the implementing class.
• The business methods of the implementing class must be public, and must NOT be declared static or final.
• Business methods that are exposed to web service clients must be annotated with javax.jws.WebMethod.
• Business methods that are exposed to web service clients must have JAXB-compatible parameters and return types.
• The implementing class must NOT be declared final and must NOT be abstract.
• The implementing class must have a default public constructor.
• The implementing class must NOT define the finalize() method.
• The implementing class may use
the javax.annotation.PostConstruct or javax.annotation.PreDestroy annotatio
ns on its methods for life cycle event callbacks.
The @PostConstruct method is called by the container before the implementing class begins responding to web
service clients.
The @PreDestroy method is called by the container before the endpoint is removed from operation.
Coding the Service Endpoint Implementation Class

In this example, the implementation class, Hello, is annotated as a web service endpoint using
the @WebService annotation. Hello declares a single method named sayHello, annotated with
the @WebMethod annotation. @WebMethod exposes the annotated method to web service clients. sayHello returns a
greeting to the client, using the name passed to sayHello to compose the greeting. The implementation class also must define a
default, public, no-argument constructor.
package helloservice.endpoint;
@WebService
public class Hello {
private String message = new String("Hello, ");
public void Hello() {}
@WebMethod
public String sayHello(String name) {
return message + name + ".";
}
}
A Simple JAX-WS Client
HelloClient is a stand-alone Java program that accesses the sayHello method of HelloService. It makes this call
through a port, a local object that acts as a proxy for the remote service. The port is created at development time by
the wsimport tool, which generates JAX-WS portable artifacts based on a WSDL file.
When invoking the remote methods on the port, the client performs these steps:
1. Uses the javax.xml.ws.WebServiceRef annotation to declare a reference to a web

service. @WebServiceRef uses the wsdlLocation element to specify the URI of the deployed service's WSDL
file:
2. @WebServiceRef(wsdlLocation="http://localhost:8080/helloservice/hello?wsdl")
3. static HelloService service;
4. Retrieves a proxy to the service, also known as a port, by invoking getHelloPort on the service.
5. Hello port = service.getHelloPort();
The port implements the SEI defined by the service.
6. Invokes the port's sayHello method, passing to the service a name.

7. String response = port.sayHello(name);
Here is the full source of HelloClient:
package simpleclient;
import javax.xml.ws.WebServiceRef;
import helloservice.endpoint.HelloService;
import helloservice.endpoint.Hello;
public class HelloClient {
@WebServiceRef(wsdlLocation="http://localhost:8080/helloservice/hello?wsdl")
static HelloService service;
public static void main(String[] args) {

try {
HelloClient client = new HelloClient();
client.doTest(args);
}
}
public void doTest(String[] args) {

try {
System.out.println("Retrieving the port from
the following service: " + service);
Hello port = service.getHelloPort();
System.out.println("Invoking the sayHello operation
on the port.");
String name;
if (args.length > 0) {
name = args[0];
} else {
name = "No Name";
}
String response = port.sayHello(name);

System.out.println(response);
}
}
}
Describe JAX-WS Client Communications Models.
• [NONE] blah
The Java API for XML-Based Web Services (JAX-WS) Web service client programming model supports both the Dispatch client API and the
Dynamic Proxy client API. The Dispatch client API is a dynamic client programming model, whereas the static client programming model for
JAX-WS is the Dynamic Proxy client. The Dispatch and Dynamic Proxy clients enable both synchronous and asynchronous invocation of JAX-
WS Web services.
• Dispatch client: Use this client 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.
• Dynamic Proxy client: Use this client when you want to invoke a Web service based on a service endpoint interface.
Dispatch client
XML-based Web services use XML messages for communications between Web services and Web services clients. The JAX-WS APIs provide
high-level methods to simplify and hide the details of converting between Java method invocations and their associated XML messages.
However, in some cases, you might desire to work at the XML message level. Support for invoking services at the XML message level is
provided by the Dispatch client API.
The Dispatch client API, javax.xml.ws.Dispatch , is a dynamic JAX-WS client programming interface. To write a Dispatch
client, you must have expertise with the Dispatch client APIs, the supported object types, and knowledge of the message representations for
the associated Web Services Description Language (WSDL) file. The Dispatch client 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
soap:Envelope, soap:Header, and soap:Body elements.
entire SOAP envelope including the
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 Dispatch client API requires application clients to construct messages or payloads as XML which requires a detailed knowledge of the
message or message payload. The Dispatch client supports the following types of objects:
• javax.xml.transform.Source: Use Source objects to enable clients to use XML APIs directly. You can
use Source objects with SOAP or HTTP bindings.
• JAXB objects: Use JAXB objects so that clients can use JAXB objects that are generated from an XML schema to create and
manipulate XML with JAX-WS applications. JAXB objects can only be used with SOAP or HTTP bindings.
• javax.xml.soap.SOAPMessage: Use SOAPMessage objects so that clients can work with SOAP
messages. You can only use SOAPMessage objects with SOAP bindings.
• javax.activation.DataSource: Use DataSource objects so that clients can work with Multipurpose
Internet Mail Extension (MIME) messages. UseDataSource only with HTTP bindings.
For example, if the input parameter type is javax.xml.transform.Source, the call to the Dispatch client API is similar to
the following code example:
Dispatch<Source> dispatch = ... ; //create a Dispatch<Source>

Source request = ... ; //create a Source object
Source response = dispatch.invoke(request);
The Dispatch parameter value determines the return type of the invoke() method.
The Dispatch client is invoked in one of three ways:
• Synchronous invocation for requests and responses using the invoke method
• Asynchronous invocation for requests and responses using the invokeAsync method with a callback or polling object
• One-way invocation using the invokeOneWay methods
The following examples demonstrate use of Dispatch methods in the synchronous, asynchronous polling, and asynchronous callback
modes.
• Synchronous, Payload-Oriented
•
• Source reqMsg = ...;
• Service service = ...;
• Dispatch<Source> disp = service.createDispatch(portName, Source.class, PAYLOAD);
• Source resMsg = disp.invoke(reqMsg);
•
• Synchronous, Message-Oriented
•
• SOAPMessage soapReqMsg = ...;
• Dispatch<SOAPMessage> disp = service.createDispatch(portName, SOAPMessage.class, MESSAGE);
• SOAPMessage soapResMsg = disp.invoke(soapReqMsg);
•
• Synchronous, Payload-Oriented With JAXB Objects
•
• JAXBContext jc = JAXBContext.newInstance("primer.po");
• Unmarshaller u = jc.createUnmarshaller();
• PurchaseOrder po = (PurchaseOrder)u.unmarshal(new FileInputStream("po.xml"));
• Dispatch<Object> disp = service.createDispatch(portName, jc, PAYLOAD);
• OrderConfirmation conf = (OrderConfirmation)disp.invoke(po);
•
• Asynchronous, Polling, Message-Oriented
•
• SOAPMessage soapReqMsg = ...;
• Dispatch<SOAPMessage> disp = service.createDispatch(portName, SOAPMessage.class, MESSAGE);
• Response<SOAPMessage> res = disp.invokeAsync(soapReqMsg);
• while (!res.isDone()) {
• // do something while we wait
• }
• SOAPMessage soapResMsg = res.get();
•
• Asynchronous, Callback, Payload-Oriented
•
• class MyHandler implements AsyncHandler<Source> {
• ...
• public void handleResponse(Response<Source> res) {
• Source resMsg = res.get();
• // do something with the results
• }
• }
•
• Source reqMsg = ...;
• Dispatch<Source> disp = service.createDispatch(portName, Source.class, PAYLOAD);
• MyHandler handler = new MyHandler();
• disp.invokeAsync(reqMsg, handler);
•
Dynamic Proxy client
The static client programming model for JAX-WS is the called the Dynamic Proxy client. The Dynamic Proxy client invokes a Web service
based on a Service Endpoint Interface (SEI) which must be provided. The Dynamic Proxy client is similar to the stub client in the Java API for
XML-based RPC (JAX-RPC) programming model. Although the JAX-WS Dynamic Proxy client and the JAX-RPC stub client are both based on
the Service Endpoint Interface (SEI) that is generated from a WSDL file , there is a major difference. The Dynamic Proxy client is dynamically
generated at run time using the Java 5 Dynamic Proxy functionality, while the JAX-RPC-based stub client is a non-portable Java file that is
generated by tooling. Unlike the JAX-RPC stub clients, the Dynamic Proxy client does not require you to regenerate a stub prior to running the
client on an application server for a different vendor because the generated interface does not require the specific vendor information.
The Dynamic Proxy instances extend the java.lang.reflect.Proxy class and leverage the Dynamic Proxy function in the
base Java Runtime Environment Version 5. The client application can then provide an interface that is used to create the proxy instance while
the runtime is responsible for dynamically creating a Java object that represents the SEI.
getLastTradePrice) on a service endpoint interface

The following example shows the use of a proxy to invoke a method (
( com.example.StockQuoteProvider). Note that no statically generated stub class is involved.
javax.xml.ws.Service service = ... ;
com.example.StockQuoteProvider proxy = service.getPort(portName, com.example.StockQuoteProvider.class);
javax.xml.ws.BindingProvider bp = (javax.xml.ws.BindingProvider)proxy;
Map<String,Object> context = bp.getRequestContext();
context.setProperty("javax.xml.ws.session.maintain", Boolean.TRUE);
proxy.getLastTradePrice("ACME");
Given a set of requirements, create and configure a Web service client that accesses a stateful Web
service.
• [NONE] blah
Traditionally JAX-WS has never taken advantage of object state, just like servlet. That is, the container creates only one instance of your
service class, and then have it serve all the requests concurrently. This makes it impossible to set values to instance fields, as you will
experience concurrency problem as soon as multiple threads hit your service.
On HTTP, session is often used to store state. This technique is still useful for web services over HTTP. JAX-WS lets you do this today:
@WebService
@Resource
private WebServiceContext wsContext;
public int getCounter() {

MessageContext msgContext = wsContext.getMessageContext();
HttpServletRequest request = (HttpServletRequest) msgContext.get(MessageContext.SERVLET_REQUEST);
HttpSession session = request.getSession();
// Get a session property "counter" from context

if (session == null) {
throw new WebServiceException("No session in WebServiceContext");
}
Integer counter = (Integer)session.getAttribute("counter");
if (counter == null) {
counter = new Integer(0);
System.out.println("Starting the Session");
}
counter = new Integer(counter.intValue() + 1);

session.setAttribute("counter", counter);
return counter;
}
}
When the JAX-WS stack implementation you are running your web services on is deploying your web service endpoint, it will inject an
instance ofWebServiceContext into the implementation instance. You can then ask it for a MessageContext, and
from this get the request, session, response etc.
NOTE: By doing this, you are binding your implementation to knowledge about which transport mechanism, it is deployed on and accessed
through. It could be something else than HTTP.
Using @HttpSessionScope
HttpSession cookies. Storing the state and accessing it from

One way to bring state to Web Services is to use
the HttpSession (from WebServiceContext) for each request takes multiple steps and does not fit well with the OO
way of accessing/storing it with instance fields. One can
use @com.sun.xml.ws.developer.servlet.HttpSessionScope annotation tells the JAX-WS RI to
Hello
create one instance of per each HTTP session. As you see this approach still relies on Http cookies but makes it easier to access
state from the context just like normal instance variables:
@HttpSessionScope
@WebService
int counter = 0;
public int getCounter() {
return counter++;
}
}
Using @Stateful
JAX-WS also provides a transport neutral mechanism to do this. It

introduces @com.sun.xml.ws.developer.Stateful to take care of maintaining all the state and the user can
@Stateful to Web Service implementation.
access it using instance variables. All the user needs to do is to add
The JAX-WS RI has a vendor extension that allows developers to bring back object state to the web service world. Normally, the JAX-WS RI
only creates one instance of a service class, and have it serve all incoming requests concurrently. This makes it essentially impossible to use
instance fields of the service class for any meaningful purpose.
The stateful web service support in the JAX-WS RI resolves this problem by having the JAX-WS RI maintain multiple instances of a service. By
using WS-Addressing behind the scene, it provides a standard-based on-the-wire protocol and easy-to-use programming model.
Application service implementation classes (or providers) who'd like to use the stateful web service support must
declare @Stateful annotation on a class. It should also have a public static method/field that
takes StatefulWebServiceManager:
@Stateful
@WebService
@Addressing
class BankAccount {
protected final int id;
private int balance;
Account(int id) { this.id = id; }
@WebMethod
public synchronized void deposit(int amount) { balance+=amount; }
// either via a public static field

public static StatefulWebServiceManager<BankAccount> manager;
// or via a public static method (the method name could be anything)

public static void setManager(StatefulWebServiceManager<BankAccount> manager) {
...
}
}
After your service is deployed but before you receive a first request, the resource injection occurs on the field or the method.
A stateful web service class does not need to have a default constructor. In fact, most of the time you want to define a constructor that takes
some arguments, so that each instance carries certain state (as illustrated in the above example).
Each instance of a stateful web service class is identified by an unique EndpointReference. Your application creates an instance
of a class, then you'll have the JAX-WS RI assign this unique EPR for the instance as follows:
@WebService
class Bank { // this is ordinary stateless service
@WebMethod
public synchronized W3CEndpointReference login(int accountId, int pin) {
if(!checkPin(pin)) {
throw new AuthenticationFailedException("invalid pin");
}
BankAccount acc = new BankAccount(accountId);
return BankAccount.manager.export(acc);
}
}
Typically you then pass this EPR to remote systems. When they send messages to this EPR, the JAX-WS RI makes sure that the particular
exported instance associated with that EPR will receive a service invocation.
Chapter 5. REST, JSON, SOAP and XML Processing APIs (JAXP, JAXB and SAAJ)
Describe the characteristics of REST Web Services.
• [NONE] blah
REST defines a set of architectural principles by which you can design Web services that focus on a system's resources, including how
resource states are addressed and transferred over HTTP by a wide range of clients written in different languages. REST has a large impact on
the Web that it has mostly displaced SOAP- and WSDL-based interface design because it's a considerably simpler style to use.
A concrete implementation of a REST Web service follows four basic design principles:
• Use HTTP methods explicitly
One of the key characteristics of a RESTful Web service is the explicit use of HTTP methods in a way that follows the protocol as
defined by RFC 2616. HTTP GET, for instance, is defined as a data-producing method that's intended to be used by a client
application to retrieve a resource, to fetch data from a Web server, or to execute a query with the expectation that the Web
server will look for and respond with a set of matching resources.
REST asks developers to use HTTP methods explicitly and in a way that's consistent with the protocol definition. This basic REST
design principle establishes a one-to-one mapping between create, read, update, and delete (CRUD) operations and HTTP
methods. According to this mapping:
o To create a resource on the server, use POST.

o To retrieve a resource, use GET.
o To change the state of a resource or to update it, use PUT.
o To remove or delete a resource, use DELETE.
An unfortunate design flaw inherent in many Web APIs is in the use of HTTP methods for unintended purposes. The request URI in
an HTTP GET request, for example, usually identifies one specific resource. Or the query string in a request URI includes a set of
parameters that defines the search criteria used by the server to find a set of matching resources. At least this is how the
HTTP/1.1 RFC describes GET. But there are many cases of unattractive Web APIs that use HTTP GET to trigger something
transactional on the server—for instance, to add records to a database. In these cases the GET request URI is not used properly
or at least not used RESTfully. If the Web API uses GET to invoke remote procedures, it looks like this:
GET /adduser?name=Mikalai HTTP/1.1
It's not a very attractive design because the Web method above supports a state-changing operation over HTTP GET. Put another
way, the HTTP GET request above has side effects. If successfully processed, the result of the request is to add a new user—in
this example, Robert—to the underlying data store. The problem here is mainly semantic. Web servers are designed to respond to
HTTP GET requests by retrieving resources that match the path (or the query criteria) in the request URI and return these or a
representation in a response, not to add a record to a database. From the standpoint of the intended use of the protocol method
then, and from the standpoint of HTTP/1.1-compliant Web servers, using GET in this way is inconsistent.
Beyond the semantics, the other problem with GET is that to trigger the deletion, modification, or addition of a record in a
database, or to change server-side state in some way, it invites Web caching tools (crawlers) and search engines to make server-
side changes unintentionally simply by crawling a link. A simple way to overcome this common problem is to move the parameter
names and values on the request URI into XML tags. The resulting tags, an XML representation of the entity to create, may be
sent in the body of an HTTP POST whose request URI is the intended parent of the entity:
POST /users HTTP/1.1

Host: myserver
Content-Type: application/xml
<user>
<name>Mikalai</name>
</user>
The method above is exemplary of a RESTful request: proper use of HTTP POST and inclusion of the payload in the body of the
request. On the receiving end, the request may be processed by adding the resource contained in the body as a subordinate of
the resource identified in the request URI; in this case the new resource should be added as a child of /users . This
containment relationship between the new entity and its parent, as specified in the POST request, is analogous to the way a file is
subordinate to its parent directory. The client sets up the relationship between the entity and its parent and defines the new
entity's URI in the POST request.
A client application may then get a representation of the resource using the new URI, noting that at least logically the resource is
located under /users, as shown below:
GET /users/Mikalai HTTP/1.1

Host: myserver
Accept: application/xml
Using GET in this way is explicit because GET is for data retrieval only. GET is an operation that should be free of side effects, a
property also known as idempotence.
A similar refactoring of a Web method also needs to be applied in cases where an update operation is supported over HTTP GET,
as shown in listing below:
GET /updateuser?name=Mikalai&newname=Mikola HTTP/1.1
This changes the name attribute (or property) of the resource. While the query string can be used for such an operation, this
query-string-as-method-signature pattern tends to break down when used for more complex operations. Because your goal is to
make explicit use of HTTP methods, a more RESTful approach is to send an HTTP PUT request to update the resource, instead of
HTTP GET, for the same reasons stated above:
PUT /users/Mikalai HTTP/1.1

Host: myserver
Content-Type: application/xml
<user>
<name>Mikola</name>
</user>
Using PUT to replace the original resource provides a much cleaner interface that's consistent with REST's principles and with the
definition of HTTP methods. The PUT request in the listing above is explicit in the sense that it points at the resource to be
updated by identifying it in the request URI and in the sense that it transfers a new representation of the resource from client to
server in the body of a PUT request instead of transferring the resource attributes as a loose set of parameter names and values
on the request URI. Listing above also has the effect of renaming the resource from Mikalai to Mikola, and in doing so
changes its URI to /users/Mikola . In a REST Web service, subsequent requests for the resource using the old URI
would generate a standard 404 Not Found error.
As a general design principle, it helps to follow REST guidelines for using HTTP methods explicitly by using nouns in URIs instead
of verbs. In a RESTful Web service, the verbs - POST, GET, PUT, and DELETE - are already defined by the protocol. And ideally, to
keep the interface generalized and to allow clients to be explicit about the operations they invoke, the Web service should not
define more verbs or remote procedures, such as /adduser /updateuser
or . This general design principle also
applies to the body of an HTTP request, which is intended to be used to transfer resource state, not to carry the name of a remote
method or remote procedure to be invoked.
• Be stateless
REST Web services need to scale to meet increasingly high performance demands. Clusters of servers with load-balancing and
failover capabilities, proxies, and gateways are typically arranged in a way that forms a service topology, which allows requests to
be forwarded from one server to the other as needed to decrease the overall response time of a Web service call. Using
intermediary servers to improve scale requires REST Web service clients to send complete, independent requests; that is, to send
requests that include all data needed to be fulfilled so that the components in the intermediary servers may forward, route, and
load-balance without any state being held locally in between requests.
A complete, independent request doesn't require the server, while processing the request, to retrieve any kind of application
context or state. A REST Web service application (or client) includes within the HTTP headers and body of a request all of the
parameters, context, and data needed by the server-side component to generate a response. Statelessness in this sense improves
Web service performance and simplifies the design and implementation of server-side components because the absence of state
on the server removes the need to synchronize session data with an external application.
Figure below illustrates a stateful service from which an application may request the next page in a multipage result set,
assuming that the service keeps track of where the application leaves off while navigating the set. In this stateful design, the
service increments and stores a previousPagevariable somewhere to be able to respond to requests for next.
Stateful services like this get complicated. In a Java Platform, Enterprise Edition (Java EE) environment stateful services require a
lot of up-front consideration to efficiently store and enable the synchronization of session data across a cluster of Java EE
containers. In this type of environment, there's a problem familiar to Servlet/JavaServer Pages (JSP) and Enterprise JavaBeans
(EJB) developers who often struggle to find the root causes
ofjava.io.NotSerializableException during session replication. Whether it's thrown by the servlet
container during HttpSession replication or thrown by the EJB container during stateful EJB replication, it's a problem
that can cost developers days in trying to pinpoint the one object that doesn't implement Serializable in a sometimes
complex graph of objects that constitute the server's state. In addition, session synchronization adds overhead, which impacts
server performance.
Stateless server-side components, on the other hand, are less complicated to design, write, and distribute across load-balanced
servers. A stateless service not only performs better, it shifts most of the responsibility of maintaining state to the client
application. In a RESTful Web service, the server is responsible for generating responses and for providing an interface that
enables the client to maintain application state on its own. For example, in the request for a multipage result set, the client should
include the actual page number to retrieve instead of simply asking for next:
A stateless Web service generates a response that links to the next page number in the set and lets the client do what it needs to
in order to keep this value around. This aspect of RESTful Web service design can be broken down into two sets of responsibilities
as a high-level separation that clarifies just how a stateless service can be maintained:
o Server
Generates responses that include links to other resources to allow applications to navigate between related resources.
This type of response embeds links. Similarly, if the request is for a parent or container resource, then a typical
RESTful response might also include links to the parent's children or subordinate resources so that these remain
connected.
Generates responses that indicate whether they are cacheable or not to improve performance by reducing the number
of requests for duplicate resources and by eliminating some requests entirely. The server does this by including
a Cache-Control and Last-Modified (a date value) HTTP response header.
o Client application
Cache-Control response header to determine whether to cache the resource (make a local copy
Uses the
Last-Modified response header and sends back the date value in
of it) or not. The client also reads the
an If-Modified-Since header to ask the server if the resource has changed. This is called Conditional
GET, and the two headers go hand in hand in that the server's response is a standard 304 code (Not Modified) and
omits the actual resource requested if it has not changed since that time. A 304 HTTP response code means the client
can safely use a cached, local copy of the resource representation as the most up-to-date, in effect bypassing
subsequent GET requests until the resource changes.
Sends complete requests that can be serviced independently of other requests. This requires the client to make full
use of HTTP headers as specified by the Web service interface and to send complete representations of resources in
the request body. The client sends requests that make very few assumptions about prior requests, the existence of a
session on the server, the server's ability to add context to a request, or about application state that is kept in
between requests.
This collaboration between client application and service is essential to being stateless in a RESTful Web service. It improves
performance by saving bandwidth and minimizing server-side application state.
• Expose directory structure-like URIs
From the standpoint of client applications addressing resources, the URIs determine how intuitive the REST Web service is going
to be and whether the service is going to be used in ways that the designers can anticipate.
REST Web service URIs should be intuitive to the point where they are easy to guess. Think of a URI as a kind of self-
documenting interface that requires little, if any, explanation or reference for a developer to understand what it points to and to
derive related resources. To this end, the structure of a URI should be straightforward, predictable, and easily understood.
One way to achieve this level of usability is to define directory structure-like URIs. This type of URI is hierarchical, rooted at a
single path, and branching from it are subpaths that expose the service's main areas. According to this definition, a URI is not
merely a slash-delimited string, but rather a tree with subordinate and superordinate branches connected at nodes. For example,
in a discussion threading service that gathers topics ranging from Java to paper, you might define a structured set of URIs like
this:
http://www.myservice.org/discussion/topics/{topic}
The root, /discussion , has a /topics node beneath it. Underneath that there are a series of topic names, such as
gossip, technology, and so on, each of which points to a discussion thread. Within this structure, it's easy to pull up discussion
threads just by typing something after /topics/.
In some cases, the path to a resource lends itself especially well to a directory-like structure. Take resources organized by date,
for instance, which are a very good match for using a hierarchical syntax.
This example is intuitive because it is based on rules:
http://www.myservice.org/discussion/2008/12/10/{topic}
The first path fragment is a four-digit year, the second path fragment is a two-digit day, and the third fragment is a two-digit
month. It may seem a little silly to explain it that way, but this is the level of simplicity we're after. Humans and machines can
easily generate structured URIs like this because they are based on rules. Filling in the path parts in the slots of a syntax makes
them good because there is a definite pattern from which to compose them:
http://www.myservice.org/discussion/{year}/{day}/{month}/{topic}
Some additional guidelines to make note of while thinking about URI structure for a RESTful Web service are:
o Hide the server-side scripting technology file extensions (.jsp, .php, .asp), if any, so you can port to something else
without changing the URIs.
o Keep everything lowercase.
o Substitute spaces with hyphens or underscores (one or the other).
o Avoid query strings as much as you can.
o Instead of using the 404 Not Found code if the request URI is for a partial path, always provide a default page or
resource as a response.
URIs should also be static so that when the resource changes or the implementation of the service changes, the link stays the
same. This allows bookmarking. It's also important that the relationship between resources that's encoded in the URIs remains
independent of the way the relationships are represented where they are stored.
• Transfer XML, JSON, or both
A resource representation typically reflects the current state of a resource, and its attributes, at the time a client application
requests it. Resource representations in this sense are mere snapshots in time. This could be a thing as simple as a
representation of a record in a database that consists of a mapping between column names and XML tags, where the element
values in the XML contain the row values. Or, if the system has a data model, then according to this definition a resource
representation is a snapshot of the attributes of one of the things in your system's data model. These are the things you want
your REST Web service to serve up.
The last set of constraints that goes into a RESTful Web service design has to do with the format of the data that the application
and service exchange in the request/response payload or in the HTTP body. This is where it really pays to keep things simple,
human-readable, and connected.
The objects in your data model are usually related in some way, and the relationships between data model objects (resources)
should be reflected in the way they are represented for transfer to a client application. In the discussion threading service, an
example of connected resource representations might include a root discussion topic and its attributes, and embed links to the
responses given to that topic:
<discussion date="{date}" topic="{topic}">
<comment>{comment}</comment>
<replies>
<reply from="joe@mail.com" href="/discussion/topics/{topic}/joe"/>
<reply from="rob@mail.com" href="/discussion/topics/{topic}/rob"/>
</replies>
</discussion>
To give client applications the ability to request a specific content type that's best suited for them, construct your service so that it
makes use of the built-in HTTP Accept header, where the value of the header is a MIME type. Some common MIME types
used by RESTful services are shown in table:
Table 5.1. Common MIME types used by RESTful services
MIME-Type Content-Type
JSON application/json
XML application/xml
XHTML application/xhtml+xml
Describe the characteristics of JSON Web Services.
• [NONE] blah
JAX-WS supports a "pluggable encoding" - meaning it can use formats other than textual XML. This extension takes advantage of this and
allows JAX-WS services to be exposed via JSON.
JSON support is implemented as a custom binding. So just like there are SOAP/HTTP binding or Plain Old XML binding, you can specify JSON
binding to expose a service as JSON service. The following code shows one way of exposing a service over JSON:
@BindingType(JSONBindingID.JSON_BINDING)
public class MyService {
public Book get(@WebParam(name="id") int id) {

Book b = new Book();
b.id = id;
return b;
}
public static final class Book {

public int id = 1;
public String title = "Java";
}
You just need jaxws-json.jar in your WEB-INF/lib for this to work.
Client-side Programming
Once the server exposes a JSON service, you'll write client-side JavaScript to access this service. First, you'll include the proxy script.
<script src="path/to/endpoint?js"></script>
myService
This creates a variable ' ' with which you can make service invocations. All the parameters are passed as a single JavaScript
object, where the property name is the parameter name. The call happens asynchronously, and when it's done your callback will be invoked
with the return value as a parameter:
myService.get(
{id:5},
function(r) {
alert("ID="+r.id);
alert("title="+r.title);
}
);
If you'd like to use a different variable name, specify that as the var query parameter, as shown below:
<script src="path/to/endpoint?js&var=svc"></script>
For client-side development, JSON endpoints serve HTML documentations on the fly, including all the available operations and "type
descriptions" for all parameters and return values.
Compare SOAP web services to REST Web Services.
• [NONE] blah
In software engineering, the term software architectural style generally refers to "a set of design rules that identify the kinds of components
and connectors that may be used to compose a system or subsystem."
Some common examples of architectural styles include the Pipe and Filter, Layered, Push Based, and so on. In the web services world,
REpresentational State Transfer (REST) is a key design idiom that embraces a stateless client-server architecture in which the web services
are viewed as resources and can be identified by their URLs. Web service clients that want to use these resources access a particular
representation by transferring application content using a small globally defined set of remote methods that describe the action to be
performed on the resource. REST is an analytical description of the existing web architecture, and thus the interplay between the style and
the underlying HTTP protocol appears seamless.
A RESTFul design may be appropriate when:

• The web services are completely stateless. A good test is to consider whether the interaction can survive a restart of the server.
• A caching infrastructure can be leveraged for performance. If the data that the web service returns is not dynamically generated
and can be cached, then the caching infrastructure that web servers and other intermediaries inherently provide can be leveraged
to improve performance. However, the developer must take care because such caches are limited to the HTTP GET method for
most servers.
• The service producer and service consumer have a mutual understanding of the context and content being passed along.
Because there is NO formal way to describe the web services interface, both parties must agree out of band on the schemas that
describe the data being exchanged and on ways to process it meaningfully.
• Bandwidth is particularly important and needs to be limited. REST is particularly useful for limited-profile devices such as PDAs
and mobile phones, for which the overhead of headers and additional layers of SOAP elements on the XML payload must be
restricted.
• Web service delivery or aggregation into existing web sites can be enabled easily with a RESTful style. Developers can use
technologies such as Asynchronous JavaScript with XML (Ajax) and toolkits such as Direct Web Remoting (DWR) to consume the
services in their web applications. Rather than starting from scratch, services can be exposed with XML and consumed by HTML
pages without significantly refactoring the existing web site architecture. Existing developers will be more productive because they
are adding to something they are already familiar with, rather than having to start from scratch with new technology.
A SOAP-based design may be appropriate when:
• A formal contract must be established to describe the interface that the web service offers. The Web Services Description
Language (WSDL) describes the details such as messages, operations, bindings, and location of the web service.
• The architecture must address complex nonfunctional requirements. Many web services specifications address such requirements
and establish a common vocabulary for them. Examples include Transactions, Security, Addressing, Trust, Coordination, and so
on. Most real-world applications go beyond simple CRUD operations and require contextual information and conversational state
to be maintained. With the RESTful approach, developers must build this plumbing into the application layer themselves.
• The architecture needs to handle asynchronous processing and invocation. In such cases, the infrastructure provided by standards
such as WSRM and APIs such as JAX-WS with their client-side asynchronous invocation support can be leveraged out of the box.
Describe the functions and capabilities of the APIs included within JAXP.
• [NONE] blah
The Java API for XML Processing (JAXP) is for processing XML data using applications written in the Java programming language. JAXP
leverages the parser standards Simple API for XML Parsing (SAX) and Document Object Model (DOM) so that you can choose to parse your
data as a stream of events or to build an object representation of it. JAXP also supports the Extensible Stylesheet Language Transformations
(XSLT) standard, giving you control over the presentation of the data and enabling you to convert the data to other XML documents or to
other formats, such as HTML. JAXP also provides namespace support, allowing you to work with DTDs that might otherwise have naming
conflicts.
Streaming API for XML (StAX) provides is the latest API in the JAXP family.
javax.xml.parsers package. That package contains vendor-neutral factory classes -

The main JAXP APIs are defined in the
SAXParserFactory,DocumentBuilderFactory, and TransformerFactory -which give you
a SAXParser, a DocumentBuilder, and an XSLT transformer, respectively. DocumentBuilder, in turn, creates a
DOM-compliant Document object.
The factory APIs let you plug in an XML implementation offered by another vendor without changing your source code. The implementation
you get depends on the setting of
the javax.xml.parsers.SAXParserFactory, javax.xml.parsers.DocumentBuilderFa
ctory, and javax.xml.transform.TransformerFactorysystem properties,
using System.setProperties() in the code, or -DpropertyName="..." on the command line. The default
values (unless overridden at runtime on the command line or in the code) point to Sun's implementation.
The Simple API for XML (SAX) APIs
The basic outline of the SAX parsing APIs are shown below. To start the process, an instance of the SAXParserFactory class is
used to generate an instance of the parser.
The parser wraps a SAXReader parse() method is invoked, the reader invokes one of several callback
object. When the parser's
methods implemented in the application. Those methods are defined by the
interfaces ContentHandler, ErrorHandler, DTDHandler, and EntityResolver.
Here is a summary of the key SAX APIs:
• SAXParserFactory
A SAXParserFactory object creates an instance of the parser determined by the system

javax.xml.parsers.SAXParserFactory.
property,
• SAXParser
The SAXParser interface defines several kinds of parse() methods. In general, you pass an XML data source and
a DefaultHandler object to the parser, which processes the XML and invokes the appropriate methods in the handler
object.
public static void main(String argv[]) {
// Use an instance of ourselves as the SAX event handler

DefaultHandler handler = new Echo();
// Use the default (non-validating) parser

SAXParserFactory factory = SAXParserFactory.newInstance();
try {
// Set up output stream
out = new OutputStreamWriter(System.out, "UTF8");
// Parse the input

SAXParser saxParser = factory.newSAXParser();
saxParser.parse(new File(argv[0]), handler);
} catch (Throwable t) {
t.printStackTrace();
}
}
• SAXReader
The SAXParser wraps a SAXReader. Typically, you don't care about that, but every once in a while you need to get
SAXParser getXMLReader() so that you can configure it. It is the SAXReader that carries
hold of it using 's
on the conversation with the SAX event handlers you define.
• DefaultHandler
DefaultHandler implements
Not shown in the diagram, a
the ContentHandler ErrorHandler DTDHandler, and EntityResolver interfaces (with
, ,
null methods), so you can override only the ones you're interested in.
• ContentHandler
Methods such as startDocument endDocument, startElement, and endElement are invoked

,
when an XML tag is recognized. This interface also defines the
methods characters and processingInstruction, which are invoked when the parser encounters the
text in an XML element or an inline processing instruction, respectively.
• ErrorHandler
Methods error fatalError

, , and warning are invoked in response to various parsing errors. The default error
handler throws an exception for fatal errors and ignores other errors (including validation errors). That's one reason you need to
know something about the SAX parser, even if you are using the DOM. Sometimes, the application may be able to recover from a
validation error. Other times, it may need to generate an exception. To ensure the correct handling, you'll need to supply your
own error handler to the parser.
• DTDHandler
Defines methods you will generally never be called upon to use. Used when processing a DTD to recognize and act on declarations
for an unparsed entity.
• EntityResolver
The resolveEntity method is invoked when the parser must identify data identified by a URI. In most cases, a URI is
simply a URL, which specifies the location of a document, but in some cases the document may be identified by a URN - a public
identifier, or name, that is unique in the web space. The public identifier may be specified in addition to the URL.
The EntityResolver can then use the public identifier instead of the URL to find the document - for example, to
access a local copy of the document if one exists.
A typical application implements most of the ContentHandler methods, at a minimum. Because the default implementations of the
ErrorHandler methods.
interfaces ignore all inputs except for fatal errors, a robust implementation may also want to implement the
When to Use SAX
SAX is fast and efficient, but its event model makes it most useful for such state-independent filtering. For example, a SAX parser calls one
method in your application when an element tag is encountered and calls a different method when text is found. If the processing you're
doing is state-independent (meaning that it does not depend on the elements have come before), then SAX works fine.
On the other hand, for state-dependent processing, where the program needs to do one thing with the data under element A but something
different with the data under element B, then a pull parser such as the Streaming API for XML (StAX) would be a better choice. With a pull
parser, you get the next node, whatever it happens to be, at any point in the code that you ask for it. So it's easy to vary the way you
process text (for example), because you can process it multiple places in the program.
SAX requires much less memory than DOM, because SAX does not construct an internal representation (tree structure) of the XML data, as a
DOM does. Instead, SAX simply sends data to the application as it is read; your application can then do whatever it wants to do with the data
it sees.
Pull parsers and the SAX API both act like a serial I/O stream. You see the data as it streams in, but you can't go back to an earlier position or
leap ahead to a different position. In general, such parsers work well when you simply want to read data and have the application act on it.
But when you need to modify an XML structure - especially when you need to modify it interactively - an in-memory structure makes more
sense. DOM is one such model. However, although DOM provides many powerful capabilities for large-scale documents (like books and
articles), it also requires a lot of complex coding.
The Document Object Model (DOM) APIs
Figure below shows the DOM APIs in action:
javax.xml.parsers.DocumentBuilderFactory class to get

You use the
a DocumentBuilder Document object that conforms to the DOM
instance, and you use that instance to produce a
specification. The builder you get, in fact, is determined by the system
property javax.xml.parsers.DocumentBuilderFactory, which selects the factory implementation that is
used to produce the builder.
static Document document;
public static void main(String argv[]) {

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
try {
DocumentBuilder builder = factory.newDocumentBuilder();
document = builder.parse( new File(argv[0]) );
} catch (SAXParseException spe) {
...
}
}
DocumentBuilder.newDocument() method to create an empty Document that implements

You can also use the
theorg.w3c.dom.Document interface. Alternatively, you can use one of the builder's parse methods to create
a Document from existing XML data.
public static void buildDom() {

try {
document = builder.newDocument();
Element root = (Element) document.createElement("rootElement");

document.appendChild(root);
root.appendChild(document.createTextNode("Some"));
root.appendChild(document.createTextNode(" "));
root.appendChild(
document.createTextNode("text") );
} catch (ParserConfigurationException pce) {
// Parser with specified options can't be built
pce.printStackTrace();
}
}
When to Use DOM

DOM is platform-neutral and language-neutral API that enables programs to dynamically update the contents of XML documents.
DOM creates an in-memory object representation of an entire XML document. This allows extreme flexibility in parsing, navigating, and
updating the contents of a document. DOM's drawbacks are high memory requirements and the need for more powerful processing
capabilities.
The Extensible Stylesheet Language Transformations (XSLT) APIs
Figure below shows the XSLT APIs in action:
A TransformerFactory object is instantiated and used to create a Transformer . The source object is the input to the
transformation process. A source object can be created from a SAX reader, from a DOM, or from an input stream.
Similarly, the result object is the result of the transformation process. That object can be a SAX event handler, a DOM, or an output stream.
When the transformer is created, it can be created from a set of transformation instructions, in which case the specified transformations are
carried out. If it is created without any specific instructions, then the transformer object simply copies the source to the result.
Here is a description of the packages that make up the JAXP Transformation APIs:
• javax.xml.transform
This package defines the factory class you use to get a Transformer object. You then configure the transformer with
input (source) and output (result) objects, and invoke its transform() method to make the transformation happen. The
source and result objects are created using classes from one of the other three packages.
• javax.xml.transform.dom
Defines the DOMSource and DOMResult classes, which let you use a DOM as an input to or output from a
transformation.
Document document;
try {
File f = new File(argv[0]);
document = builder.parse(f);
// Use a Transformer for output

TransformerFactory tFactory = TransformerFactory.newInstance();
Transformer transformer = tFactory.newTransformer();
DOMSource source = new DOMSource(document);

StreamResult result = new StreamResult(System.out);
transformer.transform(source, result);
}
• javax.xml.transform.sax
Defines the SAXSource and SAXResult classes, which let you use a SAX event generator as input to a
transformation, or deliver SAX events as output to a SAX event processor.
public class AddressBookReader implements XMLReader {...}
// Create the sax "parser"

AddressBookReader saxReader = new AddressBookReader();
Transformer transformer = tFactory.newTransformer();
File f = new File(argv[0]);
// Use the parser as a SAX source for input

FileReader fr = new FileReader(f);
BufferedReader br = new BufferedReader(fr);
InputSource inputSource = new InputSource(br);
SAXSource source = new SAXSource(saxReader, inputSource);

• javax.xml.transform.stream
Defines the StreamSource and StreamResult classes, which let you use an I/O stream as an input to or output
from a transformation.
//factory.setNamespaceAware(true);
//factory.setValidating(true);
try {
File stylesheet = new File(argv[0]);
File datafile = new File(argv[1]);

document = builder.parse(datafile);
// Use a Transformer for output

TransformerFactory tFactory = TransformerFactory.newInstance();
StreamSource stylesource = new StreamSource(stylesheet);
Transformer transformer = tFactory.newTransformer(stylesource);
DOMSource source = new DOMSource(document);

}
StAX API
The StAX API exposes methods for iterative, event-based processing of XML documents. XML documents are treated as a filtered series of
events, and infoset states can be stored in a procedural fashion. Moreover, unlike SAX, the StAX API is bidirectional, meaning that it can
both read and write XML documents.
The StAX API is really two distinct API sets: a cursor API and an iterator API.
• Cursor API
As the name implies, the StAX cursor API represents a cursor with which you can walk an XML document from beginning to end.
This cursor can point to one thing at a time, and always moves forward, never backward, usually one infoset element at a time.
The two main cursor interfaces
are XMLStreamReader XMLStreamWriter XMLStreamReader
and . includes accessor methods for
all possible information retrievable from the XML Information model, including document encoding, element names, attributes,
namespaces, text nodes, start tags, comments, processing instructions, document boundaries, and so forth; for example:
public interface XMLStreamReader {

public int next() throws XMLStreamException;
public boolean hasNext() throws XMLStreamException;
public String getText();
public String getLocalName();
public String getNamespaceURI();
// ... other methods not shown
}
A typical StAX program begins by using the XMLInputFactory class to load an implementation dependent instance
of XMLStreamReader:
URL u = new URL("http://www.example.com/data.xml");

InputStream in = u.openStream();
XMLInputFactory factory = XMLInputFactory.newInstance();
XMLStreamReader parser = factory.createXMLStreamReader(in);
The next() method in XMLStreamReader advances the cursor to the next item. Various getter methods to extract
data from the current item. Some of the most important of these getters
include: getName(), getLocalName(), getText(), etc.
For example, here's a simple bit of code that iterates through an XML document and prints out the names of the different
elements it encounters:
while (true) {
int event = parser.next();
if (event == XMLStreamConstants.END_DOCUMENT) {
parser.close();
break;
}
if (event == XMLStreamConstants.START_ELEMENT) {
System.out.println(parser.getLocalName());
}
}
XMLStreamReader, such as getText and getName, to get data at the current

You can call methods on
XMLStreamWriter provides methods that correspond
cursor location.
to StartElement and EndElement event types; for example:
public interface XMLStreamWriter {

public void writeStartElement(String localName) throws XMLStreamException;
public void writeEndElement() throws XMLStreamException;
public void writeCharacters(String text) throws XMLStreamException;
}
This interface provides methods to write elements, attributes, comments, text, and all the other parts of an XML document.
An XMLStreamWriter is created by an XMLOutputFactory like this:
OutputStream out = new FileOutputStream("data.xml");

XMLOutputFactory factory = XMLOutputFactory.newInstance();
XMLStreamWriter writer = factory.createXMLStreamWriter(out);
You write data onto the stream by using

writeXXX methods: writeStartDocument, writeStartElement, writeEndElem
various
ent, writeCharacters,writeComment, writeCDATA, etc. For example, these lines of code write a
simple document:
writer.writeStartDocument("ISO-8859-1", "1.0");
writer.writeStartElement("greeting");
writer.writeAttribute("id", "g1");
writer.writeCharacters("Hello StAX");
writer.writeEndDocument();
The cursor API mirrors SAX in many ways. For example, methods are available for directly accessing string and character
information, and integer indexes can be used to access attribute and namespace information. As with SAX, the cursor API
methods return XML information as strings, which minimizes object allocation requirements.
• Iterator API
The StAX iterator API represents an XML document stream as a set of discrete event objects. These events are pulled by the
application and provided by the parser in the order in which they are read in the source XML document.
XMLEvent, and there are subinterfaces for each event type

The base iterator interface is called
(StartDocument, StartElement, EndElement, etc.). The primary parser interface for reading iterator
events is XMLEventReader, and the primary interface for writing iterator events is XMLEventWriter.
TheXMLEventReader interface contains five methods, the most important of which is nextEvent(), which
returns the next event in an XML stream.XMLEventReader extends java.util.Iterator, which means
that returns from XMLEventReader can be cached or passed into routines that can work with the standard
Java Iterator; for example:
public interface XMLEventReader extends Iterator {

public XMLEvent nextEvent() throws XMLStreamException;
public boolean hasNext();
public XMLEvent peek() throws XMLStreamException;
}
Similarly, on the output side of the iterator API, you have:
public interface XMLEventWriter {

public void flush() throws XMLStreamException;
public void close() throws XMLStreamException;
public void add(XMLEvent e) throws XMLStreamException;
public void add(Attribute attribute) throws XMLStreamException;
}
Comparing Cursor and Iterator APIs
Before choosing between the cursor and iterator APIs, you should note a few things that you can do with the iterator API that you cannot do
with cursor API:
• Objects created from the XMLEvent subclasses are immutable, and can be used in arrays, lists, and maps, and can be
passed through your applications even after the parser has moved on to subsequent events.
• You can create subtypes of XMLEvent that are either completely new information items or extensions of existing items but
with additional methods.
• You can add and remove events from an XML event stream in much simpler ways than with the cursor API.
Similarly, keep some general recommendations in mind when making your choice:
• If you are programming for a particularly memory-constrained environment, like J2ME, you can make smaller, more efficient code
with the cursor API.
• If performance is your highest priority - for example, when creating low-level libraries or infrastructure - the cursor API is more
efficient.
• If you want to create XML processing pipelines, use the iterator API.
• If you want to modify the event stream, use the iterator API.
• If you want to your application to be able to handle pluggable processing of the event stream, use the iterator API.
• In general, if you do not have a strong preference one way or the other, using the iterator API is recommended because it is more
flexible and extensible, thereby "future-proofing" your applications.
When to Use StAX
StAX's bidirectional features, small memory footprint, and low processor requirements give it an advantage over APIs such as JAXB or DOM.
StAX is particularly effective in extracting a small set of information from a large document. The primary drawback in using StAX is that you
get a narrow view of the document - essentially you have to know what processing you will do before reading the XML document. Another
drawback is that StAX is difficult to use if you return XML documents that follow complex schema.
Chapter 6. JAXR
Describe the function of JAXR in Web service architectural model, the two basic levels of business
registry functionality supported by JAXR, and the function of the basic JAXR business objects and
how they map to the UDDI data structures.
• [NONE] blah
JAXR, the Java API for XML Registries, provides a standard API for publication and discovery of Web services through underlying registries.
JAXR does not define a new registry standard. Instead, this standard Java API performs registry operations over a diverse set of registries
and defines a unified information model for describing registry contents. Regardless of the registry provider accessed, your programs use
common APIs and a common information model. The JAXR specification defines a general-purpose API, allowing any JAXR client to access and
interoperate with any business registry accessible via a JAXR provider.
Capability profiles
Because some diversity exists among registry provider capabilities, the JAXR expert group decided to provide multilayer API abstractions
through capability profiles. Each method of a JAXR interface is assigned a capability level, and those JAXR methods with the same capability
level define the JAXR provider capability profile.
Currently, JAXR defines only two capability profiles: level 0 profile for basic features and level 1 profile for advanced features. Level 0's basic
features support so-called business-focused APIs, while level 1's advanced features support generic APIs. At the minimum, all JAXR providers
must implement a level 0 profile. A JAXR client application using only those methods of the level 0 profile can access any JAXR provider in a
portable manner. JAXR providers for UDDI must be level 0 compliant.
JAXR providers can optionally support the level 1 profile. The methods assigned to this profile provide more advanced registry capabilities
needed by more demanding JAXR clients. Support for the level 1 profile also implies full support for the level 0 profile. JAXR providers for
ebXML must be level 1 compliant. A JAXR client can discover the capability level of a JAXR provider by invoking methods on
the CapabilityProfile interface. If the client attempts to invoke capability level methods unsupported by the JAXR provider,
UnsupportedCapabilityException.
the provider will throw an
When publication or discovery of Web services is required, UDDI is the mechanism the WS-I Basic Profile has adopted to describe Web
service providers and the Web services they provide.
NOTE, because WS-I BP sanctions the use of UDDI, not ebXML, we MUST use JAXR level 0 profile.
RegistryService interfaces
The JAXR provider supports capability profiles that group the methods on JAXR interfaces by capability
level.RegistryService exposes the JAXR provider's key interfaces, that is, Web services discovery and registration. The JAXR
RegistryService interface by invoking thegetRegistryService() method on
client can obtain an instance of the
the connection established between the JAXR client and JAXR provider. Once the JAXR client has the RegistryService, it can
obtain the primary registry interfaces and perform life-cycle management and query management through the JAXR provider.
The JAXR specification defines two life-cycle management interfaces:
1. BusinessLifeCycleManager - for level 0 (we MUST use this interface according to WS-I BP 1.1)
2. LifeCycleManager - for level 1 (we MUST NOT use this interface according to WS-I BP 1.1)
BusinessLifeCycleManager defines a simple business-level API for life-cycle management. This interface resembles the
publisher's API in UDDI, which should prove familiar to the UDDI developer. For its part, LifeCycleManager interface provides
complete support for all life-cycle management needs using a generic API.
Life-cycle management includes creating, saving, updating, deprecating, and deleting registry objects. In addition,
the LifeCycleManager provides several factory methods to create JAXR information model objects. In general, life-cycle
management operations are privileged, while a user can use query management operations for browsing the registry.
JAXR's top-level interface for query management, QueryManager, has two extensions:
1. BusinessQueryManager - for level 0 (we MUST use this interface according to WS-I BP 1.1)
2. DeclarativeQueryManager - for level 1 (we MUST NOT use this interface according to WS-I BP 1.1)
Query management deals with querying the registry for registry data. A simple business-level API,
theBusinessQueryManager interface provides the ability to query for the most important high-level interfaces in the
Organization, Service, ServiceBinding, ClassificationScheme,
information model, such as
andConcept. Alternatively, the DeclarativeQueryManager interface provides a more flexible, generic API, enabling
the JAXR client to perform ad hoc queries using a declarative query language syntax. Currently, the only declarative syntaxes JAXR supports
are SQL-92 and OASIS/ebXML Registry Filter Queries. As noted in the JAXR specification, ebXML registry providers optionally support SQL
queries. If a registry provider does support SQL queries, the JAXR ebXML provider will throw
an UnsupportedCapabilityException on DeclarativeQueryManager methods.
JAXR information model
Invoking life-cycle and query management methods on the JAXR provider requires the JAXR client to create and use the JAXR information
model objects. The JAXR information model resembles the one defined in the ebXML Registry Information Model 2.0, but also accommodates
the data types defined in the UDDI Data Structure Specification. Although developers familiar with the UDDI information model might face a
slight learning curve, once understood, the JAXR information model will provide a more intuitive and natural interface to most developers.
Most JAXR information-model interfaces are derived from the abstract RegistryObject interface, which defines the common state
key, name, and description.
information, called attributes, that all registry objects share. Example attributes include:
The InternationalString interface defines attributes that must be internationalization compatible, such
as name and description. The InternationalString interface contains a collection
of LocalizedStrings, where each LocalizedString defines locale, character set, and string content.
TheRegistryObject interface also defines collections

ofClassification, ExternalIdentifier, ExternalLink, and Association objects.
TheBusinessQueryManager often uses those collections as parameters in its find methods.
RegistryObject interface, the concrete

Also specializations of the
interfaces Organization, Service, ServiceBinding, Concept,
and ClassificationSchemeprovide additional state information. For example, the Organization interface defines a
collection of Service objects, and Service defines a collection ofServiceBinding objects.
A ServiceBinding might contain a collection of SpecificationLink objects. UDDI developers should be familiar with
these concrete interfaces; they map quite well to major UDDI data types shown in the table below:
Table 6.1. UDDI-to-JAXR information model mappings
JAXR Information Model UDDI Data Model
Organization businessEntity
A business, such as a corporation whose data is contained in the registry, is represented

by an Organization instance. An Organization can have The businessEntity structure contains information about a
particular business organization and holds references to the services it
multiple Organizations under it or can refer to another organization as a offers.businessEntity is the highest in the hierarchy and
parent. An Organization can offer one or more services, represented businessEntity is
contains descriptive information. Each
byService objects which can be accessed via Collection identified by its businessKey. If itsbusinessKey is not
Organization.getServices() method. specified at publication time, the registry will automatically generate a key.
businessService
businessService entry indicates a logical service and holds

descriptive information about a Web service in business terms.
Service
A businessService is a child of
a businessEntity that provides the service. Information about
Each Service can have multiple ServiceBinding objects that specify how a businessService can be instantiated is contained within
the details about the protocol binding information for that service.
abindingTemplate. Each businessService is
has a unique identifier -serviceKey. This value is assigned by each

UDDI operator and cannot be edited by the publisher. It also contains the key
businessEntity - businessKey.
to its parent
ServiceBinding
ServiceBinding has attributes that describe the location where the service bindingTemplate
can be accessed. A ServiceBinding is associated with one or
more SpecificationLink objects that point to the technical A bindingTemplate contains information necessary for a client
specifications defining the service (e.g., a WSDL file for the Web to invoke a service. It specifies the information for a particular Web service
service).ServiceBinding instances and provides the URL of the service where it can be invoked.
areRegistryObject objects that represent technical information on a The bindingTemplate also contains references to tModels
specific way to access a specific interface offered by a Service instance. bindingTemplate is a
as well as service-specific settings. A
A ServiceBinding may have a set child of a businessService.
ofSpecificationLink instances. Maps to
a bindingTemplate in UDDI.
ClassificationScheme
A ClassificationScheme instance represents a taxonomy that may

RegistryObject
be used to classify or categorize instances. The
classification scheme, or taxonomy, can be internal or external to the registry, meaning
that the structure of the taxonomy is defined internal to the registry or is represented
somewhere outside the registry and is represented by
aClassificationScheme interface. A good example of an external
taxonomy for e-business is that of North American Industry Classification System
(NAICS) devised by the U.S. Census Bureau. NAICS is a classification scheme used to
classify businesses and services by the industry to which they belong and the business
processes they follow.
tModel
Concept
The Concept interface is used to represent taxonomy elements and their structural
relationship with each other in order to describe an internal
taxonomy. Concept instances are used to define tree structures where the root of
ClassificationScheme instance and each node in the
the tree is a
tree is a Concept instance. As any RegistryObject,
a Concept may be classified and also associated with a set of external identifiers
and links.
Association
A RegistryObject instance may be associated with zero or

more RegistryObject instances. The information model defines
anAssociation interface, an instance of which may be used to associate any
two RegistryObject instances. An Association instance publisherAssertion

represents an association between a source RegistryObject and a
targetRegistryObject. These are referred to
as sourceObject andtargetObject for
the Association instance. It is important which object is
the sourceObject and which is the targetObject as it

determines the directional semantics of an Association.

Each Association must have an associationType attribute
that identifies the type of that association. The associationType attribute
is a reference to an enumeration Conceptas defined by the
predefined associationType ClassificationScheme in

the JAXR specification. An association may need to be confirmed by the parties whose
objects are involved in that Association.
ExternalLink
ExternalLink instances model a named URI to content that may reside

outside the registry. RegistryObject may be associated with any number
overviewDoc
of ExternalLink instances to annotate a RegistryObject with
external links to external content. Consider the case where a Submitting Organization
submits a repository item (e.g. a DTD) and wants to associate some external content to
that object (e.g. the Submitting Organization's home page).
The ExternalLink enables this capability.
Classification
The Classification interface is used to

classify RegistryObjectinstances. A RegistryObject may be
classified along multiple dimensions by adding zero or
more Classification instances to theRegistryObject. For
example, anOrganization may be classified by its industry, by the products keyedReference (in categoryBag)
it sells and by its geographical location. In this example
theRegistryObject would have at least
threeClassificationinstances added to it.
The RegistryObject interface provides
severaladdClassification methods to allow a client to
add Classificationinstances to a RegistryObject.
ExternalIdentifier
ExternalIdentifier instances provide the additional identifier

information to RegistryObject such as DUNS number, Social Security
Number, or an alias name of the organization. The attribute name inherited

keyedReference (in identifierBag)
from RegistryObject is used to contain the identification scheme (Social
Security Number, etc), and the attribute value contains the actual information.
Each RegistryObjects may have 0 or more association(s)
with ExternalIdentifier.
User contact
Collection of ExternalIdentifier instances identifierBag
Collection of Classification instances categoryBag
PostalAddress address
SpecificationLink
A SpecificationLink provides the linkage between

a ServiceBindingand one of its technical specifications that describes how The union
to use the service using the ServiceBinding. For example, of tModelInstanceInfo and instanceDetails
a ServiceBinding may have
aSpecificationLink instance that describes how to access the service

using a technical specification in form of a WSDL document. It serves the same purpose
as the union
of tModelInstanceInfo andinstanceDetails in UDDI.
UDDI Example Mapped to JAXR:

Table 6.2. Mapping of UDDI Inquiry API Calls To JAXR ( BusinessQueryManager)
UDDI Method BusinessQueryManager Method
find_binding findServiceBindings
find_business findOrganizations
findAssociatedObjects(RegistryObject,
find_related_business
asociationType)
find_service findServices
find_tModel findConcepts, findClassificationSchemes
get_bindingDetail Not needed. Handled transparently by JAXR provider

UDDI Method BusinessQueryManager Method
get_businessDetail Not needed. Handled transparently by JAXR provider
Unsupported.
get_businessDetailExt Use RegistryService.makeRegistrySpecificRequest
get _serviceDetail Not needed. Handled transparently by JAXR provider
get_tModelDetail Not needed. Handled transparently by JAXR provider
Table 6.3. Mapping of UDDI Publisher API Calls to JAXR ( BusinessLifeCycleManager)
UDDI Method BusinessLifeCycleManager Method
saveAssociations(associations,
add_publisherAssertions
replace), Association.confirm
delete_binding deleteServiceBindings
delete_business deleteOrganizations
delete_publisherAssertions deleteAssociations
delete_service deleteServices
deleteClassificationsSchemes, deleteConcepts.
delete_tModel does not delete the tModel. It simply hides it

NOTE, In UDDI
delete_tModel from find_tModel calls.
The QueryManager.getRegistryObjectcalls will still return the
deleted tModel after
a deleteConcepts ordeleteClassificationSchemes call.
discard_authToken Not needed. Handled transparently by JAXR provider
findAssociations(findQulifiers,
get_assertionStatusReport associationTypes, sourceObjectConfirmed,
targetObjectConfirmed)
get_authToken Not needed. Handled transparently by JAXR provider
get_publisherAssertions QueryManager.getRegistryObjects(objectType)
get_registeredInfo QueryManager.getRegistryObjects
save_binding saveServiceBindings
save_business saveOrganizations
save_service saveServices
save_tModel saveClassificationsSchemes, saveConcepts
set_publisherAssertions saveAssociations(assiations,replace)
The JAXR specification defines the following information model interfaces:

• Organization instance is a RegistryObject that provides information on an organization that has been
published to the underlying registry.
• Service instance is a RegistryObject that provides information on services (e.g., Web Service) offered by
an Organization. An Organization can have a set of Service objects.
• ServiceBinding instance is a RegistryObject that represents technical information on how to access a
specific interface offered by a Serviceinstance. A Service can have a collection of ServiceBinding objects.
• SpecificationLink links a ServiceBinding with its technical specifications that describe how to use the
service. For example, a ServiceBinding might have SpecificationLink instances that describe how to
access the service using a technical specification in the form of a WSDL (Web Services Description Language) document.
• ClassificationScheme instance represents a taxonomy that you can use to classify or
categorize RegistryObject instances.
• Classification instances classify a RegistryObject instance using a classification scheme. Because
classification facilitates rapid discovery ofRegistryObject instances within the registry, the ability to
classify RegistryObject instances in a registry is one of the registry's most significant features.
• Concept instance represents an arbitrary notion, or concept. It can be virtually anything.

• Association instances define many-to-many associations between objects in the information model.
• RegistryPackage instances group together logically related RegistryObject instances.
A RegistryPackage might contain any number ofRegistryObject instances, and
a RegistryObject can be a member of any number of RegistryPackage objects.
• ExternalIdentifier instances provide identification information to a RegistryObject. You can base

such identification on well-known identification schemes such as DUNS (D&B's Data Universal Numbering System) number and
social security number.
• ExternalLink instances provide a link to content managed outside the registry using a URI (uniform resource
identifier).
• Slot instances dynamically add arbitrary attributes to RegistryObject instances at runtime, an ability that enables
extensibility within the information model.
• Most interfaces in the JAXR information model extend theExtensibleObject interface. It provides methods that
allow the addition, deletion, and lookup of Slot instances.
• AuditableEvent instances are RegistryObject instances that provide an audit trail
for RegistryObject instances.
• Affiliated with Organization, User objects are RegistryObject instances that provide information about
registered users within the registry. You useUser objects in a RegistryObject's audit trail.
• PostalAddress defines a postal address's attributes. Currently, it provides address information for a User and
an Organization.
Create JAXR client to connect to a UDDI business registry, execute queries to locate services that
meet specific requirements, and publish or update information about a business service.
• [NONE] blah
Establish a connection between a JAXR client and JAXR provider
The JAXR client must first connect to the JAXR provider. This connection contains the client state and preference information used when the
JAXR provider invokes methods on the registry provider.
Before executing any registry operation, a JAXR client connects with a JAXR provider as shown in the following code:
import javax.xml.registry.*;
...
// Get an instance of ConnectionFactory object
ConnectionFactory connFactory = ConnectionFactory.newInstance();
// Define connection configuration properties

// Set URLs of the query service and publishing service
Properties props = new Properties();
props.setProperty("javax.xml.registry.queryManagerURL", "http://uddi.ibm.com/testregistry/inquiryapi");
props.setProperty("javax.xml.registry.lifeCycleManagerURL",
"https://uddi.ibm.com/testregistry/protect/publishapi");
// If JAXR client goes outside firewall for query, set up HTTP proxy
props.setProperty("com.sun.xml.registry.http.proxyHost", "myhost.mydomain");
props.setProperty("com.sun.xml.registry.http.proxyPort", "8080");
// If JAXR client goes outside firewall for update, set up HTTPS proxy
props.setProperty("com.sun.xml.registry.https.proxyHost", "myhost.mydomain");
props.setProperty("com.sun.xml.registry.https.proxyPort", "8080");
// Set up properties and create Connection object

connFactory.setProperties(props);
Connection connection = connFactory.createConnection();
If the JAXR client wishes to submit data to the registry, the client must set authentication information on the connection. Note that the
establishment of this authentication information with the registry provider is registry-provider specific and negotiated between the registry
provider and the publishing user, often in the form of a Web-based interface. The user does not use the JAXR API to negotiate and establish
an account with the registry provider. After establishing a connection, the JAXR client can obtain RegistryService interfaces for
Web Services discovery and publishing:
// Get RegistryService object
RegistryService rs = connection.getRegistryService();
// Get QueryManager and LifeCycleManager objects for

// JAXR Business API (Capability Level 0 - UDDI oriented)
BusinessQueryManager bqm = rs.getBusinessQueryManager();
BusinessLifeCycleManager blcm = rs.getBusinessLifeCycleManager();
BusinessLifeCycleManager and
This example also demonstrates how to obtain the business-focused interfaces, the
the BusinessQueryManager, to perform registry operations shown in later examples:
/*
* Establish a connection to a JAXR provider.
* Set authentication information, communication preference.
* Get business-focused discovery and publish interfaces.
*/
public void makeConnection() {
// URLs for RegistryServer
String queryURL = "http://localhost/RegistryServerServlet";
String publishURL = "http://localhost/RegistryServerServlet";
/*
* Define connection configuration properties.
* For simple queries, you need the query URL.
* To use a life-cycle manager, you need the publish URL.
*/
Properties props = new Properties();
props.setProperty("javax.xml.registry.queryManagerURL", queryUrl);
props.setProperty("javax.xml.registry.lifeCycleManagerURL", publishUrl);
try {
// Create the connection, passing it the configuration properties
ConnectionFactory factory = ConnectionFactory.newInstance();
factory.setProperties(props);
connection = factory.createConnection();
System.out.println("Created connection to registry");
// Get registry service and managers

RegistryService rs = connection.getRegistryService();
// Get the capability profile

CapabilityProfile capabilityProfile = registryService.getCapabilityProfile();
if (capabilityProfile.getCapabilityLevel() == 0) {
System.out.println("Capability Level 0, Business Focused API");
}
// Get manager capabilities from registry service

BusinessQueryManager bqm = rs.getBusinessQueryManager();
BusinessLifeCycleManager blcm = rs.getBusinessLifeCycleManager();
System.out.println("Got registry service, query manager and lifecycle manager");
// Set client authorization information for privileged registry operations

PasswordAuthentication passwdAuth = new PasswordAuthentication(username,
password.toCharArray());
Set creds = new HashSet();
creds.add(passwdAuth);
// Set credentials on the JAXR provider

connection.setCredentials(creds);
System.out.println("Established security credentials");
// Set communication preference

connection.setSynchronous(true);
} catch (Exception e) {
if (connection != null) {
try {
connection.close();
} catch (JAXRException je) {
}
}
}
}
Registry operation: execute queries to locate services
Now that the JAXR client has established a connection with the JAXR provider and obtained
the BusinessQueryManager and BusinessLifeCycleManager from
the RegistryService interface, the client can now invoke methods on these interfaces. Often, a JAXR client will wish to discover
the services an organization offers. To do so, the JAXR client would invoke methods on the BusinessQueryManager.
QueryManager. There are two extensions

JAXR defines top-level interface for query management called
of QueryManager interface and they are
calledBusinessQueryManager and DeclarativeQueryManager.
Interface BusinessQueryManager provides a simple business-level API that provides the ability to query for the most
important high-level interfaces in the information model.
Interface DeclarativeQueryManager provides a more flexible generic API that provides the ability to perform ad hoc
queries using a declarative query language syntax. Currently the only declarative syntax supported is SQL-92. In version 1 of JAXR, it is
optional for a JAXR provider to provide support for SQL query syntax.
This example shows how to find all the organizations in the registry whose names begin with a specified string, qString, and to sort
them in alphabetical order:
// Define find qualifiers. Sort by name.

Collection findQualifiers = new ArrayList();
findQualifiers.add(FindQualifier.SORT_BY_NAME_DESC);
// Define name patterns. Organization name begins with qString.

Collection namePatterns = new ArrayList();
namePatterns.add(qString);
// Find organizations using the name

BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, null);
Collection orgs = response.getCollection();
Another example shows how to find all the organizations in the registry using case sensitive name pattern:
// Define find qualifiers. Do case sensitive search.

findQualifiers.add(FindQualifier.CASE_SENSITIVE_MATCH);
// Define name patterns. Organization name contains qString.

Collection namePatterns = new ArrayList();
namePatterns.add("%" + qString + "%");
// Find organizations using the name

BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, null);
Steps for finding Organization by Classification:
1. Decide on classification scheme (taxonomy).

2. Build a classification within a particular classification scheme.
3. Specify the classification as an argument to the findOrganizations method.
To find organizations by classification, you need to establish the classification within a particular classification scheme and then specify the
classification as an argument to the findOrganizations method. The following code fragment finds all organizations that
correspond to a particular classification within the North American Industry Classification System (NAICS) taxonomy:
// Get classification scheme. Taxonomy is NAICS.

ClassificationScheme cScheme = bqm.findClassificationSchemeByName(null, "ntis-gov:naics");
// Build classifications
Classification classification = blcm.createClassification(cScheme,
"Snack and Nonalcoholic Beverage Bars", "722213");
Collection classifications = new ArrayList();
classifications.add(classification);
// Find organizations via Classification

BulkResponse response = bqm.findOrganizations(null, null, classifications, null, null, null);
To find WSDL Specification Instances: use classification scheme of " uddi-org:types ". In JAXR, a concept is used to hold
information about a WSDL specification. JAXR client must find the specification concepts first, then the organizations that use those concepts.
Once you get organizations, you can then get services and bindingTemplates:
// Get classification scheme. Taxonomy is uddi-org:types.

String schemeName = "uddi-org:types";
ClassificationScheme uddiOrgTypes = bqm.findClassificationSchemeByName(null, schemeName);
// Create a classification, specifying the scheme

// and the taxonomy name and value defined for WSDL
// documents by the UDDI specification.
Classification wsdlSpecClassification = blcm.createClassification(uddiOrgTypes, "wsdlSpec", "wsdlSpec");
classifications.add(wsdlSpecClassification);
// Find concepts
BulkResponse br = bqm.findConcepts(null, null, classifications, null, null);
// Display information about the concepts found

Collection specConcepts = br.getCollection();
Iterator iter = specConcepts.iterator();
if (!iter.hasNext()) {
System.out.println("No WSDL specification concepts found");
} else {
while (iter.hasNext()) {
Concept concept = (Concept) iter.next();
String name = getName(concept);
Collection links = concept.getExternalLinks();
System.out.println("Specification Concept: Name: " + name +
"Key: " + concept.getKey().getId() + "Description: " +
getDescription(concept));
if (links.size() > 0) {
ExternalLink link = (ExternalLink) links.iterator().next();
System.out.println("URL of WSDL document: '" + link.getExternalURI() +
"'");
}
// Find organizations that use this concept

Collection specConcepts1 = new ArrayList();
specConcepts1.add(concept);
br = bqm.findOrganizations(null, null, null, specConcepts1, null, null);
// Display information about organizations
...
}
}
Finding Services and Service Bindings from Organization:
Iterator orgIter = orgs.iterator();

while (orgIter.hasNext()) {
Organization org = (Organization) orgIter.next();
Collection services = org.getServices();
Iterator svcIter = services.iterator();
while (svcIter.hasNext()) {
Service svc = (Service) svcIter.next();
Collection serviceBindings = svc.getServiceBindings();
Iterator sbIter = serviceBindings.iterator();
while (sbIter.hasNext()) {
ServiceBinding sb = (ServiceBinding) sbIter.next();
}
}
}
Another example use case might be the following:
A user browsing the UDDI registry wishes to find an organization that provides services of the NAICS (North American Industry Classification
System) type Computer Systems Design and Related Services in the United States. To perform this query with JAXR, the user would invoke
a findOrganization() method with classification listed under the well-known taxonomies NAICS and ISO 3166 Geographic
Code System (ISO 3166). As JAXR provides a taxonomy service for these classifications, the client can easily access the classification
information needed to be passed as findOrganization() parameters. A sample of this query to the taxonomy service and
registry follows below:
public void findOrganizations() throws JAXRException {
// Search criteria -- Organizations found will return in this sort order

findQualifiers.add(FindQualifier.SORT_BY_NAME_DESC);
// Query the JAXR taxonomy service

ClassificationScheme naics = businessQueryManager.findClassificationSchemeByName(
findQualifiers, "ntis-gov:naics:1997");
// Create the classification that will be a parameter to findOrganization() method

Classification computerSystemsDesign = businessLifeCycleManager.createClassification(
naics, "Computer Systems Design and Related Services", "5415");
// Query the taxonomy service

ClassificationScheme geography = businessQueryManager.findClassificationSchemeByName(
findQualifiers, "iso-ch:3166:1999");
// Create the classification passed as a parameter to findOrganization() method.

Classification us = businessLifeCycleManager.createClassification(
geography, "United States", "US");
// Add classifications to the classifications collection parameter

classifications.add(computerSystemsDesign);
classifications.add(us);
// Invoke the findOrganizations() method on BusinessQueryManager

BulkResponse bulkResponse = businessQueryManager.findOrganizations(
findQualifiers, null, classifications, null, null, null);
if (bulkResponse.getStatus() == JAXRResponse.STATUS_SUCCESS) {
System.out.println("Found Organization located in the United States ");
System.out.println("categorized Computer Systems Design and Related Service ");
}
}
Most calls invoked on the registry provider via the JAXR provider return a BulkResponse that contains any registry exceptions
encountered and a collection of concrete RegistryObject instances or RegistryObject keys. To ensure that a registry
invocation always returns a response, any exceptions generated by the registry provider are wrapped in
a RegistryException and stored in the BulkResponse's exceptions collection. In the case
of findXXX(...) methods, anyRegistryObjects found are contained in the BulkResponse collection.
For the above findOrganization() method, the BulkResponse contains a collection

of Organization objects found in the registry provider that match the classifications passed as parameters to the method. However,
these Organization objects provide limited information about the Organization and itsService objects such
as key, name, and description. Another value-added feature of JAXR is the incremental loading
of RegistryObject details. For instance, in the case of a JAXR UDDI provider, a JAXR findOrganization() method
transforms to a UDDI find_Business request. After invocation, the find_Businessrequest returns minimal business and
service information such as ID, name, and description. Using UDDI APIs, a UDDI client would need to make an additional call such
as get_BusinessDetail() to retrieve the organization details. With JAXR, the JAXR UDDI provider performs this invocation to
Organization and other RegistryObject details
the registry provider on an as-needed basis. The JAXR client can access
by using the getXXX() methods on the JAXR information model interfaces. The getOrganizationDetail() method
demonstrates how a JAXR client would obtain full Organization details:
public void getOrganizationDetail(BulkResponse bulkResponse) throws JAXRException {

// Get a collection of Organizations from BulkResponse
Collection organizations = bulkResponse.getCollection();
// Iterate through the collection to get an individual Organization

Iterator orgIter = organizations.iterator();
while (orgIter.hasNext()) {
Organization organization = (Organization) orgIter.next();
// Get a collection of Services from an Organization

Collection services = organization.getServices();
// Iterate through the collection to get an individual Service

Iterator serviceIter = services.iterator();
while (serviceIter.hasNext()) {
Service service = (Service) serviceIter.next();
// Get a collection of ServiceBindings from a Service

Collection serviceBindings = service.getServiceBindings();
// Iterate through the collection to get an individual ServiceBinding

Iterator sbIter = serviceBindings.iterator();
while (sbIter.hasNext()) {
ServiceBinding serviceBinding = (ServiceBinding) sbIter.next();
// Get URI of the service. You can access the service through this URI.
String accessURI = serviceBinding.getAccessURI();
System.out.println("Access the service " + service.getName().getValue()
+ " at this URI " + accessURI);
// Get a collection of SpecificationLinks from a ServiceBinding.

// SpecificationLinks provide further technical details needed to access the service.
Collection specificationLinks = serviceBinding.getSpecificationLinks();
// Iterate through the collection to get an individual SpecificationLink

Iterator linkIter = specificationLinks.iterator();
while (linkIter.hasNext()) {
SpecificationLink specificationLink = (SpecificationLink) linkIter.next();
// Get a collection of ExternalLinks from SpecificationLink

// An ExternalLink points to technical detail necessary to invoke the service
Collection externalLinks = specificationLink.getExternalLinks();
// Iterate through the collection to get an ExternalLink

Iterator elinkIter = externalLinks.iterator();
while (elinkIter.hasNext()) {
ExternalLink externalLink = (ExternalLink) elinkIter.next();
// The externalURI is the pointer to the technical details

// necessary to invoke the service
String externalURI = externalLink.getExternalURI();
System.out.println(
" Use the technical detail at this URI, "
+ externalURI + " to invoke the service, " +
+ service.getName().getValue());
// Obtain usage description

InternationalString usageDescription = specificationLink.getUsageDescription();
// Any parameters necessary to invoke service are in usageParameter collection

Collection usageParameters = specificationLink.getUsageParameters();
// Get the specification concept from the specification link

// This specificationConcept is equivalent to the tModel registered as
// the technical specification
Concept specificationConcept = (Concept) specificationLink.getSpecificationObject();
}
}
}
}
}
Registry operation: publish or update information about a business service
The JAXR client also publishes Web services, another important registry operation. In addition to discovering partner organization information
and services, an organization will want to register its information and services in the registry for partner use. If a JAXR client wishes to
LifeCycleManager or the more
publish an organization and its services to a registry, the client uses the
focused BusinessLifeCycleManager. Clients familiar with UDDI should use
theBusinessLifeCycleManager , which provides methods for saving information to the registry provider. Since this is a
privileged operation, the user must set authentication information on the JAXR connection. Note that the JAXR provider, not the JAXR client,
performs authentication with the registry provider. The JAXR provider negotiates this authentication with the registry provider on an as-
needed basis, and the authentication is completely transparent to the JAXR client.
LifeCycleManager interface
JAXR specification defines two interfaces –
and BusinessLifeCycleManager interface. LifeCycleManager interface provides complete support for all life
cycle management needs using a generic API. BusinessLifeCycleManager interface defines a simple business-level API
for life cycle management of some important high-level interfaces in the information model. This interface provides no new functionality
beyond that of LifeCycleManager . The goal of defining this interface is to provide an API similar to that of the publisher’s API in
UDDI. The intent is to provide a familiar API to UDDI developers.
Before it can submit data, the client must send its username and password to the registry in a set of credentials. The following code fragment
shows how to do this:
// Set userid/password
String username = "myUserName";
String password = "myPassword";
// Create authentication object

PasswordAuthentication passwdAuth = new PasswordAuthentication(username, password.toCharArray());
// Set the credential with registry provider

Set creds = new HashSet();
creds.add(passwdAuth);
connection.setCredentials(creds);
The client creates the organization and populates it with data before saving it. An Organization object is one of the more complex
data items in the JAXR API. It normally includes the following:
1. A Name object.
2. A Description object.
3. A Key object, representing the ID by which the organization is known to the registry.
4. A PrimaryContact object, which is a User object that refers to an authorized user of the registry. A User object
normally includes a PersonName object and collections
of TelephoneNumber and EmailAddress objects.
5. A collection of Classification objects.
6. Service objects and their associated ServiceBinding objects.
Creating an Organization:
// Create organization name and description

Organization org = blcm.createOrganization("The Coffee Break");
InternationalString s = blcm.createInternationalString("Purveyor of the finest coffees");
org.setDescription(s);
// Create primary contact, set name

User primaryContact = blcm.createUser();
PersonName pName = blcm.createPersonName("Jane Doe");
primaryContact.setPersonName(pName);
// Set primary contact phone number

TelephoneNumber tNum = blcm.createTelephoneNumber();
tNum.setNumber("(800) 555-1212");
Collection phoneNums = new ArrayList();
phoneNums.add(tNum);
primaryContact.setTelephoneNumbers(phoneNums);
// Set primary contact email address

EmailAddress emailAddress = blcm.createEmailAddress("jane.doe@TheCoffeeBreak.com");
Collection emailAddresses = new ArrayList();
emailAddresses.add(emailAddress);
primaryContact.setEmailAddresses(emailAddresses);
// Set primary contact for organization

org.setPrimaryContact(primaryContact);
Steps of Adding Classification:

1. Use BusinessQueryManager to find the taxonomy to which the organization wants to belong to.
2. Create a classification using the classification scheme and a concept (a taxonomy element) within the classification scheme.
3. Add the classification to the organization.
Example of Adding Classification to Organization:
// Set classification scheme to NAICS

ClassificationScheme cScheme = bqm.findClassificationSchemeByName(null, "ntis-gov:naics");
// Create and add classification

Classification classification = blcm.createClassification(cScheme, "Snack and Nonalcoholic Beverage Bars",
"722213");
classifications.add(classification);
org.addClassifications(classifications);
JAXR Provider Must Provide Taxonomies of:
1. The North American Industry Classification System (NAICS)
http://www.census.gov/epcd/www/naics.html
2. Universal Standard Products and Services Classification (UNSPSC)
http://www.eccma.org/unspsc/
3. ISO 3166 country codes classification system maintained by the International Organization for Standardization (ISO)
http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
Suppose the organization "Fly Away Airline Travel Agents" has a Web-based airline reservation service that its partner travel agencies must
be able to use. The following code creates such a business and saves it to the registry. The business has contact information, a set of services
it offers, and technical information for accessing those services:
public void saveOrganization() throws JAXRException {
// Create Organization in memory

Organization org = businessLifeCycleManager.createOrganization("Fly Away Airline Travel Agents");
// Create User -- maps to Contact for UDDI

User user = businessLifeCycleManager.createUser();
PersonName personName = businessLifeCycleManager.createPersonName("Marie A Traveler");
TelephoneNumber telephoneNumber = businessLifeCycleManager.createTelephoneNumber();

telephoneNumber.setNumber("781-333-3333");
telephoneNumber.setType("office");
Collection numbers = new ArrayList();
numbers.add(telephoneNumber);
EmailAddress email = businessLifeCycleManager.createEmailAddress("marieb@airlinetravel.com",

"office");
Collection emailAddresses = new ArrayList();
emailAddresses.add(email);
user.setPersonName(personName);
Collection telephoneNumbers = new ArrayList();
telephoneNumbers.add(telephoneNumber);
user.setTelephoneNumbers(telephoneNumbers);
user.setEmailAddresses(emailAddresses);
org.setPrimaryContact(user);
// Create service with service name and description

Service service = businessLifeCycleManager.createService("Fly Away Airline Reservation Service");
service.setDescription(businessLifeCycleManager.createInternationalString("Flight Reservation
Service"));
// Create serviceBinding
ServiceBinding serviceBinding = businessLifeCycleManager.createServiceBinding();
serviceBinding.setDescription(businessLifeCycleManager.
createInternationalString("Information for airline reservation service access"));
//Turn validation of URI off

serviceBinding.setValidateURI(false);
serviceBinding.setAccessURI("http://www.airlinetravel.com:8080/services.reservations.html ");
// Create the SpecificationLink information
SpecificationLink specificationLink = businessLifeCycleManager.createSpecificationLink();
// Set usage description

specificationLink.setUsageDescription(businessLifeCycleManager.
createInternationalString("Search for Reservations when prompted"));
String usageParameter = "Enter travel agent id when prompted";
Collection usageParameters = new ArrayList();
usageParameters.add(usageParameter);
// Set usage parameters

specificationLink.setUsageParameters(usageParameters);
// Set specificationConcept on the specificationLink

Concept httpSpecificationConcept =
(Concept) businessLifeCycleManager.createObject(businessLifeCycleManager.CONCEPT);
Key httpSpecificationKey =
businessLifeCycleManager.createKey("uuid:68de9e80-ad09-469d-8a37-088422bfbc36");
httpSpecificationConcept.setKey(httpSpecificationKey);
specificationLink.setSpecificationObject(httpSpecificationConcept);
// Add the specificationLink to the serviceBinding

serviceBinding.addSpecificationLink(specificationLink);
// Add the serviceBinding to the service

service.addServiceBinding(serviceBinding);
// Add the service to the organization

org.addService(service);
// Add classifications to the organization

ClassificationScheme naics =
businessQueryManager.findClassificationSchemeByName(null, "ntis-gov:naics");
Classification classification =
businessLifeCycleManager.createClassification(naics, "Air Transportation", "481");
org.addClassification(classification);
Collection orgs = new ArrayList();
orgs.add(org);
// Save organization and whole tree of related objects

BulkResponse br = businessLifeCycleManager.saveOrganizations(orgs);
if (br.getStatus() == JAXRResponse.STATUS_SUCCESS) {
System.out.println("Successfully saved the organization to the registry provider.");
}
}
Given a scenario, implement Java EE based web service web-tier and/or EJB-tier basic security mechanisms, such as mutual
authentication, SSL, and access control.
Prev Chapter 8. Security Next
Given a scenario, implement Java EE based web service web-tier and/or EJB-tier basic security
mechanisms, such as mutual authentication, SSL, and access control.
• [NONE] blah
HTTP Basic Authentication
HTTP Basic Authentication requires that the server request a user name and password from the web client and verify that the user name and
password are valid by comparing them against a database of authorized users. When basic authentication is declared, the following actions
occur:
1. A client requests access to a protected resource.
2. The web server returns a dialog box that requests the user name and password.
3. The client submits the user name and password to the server.
4. The server authenticates the user in the specified realm and, if successful, returns the requested resource.
The following example shows how to specify basic authentication in your deployment descriptor:
<login-config>
<auth-method>BASIC</auth-method>
</login-config>
HTTP basic authentication is not a secure authentication mechanism. Basic authentication sends user names and passwords over the Internet
as text that is Base64 encoded, and the target server is not authenticated. This form of authentication can expose user names and
passwords. If someone can intercept the transmission, the user name and password information can easily be decoded. However, when a
secure transport mechanism, such as SSL, or security at the network level, such as the IPSEC protocol or VPN strategies, is used in
conjunction with basic authentication, some of these concerns can be alleviated.
Example application that uses HTTP basic authentication in a JAX-WS service
1. Annotate the Service
Annotations are used to specify which users are authorized to access which methods of the service. In this simple example,
the @RolesAllowedannotation is used to specify that users in the application role of basicUser are authorized
sayHello(String name) method. This application role must be linked to a group of users on the
access to the
Application Server.
The code snippet is as follows:
import javax.annotation.security.RolesAllowed;
@WebService()
private String message = new String("Hello, ");
@WebMethod()
@RolesAllowed("basicUser")
public String sayHello(String name) {
return message + name + ".";
}
}
2. Add Security Elements to the Deployment Descriptor

To enable basic authentication for the service, add security elements to the application deployment descriptor, web.xml. The
security elements that need to be added to the deployment descriptor include the security-
constraint and login-config elements:
<web-app version="2.5" ...>

<display-name>Basic Authentication Security Example</display-name>
<servlet>
<display-name>HelloService</display-name>
<servlet-name>HelloService</servlet-name>
<servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>HelloService</servlet-name>
<url-pattern>/hello</url-pattern>
</servlet-mapping>
<security-constraint>
<web-resource-collection>
<web-resource-name>WRCollection</web-resource-name>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>basicUser</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
</login-config>
<security-role>
<role-name>basicUser</role-name>
</security-role>
</web-app>
3. Set Security Properties In The Client Code
You can do the following:
HelloService service = new HelloService();

Hello proxy = service.getHelloPort();
BindingProvider bindingProvider = (BindingProvider)proxy;
bindingProvider.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "userfoo");
bindingProvider.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "passbar");
BindingProvider.USERNAME_PROPERTY, BindingProvider.PASSWORD_PROPERT
Y are used primarily for service requests. When you instantiate Service, it fetches WSDL and the server is returning 401.
You could try any one of the following solutions:
• Use java.net.Authenticator class in your client application.

• Provide a local access to the WSDL using catalog.
• Configure web.xml to allow GET requests without authentication.
Mutual Authentication
With mutual authentication, the server and the client authenticate one another. There are two types of mutual authentication:
• Certificate-based mutual authentication
• User name- and password-based mutual authentication
Certificate-Based Mutual Authentication
When using certificate-based mutual authentication, the following actions occur:

2. The web server presents its certificate to the client.
3. The client verifies the server's certificate.
4. If successful, the client sends its certificate to the server.
5. The server verifies the client's credentials.
6. If successful, the server grants access to the protected resource requested by the client.
User Name- and Password-Based Mutual Authentication
In user name- and password-based mutual authentication, the following actions occur:
2. The web server presents its certificate to the client.
3. The client verifies the server's certificate.
4. If successful, the client sends its user name and password to the server, which verifies the client's credentials.
5. If the verification is successful, the server grants access to the protected resource requested by the client.
Using JAX-WS-Based Web Services with SSL
1. Write the Class for the Web Service Endpoint
SSL has no impact on the Java code for the web service endpoint. The same code works for web services that use SSL or that
don't use SSL.
In Java EE 5, you can use annotations to easily construct a JAX-WS web service. Here's an example of a web service implemented
as an EJB endpoint:
import javax.annotation.Resource;
import javax.ejb.Stateless;
import javax.xml.ws.WebServiceContext;
@Stateless
@WebService
public class HelloEjb {
@Resource
WebServiceContext wsContext;
public String hello(String msg) {

return "Ejb WS: " + wsContext.getUserPrincipal() + ": " + msg;
}
}
The @Stateless annotation marks the class as a stateless session bean, and the @WebService annotation marks
@Resource
the class as a web service. The annotation is used to declare resource dependencies that the class has - in
essence, what resources the class needs. These resources are then injected into the endpoint implementation. In this example,
WebServiceContext. The class needs
the annotation identifies a resource dependency on the
the WebServiceContext to get context information about requests, such as related security information.
Here's the same web service implemented as a servlet endpoint:
import javax.annotation.Resource;
import javax.xml.ws.WebServiceContext;
@WebService
public class HelloServlet {
@Resource
WebServiceContext wsContext;
public String hello(String msg) {

return "Servlet WS: " + wsContext.getUserPrincipal() + ": " + msg;
}
}
2. Specify Security Information in Deployment Descriptors
To use SSL in a web service that is implemented as an EJB endpoint, you need to specify security information in a vendor-specific
deployment descriptor. For a web service implemented as a servlet, you need to specify the security information in
the web.xml descriptor.
One important aspect of secure communication through SSL is server authentication, that is, confirming the identity of the server
to the client. Another aspect is client authentication, where the server confirms the identity of the client. In SSL, you can have
either server authentication or the combination of server and client authentication (but not client authentication alone). We use
the term "mutual authentication" to mean the combination of server and client authentication. (Note however that other
documents might attach a different meaning to mutual authentication. For example, in some documents, the term client
authentication is synonymous with mutual authentication).
auth-method subelement of the login-config element

For SSL mutual authentication, you need to set the
to CLIENT-CERT. You also need to set thetransport-guarantee element to CONFIDENTIAL.
Add the appropriate security elements to the web.xml deployment descriptor:
<web-app version="2.5" ...>
<display-name>Secure Mutual Authentication Example</display-name>
<security-constraint>
<web-resource-collection>
<web-resource-name>SecureHello</web-resource-name>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>CLIENT-CERT</auth-method>
</login-config>
</web-app>
3. Write the Client
After deploying the web service, you can access it from a client program. The client program for a web service application that
uses SSL is essentially the same as one that doesn't use SSL. The major difference is that instead of using HTTP as the internet
protocol, you need to use HTTPS. In the client, you use the @WebServiceRef annotation to declare a reference to a
web service. The value of the wsdlLocation @WebServiceRef
parameter in is a URL that points to the
location of the WSDL file for the service being referenced. So for a web service client that uses SSL,
the wsdlLocationparameter in the @WebServiceRef annotation needs to specify an HTTPS URL.
For example:
@WebServiceRef(wsdlLocation="https://server.com:8080/HelloEjbService/HelloEjb?WSDL")
private static HelloEjbService helloEjbService;
You can then access the port for the web service and invoke the web service:
HelloEjb helloEjbPort = helloEjbService.getHelloEjbPort();
helloEjbPort.hello("Hello World");
Client-side artifacts are generated by accessing the WSDL file through HTTPS. To do that, you need to specify the location of a
truststore file for the server and its password in the environment variable. In SSL, you can use certificates to authenticate the
server or for mutual authentication of both the server and client. The truststore file for the server contains the trusted certificates
for the server and its keys.
4. Set Up the Client Truststore and Keystore
In addition to a truststore file for the server, you also need a truststore file for the client. The client validates the server certificate
against a set of certificates in its truststore. For a secure connection to be made using SSL, the client-side truststore needs to
trust the server certificate. For SSL mutual authentication, the server-side truststore also needs to trust the client certificate. If
you modify the server-side truststore, you need to restart the server (this allows use of the new certificate). You might not need
to do this in a production environment because production certificates are signed by a common Certificate Authority (CA).
For SSL mutual authentication, you need to provide your own key in a client keystore (a file that contains the client's keys and
certificates). You can use keytool, a key and certificate management utility in JDK 5.0, to generate the keystore.
The certificate has to be loaded to the client, to achieve this, keytool command is used
keytool -import -trustcacerts -alias FOO -file "FOO_PATH\foo.cer" -storetype JKS -keystore
"FOO_PATH\foo.keystore"
5. Run the Client
Before you run the client that access a web service with SSL, you need to set the value of the environment variable.
For SSL mutual authentication, set the value to:
System.setProperty("javax.net.ssl.keyStore", "FOO_PATH/foo.keystore");
System.setProperty("javax.net.ssl.keyStorePassword", "changeit");
System.setProperty("javax.net.ssl.keyStoreType", "JKS");
System.setProperty("javax.net.ssl.trustStore", "FOO_PATH/foo.keystore");
System.setProperty("javax.net.ssl.trustStorePassword", "changeit");
System.setProperty("java.protocol.handler.pkgs", "com.sun.net.ssl.internal.www.protocol");
Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());
Describe WS-Policy that defines a base set of constructs that can be used and extended by other Web
services specifications to describe a broad range of service requirements and capabilities.
Advanced web service features are enabled and configured using a mechanism defined by the Web Services Policy Framework (WS-Policy)
specification. A web service expresses its requirements and capabilities via policies embedded in the service's WSDL description. A service
consumer verifies it can handle the expressed requirements and, optionally, uses server capabilities advertised in policies.
Technologies like Reliable Messaging, Addressing, or Secure Conversations, provides a set of policy assertions it can process. Those assertions
provide the necessary configuration details to the Metro run-time to enable proper operation of these features used by a given web service.
The assertions may specify particular configuration settings or rely on default settings that are pre-determined by the specific technology. For
instance, in the snippet shown
below,wsrm:AcknowledgementInterval and wsrm:InactivityTimeout are both optional and could be
omitted. The following is an XML snippet showing WS-Policy assertions for WS-Addressing and WS-Reliable Messaging:
<wsp:Policy wsu:Id="AddNumbers_policy">
<wsp:ExactlyOne>
<wsp:All>
<wsaw:UsingAddressing/>
<wsrm:RMAssertion>
<wsrm:InactivityTimeout Milliseconds="600000"/>
<wsrm:AcknowledgementInterval Milliseconds="200"/>
</wsrm:RMAssertion>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
This snippet would be equally valid in either a WSIT configuration file or a web service's WSDL document.
Given an XML schema for a document style Web service create a WSDL file that
describes the service and generate a service implementation.
Empty
Method
The wsdl:operation element corresponding to each method has one or more child elements as follows:
• A wsdl:input element that refers to an associated wsdl:message element to describe the

operation input.
• (Two-way methods only) an optionalwsdl:output element that refers to
a wsdl:message to describe the operation output.
• (Two-way methods only) zero or more wsdl:fault child elements, one for each exception thrown by
the method. The wsdl:fault child elements refer to associated wsdl:message elements to
describe each fault.
Each wsdl:message element has one of the following:
• Document style
A single wsdl:part child element that refers, via an element attribute, to a global element
wsdl:types section:
declaration in the
@WebService
public interface StockQuoteProvider {
float getPrice(String tickerSymbol) throws TickerException;
}
<types>
<xsd:schema targetNamespace="...">

<xsd:element name="getPrice" type="tns:getPriceType"/>
<xsd:element name="getPriceResponse" type="tns:getPriceResponseType"/>
<xsd:element name="TickerException" type="tns:TickerExceptionType"/>

...
</xsd:schema>
</types>
<message name="getPrice">
<part name="getPrice" element="tns:getPrice"/>
</message>
<message name="getPriceResponse">
<part name="getPriceResponse" element="tns:getPriceResponse"/>
</message>
<message name="TickerException">
<part name="TickerException" element="tns:TickerException"/>
</message>
<portType name="StockQuoteProvider">
<operation name="getPrice">
<input message="tns:getPrice"/>
<output message="tns:getPriceResponse"/>
<fault message="tns:TickerException"/>
</operation>
</portType>
• RPC style
Zero or more wsdl:part child elements (one per method parameter and one for a non-void return
type attribute, to named type declarations in the wsdl:types section:
value) that refer, via a
@WebService
public interface StockQuoteProvider {
float getPrice(String tickerSymbol) throws TickerException;
}
<types>
<xsd:schema targetNamespace="...">

<xsd:element name="TickerException" type="tns:TickerExceptionType"/>

...
</xsd:schema>
</types>
<part name="tickerSymbol" type="xsd:string"/>
</message>
<part name="return" type="xsd:float"/>
</message>
<message name="TickerException">
<part name="TickerException" element="tns:TickerException"/>
</message>
<fault message="tns:TickerException"/>
</operation>
</portType>
soap:operation child element of the

Each method in a Java SEI is mapped to a
wsdl:operation. The value of the style attribute of
corresponding
thesoap:operation is document or rpc.
style
If not specified, the value defaults to the value of the soap:binding
attribute of the . WS-I Basic
Profile requires that all operations within a given SOAP HTTP binding instance have the same binding style.
soap:body or soap:header child elements of

The parameters of a Java method are mapped to
the wsdl:input and wsdl:output elements for eachwsdl:operation binding element. The
value of the use attribute of the soap:body is literal.
Example shows using document style:
<types>
<schema targetNamespace="...">

<xsd:complexType name="getPriceType">
<xsd:sequence>
<xsd:element name="tickerSymbol" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="getPriceResponseType">
<xsd:sequence>
<xsd:element name="return" type="xsd:float"/>
</xsd:sequence>
</xsd:complexType>
</schema>
</types>
<part name="getPrice" element="tns:getPrice"/>
</message>
<part name="getPriceResponse" element="tns:getPriceResponse"/>
</message>
<operation name="getPrice" parameterOrder="tickerSymbol">
</operation>
</portType>
<binding name="StockQuoteProviderBinding">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
<operation name="getPrice" parameterOrder="tickerSymbol">
<soap:operation/>
<input message="tns:getPrice">
</input>
<output message="tns:getPriceResponse">
</output>
</operation>
</binding>
Example shows using rpc style:
<types>
<schema targetNamespace="...">

<xsd:complexType name="getPriceType">
<xsd:sequence>
<xsd:element form="unqualified" name="tickerSymbol" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="getPriceResponseType">
<xsd:sequence>
<xsd:element form="unqualified" name="return" type="xsd:float"/>
</xsd:sequence>
</xsd:complexType>
</schema>
</types>
<part name="tickerSymbol" type="xsd:string"/>
</message>
<part name="result" type="xsd:float"/>
</message>
</operation>
</portType>
<binding name="StockQuoteProviderBinding">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>
<soap:operation/>
<input message="tns:getPrice">
</input>
<output message="tns:getPriceResponse">
</output>
</operation>
</binding>
Implement a SOAP logging mechanism for testing and debugging a Web service
application using Java EE Web Service APIs.
• [NONE] blah
Handlers are message interceptors that can be easily plugged in to the JAX-WS runtime to do additional processing of
the inbound and outbound messages. JAX-WS defines two types of handlers, logical handlers and protocol handlers.
Protocol handlers are specific to a protocol and may access or change the protocol specific aspects of a message. Logical
handlers are protocol-agnostic and cannot change any protocol-specific parts (like headers) of a message. Logical
handlers act only on the payload of the message.
SOAP handlers are generally used to process SOAP-specific information, such as SOAP headers. For example, a SOAP
Handler can process security headers in a message and pass the request to the endpoint if the message has the required
credentials. Logical handlers are commonly used if the processing does not need access to SOAP headers, for validation
of the payload, and with Representational State Transfer ("REST") style web services. In addition, logical handlers can
use Java API for XML Binding (JAXB) for processing the payload. If you have the JAXBContext object, it's simple
to alter something in a message with a logical handler. You can get the JAXB objects and call Java methods on them
rather than dealing with Source objects or SOAPMessage objects using the SOAP with Attachments API for Java
(SAAJ) in a SOAP handler.
Handlers are invoked with a message context, which provides methods that the handler uses to access and modify
inbound or outbound messages. The message context also has properties that the handler can process. These properties
can be used to communicate additional information or metadata that is not specified in the message. The additional
information can be exchanged between a handler and service implementation or between a handler and a web service
client.
SOAP handlers extend javax.xml.ws.handler.soap.SOAPHandler. The JAX-WS

SOAPHandler class for SOAP binding. When a SOAP handler is invoked,
specification defines the
a SOAPMessageContext object is specified in the request. The SOAPMessageContext object
provides methods to access a SOAPMessage (the class for SOAP messages). Specifically, the
method getMessage() in SOAPMesageContext retrieves the SOAPMessage. After getting
a SOAPMessage, you can use SAAJ to manipulate it.
Logical handlers extend javax.xml.ws.handler.LogicalHandler . They provide access to

the message context and the message payload. If you use SOAP over HTTP for the message exchange, the content of
the SOAP body forms the payload. If you use XML over HTTP, the XML content of the primary part of the message forms
LogicalMessageContext object is specified in the
the payload. When a logical handler is invoked, a
getMessage() inLogicalMessageContext returns
request. The method
a LogicalMessage. The LogicalMessage represents a protocol-neutral XML message and contains
methods that provide access to the payload of the message.
The following figure illustrates the relationship between the message contexts, the objects they can be used to retrieve,
and the parts of a message those objects cover:
Logical handlers can coexist with SOAP handlers in a handler chain. During runtime, the handler chain is reordered so
that for an outbound message thelogical handlers execute BEFORE the SOAP handlers. For an inbound message,
the SOAP handlers execute BEFORE the logical handlers.
Writing a SOAP Message Handler
Let's look at a simple SOAP handler. SOAPLoggingHandler is a SOAP handler that logs calls to a web
service. Here's a code snippet from SOAPLoggingHandler:
public class SOAPLoggingHandler implements SOAPHandler<SOAPMessageContext> {

...
public boolean handleMessage(SOAPMessageContext smc) {

logToSystemOut(smc);
return true;
}
public boolean handleFault(SOAPMessageContext smc) {

logToSystemOut(smc);
return true;
}
public void close(MessageContext messageContext) {

}
...
}
SOAPLoggingHandler implements the SOAPHandler interface. Notice

Like all SOAP handlers,
that SOAPLoggingHandler also implements three
methods: handleMessage(), handleFault(), and close().
The SOAPHandler interface is a subinterface of the Handler interface.
The handleMessage(), handleFault(), and close() methods are the three methods defined
in the Handler interface, and should be implemented in all basic handlers. Here's how the methods are used:
• handleMessage() is called for normal processing of inbound and outbound messages.

• handleFault() is called when a message contains a protocol fault.
• close() is called after the completion of message processing by all handlers for each web service
invocation, that is, after the completion of a SOAP method exchange pattern (or "MEP").
logToSystemOut() method that both

The logging is done in the handler's
the handleMessage() and handleFault() methods call:
private void logToSystemOut(SOAPMessageContext smc) {

Boolean outboundProperty = (Boolean)smc.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
if (outboundProperty.booleanValue()) {
out.println("\nOutbound message:");
} else {
out.println("\nInbound message:");
}
SOAPMessage message = smc.getMessage();

try {
message.writeTo(out);
out.println("");
} catch (Exception e) {
out.println("Exception in handler: " + e);
}
}
logToSystemOut() method accesses

Notice that the
a SOAPMessageContext property, MESSAGE_OUTBOUND_PROPERTY, and uses
a SOAPMessageContext method,getMessage(). The value
of MESSAGE_OUTBOUND_PROPERTY indicates the message direction. A value of true means that the
message is outbound. A value offalse indicates an inbound message. Based on the property
value, logToSystemOut() prints either "Outbound message" or "Inbound
message". It then usesgetMessage() to get the SOAP message, and prints it.
Writing a Logical Message Handler
The LogicalLoggingHandler file is a logical message handler. Like

the SOAPLoggingHandler, it logs calls to a web service. Here's a code snippet
fromLogicalLoggingHandler:
public class LogicalLoggingHandler implements LogicalHandler<LogicalMessageContext> {

...
public boolean handleMessage(LogicalMessageContext context) {

return processMessage(context);
}
public boolean handleFault(LogicalMessageContext context) {

return processMessage(context);
}
public void close(MessageContext context) {

// Clean up Resources
}
}
Like all logical handlers, LogicalLoggingHandler implements the LogicalHandler interface.

And like all handlers it implements the handleMessage(),handleFault(),
and close() methods.
processMessage() method that both

The logging is done in the handler's
the handleMessage() and handleFault() methods call:
private boolean processMessage(LogicalMessageContext context) {

Boolean outboundProperty = (Boolean)context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
if (outboundProperty) {
out.println("\nOutbound message:");
} else {
out.println("\nInbound message:");
}
LogicalMessage lm = context.getMessage();
Source payload = lm.getPayload();
// Process Payload Source

printSource(payload);
// ....
// If the payload is modified,

// do lm.setPayload(source) to be safe. Without it,
// behavior may vary on the kind of source returned in
// lm.getPayload().
// See LogicalMessage JavaDoc for more details.
// lm.setPayload(modifiedPayload);
return true;
}
The processMessage() method accesses and manipulates the message payload using the logical message
LogicalMessage method, getPayload(), to get the
context for the logical handler. It calls the
payload of the message. The payload is returned as a Source object.
Notice the commented out portion of processMessage(). In some cases, you might need to call
the LogicalMessage method, setPayload(), after a modification is made to the payload. The
source returned by getPayload() depends on the JAX-WS runtime. If the returned source
is DOMSource, a modification to the encapsulated DOM tree changes the message payload in place. In that case,
there is no need to subsequently call setPayload(). However, other types of returned source provide only read
access to the message. In those cases, you need to call setPayload() after any modifications.
You can also pass a JAXBContext object in the call to getPayload(), to get the payload as a JAXB
object. Here's an example:
LogicalMessage lm = context.getMessage();
Object jaxbObject = lm.getPayload(jaxbContext);
// Modify JAXB Object
lm.setPayload(modifiedJaxbObject,jaxbContext);
Note that there is no connection between the returned object and the message payload - to change the payload, you
need to call setPayload().
Advanced web service features are enabled and configured using a mechanism defined by the Web Services Policy Framework (WS-Policy)
specification. A web service expresses its requirements and capabilities via policies embedded in the service's WSDL description. A service
consumer verifies it can handle the expressed requirements and, optionally, uses server capabilities advertised in policies.
Technologies like Reliable Messaging, Addressing, or Secure Conversations, provides a set of policy assertions it can process. Those assertions
provide the necessary configuration details to the Metro run-time to enable proper operation of these features used by a given web service.
The assertions may specify particular configuration settings or rely on default settings that are pre-determined by the specific technology. For
instance, in the snippet shown
below, wsrm:AcknowledgementInterval and wsrm:InactivityTimeout are both optional and could be
omitted. The following is an XML snippet showing WS-Policy assertions for WS-Addressing and WS-Reliable Messaging:
Given a set of requirements, create code to handle system and service exceptions and faults received
by a Web services client.
• [NONE] blah
WSDL-to-Java mapping
Let's look at the WSDL-to-Java mapping of faults to exceptions, starting with the WSDL. Run your favorite JAX-WS WSDL-to-Java code
generator on this WSDL. It gives you the generated interface and fault classes.
<wsdl:definitions targetNamespace="urn:fault.sample"
xmlns:tns="urn:fault.sample" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
<wsdl:types>
<xsd:schema targetNamespace="urn:fault.sample"
xmlns:tns="urn:fault.sample" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="op" type="tns:Op"/>
<xsd:complexType name="Op">
<xsd:sequence>
<xsd:element name="in" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="opResponse" type="tns:OpResponse"/>
<xsd:complexType name="OpResponse">
<xsd:sequence>
<xsd:element name="out" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="faultElement" type="tns:Fault"/>
<xsd:complexType name="Fault">
<xsd:sequence>
<xsd:element name="code" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
</wsdl:types>
<wsdl:message name="opRequest">
<wsdl:part name="parameters" element="tns:op"/>
</wsdl:message>
<wsdl:message name="opResponse">
<wsdl:part name="parameters" element="tns:opResponse"/>
</wsdl:message>
<wsdl:message name="faultMsg">
<wsdl:part name="parameters" element="tns:faultElement"/>
</wsdl:message>
<wsdl:portType name="PT">
<wsdl:operation name="op">
<wsdl:input message="tns:opRequest"/>
<wsdl:output message="tns:opResponse"/>
<wsdl:fault name="fault" message="tns:faultMsg"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="Binding" type="tns:PT">

<wsdl:operation name="op">
<soap:operation soapAction=""/>
<wsdl:input>
</wsdl:input>
<wsdl:output>
</wsdl:output>
<wsdl:fault name="fault">
<soap:fault use="literal" name="fault"/>
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="Service">
<wsdl:port name="Port" binding="tns:Binding">
<soap:address location="http://www.example.org/"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Generated Java interface:
package sample.fault;
public interface PT {
public String op(String in) throws FaultMsg;
}
The Java exception name is derived from the WSDL fault message's name; in this case FaultMsg:
public class FaultMsg extends Exception {

private Fault faultInfo;
public FaultMsg(String message, Fault faultInfo) {...}
public FaultMsg(String message, Fault faultInfo, Throwable cause) {...}
public Fault getFaultInfo() {...}
}
All mapped JAX-WS exceptions contain a private faultInfo instance variable. The type of this faultInfo is derived from the
Fault:
schema, which the fault's wrapper element refers to; in this case it's
public class Fault {

protected String code;
public String getCode() {...}
public void setCode(String value) {...}
}
Why does a JAX-WS mapping of faults create a fault class and a fault info class? The reason is that JAX-WS delegates the generation of
schema mappings to Java Architecture for XML Binding (JAXB). JAX-WS knows how to do Web services stuff, but it doesn't know how to do
schema stuff. JAXB knows schema. A fault or exception is a Web services artifact. The data in a fault is a schema artifact. So the JAX-WS
generator generates the exception, and the JAXB generator generates the Java bean containing the exception's data.
Java-to-WSDL mapping
JAX-WS seems to prefer that you build exceptions like the ones it generates, with the exception itself separate from the Java bean data for
the exception. If you follow this pattern, you get the reverse of the mapping described in the previous section.
But separating the exception data from the exception is not typical of how a Java programmer writes exceptions. So JAX-WS also provides a
mapping for the more natural exception. A simple example of this natural pattern is shown below.
SEI:
package sample2.fault;
public interface PT {
public String op(String in) throws Fault;
}
Exception: package sample2.fault; public class Fault extends Exception { public Fault(String code) {...} public String getCode() {...} public
void setCode(String value) {...} } ™
WSDL generated from above Java:

<definitions targetNamespace="http://fault.sample2/"
xmlns:tns="http://fault.sample2/" xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
<types>
<xsd:schema>
<xsd:import
namespace="http://fault.sample2/"
schemaLocation="PTImplService_schema1.xsd"/>
</xsd:schema>
</types>
<message name="op">
<part element="tns:op" name="parameters"/>
</message>
<message name="opResponse">
<part element="tns:opResponse" name="parameters"/>
</message>
<message name="Fault">
<part element="tns:Fault" name="fault"/>
</message>
<portType name="PTImpl">
<operation name="op">
<input message="tns:op"/>
<output message="tns:opResponse"/>
<fault message="tns:Fault" name="Fault"/>
</operation>
</portType>
<binding name="PTImplPortBinding" type="tns:PTImpl">

<operation name="op">
<input>
</input>
<output>
</output>
<fault name="Fault">
<soap:fault name="Fault" use="literal"/>
</fault>
</operation>
</binding>
<service name="PTImplService">
<port binding="tns:PTImplPortBinding" name="PTImplPort">
<soap:address location="https://localhost:9444/SampleFault/PTImplService"/>
</port>
</service>
</definitions>
Schema generated from above Java:
<xs:schema targetNamespace="http://fault.sample2/"
xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://fault.sample2/">
<xs:element name="Fault" type="tns:Fault"/>
<xs:element name="op" type="tns:op"/>
<xs:element name="opResponse" type="tns:opResponse"/>
<xs:complexType name="op">
<xs:sequence>
<xs:element minOccurs="0" name="arg0" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="opResponse">
<xs:sequence>
<xs:element minOccurs="0" name="return" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="Fault">
<xs:sequence>
<xs:element minOccurs="0" name="code" type="xs:string"/>
<xs:element minOccurs="0" name="message" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Unmodeled faults
What happens when an unmodeled fault occurs? For example, what happens when the service above throws an exception other
than sample2.fault.Fault (for instance, NullPointerException )? What happens on the client? The answer to
that depends on the messaging protocol. For instance, when communicating via SOAP/HTTP, the server-side SOAP engine creates a SOAP
message containing a SOAP fault with information relevant to the problem in the faultcode and faultstring fields:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<soapenv:Fault>
<faultcode>soapenv:Server</faultcode>
<faultstring>java.lang.NullPointerException</faultstring>
<detail/>
</soapenv:Fault>
</soapenv:Body>
</soapenv:Envelope>
SOAPFaultException. When the

Because a SOAP fault is returned to the client, JAX-WS has defined an exception named
service throws an unmodeled fault, the client receives a SOAPFaultException.
javax.xml.ws.soap.SOAPFaultException is a protocol-specific exception. It

extends javax.xml.ws.ProtocolException. JAX-WS defines another extension
ofProtocolException: javax.xml.ws.http.HTTPException for the XML/HTTP communication channel.
Those are the only standardized bindings defined for WSDL. For other bindings, assume the binding provider defines other extensions
of ProtocolException, one for each new binding.
Service, BindingProvider, and Dispatch. If calls to those classes

JAX-WS defines a number of Java classes, such as
fail, they throw WebServiceException, the general-purpose exception for the JAX-WS APIs.
java.lang.Object
extended by java.lang.Throwable
extended by java.lang.Exception
extended by java.lang.RuntimeException
extended by javax.xml.ws.WebServiceException
extended by javax.xml.ws.ProtocolException
extended by javax.xml.ws.soap.SOAPFaultException
extended by javax.xml.ws.http.HTTPException
Chapter 10. Web Services Interoperability Technologies
Describe WSIT, the features of each WSIT technology and the standards that WSIT Implements for
each technology and how it works.
Sun is working closely with Microsoft to ensure interoperability of web services enterprise technologies such as message optimization, reliable
messaging, and security. The initial release of WSIT is a product of this joint effort. WSIT is an implementation of a number of open web
services specifications to support enterprise features. In addition to message optimization, reliable messaging, and security, WSIT includes a
bootstrapping and configuration technology. Figure below shows the underlying services that were implemented for each technology.
Starting with the core XML support currently built into the Java platform, WSIT uses or extends existing features and adds new support for
interoperable web services. See the following sections for an overview of each feature:
• Bootstrapping and Configuration
Bootstrapping and configuration consists of using a URL to access a web service, retrieving its WSDL file, and using the WSDL file
to create a web service client that can access and consume a web service. The process consists of the following steps, which are
shown below:
1. Client acquires the URL for a web service that it wants to access and consume. How you acquire the URL is outside the
scope of this tutorial. For example, you might look up the URL in a Web Services registry.
2. The client uses the URL and the wsimport tool to send a MetadataExchangeRequest to access
the web service and retrieve the WSDL file. The WSDL file contains a description of the web service endpoint,
including WS-Policy assertions that describe the security and/or reliability capabilities and requirements of the service.
The description describes the requirements that must be satisfied to access and consume the web service.
3. The client uses the WSDL file to create the web service client.
4. The web service client accesses and consumes the web service.
• Message Optimization Technology
A primary function of web services applications is to share data among applications over the Internet. The data shared can vary in
format and include large binary payloads, such as documents, images, music files, and so on. When large binary objects are
encoded into XML format for inclusion in SOAP messages, even larger files are produced. When a web service processes and
transmits these large files over the network, the performance of the web service application and the network are negatively
affected. In the worst case scenario the effects are as follows:
o The performance of the web service application degrades to a point that it is no longer useful.
o The network gets bogged down with more traffic than the allotted bandwidth can handle.
One way to deal with this problem is to encode the binary objects so as to optimize both the SOAP application processing time
and the bandwidth required to transmit the SOAP message over the network. In short, XML needs to be optimized for web
services. This is the exactly what the Message Optimization technology does. It ensures that web services messages are
transmitted over the Internet in the most efficient manner.
Sun recommends that you use message optimization if your web service client or web service endpoint will be required to process
binary encoded XML documents larger than 1KB.
• Reliable Messaging Technology
Reliable Messaging is a Quality of Service (QoS) technology for building more reliable web services. Reliability is measured by a
system's ability to deliver messages from point A to point B without error. The primary purpose of Reliable Messaging is to ensure
the delivery of application messages to web service endpoints.
The reliable messaging technology ensures that messages in a given message sequence are delivered at least once and not more
than once and optionally in the correct order. When messages in a given sequence are lost in transit or delivered out of order, this
technology enables systems to recover from such failures. If a message is lost in transit, the sending system retransmits the
message until its receipt is acknowledged by the receiving system. If messages are received out of order, the receiving system
may re-order the messages into the correct order.
The Reliable Messaging technology can also be used to implement session management. A unique message sequence is created
for each client-side proxy and the lifetime of the sequence identifier coincides with the lifetime of the proxy. Therefore, each
message sequence can be viewed as a session and can be used to implement session management.
You should consider using reliable messaging if the web service is experiencing the following types of problems:
o Communication failures are occurring that result in the network being unavailable or connections being. dropped
o Application messages are being lost in transit.
o Application messages are arriving at their destination out of order and ordered delivery is a requirement.
To help decide whether or not to use reliable messaging, weigh the following advantages and disadvantages:
o Enabling reliable messaging ensures that messages are delivered exactly once from the source to the destination and,
if the ordered-delivery option is enabled, ensures that messages are delivered in order.
o Enabling reliable messaging causes a degradation of web service performance, especially if the ordered delivery option
is enabled.
o Non-reliable messaging clients cannot interoperate with web services that have reliable messaging enabled.
• Security Technology
Until now, web services have relied on transport-based security such as SSL to provide point-to-point security. WSIT implements
WS-Security so as to provide interoperable message content integrity and confidentiality, even when messages pass through
intermediary nodes before reaching their destination endpoint. WS-Security as provided by WSIT is in addition to existing
transport-level security, which may still be used.
WSIT also enhances security by implementing WS-Secure Conversation, which enables a consumer and provider to establish a
shared security context when a multiple-message-exchange sequence is first initiated. Subsequent messages use derived session
keys that increase the overall security while reducing the security processing overhead for each message.
Further, WSIT implements two additional features to improve security in web services:
o Web Services Security Policy -- Enables web services to use security assertions to clearly represent security
preferences and requirements for web service endpoints.
o Web Services Trust -- Enables web service applications to use SOAP messages to request security tokens that can
then be used to establish trusted communications between a client and a web service.
WSIT implements these features in such a way as to ensure that web service binding security requirements, as defined in the
WSDL file, can interoperate with and be consumed by WSIT and WCF endpoints.
Describe how to create a WSIT client from a Web Service Description Language (WSDL) file.
Describe how to configure web service providers and clients to use message optimization.
MTOM (Message Transmission and Optimization Mechanism) together with XOP (XML Binary Optimized Packaging) defines how an XML binary data such
asxs:base64Binary or xs:hexBinary can be optimally transmitted over the wire.
XML type, such as xs:base64Binary is sent in lined inside the SOAP envelope. This gets quite in-efficient when the data size is more, for example a SOAP endpo
images/songs etc. MTOM specifies how XOP packaging can be used to send the binary data optimally.
MTOM feature is disabled in JAX-WS by default. It can be enabled on the client and server. Once enabled all the XML binary data, XML elements of
type xs:base64Binary and xs:hexBinary is optimally transmitted.
An schema element of type xs:bas64Binary or xs:hexBinary can be annotated by using attribute reference using xmime:expectedConte
2.0 specification defines xmime:expectedContentType to Java type mapping:
image/gif java.awt.Image
image/jpg java.awt.Image
text/plain java.lang.String
text/xml javax.xml.transform.Source
application/xml javax.xml.transform.Source
multipart/* javax.activation.DataHandler
all other types javax.activation.DataHandler
<element name="image" type="base64Binary" />
is mapped to:
byte[]
<element name="image" type="base64Binary"

xmime:expectedContentTypes="image/jpeg"
xmlns:xmime="http://www.w3.org/2005/05/xmlmime"/>
is mapped to:
java.awt.Image
How to enable MTOM in JAX-WS 2.0
• Enabling MTOM on Server

o Enable using @javax.xml.ws.soap.MTOM annotation on the endpoint (SEI) implementation class:
o @javax.xml.ws.soap.MTOM
o @WebService (endpointInterface = "mtom.server.Hello")
o public class HelloImpl implements Hello {
o ....
o }
o MTOM can be also be enabled on an endpoint by specifying enable-mtom attribute to true on an endpoint element in sun-jaxws.
descriptor:
o
o <?xml version="1.0" encoding="UTF-8"?>
o <endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime' version='2.0'>
o <endpoint name="Mtom" implementation="mtom.server.HelloImpl"
o url-pattern="/hello"
o enable-mtom="true"/>
o </endpoints>
o
o Enable using @BindingType on the endpoint (SEI) implementation class:
@BindingType(value=javax.xml.ws.SOAPBinding.SOAP11HTTP_MTOM_BINDING) will enable MT

endpoint for SOAP 1.1 binding.
@BindingType(value=javax.xml.ws.SOAPBinding.SOAP12HTTP_MTOM_BINDING) will enable MT

endpoint for SOAP 1.2 binding.
• Enabling MTOM on Client

o javax.xml.ws.soap.MTOMFeature as WebServiceFeature parameter while
To enable MTOM on client-side, pass
the Proxy or Dispatch. Here is the code snippet from the client MtomApp.java of the MTOM sample:
Hello port = new HelloService().getHelloPort(new MTOMFeature()); - gives a proxy with M
javax.xml.ws.Service.createDispatch( .... ,new MTOMFeature()); - gives a Dispatch

enabled.
o JAX-WS 2.0 specification has defined API to enable and to check if the MTOM is enabled.
javax.xml.ws.soap.SOAPBinding.setMTOMEnabled(boolean enable) - enable or disable MTOM.
javax.xml.ws.soap.SOAPBinding.isMTOMEnabled() - returns true if MTOM is enabled otherwise false.
Hello port = new HelloService.getHelloPort();
//get the binding and enable mtom

SOAPBinding binding = (SOAPBinding)((BindingProvider)port).getBinding();
boolean mtomEnabled = binding.isMTOMEnabled();

binding.setMTOMEnabled(true);
xs:base64Binary and xs:hexBinary mapping to java is byte[]. JAXWS implementation has set a threshold o
As defined by JAXB 2.0 specification
ofbyte[] size. This threshold can be modified using implementation specific
property com.sun.xml.ws.developer.JAXWSProperties.MTOM_THRESHOLD_VALUE in the RequestContext on the
the MessageContext on the server side.
If thebyte[] that is being sent is less than this threshold (default is 1KB) then the binary data is base64 encoded by JAXB and in lined inside the SOAP Bodyoth
data is sent as attachment mime part inMultipart/Related package and XML infoset for the binary data is XOP encoded by JAXB -<xop:Include h
used to reference the attachment. The XOP encoding and packaging is done as per described by the XOP packaging rules. Thehref is the the Content-ID of the a
encoded as per CID URI scheme defined in RFC 2111. xmime:contentType attribute may appear on the element that includes binary data to indicate preferre
annotated on the corresponding schema.
What is MTOM
Perhaps the best way to understand the pros and cons of MTOM is to see an actual on-the-wire message. See an example below:
Content-Type: Multipart/Related; start-info="text/xml"; type="application/xop+xml"; boundary="----=_Part_0_1744155.1118953559416"

Content-Length: 3453
SOAPAction: ""
------=_Part_1_4558657.1118953559446
Content-Type: application/xop+xml; type="text/xml"; charset=utf-8
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<Detail xmlns="http://example.org/mtom/data">
<image>
<xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:5aeaa450-17f0-4484-b845-a8480c363444@example.org" />
</image>
</Detail>
</S:Body>
</S:Envelope>
------=_Part_1_4558657.1118953559446
Content-Type: image/jpeg
Content-ID: <5aeaa450-17f0-4484-b845-a8480c363444@example.org>
... binary data ...
The noteworthy points are:
1. The binary attachment is packaged in a MIME multi-part message (the same mechanism used in e-mail to handle attachments).
2. An xop:Include element is used to mark where the binary data is.
3. The actual binary data is kept in a different MIME part.
MTOM is efficient, in the sense that it doesn't have the 33% size increase penalty that xs:base64Binary has. It is interoperable, in the sense that it is a W3C sta
MIME multipart incurs a small cost proportional to the number of attachments, so it is not suitable for a large number of tiny attachments.
Schema:
<element name="Detail" type="types:DetailType"/>

<complexType name="DetailType">
<sequence>
<element name="image" type="base64Binary" />
</sequence>
</complexType>
JAX-WS and MTOM example
JAX-WS MTOM WSDL:
<definitions
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://attachment.tip/"
targetNamespace="http://attachment.tip/">
<types/>
<message name="sendImage">
<part name="image" type="xsd:base64Binary"/>
</message>
<message name="sendImageResponse"/>
<message name="sendOctet">
<part name="octet" type="xsd:base64Binary"/>
</message>
<message name="sendOctetResponse"/>
<portType name="AttachmentTip">
<operation name="sendImage">
<input message="tns:sendImage"/>
<output message="tns:sendImageResponse"/>
</operation>
<operation name="sendOctet">
<input message="tns:sendOctet"/>
<output message="tns:sendOctetResponse"/>
</operation>
</portType>
<binding name="AttachmentBinding" type="tns:AttachmentTip">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="sendImage">
<input>
<soap:body namespace="http://attachment.tip/" use="literal"/>
</input>
<output>
</output>
</operation>
<operation name="sendOctet">
<input>
</input>
<output>
</output>
</operation>
</binding>
<service name="AttachmentService">
<port binding="tns:AttachmentBinding" name="AttachmentTip">
<soap:address location="http://localhost:9080/MTOMService/services/AttachmentTip"/>
</port>
</service>
</definitions>
The MTOM binding contains no MIME information. In fact, there's no way to tell, from the WSDL, that you're dealing with attachments; the WSDL's binding looks like a norm
JAX-WS MTOM Java interface:
package tip.attachment;
import javax.jws.soap.SOAPBinding;
@WebService(name = "AttachmentTip", targetNamespace = "http://attachment.tip/")

@SOAPBinding(style = SOAPBinding.Style.RPC)
public interface AttachmentTip {
@WebMethod
public void sendImage(
@WebParam(name = "image", partName = "image")
byte[] image
);
@WebMethod
public void sendOctet(
@WebParam(name = "octet", partName = "octet")
byte[] octet
);
}
Because the WSDL is a normal-looking WSDL with no hint of attachments, you end up with a Java interface that reflects that as well. Given parts of
type base64Binary (orhexBinary ), JAX-WS maps those to parameters of type byte[]. With MTOM, the MIME-ness of the types has all been extracted
the burden placed on the client or server run time to format the content appropriately.
The interface portion of both WSDLs shows that the data type in the operations is base64Binary , which maps tobyte[] . In the JAX-RPC Sw/A WSDL, howeve
binding that the part types are a MIME image and a MIME octet stream. In the JAX-WS MTOM WSDL, this information is lost. This may seem like a bad thing, but the positiv
completely cleans up the interface. No matter what the binding, the interface is always the same. In fact, the implementors of the client and the server codebases shouldn't
notion of whether the parameter is an attachment. That's merely a detail of the SOAP message, and the writers of the WSDL-to-Java mappings have tried their best to abstr
away from the details of the SOAP message.
However, if you really want to know what the MIME type is - if you want to get back to the information you lost - JAX-WS provides support for an attribute that you can inje
element: expectedContentTypes.
JAX-WS MIME attribute:
<definitions ...>
<types>
<xsd:schema
xmlns:tns="http://attachment.tip/"
targetNamespace="http://attachment.tip/">
<xsd:element name="sendImage" type="tns:sendImage"/>
<xsd:complexType name="sendImage">
<xsd:sequence>
<xsd:element
xmlns:ns1="http://www.w3.org/2005/05/xmlmime"
ns1:expectedContentTypes="image/*"
name="image"
type="xsd:base64Binary"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="sendImageResponse" type="tns:sendImageResponse"/>
<xsd:complexType name="sendImageResponse">
<xsd:sequence/>
</xsd:complexType>
<xsd:element name="sendOctet" type="tns:sendOctet"/>
<xsd:complexType name="sendOctet">
<xsd:sequence>
<xsd:element
xmlns:ns1="http://www.w3.org/2005/05/xmlmime"
ns1:expectedContentTypes="application/octet-stream"
name="octet"
type="xsd:base64Binary"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="sendOctetResponse" type="tns:sendOctetResponse"/>
<xsd:complexType name="sendOctetResponse">
<xsd:sequence/>
</xsd:complexType>
</xsd:schema>
</types>
...
</definitions>
JAX-WS Java interface mapped from the MIME attribute:
package tip.attachment;
import java.awt.Image;
import javax.activation.DataHandler;
import javax.xml.ws.RequestWrapper;
import javax.xml.ws.ResponseWrapper;
@WebService(name = "AttachmentTip", targetNamespace = "http://attachment.tip/")

public interface AttachmentTip {
@WebMethod
@RequestWrapper(localName = "sendImage",
targetNamespace = "http://attachment.tip/",
className = "tip.attachment.SendImage")
@ResponseWrapper(localName = "sendImageResponse",
className = "tip.attachment.SendImageResponse")
Describes the best practices for production and consumption of data for interoperability between WCF web services and Jav
clients or between Java web services and WCF web service clients.
Primitives and Wrappers
Java primitive and wrapper classes map to slightly different XML schema representations. Therefore, .NET bindings will vary accordingly.
A Java primitive type and its corresponding wrapper class are shown below.
Java code fragment:
public class StockItem{

public Double wholeSalePrice;
public double retailPrice;
}
Schema fragment:
<xs:complexType name="stockItem">
<xs:sequence>
<xs:element name="wholeSalePrice" type="xs:double" minOccurs="0"/>
<xs:element name="retailPrice" type="xs:double"/>
</xs:sequence>
</xs:complexType>
.NET C# auto generated code from schema:

public partial class stockItem
{
private double wholeSalePrice;
private bool wholeSalePriceFieldSpecified;
private double retailPrice;
public double wholeSalePrice

{
get{ return this.wholeSalePrice;}
set{this.wholeSalePrice=value}
}
public bool wholeSalePriceSpecified

{
get{ return this.wholeSalePriceFieldSpecified;}
set{this.wholeSalePriceFieldSpecified=value}
}
public double retailPrice

{
get{ return this.retailPrice;}
set{this.retailPrice=value}
}
}
BigDecimal Type
Limit decimal values to the range and precision of .NET's System.decimal.
java.math.BigDecimal maps to xs:decimal.
.NET maps xs:decimal to System.decimal.
java.math.BigDecimal supports arbitrary precision. System.decimal does not. For i

These two data types support different range and precision.
only values within the range and precision of System.decimal. (See System.decimal.Minvalue and System.decimal.Maxvalu
outside of this range require a customized .NET client.
Java code fragment:
public class RetBigDecimal {

private BigDecimal arg0;
public BigDecimal getArg0() { return this.arg0; }

public void setArg0(BigDecimal arg0) { this.arg0 = arg0; }
}
Schema fragment:
<xs:complexType name="retBigDecimal">
<xs:sequence>
<xs:element name="arg0" type="xs:decimal" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
.NET auto generated code from schema

public partial class retBigDecimal{
private decimal arg0Field;
private bool arg0FieldSpecified;
public decimal arg0 {

get { return this.arg0Field;}
set { this.arg0Field = value;}
}
public bool arg0Specified {
get { return this.arg0FieldSpecified;}
set { this.arg0FieldSpecified = value;}
}
}
XMLGregorianCalendar Type
Use java.xml.datatype.XMLGregorianCalendar instead of java.util.Date and java.util.Calendar.
XMLGregorianCalendar supports the following XML schema calendar

xs:date, xs:time, xs:dateTime, xs:gYearMonth, xs:gMonthDay, xs:gYear,xs:gMonth, and xs:gDay. It is
types:
to xs:anySimpleType, the common schema type from which all the XML schema calendar types are dervived.
.NET maps xs:anySimpleType to System.string.
java.util.Date and java.util.Calendar map to xs:dateTime, but don't provide as complete XML support as XMLGregorianC
Use the annotation @XmlSchemaType for a strongly typed binding of XMLGregorianCalendar to one of the XML schema calendar types.
Java code fragment:
public class PurchaseOrder {

public javax.xml.datatype.XMLGregorianCalendar orderDate;
}
Schema fragment:
<xs:complexType name="purchaseOrder">
<xs:sequence>
<xs:element name="orderDate" type="xs:anySimpleType" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
.NET auto generated code from schema:

public partial class purchaseOrder
{
private string orderDateField;
public string orderDate
{
get { return this.orderDateField; }
set { this.orderDateField = value; }
}
}
Enum Type
A Java enum type maps to an XML schema type constrained by enumeration facets. This, in turn, binds to the .NET type enum type.
Java enum -> xs:simpleType (with enumeration facets) -> .NET enum.
Java code fragment:
public enum USState {MA, NH}
Schema fragment:
<xs:simpleType name="usState">
<xs:restriction base="xs:string">
<xs:enumeration value="NH" />
<xs:enumeration value="MA" />
</xs:restriction>
</xs:simpleType>
.NET auto generated code from schema:

public enum usState { NH, MA }
Given a scenario, design a Java EE web service using Web Services Design Pattern (Asynchronous Interaction, JMS Bridge, W
Cache, Web Service Broker), and Best Practices.
Asynchronous Interaction
• Server-Side Push Implementation
The server-side push implementation decouples the input and output messages for the interaction. In this implementation, the design is converted so that there
interactions; one from client to server that the client uses to issue its request to the server, and another from server to client that the server uses to notify the c
1. A business document like a purchase order or invoice in XML format is sent as the SOAP message in the request.
2. The service accepts the document and
a. Does not return any message to the client. This corresponds to a void return type in the Service Endpoint Interface. If due to HTTP is
not receive a successful HTTP 200 message or receives a SOAP Fault, then it is up to the client to retry the invocation or query the servic
would need to be built into the application layer.
b. Sends a SOAP message back to the client. The contents of the message are dictated by the schema in the WSDL. The message would typ
acknowledgement, informing the client that the request is being processed.
3. Once the service receives the message it is placed on a JMS queue for processing at a later time.
4. The Message Driven Beans deployed in the container actively receive and process the message containing the XML business document from the queu
5. The response to the business processing, is also placed on another JMS Queue for dispatch to the client at a later time.
6. Other Message Driven Beans can pick up the responses use the JAX-WS API to make client calls to the callback services on the service consumer's si
the business could be another XML document.
• JAX-WS-Based Implementation
The web services interfaces included in the Java EE specification provide support for non-portable asynchronous interactions, but only for JAX-WS-based interact
introduces the Dispatch<T> and Provider<T> interfaces that are used to describe the client and server sides to the interaction.
Client-side Dispatch Interface Definition:
// T is the type of the message

public interface Dispatch<T> {
//synchronous request-response
T invoke(T msg);
//async request-response
Response<T> invokeAsync(T msg);
Future<?> invokeAsync(Tmsg, AsyncHandler<T> h);
// one-way
void invokeOneWay(T msg);
}
Server-side Provider Interface Definition:
// T is the type of the message

public interface Provider<T> {
T invoke(T msg, Map<String, Object> context);
Client developer may use asynchronous invocations as defined by the JAX-WS specification. JAX-WS supports asynchronous invocations through generated asyn
the Service Endpoint Interface and javax.xml.ws.Dispatch interface. There are two forms of asynchronous invocations in JAX-WS тАУ Polling
o Polling
Client asynchronous polling invocations must be supported by components running in Servlet container, EJB container and Application Client containe
javax.xml.ws.Dispatch
components can act as JAX- WS clients. Client developers can either use the Service Endpoint Interface or
polling invocations.
javax.xml.ws.Dispatch - The invokeAsync method returns a Response that may be polled using the methods inher
from Future<T> to determine when the operation has completed and to retrieve the results.
SEI - A polling method returns a typed Response<ResponseBean> that may be polled using methods inherited from Future<?
the operation has completed and to retrieve the results:
Service service = ...;

StockQuote quoteService = (StockQuote)service.getPort(portName);
Response<Float> response = quoteService.getPriceAsync(ticker);
while (!response.isDone()) {
// do something while we wait
}
Float quote = response.get();
o Callback
Client asynchronous callback invocations should only be supported by components running in EJB, Servlet container and Application Client container.
javax.xml.ws.Dispatch to implement asynchronous callback invocations. The callback
either use the Service Endpoint Interface or
implement javax.xml.ws.AsyncHandler interface.
javax.xml.ws.Dispatch - The client supplies an AsyncHandler and the runtime calls the handleResponse met
of the operation are available. The invokeAsync method returns a wildcard Future (Future<?>) that may be polled to determin
has completed. The object returned from Future<?>.get() has no standard type. Client code should not attempt to cast the object to an
this will result in non-portable behavior.
SEI - A callback method takes an additional final parameter that is an instance of a typed AsyncHandler<ResponseBean> and re
wildcardFuture<?> Future<?>.get(
that may be polled to determine when the operation has completed. The object returned from
type. Client code should not attempt to cast the object to any particular type as this will result in non-portable behavior:
StockQuotePortProxy proxy = ...
// Set up the callback handler.

MyPriceHandler callbackHandler = new MyPriceHandler();
// Make the Web Service call

Future<?> response = proxy.getPriceAsync(ticker, callbackHandler);
class MyPriceHandler implements AsyncHandler<Float> {

...
public void handleResponse(Response<Float> response) {
Float price = response.get();
...
}
}
JMS Bridge
Provides interoperability between two different JMS implementations.
If the enterprise application is complex enough to run on more than one hardware platform, it is not uncommon for there to be two or more JMS implementations in play, an
then becomes an issue. JMS Bridge promotes vendor independence.
The JMS Bridge pattern suggests keeping the different subsystems using their own JMS implementations, but advocates the introduction of a client into the enterprise applic
messages from one JMS implementation to the next. It decouples an abstraction from its implementation so that the two can vary independently.
Web Service Cache
JAX-WS programming model provides an application handler facility that enables you to manipulate a message on either an inbound or an outbound flow. You can add hand
runtime environment to perform additional processing of request and response messages. You can use handlers for a variety of purposes such as caching, capturing and log
adding security or other information to a message. Because of the support for additional protocols beyond SOAP, JAX-WS provides two different classifications for handlers.
One type of handler is a logical handler that is protocol independent and can obtain the message in the flow as an extensible markup language (XML) message. The logical h
javax.xml.ws.handler.LogicalHandler interface. A log
message context properties and message payload. These handlers must implement the
a LogicalMessageContext object from which the handler can get the message information. Logical handlers can exist on both SOAP and XML/HTTP-based c
The second type of handler is a protocol handler. The protocol handlers operate on message context properties and protocol-specific messages. Protocol handlers are limited
javax.xml.ws.handler.soap.SOAPHandler interface. Protocol handlers receive the message as
configurations and must implement the
a javax.xml.soap.SOAPMessage to read the message data.
The JAX-WS runtime makes no distinction between server-side and client-side handler classes. The runtime does not distinguish between inbound or outbound flow when
a handleMessage(MessageContext) method or handleFault(MessageContext) method for a specific handler is invoked. You m
handlers for the server or client, and implement sufficient logic within these methods to detect the inbound or outbound direction of the current message.
To use handlers with Web Services client applications, you must add the @HandlerChain annotation to the Service Endpoint Interface or the generated service cla
handler chain configuration file. The@HandlerChain file
annotation contains a attribute that points to a handler chain configuration file that you create. For W
applications, you can also configure the handler chain programmatically using the Binding API. To modify the handlerchain class programmatically, use either the default imp
custom implementation of the HandlerResolver method.
To use handlers with your server application, you must set the @HandlerChain annotation on either the Service Endpoint Interface or the endpoint implementation
@HandlerChainannotation on the service endpoint implem
the associated handler chain configuration file. Handlers for the server are only configured by setting the
implementation class. The handler classes must be included in the deployed artifact.
For both server and client implementations of handlers using the @HandlerChain annotation, you must specify the location of the handler configuration as either a
the annotated file or as an absolute URL. For example:
@HandlerChain(file="../../common/handlers.xml")
or
@HandlerChain(file="http://java.boot.by/handlers.xml")
To create a JAX-WS handler:
1. Determine if you want to implement JAX-WS handlers on the service or the client.
a. @HandlerChain annotation and the default implementatio
Use the default implementation of a handler resolver. The runtime now uses the
ofHandlerResolver class to build the handler chain. You can obtain the existing handler chain from the Binding, add or remove ha
return the modified handler chain to the Binding object.
b. To use a custom implementation of a handler resolver, set the custom HandlerResolver class on the Service instance. The runtim
implementation of the HandlerResolver class to build the handler chain, and the default runtime implementation is not used. In this sce
the @HandlerChain annotation is not read when retrieving the handler chain from the binding after the custom HandlerResolve
registered on the Service instance. You can obtain the existing handler chain from the Binding, add or remove handlers, and then return
chain to the Binding object.
2. Configure the client handlers by setting the @HandlerChain annotation on the service instance or Service Endpoint Interface, or you can modify the ha
programmatically to control how the handler chain is built in the runtime. If you choose to modify the handler chain programmatically, then you must determine
default handler resolver or use a custom implementation of a handler resolver that is registered on the service instance. A service instance uses a handler resolv
binding providers. When the binding providers are created, the handler resolver that is registered with a service is used to create a handler chain and the handle
subsequently used to configure the binding provider.
3. Configure the server handlers by setting the @HandlerChain annotation on the Service Endpoint Interface or implementation class. When
the@HandlerChain annotation is configured on both the Service Endpoint Interface and the implementation class, the implementation class takes prior
4. Create the handler chain configuration XML file. You must create a handler chain configuration XML file for the @HandlerChain to reference.
5. 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.
6. Write your handler implementation.
Web Service Cache pattern:
Opportunities for caching:
1. Client-side transparent to the application cache.

2. Server-side transparent to the application cache.
3. Server-side application-specific cache.
Web Service Broker
A Web Service is a popular way of exposing business services to other applications. The integration of different heterogeneous systems, however, can typically involve incom
complexities. Furthermore, it is desirable to limit the set of services that are exposed by an application as Web Services. The Web Service Broker pattern uses XML and web
WebServiceBrokercoordinates the interaction among services, collects responses and performs t
selectively expose and broker the services of an application. A
typically exposed using a WSDL. TheEndpointProcessorclass is the entry point into the Web Service, and processes the client request. The EndpointP
invokes the Web Service through theWebServiceBroker, which brokers to one or more services.
Problem:
• You want to provide access to one or more services using XML and web protocols.
Forces:
• You want to reuse and expose existing services to clients.

• You want to monitor and potentially limit the usage of exposed services, based on your business requirements and system resource usage.
• Your services must be exposed using open standards to enable integration of heterogeneous applications.
• You want to bridge the gap between business requirements and existing service capabilities.
Solution:
• Use a Web Service Broker to expose and broker one or more services in your application to external clients as a Web Service using XML and standard web proto
Consequences:
• Introduces a layer between client and service.

• Existing remote Session Facades need be refactored to support local access.
• Network performance may be impacted due to web protocols.
• Coordinates interactions among one or more services, aggregates responses and may demarcate and compensate transactions.
public void sendImage(

@WebParam(name = "image", targetNamespace = "")
Image image
);
@WebMethod
@RequestWrapper(localName = "sendOctet",
className = "tip.attachment.SendOctet")
@ResponseWrapper(localName = "sendOctetResponse",
className = "tip.attachment.SendOctetResponse")
public void sendOctet(
@WebParam(name = "octet", targetNamespace = "")
DataHandler octet
);
}
One of the of additional benefits of MTOM is the fact that you can turn it on or off. In the case of Sw/A, if one side or the other doesn't support sending Sw/A attachments, t
defined by the WSDL cannot be honored. On the other hand, a client could choose to send data as an MTOM attachment or inline in the SOAP message. No matter what the
still interact with the Web service. MTOM is just an optimization of sending content, not a mandate like Sw/A.
byte[] on the Java interface. To get the mapping you are used to in JAX-RPC,
JAX-WS still supports the Sw/A model. By default, JAX-WS maps a Sw/A attachment to a
the enableMIMEContent WSDL binding definition. Listing below shows the JAX-WS version of the Java interface.
Unlike developing a web service provider, creating a web service client application always starts with an existing WSDL file. This process is
similar to the process you use to build a service from an existing WSDL file. The WSDL file that the client consumes already contains the WS-
* policy assertions (and, in some cases, any value-added WSIT policy assertions that augment Sun's implementation, but can safely be
ignored by other implementations). Most of the policy assertions are defined in the WS-* specifications. Sun's implementation processes
these standard policy assertions.
Chapter 12. Endpoint Design and Architecture

Given a scenario, design Web service applications using information models that are either
procedure-style or document-style.
• [NONE] blah
Empty
A WSDL document describes a Web service. A WSDL binding describes how the service is bound to a messaging protocol, particularly the
SOAP messaging protocol. A WSDL SOAP binding can be either a Remote Procedure Call (RPC) style binding or a document style binding. A
SOAP binding can also have an encoded use or a literal use. This gives you four style/use models:
1. RPC/encoded
2. RPC/literal
3. Document/encoded
4. Document/literal
Let's start with the Java method:
public void myMethod(int x, float y);
RPC/encoded
RPC/encoded WSDL for myMethod:
<message name="myMethodRequest">
<part name="x" type="xsd:int"/>
<part name="y" type="xsd:float"/>
</message>
<message name="empty"/>
<portType name="PT">
<operation name="myMethod">
<input message="myMethodRequest"/>
<output message="empty"/>
</operation>
</portType>
<binding .../>
RPC/encoded SOAP message for myMethod:
<soap:Envelope>
<soap:Body>
<myMethod>
<x xsi:type="xsd:int">5</x>
<y xsi:type="xsd:float">5.0</y>
</myMethod>
</soap:Body>
</soap:Envelope>
There are a number of things to notice about the WSDL and SOAP message for this RPC/encoded example:
• Strengths
o The WSDL is about as straightforward as it's possible for WSDL to be.
o The operation name appears in the message, so the receiver has an easy time dispatching this message to the
implementation of the operation.
• Weaknesses
o The type encoding info (such as xsi:type="xsd:int") is usually just overhead which degrades
throughput performance.
o You cannot easily validate this message since only the <x ...>5</x> and <y ...>5.0</y> lines
contain things defined in a schema; the rest of the soap:Body contents comes from WSDL definitions.
o Although it is legal WSDL, RPC/encoded is not WS-I compliant.
RPC/literal
The RPC/literal WSDL for this method looks almost the same as the RPC/encoded WSDL (see above). The use in the binding is
changed from encoded toliteral.
RPC/literal WSDL for myMethod:
<part name="x" type="xsd:int"/>
<part name="y" type="xsd:float"/>
</message>
</operation>
</portType>
<binding .../>
RPC/literal SOAP message for myMethod:
<soap:Envelope>
<soap:Body>
<myMethod>
<x>5</x>
<y>5.0</y>
</myMethod>
</soap:Body>
</soap:Envelope>
Here are the strengths and weaknesses of RPC/literal approach:
• Strengths
o The WSDL is still about as straightforward as it is possible for WSDL to be.
o The operation name still appears in the message.
o The type encoding info is eliminated.
o RPC/literal is WS-I compliant.
• Weaknesses
o You cannot easily validate this message since only the <x ...>5</x> and <y ...>5.0</y> lines
contain things defined in a schema; the rest of the soap:Body contents comes from WSDL definitions.
Document/encoded
Nobody follows this style. It is not WS-I compliant.
Document/literal
Document/literal WSDL for myMethod:
<types>
<schema>
<element name="xElement" type="xsd:int"/>
<element name="yElement" type="xsd:float"/>
</schema>
</types>
<part name="x" element="xElement"/>
<part name="y" element="yElement"/>
</message>
</operation>
</portType>
<binding .../>
Document/literal SOAP message for myMethod:
<soap:Envelope>
<soap:Body>
<xElement>5</xElement>
<yElement>5.0</yElement>
</soap:Body>
</soap:Envelope>
Here are the strengths and weaknesses of Document/literal approach:
• Strengths
o There is no type encoding info.
o You can finally validate this message with any XML validator. Everything within the soap:Body is defined in a
schema.
o Document/literal is WS-I compliant, but with restrictions.
• Weaknesses
o The WSDL is getting a bit more complicated. This is a very minor weakness, however, since WSDL is not meant to be
read by humans.
o The operation name in the SOAP message is lost. Without the name, dispatching can be difficult, and sometimes
impossible.
o soap:Body in a SOAP message. As you can see in listing above, this
WS-I only allows one child of the
example's soap:Body has two children.
Document/literal wrapped
Document/literal wrapped WSDL for myMethod:
<types>
<schema>
<element name="myMethod">
<complexType>
<sequence>
<element name="x" type="xsd:int"/>
<element name="y" type="xsd:float"/>
</sequence>
</complexType>
</element>
<element name="myMethodResponse">
<complexType/>
</element>
</schema>
</types>
<part name="parameters" element="myMethod"/>
</message>
<message name="empty">
<part name="parameters" element="myMethodResponse"/>
</message>
</operation>
</portType>
<binding .../>
The WSDL schema now has a wrapper around the parameters.
Document/literal wrapped SOAP message for myMethod:
<soap:Envelope>
<soap:Body>
<myMethod>
<x>5</x>
<y>5.0</y>
</myMethod>
</soap:Body>
</soap:Envelope>
Notice that this SOAP message looks like the RPC/literal SOAP message, but there's a subtle difference. In the RPC/literal SOAP message,
the <myMethod>child of <soap:Body> was the name of the operation. In the document/literal wrapped SOAP message,
the <myMethod> clause is the name of the wrapper element which the single input message's part refers to. It just so happens that
one of the characteristics of the wrapped pattern is that the name of the input element is the same as the name of the operation. This pattern
is a sly way of putting the operation name back into the SOAP message.
These are the basic characteristics of the document/literal wrapped pattern:
• The input message has a single part.

• The part is an element.
• The element has the same name as the operation.
• The element's complex type has no attributes.
Here are the strengths and weaknesses of document/literal wrapped approach:
• Strengths
o There is no type encoding info.
o Everything that appears in the soap:Body is defined by the schema, so you can easily validate this message.
o You have the method name in the SOAP message.
o Document/literal is WS-I compliant, and the wrapped pattern meets the WS-I restriction that the SOAP
message's soap:Body has only one child.
• Weaknesses
o The WSDL is even more complicated.
Reasons to use document/literal non-wrapped
If you have overloaded operations, you cannot use the document/literal wrapped style.
public void myMethod(int x);
When you add the wrapped pattern to WSDL, you require an element to have the same name as the operation, and you cannot have two
elements with the same name in XML. So you must use the document/literal, non-wrapped style or one of the RPC styles.
Reasons to use RPC/literal
Since the document/literal, non-wrapped style doesn't provide the operation name, there are cases where you'll need to use one of the RPC
styles. For instance, say you have the set of methods:

public void myMethod(int x);
public void someOtherMethod(int x, float y);
Now assume that your server receives the document/literal SOAP message. Which method should the server dispatch to? All you know for
myMethod(int x)
sure is that it's not because the message has two parameters and this method requires one. It could be either
of the other two methods. With the document/literal style, you have no way to know which one.
Instead of the document/literal message, assume that the server receives an RPC/literal message. With this message it's fairly easy for a
server to decide which method to dispatch to. You know the operation name is myMethod, and you know you have two parameters, so it
must be myMethod(int x, float y).
Reasons to use RPC/encoded
The primary reason to prefer the RPC/encoded style is for data graphs. Imagine that you have a binary tree whose nodes are defined:
<complexType name="Node">
<sequence>
<element name="name" type="xsd:string"/>
<element name="left" type="Node" xsd:nillable="true"/>
<element name="right" type="Node" xsd:nillable="true"/>
</sequence>
</complexType>
With this node definition, you could construct a tree whose root node A points to node B through both its left and right links. The standard
way to send data graphs is to use the href attribute, which is part of the RPC/encoded style:
<A>
<name>A</name>
<left href="12345"/>
<right href="12345"/>
</A>
<B id="12345">
<name>B</name>
<left xsi:nil="true"/>
<right xsi:nil="true"/>
</B>
Under any literal style, the href attribute is not available, so the graph linkage is lost. You still have a root node, A, which points to a
node B to the left and another node B to the right. These B nodes are equal, but they are not the same node. Data have been duplicated
instead of being referenced twice:
<A>
<name>A</name>
<left>
<name>B</name>
</left>
<right>
<name>B</name>
</right>
</A>
Design a Web service for an asynchronous, document-style process and describe how to refactor a
Web service from a synchronous to an asynchronous model.
• [BLUEPRINTS] Chapter 8 - Application Architecture
Refactoring Synchronous to Asynchronous Interactions
Sometimes your application requires an asynchronous Web Service interaction. Web Services that use asynchronous interactions tend to be
more responsive and scale better. However, Web Services provide only a synchronous mode of operation, especially when using the HTTP
protocol. In your application you can convert this synchronous interaction to an asynchronous request and reply. You may be able to refactor
some of the synchronous interactions of a Web Service application to asynchronous interactions.
Figure below illustrates a synchronous interaction. Notice how the client must suspend its processing until the service completes processing of
the request and returns a response.
On the other hand, with the asynchronous interaction, the client continues its processing without waiting for the service. In both the
synchronous and asynchronous communication figures, the vertical lines represent the passage of time, from top to bottom. The vertical
rectangular boxes indicate when the entity (client or service) is busy processing the request or waiting for the other entity to complete
processing. In figure below, the open arrowhead indicates asynchronous communication and the dashed vertical line indicates that the entity
is free to work on other things while a request is being processed.
When a component makes a synchronous call to another component, the calling component must wait for the receiving component to finish
its processing. If the calling component instead makes the call asynchronously, the caller can proceed with its own work without waiting for
the receiving component to do its job.
Below is the list of steps which need to be done to convert a synchronous endpoint to an asynchronous endpoint:
• Change a synchronous request/reply interaction into a request that returns void as the immediate reply.
• Change the client code to send the message request and immediately return.
• Have the client establish a reply address for receiving the response and include this reply address in the request. By including a
reply address, the service knows where to send the response message.
• A correlation identifier needs to be established between the request message and the service response message. Both the
client and the service use this identifier to associate the request and the reply.
• Refactor the server endpoint to accept the request, send it to a JMS queue for processing later, and immediately return an
acknowledgement to the client. The service retains the correlation identifier.
• Have the service processing layer use a message-driven bean to process the received request. When a response is ready, the
service sends the response to the reply address. In addition to the results, the response message contains the same correlation
identifier so that the service requestor can identify the request to which this response relates.
• Have the client accept the response at a Web Service that it establishes at the reply address.
The JMS queue stores the messages until the message-driven beans are ready to process them, thereby controlling the rate of delivery. Thus,
the component can process the messages without being overwhelmed, which helps the service to scale better.
The policy assertions describe any requirements from the server as well as any optional features the client may use. The WSIT build tools and
run-time environment detect the WSDL's policy assertions and configure themselves appropriately, if possible. If an unsupported assertion is
found, an error message describing the problem will be displayed.
Typically, you retrieve the WSDL directly from a web service provider using the wsimport tool. The wsimport tool then generates
javac, is then called to compile the
the corresponding Java source code for the interface described by the WSDL. The Java compiler,
source into class files. The programming code uses the generated classes to access the web service.
<wsp:Policy wsu:Id="AddNumbers_policy">
<wsp:ExactlyOne>
<wsp:All>
<wsaw:UsingAddressing/>
<wsrm:RMAssertion>
<wsrm:InactivityTimeout Milliseconds="600000"/>
<wsrm:AcknowledgementInterval Milliseconds="200"/>
</wsrm:RMAssertion>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
This snippet would be equally valid in either a WSIT configuration file or a web service's WSDL document.

Chapter

Enviado por

Dados do documento

Descrição original:

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Chapter

Enviado por

Direitos autorais:

Formatos disponíveis

Chapter 1.

XML Web Service Standards

Basic Profile. SOAP Envelopes

The children of the soap:Body element in an ENVELOPE MUST be namespace qualified.

An ENVELOPE MUST NOT contain a Document Type Declaration.

An ENVELOPE MUST NOT contain Processing Instructions.

An ENVELOPE SHOULD NOT contain the namespace

A DESCRIPTION SHOULD NOT contain the namespace

<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >

<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >

soap:encodingStyle attributes on any of the elements whose namespace name

Basic Profile. SOAP Processing Model

Basic Profile. SOAP Faults

soap:Fault element MUST NOT have element children other

<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >

<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >

<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns='' >

INCORRECT example (children of the soap:Fault elements have namespace qualification):

<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >

NOTE: The set of faultcode values defined in SOAP 1.1 document

<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >

Basic Profile. Use of SOAP in HTTP

A MESSAGE MUST be sent using either HTTP/1.1 or HTTP/1.0.

A MESSAGE SHOULD be sent using HTTP/1.1.

A HTTP request MESSAGE MUST use the HTTP POST method.

A MESSAGE MUST NOT use the HTTP Extension Framework (RFC2774).

CORRECT example #1:

A WSDL Description that has:

<soapbind:operation soapAction="foo" />

results in a message with a SOAPAction HTTP header field of:

CORRECT example #2:

A WSDL Description that has:

<soapbind:operation soapAction="" />

results in a message with a corresponding SOAPAction HTTP header field as follows:

Basic Profile. Service Description. Document Structure

CORRECT description example:

CORRECT description example:

INCORRECT description example (imports not "wsdl" document):

A DESCRIPTION MUST specify a non-empty location attribute on the wsdl:import element.

<definitions name="StockQuote" targetNamespace="http://example.com/stockquote/definitions">

INCORRECT example ( wsdl:types elements MUST precede all other elements):

Basic Profile. Service Description. Types

In a DESCRIPTION, declarations MUST NOT extend or restrict the soapenc:Array type.

In a DESCRIPTION, elements SHOULD NOT be named using the convention ArrayOfXXX.

An ENVELOPE MUST NOT include the soapenc:arrayType attribute.

Given the WSDL Description:

<xsd:element name="MyArray1" type="tns:MyArray1Type"/>

The envelope would serialize as (omitting namespace declarations for clarity):

Given the WSDL Description:

<xsd:element name="MyArray2" type="tns:MyArray2Type"/>

The envelope would serialize as (omitting namespace declarations for clarity):

<MyArray2 soapenc:arrayType="tns:MyArray2Type[]" >

Describe the use of XML schema in Java EE Web services.

• [SCHEMA_PART_0] XML Schema Part 0: Primer Second Edition

• [SOAP_1.2_PART_2] SOAP Version 1.2 Part 2: Adjuncts

Let's start from "Hello World!" example:

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

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

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

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

Another example of XML document for more complex purchase order:

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

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