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. soap:Envelope.

A RECEIVER MUST generate a fault if they encounter an envelope whose document element is not

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". xmlns:xml="http://www.w3.org/XML/1998/namespace". soap:Envelope following the soap:Body element.

A DESCRIPTION SHOULD NOT contain the namespace declaration

An ENVELOPE MUST NOT have any element children of

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>

An ENVELOPE MUST NOT contain is

soap:encodingStyle attributes on any of the elements whose namespace name "http://schemas.xmlsoap.org/soap/envelope/". soap:encodingStyle attributes on any element that is a child of soap:Body. soap:encodingStyle attribute on any element that is a

An ENVELOPE MUST NOT contain

An ENVELOPE described in an rpc-literal binding MUST NOT contain grandchild of

soap:Body.

An ENVELOPE containing a

soap:mustUnderstand attribute MUST only use the lexical forms "0" and "1". xsi:type attribute in envelopes except as required in order to indicate a derived type

A RECEIVER MUST NOT mandate the use of the (see XML Schema Part 1: Structures, Section 2.6.1).

The

namespace

soap:Envelope, soap:Header, and soap:Body elements in an ENVELOPE MUST NOT have attributes in the "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.

A RECEIVER MUST generate a that has a receiver does not understand.

"soap:MustUnderstand" fault when an envelope contains a mandatory header block (i.e., one soap:mustUnderstandattribute with the value "1") targeted at the receiver (via soap:actor) that the

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.

When an ENVELOPE is a Fault, the than

soap:Fault element MUST NOT have element children other 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:

<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> 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='' > <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> </detail> </soap:Fault>

INCORRECT example (children of the

soap:Fault elements have namespace qualification):

<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <soap:faultcode>soap:Client</soap:faultcode> <soap:faultstring>Invalid message format</soap:faultstring> <soap:faultactor>http://example.org/someactor</soap:faultactor> <soap: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> </soap:detail> </soap:Fault>

A RECEIVER MUST accept faults that have any number of elements, including zero, appearing as children of the children can be qualified OR unqualified.

detail element. Such

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

SOAP 1.1 (supplying additional information if necessary in the fault's specifying authority (in that order of preference).

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

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

VersionMismatch, MustUnderstand, Client, Server. faultcode element the content of that element SHOULD NOT use of the SOAP 1.1 "dot" notation to

When an ENVELOPE contains a 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:

<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <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. SOAPAction HTTP header field in a message is not quoted.

A RECEIVER MAY respond with a fault if the value of the

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. "import" statement.

To import XML Schema Definitions, a DESCRIPTION MUST use the XML Schema

A DESCRIPTION MUST use the XML Schema

"import" statement only within the xsd:schema element of the types section.

In a DESCRIPTION the root element is not

schemaLocation attribute of an xsd:import element MUST NOT resolve to any document whose "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:

<definitions name="StockQuote" targetNamespace="http://example.com/stockquote/" xmlns:xsd1="http://example.com/stockquote/schemas" ... 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="xsd1:TradePriceRequest"/> </message> ... </definitions>

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

<definitions name="StockQuote" targetNamespace="http://example.com/stockquote/definitions" xmlns:xsd1="http://example.com/stockquote/schemas" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote/schemas"

location="http://example.com/stockquote/stockquote.xsd"/> <message name="GetLastTradePriceInput"> <part name="body" element="xsd1:TradePriceRequest"/> </message> ... </definitions>

A DESCRIPTION MUST specify a non-empty

location attribute on the wsdl:import element.

When they appear in a DESCRIPTION, except

wsdl:import elements MUST precede all other elements from the WSDL namespace wsdl:documentation. wsdl:types elements MUST precede all other elements from the WSDL namespace wsdl:documentation andwsdl:import.

When they appear in a DESCRIPTION, except

CORRECT example:

<definitions name="StockQuote" targetNamespace="http://example.com/stockquote/definitions"> <import namespace="http://example.com/stockquote/base" location="http://example.com/stockquote/stockquote.wsdl"/> <message name="GetLastTradePriceInput"> <part name="body" element="..."/> </message> ... </definitions>

CORRECT example:

<definitions name="StockQuote" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <types> <schema targetNamespace="http://example.com/stockquote/schemas" xmlns="http://www.w3.org/2001/XMLSchema"> ....... </schema> </types> <message name="GetLastTradePriceInput"> <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):

<definitions name="StockQuote" ... 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" type="tns:TradePriceRequest"/>

</message> ... <service name="StockQuoteService"> <port name="StockQuotePort" binding="tns:StockQuoteSoap"> .... </port> </service> <types> <schema targetNamespace="http://example.com/stockquote/schemas" xmlns="http://www.w3.org/2001/XMLSchema"> ....... </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

on an

targetNamespace attribute on the xsd:schemaelement, or to a namespace defined in the namespace attribute xsd:import element within the xsd:schema element. soapenc:Array type.

In a DESCRIPTION, declarations MUST NOT extend or restrict the

In a DESCRIPTION, declarations MUST NOT use

wsdl:arrayType attribute in the type declaration. ArrayOfXXX.

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

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:

Given the WSDL Description:

<xsd:element name="MyArray2" type="tns:MyArray2Type"/> <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>

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

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

<?xml version="1.0" encoding="UTF-8" ?> <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.

<?xml version="1.0" encoding="UTF-8" ?> <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:

<?xml version="1.0" encoding="UTF-8" ?> <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:

<?xml version="1.0" encoding="UTF-8" ?> <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:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <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"> <name>Mikalai Zaikin</name> </author>

SOAP 1.2

<e:Books> <e:Book> <title>SCDJWS 5.0 Study Guide</title> <author id="mz" > <name>Mikalai Zaikin</name> </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. maxOccurs is 1.

Default value of

XML Schema defines four main elements:

1. 2. 3. 4.

xsd:element declares an element and assigns it a type. xsd:attribute declares an attribute and assigns it a type. xsd:complexType defines a new complex type. 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 of

xsd:simpleType element defines the subtype. The name attribute xsd: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

the new type. 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 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:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <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:

<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:simpleType name="myYear"> <xsd:restriction base="xsd:gYear"> <xsd:minInclusive value="1974"/> <xsd:maxInclusive value="2100"/> </xsd:restriction> </xsd:simpleType> </xsd:schema>

The facet lists all allowed values. Applies to all simple types except name must be one of the following : IBA JV, IBM, COMPAQ, DELL, HP.

enumeration

boolean. For example, the computer brand

<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <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

group must be the top level element of its type. The The no choices or sequences. Example:

xsd:all

xsd:all group must occur zero or once; that is minOccurs and maxOccurs must each be 0 or 1. xsd:all group may contain only individual element declarations;

<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <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>

have

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:

<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <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 o o o o

Strings Enumerations Array of Bytes

Compound Types: Arrays 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 include:

boolean (true, false, 0 or 1), byte, short, int, long, float, double, string (java.l 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

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:
The datatype " "

<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"/>

(In this example, the type

" and which also allows an " " and " " attribute. See the SOAP Encoding schema for the exact datatype is " definition. Schemas MAY use these declarations from the SOAP Encoding schema but are not required to.)

SOAP-ENC:string is used as the element's type as a convenient way to declare an element whose xsd:string id href

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

Green", "Blue", "Brown") could be defined as an enumeration based on string 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"
type. For example the set of color names (" the Specification can be used to define enumeration types. If a schema is generated from another notation in which no specific base type is applicable, use " "

string". In the following schema example "EyeColor" is defined as a string with the possible values of 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 "

have matching " " attributes. The recommended representation of an opaque array of bytes is the ' ' 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 "

href

id" attribute. Additional accessor elements MAY then base64

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 accessor instance MUST contain an " accessor named "

xsi:type" attribute that describes the type of the actual value. For example, a polymorphic 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> <title>SCDJWS 5.0 Study Guide</title> <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 single dimension of unspecified size.

arraySize attribute information item is "*", that is by default arrays are considered to have a

<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)

" or a type derived there from. Arrays are represented as In SOAP 1.1 arrays are defined as having a type of " 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 can also be created to represent, for example, arrays limited to integers or arrays of some userrestrictions of 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 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:

SOAP-ENC:Array

SOAP-ENC:Array

href"

<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 "

can be determined by inspection of the

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

unqualified element names without restriction. These convey no type information, so when used they must either have an

from 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 "

xsi:type attribute or the containing element must have a SOAP-ENC:arrayType attribute. Naturally, types derived SOAP-ENC:Array SOAP-ENC Array". Using these, we might write:

<SOAP-ENC:Array SOAP-ENC:arrayType="xsd:int[3]"> <SOAP-ENC:int>1</SOAP-ENC:int> <SOAP-ENC:int>2</SOAP-ENC:int> <SOAP-ENC:int>3</SOAP-ENC:int> </SOAP-ENC:Array>

arrayType. 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 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.
Arrays can contain instances of any subtype of the specified for the type specified in the 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> <item>row1column2</item> <item>row1column3</item> </SOAP-ENC:Array> <SOAP-ENC:Array id="array-2" SOAP-ENC:arrayType="xsd:string[2]"> <item>row2column1</item> <item>row2column2</item> </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>row1column1</item> <item>row1column2</item> <item>row1column3</item> <item>row2column1</item> <item>row2ccolumn2</item> <item>row2column3</item> </SOAP-ENC:Array>

NOTE: According to WS-I BP 1.1 you MUST NOT use or

soapenc:Array type for array declarations 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 xsd:integer xsd:int xsd:long xsd:short xsd:decimal xsd:float xsd:double xsd:boolean xsd:byte xsd:QName xsd:dateTime xsd:base64Binary xsd:hexBinary xsd:unsignedInt

java.lang.String java.math.BigInteger int long short java.math.BigDecimal float double boolean byte QName XMLGregorianCalendar byte[] byte[] long

xsd:unsignedShort int xsd:unsignedByte xsd:time xsd:date xsd:g
Wrapper Classes

short XMLGregorianCalendar XMLGregorianCalendar XMLGregorianCalendar

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:
<element name="count" type="xsd:int" nillable="true" />

2. 3. 4.

5.

An its

element element with its minOccurs attribute set to 0 and its maxOccurs attribute set to 1, or maxOccurs attribute not specified, as shown:
<element name="count" type="xsd:int" minOccurs="0" />

6. 7. 8.

9.

An its

attribute element with its use attribute set to optional, or not specified, and having neither default attribute nor its fixed attribute specified, as shown:
<element name="date"> <complexType> <sequence/> <attribute name="count" type="xsd:int" use="optional" /> </complexType> </element>

10. 11. 12. 13. 14. 15. 16. 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 xsd:long xsd:short xsd:float xsd:double xsd:boolean xsd:byte xsd:unsignedByte

java.lang.Integer java.lang.Long java.lang.Short java.lang.Float java.lang.Double java.lang.Boolean java.lang.Byte java.lang.Short

xsd:unsignedShort java.lang.Integer xsd:unsignedInt xsd:unsignedLong java.lang.Long 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 builtin 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 in

nillable attribute to indicate that whether the element's content could be nil, as <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. nillable attribute. Consider following XML Schema:

More examples on

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <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 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 one

<xsd:any/>

Order. It contains two regular elements and

<xsd:any/> element:

<schema elementFormDefault="qualified" xmlns="http://www.w3.org/2001/XMLSchema"> <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 an that

Order element without defining its format in the schema. The JAX-RPC 1.1 specification defines <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 than a mapped Java object.

SOAPElement rather

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 intermediary and the ultimate SOAP receiver MUST act in this role.

next

"http://www.w3.org/2003/05/soapenvelope/role/next" "http://www.w3.org/2003/05/soapenvelope/role/none" "http://www.w3.org/2003/05/soapenvelope/role/ultimateReceiver"

none ultimateReceiver

SOAP nodes MUST NOT act in this role.

The ultimate receiver MUST act in 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

specified role. SOAP 1.2 specification refers to the value of the SOAP corresponding SOAP header block.

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

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/soapenvelope/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

A SOAP header block MAY carry a item is

mustUnderstand attribute information item. When the value of such an attribute information "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. 2. 3.

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. Identify all header blocks targeted at the node that are mandatory. 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 of set to . 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. 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. 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.

Value

Code

"env:MustUnderstand"

4. 5.

Relaying SOAP Messages

A SOAP header block MAY carry a the header block is said to be relayable.

relay attribute information item. When the value of such an attribute information item is "true",

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. 2. 3.

Remove all processed SOAP header blocks. Remove all non-relayable SOAP header blocks that were targeted at the forwarding node but ignored during processing. 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".

If a SOAP node receives a message whose version is not supported it MUST generate a fault with a to

Value of Code set "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". Upgrade SOAP header block indicating support for SOAP Version 1.2:

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

<?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

and elements. SOAP does not define their contents. The elements are that SOAP defines. These are the specific to the application that creates and processes the SOAP message. However, the SOAP specification does define how a SOAP node processes these elements.

env:Envelope that includes the namespace URL for SOAP. Enclosed within this are two subelements env:Header env:Body

element is OPTIONAL in SOAP, but it has been included in the sample to illustrate its use. The SOAP header is an The extension mechanism that provides a way for information to be passed within a SOAP message that is not part of the business message includes an immediate child element that contains a set of quality of service payload. In the previous example, the parameters. This immediate child is called a header block. A header can contain many header blocks. The header block has its own XML , , and elements appear. The SOAP specification allows header blocks namespace in which the 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.

env:Header

env:Header

priority timestamp

persist

The 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 and what goes into the elements is a matter of business application and system design. In a typical the enterprise environment, middleware that supports a defined set of service policies mandates what headers are required in a SOAP message. is then used to contain necessary application-specific information, which is processed by the ultimate receiver of the The remote service implemention.

env:Body

env:Header env:Body

env:Body

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:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <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 element has a role attribute set to a value of . 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 the roles defined within the SOAP 1.2 specification. The SOAP 1.2 specification defines three roles:

hb1:firstHeaderBlock

http://example.org/Qos

hb2:secondHeaderBlock has its role attribute set to one of

http://www.w3.org/2003/05/soap-envelope/role/none
URI, no SOAP node should process the contents of the header block. Nodes If a header block has a role set to the might need to examine the header contents if another header block references them, but they should not be processed.

"none"

http://www.w3.org/2003/05/soap-envelope/role/next

"next" URI, because this is a "next" URI is one that the next SOAP node in the message path should examine and possibly process. In the previous example, the hb2:secondHeaderBlock has its role attribute set to "next".
Every SOAP node must be capable of processing a header block with its role attribute set to the role that every node should assume. A header block with a role set to the

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

as an ultimate SOAP receiver. In the example, the receiver because it doesn't have a role attribute.

"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 actor attribute. In SOAP 1.2 this attribute is renamed to role. The semantics of the attribute are

NOTE: SOAP 1.1 has the 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:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Header> <hb1:firstHeaderBlock exmlns:hb1="http://example.org/hb1" env:role="http://example.org/Qos" env:mustUnderstand="1"> ..... </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>

In the example, the SOAP node that is targeted by the

attribute is set to . This is commonly referred to as a mandatory header block. The SOAP because a 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"

hb1:firstHeaderBlock element must process the header block 1

attribute and is targeted at a header block, even though it might be targeted at it. If a header block has a SOAP node, the SOAP node is obliged to generate and return a SOAP fault if it is unable to process the header block.

"mustUnderstand" attribute set to 0, or there is no such attribute, a SOAP node might choose to ignore and not process the "mustUnderstand"

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, attribute. If this attribute is set to SOAP 1.2 introduces the forward the header block to the next node if it chooses not to process it.

"relay"

true, a SOAP node that detects a header targeted at itself can

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Header> <hb1:firstHeaderBlock xmlns:hb1="http://example.org/hb1" env:role="http://example.org/Qos" env:mustUnderstand="1"> ..... </hb1:firstHeaderBlock> <hb2:secondHeaderBlock xmlns:hb1="http://example.org/hb2" env:role="http://www.w3.org/2003/05/soap-envelope/role/next" env:relay="true"> ..... </hb2:secondHeaderBlock> <hb3:thirdHeaderBlock xmlns:hb1="http://example.org/hb3"> ..... </hb3:thirdHeaderBlock> </env:Header> <env:Body> ..... </env:Body> </env:Envelope>

In the example, the second header block is targeted at the to

"next" node in the message path. It also has the "relay" attribute set 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:

If relaying the message, a SOAP intermediary MAY substitute SOAP intermediary MAY omit a SOAP

"true" for the value "1", or "false" for "0". In addition, a 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. 2. 3. 4.

Provide a URI to name the MEP. Describe the life cycle of a message exchange conforming to the pattern. 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.) 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. 2. 3.

