<!-- | |
~ Licensed to the Apache Software Foundation (ASF) under one | |
~ or more contributor license agreements. See the NOTICE file | |
~ distributed with this work for additional information | |
~ regarding copyright ownership. The ASF licenses this file | |
~ to you under the Apache License, Version 2.0 (the | |
~ "License"); you may not use this file except in compliance | |
~ with the License. You may obtain a copy of the License at | |
~ | |
~ http://www.apache.org/licenses/LICENSE-2.0 | |
~ | |
~ Unless required by applicable law or agreed to in writing, | |
~ software distributed under the License is distributed on an | |
~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
~ KIND, either express or implied. See the License for the | |
~ specific language governing permissions and limitations | |
~ under the License. | |
--> | |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" | |
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> | |
<head> | |
<meta name="generator" content= | |
"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /> | |
<meta http-equiv="content-type" content="" /> | |
<title>Apache Axis2 User's Guide- Introduction to Services</title> | |
</head> | |
<body> | |
<a name="introservices" id="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> | |
<?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 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" id="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> |