<html lang="en">
<head>
  <meta http-equiv="content-type" content="">
  <title>Apache Axis2 User's Guide- Introduction to Services</title>
  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
  media="all">
</head>

<body>
<a name="introservices"></a>

<h1>Apache Axis2 User's Guide - Introduction to Services</h1>

<p>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).</p>

<h2>Content</h2>
<ul>
  <li><a href="userguide.html#intro">Introducing Axis2</a><br>

    <ul>
      <li><a href="userguide.html#whatis">What is Axis2?</a></li>
      <li><a href="userguide.html#underhood">What's under the hood?</a></li>
      <li><a href="userguide.html#handlessoap">How Axis2 handles SOAP
        messages</a></li>
      <li><a href="userguide.html#distributions">Axis2 distributions</a></li>
      <li><a href="userguide.html#sbd">The Axis2 Standard Binary
        Distribution</a></li>
      <li><a href="userguide.html#hierarchy">Axis2.war Directory
      Hierarchy</a></li>
      <li><a href="userguide.html#docs">Axis2 Documents Distribution</a></li>
      <li><a href="userguide.html#clients">Axis2 and clients</a></li>
    </ul>
  </li>
  <li><a href="userguide-installingtesting.html#installingtesting">Installing
    and testing client code</a></li>
  <li><a
    href="userguide-introtoservices.html#introservices"><strong>Introduction
    to Services</strong></a><br>

    <ul>
      <li><a
        href="userguide-introtoservices.html#messageexchange"><strong>Message
        Exchange Patterns</strong></a></li>
    </ul>
  </li>
  <li><a href="userguide-creatingclients.html#createclients">Creating
    Clients</a><br>

    <ul>
      <li><a href="userguide-creatingclients.html#choosingclient">Choosing a
        Client Generation Method</a></li>
      <li><a href="userguide-creatingclients.html#generating">Generating
        Clients</a></li>
      <li><a href="userguide-creatingclients.html#adb">Axis Data Binding
        (ADB)</a></li>
    </ul>
  </li>
  <li><a href="userguide-buildingservices.html#buildservices">Building
    Services</a><br>

    <ul>
      <li><a href="userguide-buildingservices.html#getcomfortable">Getting
        Comfortable with the Available Options</a></li>
      <li><a href="userguide-buildingservices.html#createscratch">Creating a
        service from scratch</a></li>
      <li><a href="userguide-buildingservices.html#deploypojo">Deploying
        Plain Old Java Objects</a></li>
      <li><a href="userguide-buildingservices.html#deployrun">Deploying and
        running an Axis2 service created from WSDL</a></li>
    </ul>
  </li>
  <li><a href="userguide-samples.html">Samples</a></li>
  <li><a href="userguide-forfurtherstudy.html">For Further Study</a></li>
</ul>

<h3>Code Listing 4: Example SOAP Message</h3>
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/03/addressing"&gt; 
 &lt;env:Header&gt;

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

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

 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>

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

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

<p>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.</p>
<a name="messageexchange"></a>

<h2>Message Exchange Patterns</h2>

<p>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:</p>
<ul>
  <li>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.</li>
  <li>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.</li>
</ul>

<p>Within these two MEPs, you also have several variables to consider:</p>
<ul>
  <li>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.</li>
  <li>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.</li>
</ul>

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

<p><strong>See Next Section</strong> - <a
href="userguide-creatingclients.html#createclients">Creating Clients</a></p>
</body>
</html>