4.

5.

MUST identify itself with a URI. This enables the module to be unambiguously referenced in description languages or during negotiation. MUST declare the features provided by a module. 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. 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. 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

The 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 feature and whether it is optional or mandatory. NOTE: The

Envelope is the top element of the XML document representing the message. Header

Header element is OPTIONAL. 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". Header element information item. Body element information item.

The element MUST be present in a SOAP message. One or two element information items in its [children] property in order as follows: a. b. An optional

A mandatory

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:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <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 qualified.

Header element. All immediate child elements of the SOAP Header element MUST be namespaceHeader element be namespace qualified.

NOTE: WS-I BP 1.0 requires all immediate children of

3.

SOAP 1.2 Schema for

Header:

4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17.
18.

<xs:complexType name="Header"> <xs:annotation> <xs:documentation> Elements replacing the wildcard MUST be namespace qualified, but can be in the targetNamespace </xs:documentation> </xs:annotation> <xs:sequence> <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:complexType>

Example:

19. 20. 21. 22. 23. 24. 25. 26.
27.

<env:Header xmlns:env="http://www.w3.org/2003/05/soap-envelope" > <t:Transaction xmlns:t="http://example.org/2001/06/tx" env:mustUnderstand="1" > 5 </t:Transaction> </env:Header>

Body

• • •

The element name is "

Body".

The element MUST be present in a SOAP message and MUST be an immediate child element of a

Envelope element. It MUST directly follow the SOAP Header element if present. Otherwise it MUST Envelope 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 be the first immediate child element of the SOAP 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. 31. 32. 33. 34. 35. 36. 37.
38.

<xs:complexType name="Body"> <xs:sequence> <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:complexType>

Example:

39. 40. 41. 42. 43. 44. 45. 46.

<env:Body xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <m:alert xmlns:m="http://example.org/alert"> <m:msg>Pick up Mary at school at 2pm</m:msg> </m:alert> </env:Body>

The SOAP

message. Typical uses of the

Body element provides a simple mechanism for exchanging mandatory information intended for the ultimate recipient 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. Header 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 and each body entry is encoded as an independent element within the SOAP Body element. The encoding rules for body entries are as
first immediate child element of the

If a

follows:

1.

WS-I BP 1.1: The children of the

soap:Body element in an ENVELOPE MUST be namespace qualified. soap:encodingStyle attributes on any element that is a child

WS-I BP 1.1: An ENVELOPE MUST NOT contain of

soap:Body. rpc-literal binding MUST NOT soap:encodingStyle attribute on any element that is a grandchild of soap:Body.

2.

WS-I BP 1.1: An ENVELOPE described in an contain

SOAP Fault

SOAP defines one body entry, which is the of

Fault entry used for reporting errors. Here is SOAP 1.2 Schema definition

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

MUST appear as a body entry and MUST NOT appear more than once within a more child element information items in its [children] property in order as follows:

Fault element is used to carry error and/or status information within a SOAP message. If present, the SOAP Fault element Body element. The SOAP Fault element defines two or Code element.

1.

A MANDATORY

2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12.

<xs:element name="Code" type="tns:faultcode"/> ... <xs:complexType name="faultcode"> <xs:sequence> <xs:element name="Value" type="tns:faultcodeEnum"/> <xs:element name="Subcode" type="tns:subcode" minOccurs="0"/> </xs:sequence> </xs:complexType>

The

Code element information item has: • •
A [local name] of

Code. Value element information item. Value env:faultCodeEnum. SOAP 1.2

One or two child element information items in its [children] property, in order, as follows: a. A MANDATORY

element information item is The type of the 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. e. f. g. h. i. j. k. l.

<xs:element name="Subcode" type="tns:subcode" minOccurs="0"/> ... <xs:complexType name="subcode"> <xs:sequence> <xs:element name="Value" type="xs:QName"/> <xs:element name="Subcode" type="tns:subcode" minOccurs="0"/> </xs:sequence> </xs:complexType>

The

Subcode element information item has: o o
A [local name] of

Subcode. Value element information item. Value xs:QName. The value

One or two child element information items in its [children] property, in order, as follows: i. A MANDATORY

element information item is The type of the of this element is an application defined subcategory of the value of child element information item of the the information item's parent element information item.

Value

Subcode element

ii. 13. A MANDATORY

An optional

Subcode element information item.

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] of One or more

Reason. Text element information item children.

of

Text element information item MUST have a mandatory attribute information item with a [local name] lang 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
Each child capitalization thereof.

Each child information item.

Text element information item SHOULD have a different value for its xml:lang attribute

<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 element information item is intended to provide information about which SOAP node on the SOAP message path caused the fault to happen.

Node

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

Node

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. Role element information item is xs:anyURI.

The type of the

<xs:element name="Role" type="xs:anyURI" minOccurs="0"/>

The value of the message.

Role element information item MUST be one of the roles assumed by the node during processing of the

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

Detail

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 about a message not containing the proper credentials, a timeout, etc. The presence of the Detail element information item
to the SOAP fault codes describing the fault. For example, the

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.

The values of the the

Value child element information item of the Code element information item are RESTRICTED to those defined by env: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 Detail 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.
SOAP fault codes are to be interpreted as modifiers of the contents of the provide the context for the Sample SOAP fault where the the

Detail element information item is to be interpreted in the context of "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

not match the

Envelope element information item. The namespace, local name or both did Envelope element information item required by this recommendation. Header

MustUnderstand

An immediate child element information item of the SOAP element information 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.

Receiver

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.

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 requestresponse 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

, which sends the message and blocks until it receives a response. A standalone client can method operate only in a client role, that is, it can only send requests and receive their responses.

SOAPConnection.call

SOAPMessage object represents an XML document that is a SOAP message. A SOAPMessage object always has a required SOAPEnvelope object, which must in turn always contain a SOAPBody object. TheSOAPEnvelope object may also contain a SOAPHeader object, to
A SOAP part, and it may also have one or more attachment parts. The SOAP part must always have a which one or more headers can be added.

object can hold XML fragments as the content of the message being sent. If you want to send content that is not in XML The 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:

SOAPBody

.mp3, .jpg, and .mpg files.

A

SOAPConnection object. 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:
The first thing a SAAJ client needs to do is get a connection in the form of a

SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance();
The client can use

factory to create a SOAPConnection object.

SOAPConnection connection = factory.createConnection();

Messages, like connections, are created by a factory. To obtain a implementation for the

MessageFactory object, you get an instance of the default MessageFactory class. This instance can then be used to create a SOAPMessage object:

MessageFactory messageFactory = MessageFactory.newInstance(); SOAPMessage message = messageFactory.createMessage();

SOAPMessage objects that messageFactory creates, including message in the previous line of code, will be SOAP SOAPMessage object message automatically contains the 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
All of the messages. This means that they will have no pre-defined headers. The new 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; ... }

As stated earlier, all messages have a a

SOAPPart object, which has a SOAPEnvelope object containing 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 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:
One way to add content to the SOAP part of a message is to create a a

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>

