SOAPFrancesco Ierna

SOAP

Enconding types used in SOAP messages :

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

SOAP is a protocol that allows the exchange of structured data specified by an XML schema between peers in a decentralized, distributed environment

There are following SOAP encoding types:

Simple types. Adopts all the types found including :

Boolean , byte, short, int, long, float, double,java.lang.String, java.math.BigDecimal, java.util.GregorianCalendar, java.util.Date,byte []

String , Enumarations, Arrays of bytes

Compound types. The members of a Compound Value are encoded as accessor elements

Arrays

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

Structure

SOAP

Example TypesSimple:

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

Compound:

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

<book><author>Mikalai Zaikin</author><title>SCDJWS 5.0 Study Guide</title><intro>This is a certification guide</intro></book>

Example TypesArrays (SOAP 1.2):<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>

<numbers enc:itemType="xs:int" enc:arraySize="2"><number>3</number><number>4</number></numbers>

Table mappingXML Schema type SOAP Java type

xsd:string → java.lang.Stringxsd:integer java.math.BigInteger→xsd:int int→xsd:long long→xsd:short short→xsd:decimal java.math.BigDecimal→xsd:float float→xsd:double double→xsd:boolean boolean→xsd:byte byte→xsd:QName QName→xsd:dateTime XMLGregorianCalendar→xsd:base64Binary byte[]→xsd:hexBinary byte[]→xsd:unsignedInt long→xsd:unsignedShort int→xsd:unsignedByte short→xsd:time XMLGregorianCalendar→xsd:date XMLGregorianCalendar→xsd:g XMLGregorianCalendar→

SOAP Processing Model

Processing Model :

Allow to send messages from a sender to a receiver through zero or many intermediates.

Specifies how a SOAP reiceiver processes a SOAP message.

Each subsequent depends on the response to the previous message.

Nodes :

Inital sender, ultimate receiver(ultimateReceiver) or intermediary(next). None → must not act in this rôle.

Processed by a URL

Roles :

One o more roles

Processed by a URI known as the SOAP role name

Invariant during the proccessing of an individual SOAP message

Processing SOAP messagesSteps :

Determine the set of roles in which the node is to act.

Contents of the enveloppe, may be inspected in making such determination.

Identify all headers block are mandatory

If one or more of the SOAP header blocks in the preceding step are not understood by the node then generate a single SOAP fault with the value of Code set to env:mustUnderstand.

Fault : max 1

No processing body

If Ultimate Receiver : if we have the last SOAP node we process the SOAP body.

In the case of a SOAP intermediary, and where the SOAP message exchange pattern and results of processing require that the SOAP message be sent further along the SOAP message path, relay the message as described in section

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 enveloppe and a [namespace name] of "http://www.w3.org/2003/05/soap-envelope".

Processing SOAP messages

SOAP Message<Envelope> is mandatory :

Namespace → "http://www.w3.org/2003/05/soap-envelope" and URL

<Header> is optional. Information passed through the SOAP Messages that is not included in the body.

Many header blocks.

First child of the enveloppe.

Must be namespaces qualified.

Roles : by URI Example http://example.org/Qos SOAP 1.2. Three types(none, next, ultimateReceiver(Default)) :

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

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

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

<Body> is mandatory. It contains the payload of the message that is the information being transferred from the initial sender to the ultimate receiver.

After header blocks, if it's present

Should namespaces qualified

May contain XML well-formed or be empty

Contains or data or fault

Envelopes rolesA receiver of an envelope that does not belong to the http://schemas.xmlsoap.org/soap/envelope/ namespace (the SOAP 1.1 namespace) must generate a fault.

Must not contain a Document Type Declaration

Must not contain Processing Instructions

Should not contain the namespace declaration xmlns:xml="http://www.w3.org/XML/1998/namespace"

Must not contain soap:encodingStyle attributes on any elements belonging to the same namespace as the SOAP <Envelope> element

Any soap:mustUnderstand attribute appearing in a SOAP Envelope is only allowed to have the value “0” or “1”.

