- Forward


Simple Object Access Protocol (SOAP) v1.2
An Introduction with Examples in Java


Prof. David Bernstein
James Madison University

Computer Science Department
bernstdh@jmu.edu

Print

Simple Object Access Protocol Basics
Back SMYC Forward
  • What It's Used For:
    • Transmit objects and method calls over a network
  • What It Is:
    • A set of rules for encoding application-defined datatypes
    • A set of rules for representing remote procedure calls and responses
SOAP Basics (cont.)
Back SMYC Forward
  • Protocols:
    • Can be used with a number of "transport" protocols
    • Is generally used with HTTP
  • Encoding Scheme:
    • All SOAP messages are encoded in XML
    • SOAP messages consist of an envelope, an optional header, and a body
The SOAP Envelope
Back SMYC Forward
  • The Local Name:
    • Envelope is the top element of the XML document representing the message
    • It may contain namespace declarations and/or additional attributes
  • The Namesapce:
    • http://www.w3.org/2003/05/soap-envelope
  • The encodingStyle Attribute:
    • Used to indicate the serialization rules used
    • The value of this attribute is an ordered list of URIs
    • The "standard" serialization rules are defined in http://www.w3.org/2003/05/soap-encoding
The SOAP Envelope (cont.)
Back SMYC Forward

An Example

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:xml="http://www.w3.org/XML/1998/namespace"> </env:Envelope>
The SOAP Header
Back SMYC Forward
  • Purpose:
    • The Header is a generic mechanism for adding features to a SOAP message
  • Example:
    • The Header could be used to indicate who should deal with a feature and whether it is optional or mandatory
  • Requirements:
    • If present, the Header element MUST be the first immediate child of the Envelope element
The SOAP Body
Back SMYC Forward
  • The Element:
    • Body is a container element
    • It must be an immediate child element of the Envelope element
    • It must directly follow the Header element, if one is present, otherwise it must be the first immediate child of Envelope
  • Contents:
    • May contain character information items
    • May contain elements information items
    • May contain attribute information items
    • May contain Fault items
The SOAP Body (cont.)
Back SMYC Forward

An Example

<env:Body> <TextAlert> <Message>Port Rd. has been closed</Message> <Alert>Road CLosed - Find Alternate</Alert> <Priority>6</Priority> </TextAlert> </env:Body>
The Fault Element
Back SMYC Forward
  • Mandatory Sub-elements:
    Code The machine-usable cause of the fault
    Reason The human-readable cause of the fault
  • Optional Sub-elements:
    Node The Node that caused the fault
    Role The role the Node that caused the fault was playing
    Detail Application-specific information
  • Fault Codes:
    • "VersionMismatch", "MustUnderstand", "DataEncodingUnknown", "Sender", "Receiver"
    • Can be extended using the "." operator (e.g., "Server.IncorrectSymbol")
Data Types
Back SMYC Forward
  • Types:
    • Simple (scalar) types
    • Compound types constructed as a composite of several parts, each with a type
  • Simple Types:
    • SOAP uses all the built-in datatypes that can be used to write an XML Schema
  • Compound Types:
    • struct
    • array (including sparse array)
Data Types (cont.)
Back SMYC Forward

An Example

<element name="age" type="int"/> <element name="height" type="float"/> <element name="eyecolor"> <simpleType base="xsd:string"> <enumeration value="Green"/> <enumeration value="Blue"/> </simpleType> </element>
Data Types (cont.)
Back SMYC Forward

An Example Using References

<complexType name="Book"> <!-- Either the following group must occur or else the href attribute must appear, but not both. --> <sequence minOccurs="0" maxOccurs="1"> <element name="title" type="xsd:string"/> <element name="firstauthor" type="Person"/> <element name="secondauthor" type="Person"/> </sequence> <attribute name="href" type="uriReference"/> <attribute name="id" type="ID"/> </complexType>
<Book> <title>Paradise Lost</title> <firstauthor href="http://www.dartmouth.edu/~milton/"/> </Book>
Method/Procedure Calls
Back SMYC Forward
  • Required:
    • The URI of the target object
    • The method name
    • The parameters
  • The Invocation:
    • A method invocation is usually represented as elements that contain both "in" and "in/out" parameters
  • The Response:
    • A method response is usually represented as elements that are similar to the method invocation
Method/Procedure Calls (cont.)
Back SMYC Forward

An Example: Convert from U.S. dollars to British Pounds

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Body> <CurrencyConverter> <convert> <fromCurrency>USD</fromCurrency> <toCurrency>GBP</toCurrency> <amount>100.00</amount> </convert> </CurrencyConverter> <env:Body> </env:Envelope>
Method/Procedure Calls (cont.)
Back SMYC Forward

An Example Response

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Body> <CurrencyConverterResponse> <convert> <amount>72.45</amount> </convert> </CurrencyConverterResponse> </env:Body> </env:Envelope>
Method/Procedure Calls (cont.)
Back SMYC Forward

An Example Fault

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Body> <env:Fault> <env:Code>env:Server</env:Code> <env:Reason>Server Error</env:Reason> <env:Detail> <FaultDetails> <code>8</code> <message>Unknown fromCurrency</message> </FaultDetails> </env:Detail> </env:Fault> </env:Body> </env:Envelope>
A Currency Converter
Back SMYC Forward

The Interface

javaexamples/http/v5/CurrencyConverter.java
 
A Currency Converter (cont.)
Back SMYC Forward

The Server Side - The Implementation

javaexamples/http/v5/CurrencyConverterImpl.java
 
A Currency Converter (cont.)
Back SMYC Forward

The Server Side - The Handler

javaexamples/http/v5/CurrencyConverterSOAPHandler.java
 
A Currency Converter (cont.)
Back SMYC Forward

The Server Side - The Servlet

javaexamples/http/v5/CurrencyConverterSOAPServlet.java
 
A Currency Converter (cont.)
Back SMYC Forward

The Client Side

javaexamples/http/v5/CurrencyConverterStub.java
 
The javax.xml.soap Package
Back SMYC Forward
  • Purposes:
    • Creating/building SOAP messages
  • Some of the Interfaces:
    • SOAPBody javax.xml.soap.SOAPBody , SOAPElement javax.xml.soap.SOAPElement , SOAPEnvelope javax.xml.soap.SOAPEnvelope , SOAPFault javax.xml.soap.SOAPFault , SOAPHeader javax.xml.soap.SOAPHeader , and Text javax.xml.soap.Text
  • Some of the Classes:
    • SOAPMessage javax.xml.soap.SOAPMessage and SOAPPart javax.xml.soap.SOAPPart ,
The javax.xml.soap Package (cont.)
Back SMYC Forward
  • Use:
    • Factories are used to create objects that implement these interfaces
  • Some of the Factories:
    • MessageFactory javax.xml.soap.MessageFactory , SOAPElementFactory javax.xml.soap.SOAPElementFactory , and SOAPFactory javax.xml.soap.SOAPFactory
The Currency Converter Revisited
Back SMYC Forward

Creating a Request

javaexamples/soap/CurrencyConverterRequestFactory.java
 
SOAP Connections
Back SMYC Forward
  • Purposes:
    • Use SOAP to invoke a remote method
  • The Factory:
    • SOAPConnectionFactory javax.xml.soap.SOAPConnectionFactory
  • The Connection:
    • SOAPConnection javax.xml.soap.SOAPConnection
The Currency Converter Revisited Again
Back SMYC Forward

Making a Request

javaexamples/soap/CurrencyConverterClient.java
 
There's Always More to Learn
Back -