SOAPPart object by passing it a javax.xml.transform.Source object, which 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
Another way is to add content to the may be a document.

DOMSource object. The first step is to get the SOAPPart object from 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:
The following code fragments illustrates adding content as a the

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

send as the content of a SOAP message, 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:

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.

object may have no attachment parts, but if it is to contain anything that is not in XML format, that content must be A 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

SOAPMessage

the

javax.activation.DataHandler object handler. The Message object message creates 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

to the method

SOAPMessage object can also give content to an AttachmentPart object by passing an Object and its content type createAttachmentPart:

AttachmentPart attachPart = message.createAttachmentPart( "content-string", "text/plain"); message.addAttachmentPart(attachPart);

Once you have populated a the

SOAPMessage object, you are ready to send it. A client uses 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 ( illustrates the use of the

claim.tiff), also it

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 " " header line has been continued across two lines so the example prints easily. SOAP message senders should send headers on a single long line.

Content-Type

NOTE: Associate the attachment to a

theSignedForm element by adding an href attribute. The attachment is referred to through

cid (Content-ID) URL:

... <myElement href="cid:xxxx" /> ... --MIME_boundary Content-Type: image/tiff Content-Transfer-Encoding: binary Content-ID: <xxxx> ...

NOTE: Unlike SOAP 1.1 XML references, do not use ' ' (pound sign) in refer to attachment you must prepend unique identifier with prefix '

#

href attribute value when you refer to attachment, also when you 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. 2. 3. 4. 5. 6. 7.

Create SOAP connection and SOAP message objects through factories. Retrieve the message body from the message object (intermediary steps: retrieve the SOAP part and envelope). Create a new XML element to represent the request.

DataHandler object. source and percent). Associate the attachment to the first parameter by adding an href attribute. The attachment is referred to through a cid (Content-ID) URI.
Create the attachment and initialize it with a Create more elements to represent the two parameters ( 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-Transfer-Encoding: binary Content-Id: <EB6FC7EDE9EF4E510F641C481A9FF1F3> <?xml version="1.0" encoding="UTF-8"?> <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-Transfer-Encoding: binary 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

2.

services The binding layer describes concrete properties:

• • •

protocols data formats

The

multiple namespaces used throughout the remainder of the document. An actual WSDL document consists of a set of the following kinds:

definitions element MUST be the root element of all WSDL documents. It defines the name of the web service, declares definitions of types types

- Contains XML Schema element and type definitions. The 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 is not required.

types element

element encloses data type definitions that are relevant for the exchanged messages. For maximum The interoperability and platform neutrality, WSDL prefers the use of XSD as the canonical type system, and treats it as the intrinsic type system.

types

<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 the

targetNamespace attribute on the xsd:schema element, or to a namespace defined in namespace attribute on an xsd:import element within the xsd:schema element.

WS-I BP 1.1: All a

xsd:schema elements contained in a wsdl:types element of a DESCRIPTION MUST have 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). soapenc:Array type.

WS-I BP 1.1: In a DESCRIPTION, declarations MUST NOT extend or restrict the

WS-I BP 1.1: In a DESCRIPTION, declarations MUST NOT use

wsdl:arrayType attribute in the type declaration. ArrayOfXXX.

WS-I BP 1.1: In a DESCRIPTION, elements SHOULD NOT be named using the convention

WS-I BP 1.1: An ENVELOPE MUST NOT include the

soapenc:arrayType attribute.

CORRECT:

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 (uses

soapenc:arrayType attribute and soapenc:Array type):

Given the WSDL Description:

<xsd:element name="MyArray2" type="tns:MyArray2Type"/> <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>

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

<MyArray2 soapenc:arrayType="tns:MyArray2Type[]" > <x>abcd</x> <x>efgh</x> </MyArray2>

XML Schema type. The

message - Consists of either a number of named parts typed by XML Schema elements, or a single part typed by a 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 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):
A DESCRIPTION MUST NOT use a

message parameters or message return values.

Solicit-Response and Notification type operations in wsdl:portType definition.

<wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken"> <wsdl:input name="nmtoken"? message="qname"/> </wsdl:operation> </wsdl:portType > </wsdl:definitions>

o o o o o o o o o o o o

request-response: The endpoint receives an

RPC - Remote Procedure Call). (NOTE: The WS-I BP 1.1 restricts the valid and request-response operations).

input message and then responds with an output message (like wsdl:operations to one-way

<wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken" parameterOrder="nmtokens"> <wsdl:input name="nmtoken"? message="qname"/> <wsdl:output name="nmtoken"? message="qname"/> <wsdl:fault name="nmtoken" message="qname"/>* </wsdl:operation> </wsdl:portType > </wsdl:definitions>

o

solicit-response: The endpoint sends an DESCRIPTION MUST NOT use a

output message and then receives an input message (NOTE: A Solicit-Response and Notification type operations in

wsdl:portType definition - R2303 - BP 1.1).
<wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken" parameterOrder="nmtokens"> <wsdl:output name="nmtoken"? message="qname"/> <wsdl:input name="nmtoken"? message="qname"/> <wsdl:fault name="nmtoken" message="qname"/>* </wsdl:operation> </wsdl:portType > </wsdl:definitions>

o o o o o o o o o o o

o o o o o o o o o o

notification: The endpoint sends an 1.1).

output message (NOTE: A DESCRIPTION MUST NOT use SolicitResponse and Notification type operations in a wsdl:portType definition - R2303 - BP

<wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken" parameterOrder="nmtokens"> <wsdl:output name="nmtoken"? message="qname"/> </wsdl:operation> </wsdl:portType > </wsdl:definitions>

portType element combines multiple message elements to form a complete one-way or round-trip operation. For portType 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
The example, a 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 Section 3.

wsdl:binding element in a DESCRIPTION MUST use WSDL SOAP Binding as defined in WSDL 1.1

wsdl:binding element in a DESCRIPTION MUST specify the HTTP transport protocol with SOAP binding. transportattribute of its soapbind:binding child MUST have the value "http://schemas.xmlsoap.org/soap/http".
WS-I BP 1.1: A Specifically, the 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.

of

wsdl:binding and its wsdl:portType have the same list 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:
The WS-I BP 1.1 requires that a WS-I BP 1.1: A the

wsdl:binding in a DESCRIPTION MUST have the same set of wsdl:operations as wsdl:portType to which it refers.

element defines the address for invoking the specified service. Most commonly, this includes a URL for invoking The the SOAP service.

service - Describes a collection of named ports, each associated with a binding and a network address. service

The simplified structure of a WSDL document is:

<definitions> <!-- root WSDL element --> <types> <!-- defines data types to be transmitted --> </types> <message> <!-- defines messages to be transmitted --> </message> <portType> <!-- defines operations (functions) to be supported --> </portType> <binding> <!-- defines how will the messages be transmitted on the wire --> </binding> <service> <!-- defines location of web 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"> * <wsdl:documentation .... />? <part name="nmtoken" element="qname"? type="qname"?/> *

</wsdl:message> <wsdl:portType name="nmtoken">* <wsdl:documentation .... />? <wsdl:operation name="nmtoken">* <wsdl:documentation .... /> ? <wsdl:input name="nmtoken"? message="qname">? <wsdl:documentation .... /> ? </wsdl:input> <wsdl:output name="nmtoken"? message="qname">? <wsdl:documentation .... /> ? </wsdl:output> <wsdl:fault name="nmtoken" message="qname"> * <wsdl:documentation .... /> ? </wsdl:fault> </wsdl:operation> </wsdl:portType> <wsdl:binding name="nmtoken" type="qname">* <wsdl:documentation .... />? <-- extensibility element --> * <wsdl:operation name="nmtoken">* <wsdl:documentation .... /> ? <-- extensibility element --> * <wsdl:input> ? <wsdl:documentation .... /> ? <-- extensibility element --> </wsdl:input> <wsdl:output> ? <wsdl:documentation .... /> ? <-- extensibility element --> * </wsdl:output> <wsdl:fault name="nmtoken"> * <wsdl:documentation .... /> ? <-- extensibility element --> * </wsdl:fault> </wsdl:operation> </wsdl:binding> <wsdl:service name="nmtoken"> * <wsdl:documentation .... />? <wsdl:port name="nmtoken" binding="qname"> * <wsdl:documentation .... /> ? <-- extensibility element --> </wsdl:port> <-- extensibility element --> </wsdl:service> <-- extensibility element --> * </wsdl:definitions>

Example of simple WSDL (SOAP 1.1 Request-Response via HTTP):

<?xml version="1.0" encoding="UTF-8"?> <definitions name="StockQuote" 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/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <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 name="GetLastTradePriceInput"> <part name="body" element="xsd1:TradePriceRequest"/> </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> <soap:body use="literal"/> </output> </operation> </binding> <service name="StockQuoteService"> <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 defined by a particular

portType, as well as the data formats for the messages that are

portType element.

binding attributes are: o o name any name type - points to the port type defined in the abstract part

soap:binding attributes are: o o style - "rpc" | "document" transport - Communication protocol : SOAP, Transport protocol : HTTP/SMTP

operation element: o o
defines each operation that the port exposes. must also specify how the input and output are encoded :

literal | encoded

<binding name="ProcurementSoapBinding" type="tns:procurementPortType"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="orderGoods"> <soap:operation soapAction="http://example.com/orderGoods"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </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 associates message exchange patterns with one or more messages. An messages. An operations in a transport and wire independent manner.

operation

interface groups these

In the concrete part of the description,

associates network address with a binding. Finally, a service interface. Figure below shows the conceptual WSDL component model:

endpoint

bindings specify the transport and wire format for interfaces. A service groups the endpoints that implement a common

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

in other components such as bindings. The interface element has other interfaces. Interfaces are referred to by 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.

interface element encloses a named set of abstract operations and the abstract messages. It can optionally extend one or more QName operation

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

. All operations defined within the interface must be bound in the binding. An endpoint in the service component an 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.

binding element defines the underlying transport and wire format for messages. Each binding in the WSDL references to interface

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.

information is contained in the binding. Service can be referred by

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 a name and interface which are required attributes.
A 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: "" <?xml version="1.0" encoding="UTF-8" ?> <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:

• • •

a

find_binding: Used to locate specific bindings within a registered businessService. Returns bindingDetail 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.

• • • • • • •

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.
Returns a

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 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
the petition. valid and should be considered invalid if used after this message is received and until such time as an

discard_authToken: Used to inform an Operator Site that a previously provided authentication token is no longer authToken value is recycled or reactivated at an operator's discretion. Seeget_authToken. get_assertionStatusReport: Used to get a status report containing publisher assertions and status businessEntity

information. This report is useful to help an administrator manage active and tentative publisher assertions. Publisher assertions structures. Relationships are a are used in UDDI to manage publicly visible relationships between feature introduced in generic 2.0 that help manage complex business structures that require more than

businessEntity or more than one publisher account to manage parts of a businessEntity. Returns 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
one an when using all other API's defined in the publishers API. This function serves as the program's equivalent of a login request.

• • • •

message containing all publisher assertions associated with a publisher account. Returns a specific publisher account. Publisher assertions are used to control publicly visible business relationships.

get_publisherAssertions: Used to get a list of active publisher assertions that are controlled by an individual publisherAssertions get_registeredInfo: Used to request an abbreviated synopsis of all information currently managed by a given

individual.

existing registered business.

save_binding: Used to register new bindingTemplate information or update bindingTemplate information. Use this to control information about technical capabilities exposed by a

existing

• • •

save_business: Used to register new businessEntity information or update 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 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.

@WebService

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.

deployment descriptor is optional because you can use For JAX-WS Web services, the use of the 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

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 o

the

@WebService annotation:
@WebService(wsdlLocation="http://myhost.com/ExampleService.wsdl")

o o o o o o o o o o

the

webservices.xml file specifies a different file name for the WSDL document as follows:
<webservices> <webservice-description> <webservice-description-name>ExampleService</webservice-description-name> <wsdl-file>META-INF/wsdl/ExampleService.wsdl</wsdl-file> .... </webservice-description> </webservices>

METAINF/wsdl/ExampleService.wsdl overrides the annotation value.
In this case, the value that is specified in the deployment descriptor,

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.

or annotation to declare JAXThe application server also supports the usage of the 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.

@Resource

@WebServiceRef

Enterprise Edition 5 (Java EE 5). By placing the

@Resource annotation is defined by the JSR-250, Common Annotations specification that is included in Java Platform, @Resource annotation on a variable of 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 The

@WebServiceRef annotation is defined by the JAX-WS specification. @Resource and @WebServiceRef annotations for resource injection:

The following example illustrates using the

@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

schema generator and you can configure the a new schema file is generated when using the compiler so that it does not automatically generate new classes for a particular schema. You can use

@XMLSeeAlso annotation. With the improved compilation support, you now have the flexibility to control the whether schemagen xjc schema @XMLSeeAlso

annotation to ensure that JAXB is aware of all the classes included in an inheritance hierarchy for a the service endpoint interface.

Dynamic and static clients

The dynamic client API for JAX-WS is called the dispatch client ( an XML messaging oriented client. The data is sent in either

javax.xml.ws.Dispatch). The dispatch client is PAYLOAD or MESSAGE mode.

When using the the

PAYLOAD mode, the dispatch client is only responsible for providing the contents of 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 soap:Envelope, soap:Header, and soap:Body elements. JAX-WS does not add anything additional

When using the

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

XML Source enables a user to pass a represents the data in a

javax.xml.transform.Source into the runtime environment which Source object to be processed. SOAPMessage object across the interface.

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

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

and command-line tools for generating portable artifacts for JAX-WS Web JAX-WS provides the services. When creating JAX-WS Web services, you can start with either a WSDL file or an implementation bean class.

wsgen

wsimport

If you start with an implementation bean class, use the artifacts, including a WSDL file if requested.

wsgen command-line tool to generate all the Web services server

command-line tool to generate all the Web services artifacts for either the If you start with a WSDL file, use 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.

wsimport

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 three standard features: the the

AddressingFeature, the MTOMFeature, and 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 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).