SOAP elements must not have attributes belonging to the same namespace asthe SOAP <Envelope> element (http://schemas.xmlsoap.org/soap/envelope/): <Envelope>, <Header>, <Body>

Envelopes ModelA receiver of a SOAP message must process SOAP Envelopes so that it at least appears as if all mandatory header blocks

A receiver of a SOAP message that contains a mandatory header block targeted at the receiver, using the soap:role attribute in the header block, must generate a “soap:MustUnderstand” fault if the receiver does not understand the header block

When a fault is generated, the receiver should not perform any further processing of the SOAP Envelope, except for any processing required to roll back the effects of the processing of the SOAP Envelope up to the point of the fault.

If the normal processing of a SOAP Envelope would have resulted in a SOAP response being sent, a receiver must transmit a fault in place of the response if a fault is generated.

Envelopes FaultA When a SOAP message is a fault, the SOAP <Fault> element must not have any other child elements than: <faultcode>, <faultactor>, <faultstring>, <detail>

The above child elements of a SOAP <Fault> element must not be namespace qualified.

A receiver of a fault must be able to handle faults in which the <faultstring> element has a xml:lang attribute.

SOAP Envelope contains a <faultcode> element, its contents should be:

One of the fault codes defined in SOAP 1.1, supplying any additional information in the

<detail> element. Using these fault codes is preferred.

A qualified name whose namespace is controlled by the fault's specifying authority

Envelopes HttpSOAP messages must be sent using either HTTP/1.0 or HTTP/1.1, where HTTP/1.1 is preferred.

A HTTP request message must be sent using the HTTP POST method.

SOAPAction HTTP header field in a HTTP request message must be a quoted string.

The 2xx HTTP status codes must be used to indicate the successful outcome of a HTTP request.

“200 OK“ or “202 Accepted” should be used to indicate the successful outcome of a HTTP request which response does not contain a SOAP message

The 4xx HTTP status codes must be used when there is a problem with the format of a request.

400 Bad Request” should be used when a HTTP request is malformed.

405 Method not Allowed” should be used when the method of a HTTP request message is not POST.

“415 Unsupported Media Type” should be used when the value of the Content-Type HTTP header field is not permitted by its WSDL description

500 Internal Server Error” must be used when the HTTP response contains a SOAP fault.

Example SOAP MessagesEXAMPLE 1: NO ROLES<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Header>

<pns:qualityOfService xmlns:pns="http://example.org/qos"> <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:quantity>100</bmns:quantity></bmns:businessPO>

</env:Body></env:Envelope>

EXAMPLE 2: NEXT<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Header>

<pns:qualityOfService xmlns:pns="http://example.org/qos" env:role="http://www.w3.org/2003/05/soap-envelope/role/next"> <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:quantity>100</bmns:quantity></bmns:businessPO>

</env:Body></env:Envelope>

SOAP Extensibility ModelExtensibility Model :

Simple messaging framework.

Extensibility can be used to add capabilities found in richer messaging enveroiment

Two mechanism through which features can be expressed

SOAP Processing Model

Beahavior of a single SOAP node with respect to the processing of an individual message

SOAP Protocol Binding Framework

Binding : The formal set of rules for carrying a SOAP message within or on top of another protocol (underlying protocol) for the purpose of exchange is called a binding

Mediates the act of sending and receiving SOAP messages by a SOAP node via an underlying protocol

The SOAP Protocol Binding Framework provides general rules for the specification of protocol bindings; the framework also describes the relationship between bindings and SOAP nodes that implement those bindings

SOAP Fault MessageSoap Fault : used to carry error and/or status information within SOAP message.

If present it must appear as a body entry and must appear not more than once within a body element.

Possible reasons for faults may be improper message formatting, version mismatches, trouble processing a header and application-specific errors

A SOAP fault is generated by the node, be it an intermediary or the ultimate receiver

If the messaging exchange pattern One-Way is used, then the SOAP fault must not be transmitted to the immediate sender. The SOAP fault may be stored somewhere

If the messaging exchange pattern Request-Response is used, then the SOAP fault must be transmitted to the immediate sender, that is, the SOAP node immediately preceding the current SOAP node in the messaging chain

The node receiving the SOAP fault may, in turn, take some action and also, optionally, transmit the SOAP fault further up the SOAP messaging path to its previous node, if any

SOAP Fault MessageSoap Fault : used to carry error and/or status information within SOAP message.

If present it must appear as a body entry and must appear not more than once within a body element.

Two or more child element items in its property in order as follow :

Code : mandatory has two elements:

Value (mandatory). Enum fault codes (env:faultCodeEnum)

Subcode has two elements :

Value (mandatory). Element information is xs:QName

Subcode (optional).

Reason : mandatory provides a human-readable explanation of the fault

Text : One or more elements

Mandatory attributes information item

Node : optional. Provides information about which SOAP node on the SOAP message path caused the fault to happen. URI idetifies the SOAP nodes that generated the Fault message.

Next : must include who is that generated the fault message.

UltimateReceiver : may include info

Rôle : optional. identifies the role the node was operating in at the point the fault occurred.

information item is xs:anyURI

Detail : optional. is intended for carrying application specific error information.

Character : any number of childs

Example Fault Example Code:<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>

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

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

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

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

SAAJ SAAJ : SOAP 1.1 with attachments.

It provides a standard way to send XML documents over the Internet from the Java platform

Standalone client that sends the message directly to a webservices that is implemented for req/resp messaging is :

Syncroninus

SOAPMessage is sent over a SOAPConnection object via the method SOAPConnection.call

XML document that is a SOAPMessage (envelope, header, body)

Body :

XML document : standard SOAP message

Not XML Document(jpg, mp3, mpg) and then you must use attachment part within the SOAP message.

Processing creation and sending SOAP message with attachment :

Creating SOAP connection

Creationg SOAP message

Populating the message

Sending the message

Retrieving the reply

SAAJ StepsConnectionFactory SOAP:SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance();

Connection SOAP from ConnectionFactory:SOAPConnection connection = factory.createConnection();

MessageFactory:MessageFactory messageFactory = MessageFactory.newInstance();

Message from MessageFactory:SOAPMessage message = messageFactory.createMessage();

MessageSOAP: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");

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

SAAJ Steps

SAAJ Steps

SOAP Message: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);

SOAP Message Body:SOAPBodyElement docElement = body.addDocument(document);

Attachment Parts:URL url = new URL("http://foo.bar/img.jpg");DataHandler handler = new DataHandler(url);AttachmentPart attachPart = message.createAttachmentPart(handler);message.addAttachmentPart(attachPart);

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

Send Message:SOAPMessage response = soapConnection.call(message, endpoint);

SAAJ Diagram

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

Two types :

logical handlers : are protocol-agnostic and cannot change any protocol-specific parts (like headers) of a message

are commonly used if the processing does not needaccess to SOAP headers, for validation of the payload, and with Representational State Transfer ("REST") style web services

Extend javax.xml.ws.handler.LogicalHandler

Protocol handlers : are specific to a protocol and may access or change the protocol specific aspects of a message.

SOAP handlers are generally used to process SOAP-specific information, such as SOAP headers

Handlers are invoked with a message context, which provides methods that the handler uses to access and modify inbound or outbound messages.

extend javax.xml.ws.handler.soap.SOAPHandler

Methods SOAPLoggingHandler :

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,

Handlers

Handlers - Message-Context