Apache Axis2 User's Guide - Introduction to Services

The term "Web services" can apply to a number of different ways of sending information back and forth. However, this guide focuses on the sending and receiving of SOAP messages. SOAP messages are XML documents that consist of an "envelope" containing a "payload" (see Code Listing 4).

Content

Code Listing 4: Example SOAP Message

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/03/addressing"> 
 <env:Header>

    <wsa:MessageID>
      http://ws.apache.org/9C21DE32-DB42-1228-C42E-66CB101421AD
    </wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>http://example.com/projects/clientApp</wsa:Address>
    </wsa:ReplyTo>
    
<wsa:To>http://example.com/axis2/publishingService</wsa:To>
    
<wsa:Action>http://example.com/axis2/addDocument</wsa:Action>
 
</env:Header>
 <env:Body>

  <addDocument>
   <docTitle>What I Did On My Summer Vacation</doctitle>
   <docSubtitle>Children's Essays from Accross the World</docSubtitle>
   <docLocation>contentRepos/summerVac.doc</docLocation>
  </addDocument>

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

This XML document consists of the outer element or the SOAP Envelope, and its contents. The SOAP Envelope is in the SOAP namespace, http://www.w3.org/2003/05/soap-envelope, prefixed as env: and contains up to two children. This envelope is a standard format that pertains to every single SOAP message sent and received by any SOAP Web service.

The contents of the Envelope consists of two parts; the first being the SOAP headers-the contents of the env:Header element. These headers, such as the WS-Addressing elements shown here, provide additional information about the message and how it should be handled. A SOAP message may carry headers relating to several aspects of the message, or it may carry no headers at all. These headers are typically processed by the message handlers.

The second and arguably the most important part of the message is the payload, which consists of the contents of the env:Body element. This is the actual message intended for the receiver, and it is the information that the main application will ultimately process.

Message Exchange Patterns

Although all SOAP messages carry the same structure, the ways in which they are used can be combined into a number of different "message exchange patterns", or MEPs. The two major message exchange patterns are:

In-Out: in this MEP, the client sends a SOAP message to the server, which processes the message and sends a response back. This is probably the most commonly used MEP, and is useful for tasks such as searching for information or submitting information in situations in where acknowledgment is important.
In-Only: In this MEP, the client sends a message to the server without expecting a response. You may use this MEP for activities such as pinging a server to wake it up, reporting logging information for which you do not need an acknowledgment and so on.

Within these two MEPs, you also have several variables to consider:

Blocking versus non-blocking: When the client sends a message, the application may wait to receive a response before moving on, or it may simply send a message and move on by specifying a callback action to be completed when the response is received.
Number of parameters: Ultimately, a message sent from a client to server is intended to execute a particular action. That action may not require any parameters, or it may require one or more parameters. These parameters must be encoded as part of the payload of the message.

Taking all these options into consideration, you can create virtually any MEP. For example, you can create an Out-Only system by reversing roles for the In-Only MEP. Apache Axis2 also includes support for less prominent MEPs, such as Robust-In-Only.

See Next Section - Creating Clients