wsdl:binding

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

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). 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. 2. 3. 4.

It MUST carry a javax.jws.WebService annotation Any of its methods MAY carry a javax.jws.WebMethod annotation javax.jws.WebMethod if used, MUST NOT have the exclude element set to true. 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:

<?xml version="1.0" encoding="UTF-8"?> <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 interface HelloWorld extends java.rmi.Remote { public java.lang.String hello(java.lang.String name) throws java.rmi.RemoteException; }

JAX-WS complete HelloWorld SEI:

package com.ibm.samples.helloworld; import import import import import import javax.jws.WebMethod; javax.jws.WebParam; javax.jws.WebResult; javax.jws.WebService; javax.xml.ws.RequestWrapper; javax.xml.ws.ResponseWrapper;

@WebService(name = "HelloWorld", targetNamespace = "urn:samples.ibm.com/HelloWorld") public interface 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", targetNamespace = "urn:samples.ibm.com/HelloWorld", 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: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>

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 interface HelloWorld extends java.rmi.Remote { 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) public interface HelloWorld { @WebMethod(action = "urn:helloWorld/sample/ibm/com/hello") @WebResult(name = "helloResponse", targetNamespace = "urn:helloWorld/sample/ibm/com", partName = "helloResult") public String hello( @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:message name="helloRequestMsg"> <wsdl:part name="helloParameters" type="xsd:string"/> </wsdl:message> <wsdl:message name="helloResponseMsg"> <wsdl:part name="helloResult" type="xsd:string"/> </wsdl:message>

JAX-RPC RPC/literal mapping:

public interface HelloWorld extends java.rmi.Remote { public java.lang.String hello(java.lang.String helloParameters) throws java.rmi.RemoteException; }

JAX-WS RPC/Literal mapping:

@WebService(name = "HelloWorld", targetNamespace = "urn:helloWorld/sample/ibm/com") @SOAPBinding(style = Style.RPC) public interface HelloWorld { @WebMethod(action = "urn:helloWorld/sample/ibm/com/hello") @WebResult(name = "helloResult", partName = "helloResult") public String hello( @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:

@WebMethod(action = "urn:samples.ibm.com/HelloWorld/hello") @RequestWrapper(localName = "hello", targetNamespace = "urn:samples.ibm.com/HelloWorld", className = "com.ibm.samples.helloworld.Hello") @ResponseWrapper(localName = "helloResponse", targetNamespace = "urn:samples.ibm.com/HelloWorld", className = "com.ibm.samples.helloworld.HelloResponse") public Future<?> helloAsync( @WebParam(name = "name", targetNamespace = "") String name, @WebParam(name = "asyncHandler", targetNamespace = "") AsyncHandler<String> asyncHandler );

JAX-WS asynchronous polling:

@WebMethod(action = "urn:samples.ibm.com/HelloWorld/hello") @RequestWrapper(localName = "hello", targetNamespace = "urn:samples.ibm.com/HelloWorld", className = "com.ibm.samples.helloworld.Hello") @ResponseWrapper(localName = "helloResponse", targetNamespace = "urn:samples.ibm.com/HelloWorld", className = "com.ibm.samples.helloworld.HelloResponse") public Response<String> helloAsync( @WebParam(name = "name", targetNamespace = "") 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 interface HelloWorld extends java.rmi.Remote { 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:

@WebService(name = "HelloWorld", targetNamespace = "urn:helloWorld/sample/ibm/com") public interface HelloWorld { @WebMethod(action = "urn:helloWorld/sample/ibm/com/hello") @RequestWrapper(localName = "hello", targetNamespace = "urn:helloWorld/sample/ibm/com", className = "helloworld.sample.ibm.com.Hello") @ResponseWrapper(localName = "helloResponse", targetNamespace = "urn:helloWorld/sample/ibm/com", className = "helloworld.sample.ibm.com.HelloResponse") public void hello( @WebParam(name = "name", targetNamespace = "") 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 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 overrides any corresponding information that is specified by annotations.

webservices.xml

webservices.xml deployment descriptor

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 The name of the

Description

Default

name

wsdl:portType

The unqualified name of the Java class or interface

targetNamespace

The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules. The Service name of the web service:

The namespace mapped from the package name containing the web service according to section 3.2 of the JAX-WS 2.0 specification.

serviceName

The unqualified name of the Java class or interface +

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

endpointInterface

WebService properties are

ignored as are all other 181 annotations. Only the annotations on the service endpoint interface will be taken into consideration. The endpoint implementation class is not required to implement the

None – If not specified, the endpoint implementation class is used to generate the web service contract. In this case, a service endpoint interface is not required.

endpointInterface. wsdl:portName
The

portName

The

WebService.name + "Port"

Property

Description Specifies the Web address of the WSDL document defining the Web service. The Web address is either relative or absolute.

Default

wsdlLocation

-

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

AddNumbersImpl

@WebService annotation on the endpoint implementation is modified to specify the endpoint interface and the actual @WebService annotation. The following is the above AddNumbersImpl modified to use a service endpoint interface.
the service endpoint interface must also have a Example 2:

@WebService(endpointInterface = "com.example.AddNumbersIF") public class AddNumbersImpl { public int addNumbers(int number1, int number2) { return number1 + number2; } }

@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 o o

If the

implementation class MUST NOT have any

@WebService annotation of an implementation class references an Service Endpoint Interface (SEI), the @WebMethod annotations.

ALL public methods for an SEI are considered exposed methods regardless of whether

@WebMethod annotation is specified or not. It is incorrect to have an @WebMethod annotation on an exclude attribute. 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,
the SEI that contains the 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

Property

Description

Default The name of the

operationName

The name of the

wsdl:operation matching this method. For operations using the mode

Property defined by

Description

Default Java method

SOAPBinding.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.
""

action exclude
Example:

The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules. Used to exclude a method from the WebService.

false

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers") public interface AddNumbersIF { @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 the

@WebMethod annotation is only supported on classes that are annotated with @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

Property Name of the parameter.

Description

Default

and

name

rpc style @WebParam.partNamehas not been specified, this is name of the wsdl:partrepresenting
If the operation is

the parameter.

@WebMethod.operationName, document style and the parameter style is BARE. Otherwise, the default is argN, where N represents the index of the
if the operation is parameter in the method signature (starting at

@WebMethod.operationName, if the operation isdocument style and the parameter style

arg0).

Property is

Description

Default

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

the mode is

documentstyle, the parameter style is BARE, and OUTor INOUT.
-

targetNamespace

Represents the direction the parameter flows for this method. Possible values are

IN, INOUT and OUT. INOUTand OUT modes OUT andINOUT parameters can be used RPC and DOCUMENTbindings.

mode

can only be used with parameters that meet the requirements for a holder as classified by section 3.5 of the JAX-WS 2.0 specification. by all

for non-holder parameters holder parameters.

IN

INOUT for

header partName

-

FALSE partName for the parameter RPCor DOCUMENT/BARE operations. @WebParam.name

Used to specify the with

Example 1:

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers") public interface AddNumbersIF { @WebMethod(operationName="add", action="urn:addNumbers") @WebResult(name="return") public int addNumbers( @WebParam(name="num1")int number1, @WebParam(name="num2")int number2 ); }

Example 2:

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers") public interface AddNumbersIF { @WebMethod(operationName="add", action="urn:addNumbers") @WebResult(name="return") public void addNumbers( @WebParam(name="num1")int number1, @WebParam(name="num2")int number2, @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

Property

Description

Default

Property

Description

Default

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

name

wire. For bindings this is the part name of the return value in the response message. For

RPC

"return" for RPC and DOCUMENT/WRAPPED bindings.
Method name +

DOCUMENT bindings this is the local name

of the XML element representing the return value.

"Response for DOCUMENT/BARE bindings.

targetNamespace header partName

-

-

-

FALSE partName for the result @WebResult.name RPC orDOCUMENT/BARE operations.

Used to specify the with

Example:

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers") public interface AddNumbersIF { @WebMethod(operationName="add", action="urn:addNumbers") @WebResult(name="return") public int addNumbers( @WebParam(name="num1")int number1, @WebParam(name="num2")int number2 ); }

javax.jws.HandlerChain

This annotation is used to specified an externally defined handler chain.

Table 4.5. javax.jws.HandlerChain

Property

Description Location of the file containing the handler chain definition. The location can be relative or absolute with in a classpath system. If the location is relative, it is relative to the package of the web service. If it is absolute, it is absolute from some path on the classpath. DEPRECATED: The handler chain name from within the handler chain file.

Default

file name
Example:

none

""

@WebService @HandlerChain(file="handlers.xml") public class AddNumbersImpl { public int addNumbers(int number1, int number2) { return number1 + number2; } }

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 Interface (SEI) or the server endpoint implementation class.

@HandlerChain annotation on the Service Endpoint

Use one of several ways to configure a client side handler. You can configure a client side handler by using

@HandlerChain annotation on the generated service class or SEI. Additionally, you can programmatically register HandlerResolver interface on theService, or programmatically set the handler chain on the Binding object.
the your own implementation of the

javax.jws.soap.SOAPBinding

annotation on a endpoint implementation or service endpoint interface. JSR 181 also allows you to specify a 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.

SOAPBinding

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

Property

Description Defines the style for messages used in a web service. The value can be either

Default

style use

DOCUMENT or RPC.

DOCUMENT LITERAL

Defines the encoding used for messages used in web service. Can only be

LITERAL for JAX-WS 2.1 WRAPPED or BARE. BARE can only be used DOCUMENT style bindings.

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

Choice of with

WRAPPED

Example:

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers") @SOAPBinding(style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.LITERAL) public interface AddNumbersIF { @WebMethod(operationName="add", action="urn:addNumbers") @WebResult(name="return") public int addNumbers( @WebParam(name="num1")int number1, @WebParam(name="num2")int number2 ); }

JSR 224 (JAX-WS) Annotations

javax.xml.ws.BindingType

annotation is used to specify the binding to use for a web service endpoint implementation class. As The well as specify additional features that may be enabled.

BindingType

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/") public class AddNumbersImpl { public int addNumbers(int number1, int number2) { return number1 + number2; } }

Example 2: Here is another sample use of the enables both the

BindingType annotation that specifies use of the SOAP1.1/HTTP binding, it AddressingFeature and the MTOMFeature and also sets the threshold feature parameter 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 specifying

@BindingType annotation on the JavaBeans endpoint implementation class to enable MTOM by

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", targetNamespace="http://server.fromjava/", className="fromjava.client.AddNumbersResponse") public int addNumbers( @WebParam(name = "arg0", targetNamespace = "") int arg0, @WebParam(name = "arg1", targetNamespace = "") 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", targetNamespace="http://server.fromjava/", className="fromjava.client.AddNumbers") @ResponseWrapper(localName="addNumbersResponse", targetNamespace="http://server.fromjava/", className="fromjava.client.AddNumbersResponse") public int addNumbers( @WebParam(name = "arg0", targetNamespace = "") int arg0, @WebParam(name = "arg1", targetNamespace = "") int arg1); }

javax.xml.ws.ServiceMode

developer to indicate whether a This annotation allows the entire protocol messages or just with protocol message payloads.

Provider

Provider implementation wishes to work with

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 the

@ServiceMode annotation is only supported on classes that are annotated with @WebServiceProvider annotation.

javax.xml.ws.WebEndpoint

Used to annotate the get

PortName() methods of a generated service interface. wsdl:port element inside @WebServiceClient annotation on the

The information specified in this annotation is sufficient to uniquely identify a . The latter is determined based on the value of the a generated service interface itself.

wsdl:service

Example:

@WebServiceClient(name="AddNumbersImplService", targetNamespace="http://server.fromjava/", 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) { e.printStackTrace(); } 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

The information specified in this annotation is sufficient to uniquely identify a document. This client view.

wsdl:service element inside a WSDL wsdl:serviceelement represents the Web service for which the generated service interface provides a

Example:

@WebServiceClient(name="AddNumbersImplService", targetNamespace="http://server.fromjava/", 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) { e.printStackTrace(); } 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); } catch(Exception e) { e.printStackTrace(); 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 o o •

A Java class that implements a Web service must specify either

@WebService or @WebServiceProvider annotation. Both annotations cannot be present. @WebServiceProvider annotation is only supported on the service implementation class. Any class with the @WebServiceProvider annotation must implement the javax.xml.ws.Provider interface.
the The

javax.xml.ws.WebServiceRef

annotation is used to define a reference to a web service and (optionally) an injection target for The it. Web service references are resources in the Java EE 5 sense.

@WebServiceRef

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); } catch(Exception e) { e.printStackTrace(); } } }

NOTE: The

@WebServiceRef annotation can be used to inject instances of JAX-WS services and ports. @WebServiceRef

NOTE: The 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 a complete list of supported class types.

@Resourceannotation. See the Java Platform, Enterprise Edition (Java EE) 5 specification for

javax.xml.ws.Feature

The

annotation is used with

@Feature annotation is used to enable/disable a feature to use for a web service endpoint implementation class. This @BindingType annotation.

@BindingType annotation that specifies use of the SOAP1.1/HTTP binding, it enables both AddressingFeature and theMTOMFeature and also sets the threshold feature parameter on the MTOMFeature:
Here is a sample use of the the

@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 with

@FeatureParameter annotation is used to specify paramaters for a feature. This annotation is used @Feature.

javax.xml.ws.Action

annotation allows explicit association of The messages of the mapped WSDL operation.

@Action

Action message addressing property with input, output, and fault

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

messages of the WSDL operation based upon which attributes of the

wsaw:Action attribute on the WSDL input, output and fault Action annotation have been specified.

Example: Specify explicit values for

Action message addressing property for input and output messages:

@javax.jws.WebService public class AddNumbersImpl { @javax.xml.ws.Action( input="http://example.com/inputAction", output="http://example.com/outputAction") public int addNumbers(int number1, int number2) { return number1 + number2; } }

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 of

@FaultAction annotation is used inside an @Action annotation to allow an explicit association Action message addressing property with the fault messages of the WSDL operation mapped from the exception class. className class contains

The fault message in the generated WSDL operation mapped for explicit

wsaw:Action attribute. Action

message addressing property for the input, output and fault message if the Java Example: Specify explicit values for method throws only one service specific exception:

@javax.jws.WebService public class AddNumbersImpl { @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 { return number1 + number2; } }

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 JAXfor processing Java source files with annotations and WS making them web services. APT will compile the Java source files and generate any additional classes needed to make an

AnnotationProcossor

javax.jws.*

javax.jws.WebService annotated class a Web service.

o

WsGen

Tool to process a compiled classes to make it a Web service.

javax.jws.WebService annotated class and to generate the necessary

o

WsImport

) interface that can be either Tool to import a WSDL and to generate an SEI (a implemented on the server to build a web service, or can be used on the client to invoke the web service.

javax.jws.WebService

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.

apt, annotation processing tool, includes a set of new reflective APIs and supporting infrastructure to process program 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
The tool annotations. The 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 them web services.

AnnotationProcessor for processing Java source files with javax.jws.* annotations and making

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 The

javax.jws.WebService annotation.

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

element to the annotation in the You may specify an explicit interface by adding the implementation class. You must then provide an interface that defines the public methods made available in the endpoint implementation class.

endpointInterface

@WebService

You use the endpoint implementation class and the the JAX-WS runtime.

wsgen tool to generate the web service artifacts that connect a web service client to

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. 2. 3. 4. 5. 6. 7. 8. 9.

Code the implementation class. Compile the implementation class. to generate the artifacts required to deploy the service. Use Package the files into a WAR file. Deploy the WAR file. The web service artifacts (which are used to communicate with clients) are generated by the Application Server during deployment. Code the client class. to generate and compile the web service artifacts needed to connect to the service. Use Compile the client class. Run the client.

wsgen

wsimport

Requirements of a JAX-WS Endpoint

JAX-WS endpoints must follow these requirements:

• •

The implementing class must be annotated with either

• • • • • • •

javax.jws.WebService or javax.jws.WebServiceProvider annotation. endpointInterface 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.
the The implementing class may explicitly reference an SEI through the 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 The implementing class may use the ns on its methods for life cycle event callbacks.

finalize() method.

javax.annotation.PostConstruct or javax.annotation.PreDestroy annotatio @PostConstruct method is called by the container before the implementing class begins responding to web @PreDestroy method is called by the container before the endpoint is removed from operation.

The service clients.

The

Coding the Service Endpoint Implementation Class

Hello, is annotated as a web service endpoint using @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
In this example, the implementation class, the default, public, no-argument constructor.

package helloservice.endpoint; import javax.jws.WebService; @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 service. file:

javax.xml.ws.WebServiceRef annotation to declare a reference to a web @WebServiceRef uses the wsdlLocation element to specify the URI of the deployed service's WSDL

2. 3.

@WebServiceRef(wsdlLocation="http://localhost:8080/helloservice/hello?wsdl") 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); } catch(Exception e) { e.printStackTrace(); } } 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); } catch(Exception e) { e.printStackTrace(); } } }

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

