clustering/xdocs/1_1/userguide-introtoservices.html - axis-axis2-java-core - Git at Google

 <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 to send
 information back and forth, but 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 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 third and arguably 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 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 use
 them 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, in
     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 which
     acknowledgment is important.</li>
   <li>In-Only: In this MEP, the client sends a message to the server without
     the expectation of receiving a response. You may use this MEP for
     activities such as pinging a server to wake it up, reporting logging
     information for which you need no 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 then move on, 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
     require no 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 of 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. 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>
	<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 to send
	information back and forth, but 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 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><?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></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 third and arguably 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 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 use
	them 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, in
	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 which
	acknowledgment is important.</li>
	<li>In-Only: In this MEP, the client sends a message to the server without
	the expectation of receiving a response. You may use this MEP for
	activities such as pinging a server to wake it up, reporting logging
	information for which you need no 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 then move on, 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
	require no 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 of 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. 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>