, is a dynamic JAX-WS client programming interface. To write a Dispatch The Dispatch client API, 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

javax.xml.ws.Dispatch

MESSAGE or PAYLOAD mode. javax.xml.ws.Service.Mode.MESSAGE mode, the Dispatch client is responsible for providing the soap:Envelope, soap:Header, and soap:Body elements. javax.xml.ws.Service.Mode.PAYLOAD mode, the Dispatch client is only responsible for providing soap:Body and JAX-WS includes the payload in a soap:Envelope element.

When using the

entire SOAP envelope including the

When using the

the contents of the

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 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.
messages. You can only use

For example, if the input parameter type is the following code example:

javax.xml.transform.Source, the call to the Dispatch client API is similar to

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

Asynchronous invocation for requests and responses using the One-way invocation using the

invoke method invokeAsync method with a callback or polling object

invokeOneWay methods Dispatch methods in the synchronous, asynchronous polling, and asynchronous callback

The following examples demonstrate use of 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 = ...; Service service = ...; 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")); Service service = ...;

• • •

Dispatch<Object> disp = service.createDispatch(portName, jc, PAYLOAD); OrderConfirmation conf = (OrderConfirmation)disp.invoke(po);

• • • • • • • • • • •

Asynchronous, Polling, Message-Oriented

SOAPMessage soapReqMsg = ...; Service service = ...; 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 = ...; Service service = ...; 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.

class and leverage the Dynamic Proxy function in the The Dynamic Proxy instances extend 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.

java.lang.reflect.Proxy

The following example shows the use of a proxy to invoke a method ( (

getLastTradePrice) on a service endpoint interface 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 public class Hello { @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 into the implementation instance. You can then ask it for a instance of from this get the request, session, response etc.

WebServiceContext

MessageContext, and

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

One way to bring state to Web Services is to use

(from the way of accessing/storing it with instance fields. One can use

HttpSession

HttpSession cookies. Storing the state and accessing it from WebServiceContext) for each request takes multiple steps and does not fit well with the OO

per each HTTP session. As you see this approach still relies on Http cookies but makes it easier to access create one instance of state from the context just like normal instance variables:

@com.sun.xml.ws.developer.servlet.HttpSessionScope annotation tells the JAX-WS RI to Hello

@HttpSessionScope @WebService public class Hello { int counter = 0; public int getCounter() { return counter++; } }

Using @Stateful

JAX-WS also provides a transport neutral mechanism to do this. It introduces

access it using instance variables. All the user needs to do is to add

@com.sun.xml.ws.developer.Stateful to take care of maintaining all the state and the user can @Stateful to Web Service implementation.

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 takes

@Stateful annotation on a class. It should also have a public static method/field that 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 of a class, then you'll have the JAX-WS RI assign this unique EPR for the instance as follows:

EndpointReference. Your application creates an instance

@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 o o o

To create a resource on the server, use POST. To retrieve a resource, use GET. To change the state of a resource or to update it, use PUT. 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 serverside 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 <?xml version="1.0"?> <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 . 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.

/users

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 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:

name

PUT /users/Mikalai HTTP/1.1 Host: myserver Content-Type: application/xml <?xml version="1.0"?> <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

. In a REST Web service, subsequent requests for the resource using the old URI changes its URI to would generate a standard 404 Not Found error.

/users/Mikola

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 or . This general design principle also define more verbs or remote procedures, such as 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.

/adduser /updateuser

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

java.io.NotSerializableException during session replication. Whether it's thrown by the servlet 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
of container during 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 Last-Modified response header and sends back the date value in an If-Modified-Since header to ask the server if the resource has changed. This is called Conditional
Uses the of it) or not. The client also reads the 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 selfdocumenting 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, , has a 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

/discussion

/topics

/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 o o o 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. Keep everything lowercase. Substitute spaces with hyphens or underscores (one or the other). Avoid query strings as much as you can. 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:

<?xml version="1.0"?> <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 header, where the value of the header is a MIME type. Some common MIME types used by RESTful services are shown in table:

Accept

Table 5.1. Common MIME types used by RESTful services

MIME-Type

Content-Type

JSON XML XHTML

application/json application/xml 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>

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

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.

The main JAXP APIs are defined in the

javax.xml.parsers package. That package contains vendor-neutral factory classes 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 used to generate an instance of the parser.

SAXParserFactory class is

object. When the parser's The parser wraps a methods implemented in the application. Those methods are defined by the interfaces

SAXReader

parse() method is invoked, the reader invokes one of several callback

ContentHandler, ErrorHandler, DTDHandler, and EntityResolver.

Here is a summary of the key SAX APIs:

SAXParserFactory
A

property,

SAXParserFactory object creates an instance of the parser determined by the system javax.xml.parsers.SAXParserFactory.

SAXParser
The

a object.

SAXParser interface defines several kinds of parse() methods. In general, you pass an XML data source and DefaultHandler object to the parser, which processes the XML and invokes the appropriate methods in the handler

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

hold of it using 's on the conversation with the SAX event handlers you define.

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

DefaultHandler
Not shown in the diagram, a

, , the null methods), so you can override only the ones you're interested in.

DefaultHandler implements ContentHandler ErrorHandler DTDHandler, and EntityResolver interfaces (with

ContentHandler
, Methods such as when an XML tag is recognized. This interface also defines the

startDocument endDocument, startElement, and endElement are invoked processingInstruction, which are invoked when the parser encounters the

and methods text in an XML element or an inline processing instruction, respectively.

characters

ErrorHandler
, , and are invoked in response to various parsing errors. The default error Methods 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.

error fatalError

warning

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
method is invoked when the parser must identify data identified by a URI. In most cases, a URI is The 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 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.

resolveEntity

EntityResolver

A typical application implements most of the

interfaces ignore all inputs except for fatal errors, a robust implementation may also want to implement the

ContentHandler methods, at a minimum. Because the default implementations of the ErrorHandler methods.

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:

You use the

instance, and you use that instance to produce a a specification. The builder you get, in fact, is determined by the system property used to produce the builder.

javax.xml.parsers.DocumentBuilderFactory class to get DocumentBuilder Document object that conforms to the DOM javax.xml.parsers.DocumentBuilderFactory, which selects the factory implementation that is

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) { ... } }

You can also use the the

DocumentBuilder.newDocument() method to create an empty Document that implements org.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() { DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); try { DocumentBuilder builder = factory.newDocumentBuilder(); 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:

object is instantiated and used to create a . The source object is the input to the A transformation process. A source object can be created from a SAX reader, from a DOM, or from an input stream.

TransformerFactory

Transformer

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

method to make the transformation happen. The input (source) and output (result) objects, and invoke its source and result objects are created using classes from one of the other three packages.

Transformer object. You then configure the transformer with transform()

javax.xml.transform.dom
Defines the transformation.

DOMSource and DOMResult classes, which let you use a DOM as an input to or output from a

Document document; try { File f = new File(argv[0]); DocumentBuilder builder = factory.newDocumentBuilder(); 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
and classes, which let you use a SAX event generator as input to a Defines the transformation, or deliver SAX events as output to a SAX event processor.

SAXSource

SAXResult

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); StreamResult result = new StreamResult(System.out); transformer.transform(source, result);

javax.xml.transform.stream
Defines the from a transformation.

StreamSource and StreamResult classes, which let you use an I/O stream as an input to or output

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); //factory.setNamespaceAware(true); //factory.setValidating(true); try { File stylesheet = new File(argv[0]); File datafile = new File(argv[1]); DocumentBuilder builder = factory.newDocumentBuilder(); 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); StreamResult result = new StreamResult(System.out); transformer.transform(source, result); }

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 and . includes accessor methods for are 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:

XMLStreamReader

XMLStreamWriter XMLStreamReader

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 of

XMLInputFactory class to load an implementation dependent instance

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 method in 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:

next()

XMLStreamReader

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 XMLStreamWriter provides methods that correspond to StartElement and EndElement event types; for example:
You can call methods on cursor location.

public interface XMLStreamWriter { public void writeStartElement(String localName) throws XMLStreamException; public void writeEndElement() throws XMLStreamException; public void writeCharacters(String text) throws XMLStreamException; // ... other methods not shown }

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 various

writeXXX methods: writeStartDocument, writeStartElement, writeEndElem 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 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:
The base iterator interface is called (

public interface XMLEventReader extends Iterator { public XMLEvent nextEvent() throws XMLStreamException; public boolean hasNext(); public XMLEvent peek() throws XMLStreamException; // ... other methods not shown }

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; // ... other methods not shown }

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 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 with additional methods.

XMLEvent

XMLEvent that are either completely new information items or extensions of existing items but

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

the provider will throw an

CapabilityProfile interface. If the client attempts to invoke capability level methods unsupported by the JAXR provider, UnsupportedCapabilityException.

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.

client can obtain an instance of the

RegistryService exposes the JAXR provider's key interfaces, that is, Web services discovery and registration. The JAXR RegistryService interface by invoking thegetRegistryService() method on 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. 2.

BusinessLifeCycleManager - for level 0 (we MUST use this interface according to WS-I BP 1.1) 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, provides several factory methods to create JAXR information model objects. In general, life-cycle the management operations are privileged, while a user can use query management operations for browsing the registry.

LifeCycleManager

JAXR's top-level interface for query management,

QueryManager, has two extensions:

1. 2.

BusinessQueryManager - for level 0 (we MUST use this interface according to WS-I BP 1.1) 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,

BusinessQueryManager interface provides the ability to query for the most important high-level interfaces in the Organization, Service, ServiceBinding, ClassificationScheme, andConcept. Alternatively, the DeclarativeQueryManager interface provides a more flexible, generic API, enabling
the information model, such as 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

information, called attributes, that all registry objects share. Example attributes include: The as

RegistryObject interface, which defines the common state key, name, and description.

InternationalString interface defines attributes that must be internationalization compatible, such name and description. The InternationalString interface contains a collection of LocalizedStrings, where each LocalizedString defines locale, character set, and string content. RegistryObject interface also defines collections Classification, ExternalIdentifier, ExternalLink, and Association objects. TheBusinessQueryManager often uses those collections as parameters in its find methods.
Also specializations of the

The of

RegistryObject interface, the concrete 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
interfaces 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
A business, such as a corporation whose data is contained in the registry, is represented

businessEntity
The

Organization instance. An Organization can have multiple Organizations under it or can refer to another organization as a parent. An Organization can offer one or more services, represented byService objects which can be accessed via Collection Organization.getServices() method.
by an

businessEntity structure contains information about a

particular business organization and holds references to the services it offers.

contains descriptive information. Each

businessEntity is the highest in the hierarchy and businessEntity is identified by its businessKey. If itsbusinessKey is not
specified at publication time, the registry will automatically generate a key.

JAXR Information Model

UDDI Data Model

businessService businessService entry indicates a logical service and holds Service
Each descriptive information about a Web service in business terms.

Service can have multiple ServiceBinding objects that specify

the details about the protocol binding information for that service.

businessService is a child of businessEntity that provides the service. Information about how a businessService can be instantiated is contained within abindingTemplate. Each businessService is has a unique identifier -serviceKey. This value is assigned by each
A a UDDI operator and cannot be edited by the publisher. It also contains the key to its parent

businessEntity - businessKey.

ServiceBinding ServiceBinding has attributes that describe the location where the service can be accessed. A ServiceBinding is associated with one or more SpecificationLink objects that point to the technical
specifications defining the service (e.g., a WSDL file for the Web

bindingTemplate
A

bindingTemplate contains information necessary for a client

ServiceBinding instances RegistryObject objects that represent technical information on a specific way to access a specific interface offered by a Service instance. A ServiceBinding may have a set ofSpecificationLink instances. Maps to a bindingTemplate in UDDI.
service). are

to invoke a service. It specifies the information for a particular Web service and provides the URL of the service where it can be invoked. The

as well as service-specific settings. A

bindingTemplate also contains references to tModels bindingTemplate is a child of a businessService.

ClassificationScheme
A

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

ClassificationScheme instance represents a taxonomy that may RegistryObject

ClassificationScheme

tModel

Concept
The

Concept interface is used to represent taxonomy elements and their structural

relationship with each other in order to describe an internal

the tree is a

Concept instances are used to define tree structures where the root of ClassificationScheme instance and each node in the tree is a Concept instance. As any RegistryObject, a Concept may be classified and also associated with a set of external identifiers
taxonomy. and links.

Association RegistryObject instance may be associated with zero or RegistryObject instances. The information model defines anAssociation interface, an instance of which may be used to associate any two RegistryObject instances. An Association instance 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
A more

publisherAssertion

JAXR Information Model determines the directional semantics of an Each

UDDI Data Model

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

overviewDoc

ExternalLink enables this capability.

Classification
The

classify more

Classification interface is used to RegistryObjectinstances. A RegistryObject may be Classification instances to theRegistryObject. For Organization may be classified by its industry, by the products keyedReference (in categoryBag)

classified along multiple dimensions by adding zero or

example, an the

it sells and by its geographical location. In this example

RegistryObject would have at least Classificationinstances added to it. The RegistryObject interface provides severaladdClassification methods to allow a client to add Classificationinstances to a RegistryObject.
three

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 from RegistryObject is used to contain the identification scheme (Social
Security Number, etc), and the attribute value contains the actual information. Each with

keyedReference (in identifierBag)

RegistryObjects may have 0 or more association(s) ExternalIdentifier. contact ExternalIdentifier instances Classification instances identifierBag categoryBag address

User
Collection of

Collection of

PostalAddress SpecificationLink
A a

SpecificationLink provides the linkage between ServiceBindingand one of its technical specifications that describes how to use the service using the ServiceBinding. For example, 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

The union of

tModelInstanceInfo and instanceDetails

JAXR Information Model of

UDDI Data Model

tModelInstanceInfo andinstanceDetails in UDDI.

UDDI Example Mapped to JAXR:

Table 6.2. Mapping of UDDI Inquiry API Calls To JAXR (

BusinessQueryManager) BusinessQueryManager Method

UDDI Method

find_binding find_business find_related_business find_service find_tModel get_bindingDetail

findServiceBindings findOrganizations findAssociatedObjects(RegistryObject, asociationType) findServices findConcepts, findClassificationSchemes
Not needed. Handled transparently by JAXR provider

UDDI Method

BusinessQueryManager Method
Not needed. Handled transparently by JAXR provider Unsupported. Use

get_businessDetail get_businessDetailExt get _serviceDetail get_tModelDetail

RegistryService.makeRegistrySpecificRequest

Not needed. Handled transparently by JAXR provider

Not needed. Handled transparently by JAXR provider

Table 6.3. Mapping of UDDI Publisher API Calls to JAXR (

BusinessLifeCycleManager) BusinessLifeCycleManager Method

UDDI Method

add_publisherAssertions delete_binding delete_business

saveAssociations(associations, replace), Association.confirm deleteServiceBindings deleteOrganizations

delete_publisherAssertions deleteAssociations delete_service deleteServices deleteClassificationsSchemes, deleteConcepts.
NOTE, In UDDI

delete_tModel

delete_tModel does not delete the tModel. It simply hides it find_tModel calls. The QueryManager.getRegistryObjectcalls will still return the deleted tModel after a deleteConcepts ordeleteClassificationSchemes call.
from

discard_authToken get_assertionStatusReport get_authToken get_publisherAssertions get_registeredInfo save_binding save_business save_service save_tModel set_publisherAssertions

Not needed. Handled transparently by JAXR provider

findAssociations(findQulifiers, associationTypes, sourceObjectConfirmed, targetObjectConfirmed)
Not needed. Handled transparently by JAXR provider

QueryManager.getRegistryObjects(objectType) QueryManager.getRegistryObjects saveServiceBindings saveOrganizations saveServices saveClassificationsSchemes, saveConcepts saveAssociations(assiations,replace)

The JAXR specification defines the following information model interfaces:

• • • • • •

instance is a published to the underlying registry.

Organization

RegistryObject that provides information on an organization that has been

Service instance is a RegistryObject that provides information on services (e.g., Web Service) offered by 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
an 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 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
categorize 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). instances dynamically add arbitrary attributes to extensibility within the information model. Most interfaces in the JAXR information model extend the

Slot

RegistryObject instances at runtime, an ability that enables

allow the addition, deletion, and lookup of

ExtensibleObject interface. It provides methods that 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 Web Services discovery and publishing:

RegistryService interfaces for

// 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();
This example also demonstrates how to obtain the business-focused interfaces, the the

BusinessLifeCycleManager and 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) { e.printStackTrace(); 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

BusinessQueryManager and BusinessLifeCycleManager from 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.
the the

QueryManager. There are two extensions 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
JAXR defines top-level interface for query management called of important high-level interfaces in the information model.

provides a more flexible generic API that provides the ability to perform ad hoc Interface 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.

DeclarativeQueryManager

This example shows how to find all the organizations in the registry whose names begin with a specified string, them in alphabetical order:

qString, and to sort

// 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. Collection findQualifiers = new ArrayList(); 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); Collection orgs = response.getCollection();

Steps for finding

Organization by Classification:

1. 2. 3.

Decide on classification scheme (taxonomy). Build a classification within a particular classification scheme. 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 method. The following code fragment finds all organizations that classification as an argument to the correspond to a particular classification within the North American Industry Classification System (NAICS) taxonomy:

findOrganizations

// 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); Collection orgs = response.getCollection();

To find WSDL Specification Instances: use classification scheme of " ". 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

uddi-org:types

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"); Collection classifications = new ArrayList(); 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 method with classification listed under the well-known taxonomies NAICS and ISO 3166 Geographic a 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 registry follows below:

findOrganization()

findOrganization() parameters. A sample of this query to the taxonomy service and

public void findOrganizations() throws JAXRException { // Search criteria -- Organizations found will return in this sort order Collection findQualifiers = new ArrayList(); 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 Collection classifications = new ArrayList(); 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

instances or encountered and a collection of concrete invocation always returns a response, any exceptions generated by the registry provider are wrapped in a of

RegistryObject

BulkResponse that contains any registry exceptions RegistryObject keys. To ensure that a registry

RegistryException and stored in the BulkResponse's exceptions collection. In the case findXXX(...) methods, anyRegistryObjects found are contained in the BulkResponse collection.

findOrganization() method, the BulkResponse contains a collection 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
For the above of service information such as ID, name, and description. Using UDDI APIs, a UDDI client would need to make an additional call such

get_BusinessDetail() to retrieve the organization details. With JAXR, the JAXR UDDI provider performs this invocation to Organization and other RegistryObject details by using the getXXX() methods on the JAXR information model interfaces. The getOrganizationDetail() method demonstrates how a JAXR client would obtain full Organization details:
as the registry provider on an as-needed basis. The JAXR client can access

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 publish an organization and its services to a registry, the client uses the focused

LifeCycleManager or the more BusinessLifeCycleManager. Clients familiar with UDDI should use

the , 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 asneeded basis, and the authentication is completely transparent to the JAXR client.

BusinessLifeCycleManager

LifeCycleManager interface 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
JAXR specification defines two interfaces – and for life cycle management of some important high-level interfaces in the information model. This interface provides no new functionality . The goal of defining this interface is to provide an API similar to that of the publisher’s API in beyond that of UDDI. The intent is to provide a familiar API to UDDI developers.

LifeCycleManager

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 data items in the JAXR API. It normally includes the following:

Organization object is one of the more complex

1. 2. 3. 4.

5. 6.

Name object. Description object. A Key object, representing the ID by which the organization is known to the registry. 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. A collection of Classification objects. Service objects and their associated ServiceBinding objects.
A A

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. 2. 3.

Use to find the taxonomy to which the organization wants to belong to. Create a classification using the classification scheme and a concept (a taxonomy element) within the classification scheme. Add the classification to the organization.

BusinessQueryManager

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"); Collection classifications = new ArrayList(); 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 } }
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

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.

[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. 2. 3. 4.

A client requests access to a protected resource. The web server returns a dialog box that requests the user name and password. The client submits the user name and password to the server. 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

access to the Application Server.

@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

The code snippet is as follows:

import javax.jws.WebMethod; import javax.jws.WebService; import javax.annotation.security.RolesAllowed; @WebService() public class Hello { 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, security elements that need to be added to the deployment descriptor include the

web.xml. 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> <url-pattern>/hello</url-pattern> <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. web.xml to allow GET requests without authentication.

Provide a local access to the WSDL using catalog. Configure

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:

1. 2. 3. 4. 5. 6.

A client requests access to a protected resource. The web server presents its certificate to the client. The client verifies the server's certificate. If successful, the client sends its certificate to the server. The server verifies the client's credentials. 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:

1. 2. 3. 4. 5.

A client requests access to a protected resource. The web server presents its certificate to the client. The client verifies the server's certificate. If successful, the client sends its user name and password to the server, which verifies the client's credentials. 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 import import import

javax.annotation.Resource; javax.ejb.Stateless; javax.jws.WebService; javax.xml.ws.WebServiceContext;

@Stateless @WebService public class HelloEjb { @Resource WebServiceContext wsContext; public String hello(String msg) { return "Ejb WS: " + wsContext.getUserPrincipal() + ": " + msg; } }

The

annotation is used to declare resource dependencies that the class has - in the class as a web service. The essence, what resources the class needs. These resources are then injected into the endpoint implementation. In this example, the annotation identifies a resource dependency on the the

@Stateless annotation marks the class as a stateless session bean, and the @WebService annotation marks @Resource

WebServiceContext. The class needs 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.jws.WebService; 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).

For SSL mutual authentication, you need to set the to

auth-method subelement of the login-config element CLIENT-CERT. You also need to set thetransport-guarantee element to CONFIDENTIAL. web.xml deployment descriptor:

Add the appropriate security elements to the

<?xml version="1.0"?> <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> <url-pattern>/hello</url-pattern> <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

parameter in is a URL that points to the web service. The value of the location of the WSDL file for the service being referenced. So for a web service client that uses SSL, the

wsdlLocation

@WebServiceRef annotation to declare a reference to a @WebServiceRef

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. keytool command is used

The certificate has to be loaded to the client, to achieve this,

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 and are both optional and could be below, omitted. The following is an XML snippet showing WS-Policy assertions for WS-Addressing and WS-Reliable Messaging:

wsrm:AcknowledgementInterval

wsrm:InactivityTimeout

<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 operation input.

wsdl:input element that refers to an associated wsdl:message element to describe the

a

wsdl:output element that refers to 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
(Two-way methods only) an optional

describe each fault.

Each

wsdl:message element has one of the following: •
Document style

A single

declaration in the

wsdl:part child element that refers, via an element attribute, to a global element wsdl:types section:

@WebService public interface StockQuoteProvider { float getPrice(String tickerSymbol) throws TickerException; } <types> <xsd:schema targetNamespace="..."> <!-- element declarations --> <xsd:element name="getPrice" type="tns:getPriceType"/> <xsd:element name="getPriceResponse" type="tns:getPriceResponseType"/> <xsd:element name="TickerException" type="tns:TickerExceptionType"/> <!-- type definitions --> ... </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

value) that refer, via a

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:

@WebService public interface StockQuoteProvider { float getPrice(String tickerSymbol) throws TickerException; }

<types> <xsd:schema targetNamespace="..."> <!-- element declarations --> <xsd:element name="TickerException" type="tns:TickerExceptionType"/> <!-- type definitions --> ... </xsd:schema> </types> <message name="getPrice"> <part name="tickerSymbol" type="xsd:string"/> </message> <message name="getPriceResponse"> <part name="return" type="xsd:float"/> </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>

Each method in a Java SEI is mapped to a corresponding

soap:operation child element of the wsdl:operation. The value of the style attribute of thesoap:operation is document or rpc.
attribute of the . WS-I Basic If not specified, the value defaults to the value of the Profile requires that all operations within a given SOAP HTTP binding instance have the same binding style.

style

soap:binding

soap:body or soap:header child elements of wsdl:input and wsdl:output elements for eachwsdl:operation binding element. The value of the use attribute of the soap:body is literal.
The parameters of a Java method are mapped to the Example shows using document style:

<types> <schema targetNamespace="..."> <xsd:element name="getPrice" type="tns:getPriceType"/> <xsd:complexType name="getPriceType"> <xsd:sequence> <xsd:element name="tickerSymbol" type="xsd:string"/>

</xsd:sequence> </xsd:complexType> <xsd:element name="getPriceResponse" type="tns:getPriceResponseType"/> <xsd:complexType name="getPriceResponseType"> <xsd:sequence> <xsd:element name="return" type="xsd:float"/> </xsd:sequence> </xsd:complexType> </schema> </types> <message name="getPrice"> <part name="getPrice" element="tns:getPrice"/> </message> <message name="getPriceResponse"> <part name="getPriceResponse" element="tns:getPriceResponse"/> </message> <portType name="StockQuoteProvider"> <operation name="getPrice" parameterOrder="tickerSymbol"> <input message="tns:getPrice"/> <output message="tns:getPriceResponse"/> </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"> <soap:body use="literal"/> </input> <output message="tns:getPriceResponse"> <soap:body use="literal"/> </output> </operation> </binding>

Example shows using rpc style:

<types> <schema targetNamespace="..."> <xsd:element name="getPrice" type="tns:getPriceType"/> <xsd:complexType name="getPriceType"> <xsd:sequence> <xsd:element form="unqualified" name="tickerSymbol" type="xsd:string"/> </xsd:sequence> </xsd:complexType> <xsd:element name="getPriceResponse" type="tns:getPriceResponseType"/> <xsd:complexType name="getPriceResponseType"> <xsd:sequence> <xsd:element form="unqualified" name="return" type="xsd:float"/> </xsd:sequence> </xsd:complexType> </schema> </types> <message name="getPrice"> <part name="tickerSymbol" type="xsd:string"/> </message> <message name="getPriceResponse"> <part name="result" type="xsd:float"/> </message> <portType name="StockQuoteProvider"> <operation name="getPrice"> <input message="tns:getPrice"/> <output message="tns:getPriceResponse"/> </operation> </portType> <binding name="StockQuoteProviderBinding"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>

<operation name="getPrice"> <soap:operation/> <input message="tns:getPrice"> <soap:body use="literal"/> </input> <output message="tns:getPriceResponse"> <soap:body use="literal"/> </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 object, it's simple use Java API for XML Binding (JAXB) for processing the payload. If you have the 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 (SAAJ) in a SOAP handler.

JAXBContext

SOAPMessage objects using the SOAP with Attachments API for Java

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

specification defines the

javax.xml.ws.handler.soap.SOAPHandler. The JAX-WS SOAPHandler class for SOAP binding. When a SOAP handler is invoked, 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. javax.xml.ws.handler.LogicalHandler

. They provide access to Logical handlers extend 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 the payload. When a logical handler is invoked, a request. The method

LogicalMessageContext object is specified in the getMessage() inLogicalMessageContext returns 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. service. Here's a code snippet from

SOAPLoggingHandler is a SOAP handler that logs calls to a web 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) { } ... }

Like all SOAP handlers, that

SOAPLoggingHandler implements the SOAPHandler interface. Notice SOAPLoggingHandler also implements three

handleMessage(), handleFault(), and close(). 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:
methods: The

• • •

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").

The logging is done in the handler's the

logToSystemOut() method that both 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 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.
Notice that the a Writing a Logical Message Handler

LogicalLoggingHandler file is a logical message handler. Like SOAPLoggingHandler, it logs calls to a web service. Here's a code snippet fromLogicalLoggingHandler:
The the

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 and

handleMessage(),handleFault(),

close() methods. processMessage() method that both handleMessage() and handleFault() methods call:

The logging is done in the handler's the

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

context for the logical handler. It calls the

processMessage() method accesses and manipulates the message payload using the logical message LogicalMessage method, getPayload(), to get 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 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.
the You can also pass a object. Here's an example:

JAXBContext object in the call to getPayload(), to get the payload as a JAXB

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 and are both optional and could be below, omitted. The following is an XML snippet showing WS-Policy assertions for WS-Addressing and WS-Reliable Messaging:

wsrm:AcknowledgementInterval

wsrm:InactivityTimeout

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"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="op"> <soap:operation soapAction=""/> <wsdl:input> <soap:body use="literal"/> </wsdl:input> <wsdl:output> <soap:body use="literal"/> </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:

package sample.fault; 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

schema, which the fault's wrapper element refers to; in this case it's

faultInfo instance variable. The type of this faultInfo is derived from the Fault:

package sample.fault; 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"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="op"> <soap:operation soapAction=""/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </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 (for instance, )? What happens on the client? The answer to than 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

sample2.fault.Fault

NullPointerException

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>

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. When the 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 WebServiceException, the general-purpose exception for the JAX-WS APIs.

JAX-WS defines a number of Java classes, such as fail, they throw

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

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. tool to send a to access The client uses the URL and the 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. The client uses the WSDL file to create the web service client.

wsimport

MetadataExchangeRequest

3.

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 o

The performance of the web service application degrades to a point that it is no longer useful. 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 o o

Communication failures are occurring that result in the network being unavailable or connections being. dropped Application messages are being lost in transit. 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 o 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. Enabling reliable messaging causes a degradation of web service performance, especially if the ordered delivery option is enabled. 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 o

Web Services Security Policy -- Enables web services to use security assertions to clearly represent security preferences and requirements for web service endpoints. 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 as

xs:base64Binary or xs:hexBinary can be optimally transmitted over the wire. 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 XML type, such as 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 2.0 specification defines

xs:bas64Binary or xs:hexBinary can be annotated by using attribute reference using xmime:expectedConte xmime:expectedContentType to Java type mapping:
java.awt.Image java.awt.Image java.lang.String javax.xml.transform.Source javax.xml.transform.Source javax.activation.DataHandler javax.activation.DataHandler

image/gif image/jpg text/plain text/xml application/xml multipart/* all other types

<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 o o o o o

Enable using

@javax.xml.ws.soap.MTOM annotation on the endpoint (SEI) implementation class:

@javax.xml.ws.soap.MTOM @WebService (endpointInterface = "mtom.server.Hello") public class HelloImpl implements Hello { .... }

o o o o o o o

MTOM can be also be enabled on an endpoint by specifying descriptor:

enable-mtom attribute to true on an endpoint element in sun-jaxws.

<?xml version="1.0" encoding="UTF-8"?> <endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime' version='2.0'> <endpoint name="Mtom" implementation="mtom.server.HelloImpl" url-pattern="/hello" enable-mtom="true"/>

o o

</endpoints>

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

To enable MTOM on client-side, pass the

javax.xml.ws.soap.MTOMFeature as WebServiceFeature parameter while 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 byte[] 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.
As defined by JAXB 2.0 specification of If the

byte[] 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 Multipart/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
data is sent as attachment mime part in 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. 2. 3.

The binary attachment is packaged in a MIME multi-part message (the same mechanism used in e-mail to handle attachments). element is used to mark where the binary data is. An The actual binary data is kept in a different MIME part.

xop:Include

MTOM is efficient, in the sense that it doesn't have the 33% size increase penalty that 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.

xs:base64Binary

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/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 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"> <soap:operation soapAction=""/> <input> <soap:body namespace="http://attachment.tip/" use="literal"/> </input>

<output> <soap:body namespace="http://attachment.tip/" use="literal"/> </output> </operation> <operation name="sendOctet"> <soap:operation soapAction=""/> <input> <soap:body namespace="http://attachment.tip/" use="literal"/> </input> <output> <soap:body namespace="http://attachment.tip/" use="literal"/> </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 import import import javax.jws.WebMethod; javax.jws.WebParam; javax.jws.WebService; 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 (or ), JAX-WS maps those to parameters of type type the burden placed on the client or server run time to format the content appropriately.

base64Binary

hexBinary

byte[]. With MTOM, the MIME-ness of the types has all been extracted byte[]

, which maps to . In the JAX-RPC Sw/A WSDL, howeve The interface portion of both WSDLs shows that the data type in the operations is 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.

base64Binary

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/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 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 import import import import import import java.awt.Image; javax.activation.DataHandler; javax.jws.WebMethod; javax.jws.WebParam; javax.jws.WebService; javax.xml.ws.RequestWrapper; 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", targetNamespace = "http://attachment.tip/", 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.

These two data types support different range and precision. only values within the range and precision of outside of this range require a customized .NET client.

java.math.BigDecimal supports arbitrary precision. System.decimal does not. For i System.decimal. (See System.decimal.Minvalue and System.decimal.Maxvalu

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.

types:

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 to xs:anySimpleType, the common schema type from which all the XML schema calendar types are dervived. xs:anySimpleType to System.string.

.NET maps

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

A business document like a purchase order or invoice in XML format is sent as the SOAP message in the request. The service accepts the document and a.

3. 4. 5. 6.

Does not return any message to the client. This corresponds to a 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. Once the service receives the message it is placed on a JMS queue for processing at a later time. The Message Driven Beans deployed in the container actively receive and process the message containing the XML business document from the queu The response to the business processing, is also placed on another JMS Queue for dispatch to the client at a later time. 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.

void

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 components can act as JAX- WS clients. Client developers can either use the Service Endpoint Interface or polling invocations.

javax.xml.ws.Dispatch

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 the operation has completed and to retrieve the results:

Response<ResponseBean> that may be polled using methods inherited from Future<?

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. either use the Service Endpoint Interface or implement

javax.xml.ws.Dispatch to implement asynchronous callback invocations. The callback 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

has completed. The object returned from this will result in non-portable behavior.

invokeAsync method returns a wildcard Future (Future<?>) that may be polled to determin Future<?>.get() has no standard type. Client code should not attempt to cast the object to an

SEI - A callback method takes an additional final parameter that is an instance of a typed

wildcard 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:

Future<?>

AsyncHandler<ResponseBean> and re Future<?>.get(

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 message context properties and message payload. These handlers must implement the a

javax.xml.ws.handler.LogicalHandler interface. A log LogicalMessageContext object from which the handler can get the message information. Logical handlers can exist on both SOAP and XML/HTTP-based c javax.xml.ws.handler.soap.SOAPHandler interface. Protocol handlers receive the message as javax.xml.soap.SOAPMessage to read the message data. handleMessage(MessageContext) handleFault(MessageContext)

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 configurations and must implement the a

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

method or method for a specific handler is invoked. You m a 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

handler chain configuration file. The 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

@HandlerChain

@HandlerChain annotation to the Service Endpoint Interface or the generated service cla file

HandlerResolver method.

To use handlers with your server application, you must set the

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.

@HandlerChain annotation on either the Service Endpoint Interface or the endpoint implementation @HandlerChainannotation on the service endpoint implem

For both server and client implementations of handlers using the the annotated file or as an absolute URL. For example:

@HandlerChain annotation, you must specify the location of the handler configuration as either a

@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. Use the default implementation of a handler resolver. The runtime now uses the

2.

@HandlerChain annotation and the default implementatio HandlerResolver 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. Configure the client handlers by setting the @HandlerChain annotation on the service instance or Service Endpoint Interface, or you can modify the ha
of

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

the 4. 5. 6.

@HandlerChain annotation on the Service Endpoint Interface or implementation class. When @HandlerChain annotation is configured on both the Service Endpoint Interface and the implementation class, the implementation class takes prior Create the handler chain configuration XML file. You must create a handler chain configuration XML file for the @HandlerChain to reference.
Add the handler chain configuration XML file in the class path for the Service Endpoint Interface when configuring the server or client handlers using

annotation. You must also include the handler classes contained in the configuration XML file in your class path. the Write your handler implementation.

@HandlerChain

Web Service Cache pattern:

Opportunities for caching:

1. 2. 3.

Client-side transparent to the application cache. Server-side transparent to the application cache. 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 selectively expose and broker the services of an application. A typically exposed using a WSDL. The

WebServiceBrokercoordinates the interaction among services, collects responses and performs t EndpointProcessorclass 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:


Forces:

You want to provide access to one or more services using XML and web protocols.

• • • •
Solution:

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.

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", targetNamespace = "http://attachment.tip/", className = "tip.attachment.SendOctet") @ResponseWrapper(localName = "sendOctetResponse", targetNamespace = "http://attachment.tip/", 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.

JAX-WS still supports the Sw/A model. By default, JAX-WS maps a Sw/A attachment to a the

byte[] on the Java interface. To get the mapping you are used to in JAX-RPC, 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. 2. 3. 4.

RPC/encoded RPC/literal Document/encoded 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 • o o o
RPC/literal

The operation name appears in the message, so the receiver has an easy time dispatching this message to the implementation of the operation.

Weaknesses The type encoding info (such as throughput performance.

xsi:type="xsd:int") is usually just overhead which degrades <x ...>5</x> and <y ...>5.0</y> lines soap:Body contents comes from WSDL definitions.

You cannot easily validate this message since only the contain things defined in a schema; the rest of the

Although it is legal WSDL, RPC/encoded is not WS-I compliant.

The RPC/literal WSDL for this method looks almost the same as the RPC/encoded WSDL (see above). The changed from

use in the binding is

encoded toliteral. myMethod:

RPC/literal WSDL for

<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/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 o o o o

The WSDL is still about as straightforward as it is possible for WSDL to be. The operation name still appears in the message. The type encoding info is eliminated. RPC/literal is WS-I compliant.

Weaknesses You cannot easily validate this message since only the contain things defined in a schema; the rest of the

<x ...>5</x> and <y ...>5.0</y> lines 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> <message name="myMethodRequest"> <part name="x" element="xElement"/> <part name="y" element="yElement"/> </message> <message name="empty"/> <portType name="PT"> <operation name="myMethod"> <input message="myMethodRequest"/> <output message="empty"/> </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 o o

There is no type encoding info. You can finally validate this message with any XML validator. Everything within the schema. Document/literal is WS-I compliant, but with restrictions.

soap:Body is defined in a

Weaknesses

o o 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. The operation name in the SOAP message is lost. Without the name, dispatching can be difficult, and sometimes impossible. WS-I only allows one child of the example's

soap:Body in a SOAP message. As you can see in listing above, this 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> <message name="myMethodRequest"> <part name="parameters" element="myMethod"/> </message> <message name="empty"> <part name="parameters" element="myMethodResponse"/> </message> <portType name="PT"> <operation name="myMethod"> <input message="myMethodRequest"/> <output message="empty"/> </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

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

<myMethod>child of <soap:Body> was the name of the operation. In the document/literal wrapped SOAP message, <myMethod>

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 o o o o

There is no type encoding info. Everything that appears in the

soap:Body is defined by the schema, so you can easily validate this message.

You have the method name in the SOAP message. 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 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, float y); 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, float y); 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 because the message has two parameters and this method requires one. It could be either sure is that it's not of the other two methods. With the document/literal style, you have no way to know which one.

myMethod(int x)

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 must be

myMethod, and you know you have two parameters, so it

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 way to send data graphs is to use the

A points to node B through both its left and right links. The standard 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

to the left and another node node instead of being referenced twice:

B

href attribute is not available, so the graph linkage is lost. You still have a root node, A, which points to a B to the right. These B nodes are equal, but they are not the same node. Data have been duplicated

<A> <name>A</name> <left> <name>B</name> <left xsi:nil="true"/> <right xsi:nil="true"/>

</left> <right> <name>B</name> <left xsi:nil="true"/> <right xsi:nil="true"/> </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

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.

wsimport tool. The wsimport tool then generates javac, is then called to compile the

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

Master your semester with Scribd & The New York Times

Special offer for students: Only $4.99/month.

Master your semester with Scribd & The New York Times

Cancel anytime.