You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2007/02/16 12:31:37 UTC
svn commit: r508372 - in /webservices/axis2/trunk/java/xdocs/1_1:
mtom-guide.html pojoguide.html
Author: chatra
Date: Fri Feb 16 03:31:36 2007
New Revision: 508372
URL: http://svn.apache.org/viewvc?view=rev&rev=508372
Log:
reviewed and committed changes in patch in AXIS2-2201
Modified:
webservices/axis2/trunk/java/xdocs/1_1/mtom-guide.html
webservices/axis2/trunk/java/xdocs/1_1/pojoguide.html
Modified: webservices/axis2/trunk/java/xdocs/1_1/mtom-guide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/1_1/mtom-guide.html?view=diff&rev=508372&r1=508371&r2=508372
==============================================================================
--- webservices/axis2/trunk/java/xdocs/1_1/mtom-guide.html (original)
+++ webservices/axis2/trunk/java/xdocs/1_1/mtom-guide.html Fri Feb 16 03:31:36 2007
@@ -1,13 +1,15 @@
<html>
<head>
+ <meta http-equiv="content-type" content="">
<title>Handling Binary data with Axis2 (MTOM/SwA)</title>
- <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
</head>
<body>
-<h1>Handling Binary data with Axis2 (MTOM/SwA)</h1>
+<h1>Handling Binary Data with Axis2 (MTOM/SwA)</h1>
-<p>This document will describe how to use Axis2 functionality to send/receive
+<p>This document describes how to use the Axis2 functionality to send/receive
binary data with SOAP.</p>
<h2>Content</h2>
@@ -17,14 +19,12 @@
<li><a href="#11">Where Does MTOM Come In?</a></li>
</ul>
</li>
-
<li><a href="#2">MTOM with Axis2 </a>
<ul>
<li><a href="#21">Programming Model</a></li>
<li><a href="#22">Enabling MTOM Optimization at Client Side</a></li>
<li><a href="#23">Enabling MTOM Optimization at Server Side</a></li>
<li><a href="#24">Accessing Received Binary Data (Sample Code) </a>
-
<ul>
<li><a href="#241">Service</a></li>
<li><a href="#242">Client</a></li>
@@ -37,15 +37,13 @@
</ul>
</li>
</ul>
-
</li>
<li><a href="#3">SOAP with Attachments with Axis2</a>
<ul>
- <li><a href="#31">Sending SwA type attachments</a></li>
- <li><a href="#32">Receiving SwA type attachments</a></li>
+ <li><a href="#31">Sending SwA Type Attachments</a></li>
+ <li><a href="#32">Receiving SwA Type Attachments</a></li>
<li><a href="#33">MTOM Backward Compatibility with SwA</a></li>
</ul>
-
</li>
<li><a href="#4">Advanced Topics </a>
<ul>
@@ -57,10 +55,10 @@
<h2>Introduction</h2>
-<p>Despite the flexibility, interoperability and global acceptance of XML,
+<p>Despite the flexibility, interoperability, and global acceptance of XML,
there are times when serializing data into XML does not make sense. Web
-services users may need to transmit binary attachments of various sorts like
-images, drawings, xml docs, etc together with SOAP message. Such data are
+services users may want to transmit binary attachments of various sorts like
+images, drawings, XML docs, etc., together with a SOAP message. Such data is
often in a particular binary format.<br>
</p>
@@ -71,17 +69,17 @@
<blockquote>
<p>Sending binary data by value is achieved by embedding opaque data (of
- course after some form of encoding) as element or attribute content of
+ course after some form of encoding) as an element or attribute content of
the XML component of data. The main advantage of this technique is that
- it gives applications the ability to process and describe data, based and
- looking only on XML component of the data.</p>
+ it gives applications the ability to process and describe data, based
+ only on the XML component of the data.</p>
<p>XML supports opaque data as content through the use of either base64
- or hexadecimal text encoding. Both these techniques bloat the size of the
- data. For UTF-8 underlying text encoding, base64 encoding increases the
- size of the binary data by a factor of 1.33x of the original size, while
- hexadecimal encoding expands data by a factor of 2x. Above factors will
- be doubled if UTF-16 text encoding is used. Also of concern is the
+ or hexadecimal text encoding. Both techniques bloat the size of the data.
+ For UTF-8 underlying text encoding, base64 encoding increases the size of
+ the binary data by a factor of 1.33x of the original size, while
+ hexadecimal encoding expands data by a factor of 2x. The above factors
+ will be doubled if UTF-16 text encoding is used. Also of concern is the
overhead in processing costs (both real and perceived) for these formats,
especially when decoding back into raw binary.</p>
</blockquote>
@@ -89,25 +87,24 @@
<blockquote>
<p>Sending binary data by reference is achieved by attaching pure
- binary data as external unparsed general entities outside of the XML
- document and then embedding reference URI's to those entities as
+ binary data as external unparsed general entities outside the XML
+ document and then embedding reference URIs to those entities as
elements or attribute values. This prevents the unnecessary bloating of
data and wasting of processing power. The primary obstacle for using
these unparsed entities is their heavy reliance on DTDs, which impedes
- modularity as well as use of XML namespaces.</p>
+ modularity as well as the use of XML namespaces.</p>
<p>There were several specifications introduced in the Web services
world to deal with this binary attachment problem using the "by
reference" technique. <a
href="http://www.w3.org/TR/SOAP-attachments">SOAP with Attachments</a>
-
is one such example. Since SOAP prohibits document type declarations
- (DTD) in messages, this leads to the problem of not representing data
- as part of the message infoset, creating two data models. This scenario
- is like sending attachments with an e-mail message. Even though those
- attachments are related to the message content they are not inside the
- message. This causes the technologies for processing and description
- of data based on XML component of the data, to malfunction. One example
- is WS-Security.</p>
+ (DTD) in messages, this leads to the problem of not representing data
+ as part of the message infoset, therefore creating two data models.
+ This scenario is like sending attachments with an e-mail message. Even
+ though those attachments are related to the message content they are
+ not inside the message. This causes the technologies that process and
+ describe the data based on the XML component of the data to
+ malfunction. One example is WS-Security.</p>
</blockquote>
</li>
</ol>
@@ -117,42 +114,40 @@
<p><a href="http://www.w3.org/TR/2004/PR-soap12-mtom-20041116/">MTOM (SOAP
Message Transmission Optimization Mechanism)</a> is another specification
-which focuses on solving the "Attachments" problem. MTOM tries to leverage
-the advantages of the above two techniques by trying to merge the two
-techniques. MTOM is actually a "by reference" method. Wire format of a MTOM
-optimized message is same as the Soap with Attachments message, which also
-makes it backward compatible with SwA endpoints. The most notable feature of
-MTOM is the use of XOP:Include element, which is defined in <a
+that focuses on solving the "Attachments" problem. MTOM tries to leverage the
+advantages of the above two techniques by trying to merge the two techniques.
+MTOM is actually a "by reference" method. The wire format of a MTOM optimized
+message is the same as the SOAP with Attachments message, which also makes it
+backward compatible with SwA endpoints. The most notable feature of MTOM is
+the use of the XOP:Include element, which is defined in the <a
href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XML Binary Optimized
-Packaging (XOP)</a> specification to reference the binary attachments
+Packaging (XOP)</a> specification to reference the binary attachments
(external unparsed general entities) of the message. With the use of this
-exclusive element the attached binary content logically become inline (by
-value) with the SOAP document even though actually it is attached separately.
+exclusive element, the attached binary content logically becomes inline (by
+value) with the SOAP document even though it is actually attached separately.
This merges the two realms by making it possible to work only with one data
model. This allows the applications to process and describe by only looking
-at XML part making reliance on DTDs obsolete. On a lighter note, MTOM has
-standardized the referencing mechanism of SwA. The following is an extract
-from the <a href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XOP</a>
-
-specification.</p>
+at the XML part, making the reliance on DTDs obsolete. On a lighter note,
+MTOM has standardized the referencing mechanism of SwA. The following is an
+extract from the <a
+href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XOP</a> specification.</p>
<p><em>At the conceptual level, this binary data can be thought of as being
base64-encoded in the XML Document. As this conceptual form might be needed
-during some processing of the XML Document (e.g., for signing the XML
+during some processing of the XML document (e.g., for signing the XML
document), it is necessary to have a one-to-one correspondence between XML
Infosets and XOP Packages. Therefore, the conceptual representation of such
binary data is as if it were base64-encoded, using the canonical lexical form
-of XML Schema base64Binary datatype (see <a href="#XMLSchemaP2">[XML Schema
-Part 2: Datatypes Second Edition] </a> <a
+of the XML Schema base64Binary datatype (see <a href="#XMLSchemaP2">[XML
+Schema Part 2: Datatypes Second Edition] </a> <a
href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#base64Binary">3.2.16
base64Binary</a>). In the reverse direction, XOP is capable of optimizing
only base64-encoded Infoset data that is in the canonical lexical
form.</em></p>
<p>Apache Axis2 supports <strong>Base64 encoding</strong>, <strong>SOAP with
-Attachments</strong> & <strong>MTOM (SOAP Message Transmission
-Optimization Mechanism).</strong></p>
-
+Attachments</strong> and <strong>MTOM (SOAP Message Transmission Optimization
+Mechanism).</strong></p>
<a name="2"></a>
<h2>MTOM with Axis2</h2>
@@ -160,28 +155,29 @@
<h3>Programming Model</h3>
-<p>AXIOM is (and may be the first) Object Model which has the ability to hold
-binary data. It has been given this ability by allowing OMText to hold raw
-binary content in the form of javax.activation.DataHandler. OMText has been
-chosen for this purpose with two reasons. One is that XOP (MTOM) is capable
-of optimizing only base64-encoded Infoset data that is in the canonical
-lexical form of XML Schema base64Binary datatype. Other one is to preserve
-the infoset in both sender and receiver (To store the binary content in the
-same kind of object regardless of whether it is optimized or not).</p>
+<p>AXIOM is (and may be the first) Object Model that has the ability to hold
+binary data. It has this ability as OMText can hold raw binary content in the
+form of javax.activation.DataHandler. OMText has been chosen for this purpose
+with two reasons. One is that XOP (MTOM) is capable of optimizing only
+base64-encoded Infoset data that is in the canonical lexical form of XML
+Schema base64Binary datatype. Other one is to preserve the infoset in both
+the sender and receiver. (To store the binary content in the same kind of
+object regardless of whether it is optimized or not).</p>
<p>MTOM allows to selectively encode portions of the message, which allows us
to send base64encoded data as well as externally attached raw binary data
-referenced by "XOP" element (optimized content) to be send in a SOAP message.
-User can specify whether an OMText node which contains raw binary data or
-base64encoded binary data is qualified to be optimized or not at the
-construction time of that node or later. To take the optimum efficiency of
-MTOM a user is advised to send smaller binary attachments using
-base64encoding (None optimized) and larger attachments as optimized
-content.</p>
-<source><pre> OMElement imageElement = fac.createOMElement("image", omNs);
+referenced by the "XOP" element (optimized content) to be sent in a SOAP
+message. You can specify whether an OMText node that contains raw binary data
+or base64encoded binary data is qualified to be optimized at the time of
+construction of that node or later. For optimum efficiency of MTOM, a user is
+advised to send smaller binary attachments using base64encoding
+(non-optimized) and larger attachments as optimized content.</p>
+
+<p></p>
+<pre> OMElement imageElement = fac.createOMElement("image", omNs);
// Creating the Data Handler for the file. Any implementation of
- // javax.activation.DataSource interface can fit here.
+ // javax.activation.DataSource interface can fit here.
javax.activation.DataHandler dataHandler = new javax.activation.DataHandler(new FileDataSource("SomeFile"));
DataHandler dataHandler = new DataHandler(dataSource);
@@ -192,83 +188,86 @@
//User can set optimized to false by using the following
//textData.doOptimize(false);</pre>
-</source>
-<p>Also a user can create an optimizable binary content node using a base64
-encoded string, which contains encoded binary content, given with the mime
+
+<p>Also, a user can create an optimizable binary content node using a base64
+encoded string, which contains encoded binary content, given with the MIME
type of the actual binary representation.</p>
-<source><pre> String base64String = "some_base64_encoded_string";
+
+<p></p>
+<pre> String base64String = "some_base64_encoded_string";
OMText binaryNode =<strong>fac.createOMText(base64String,"image/jpg",true);</strong></pre>
-</source>
-<p>Axis2 uses javax.activation.DataHandler to handle the binary data. All
+
+<p>Axis2 uses javax.activation.DataHandler to handle the binary data. All the
optimized binary content nodes will be serialized as Base64 Strings if "MTOM
-is not enabled". One can also create binary content nodes which will not be
-optimized at any case. They will be serialized and send as Base64 Strings.</p>
-<source><pre> //create an OMText node with the above DataHandler and set "optimized" to false
+is not enabled". You can also create binary content nodes, which will not be
+optimized at any case. They will be serialized and sent as Base64 Strings.</p>
+
+<p></p>
+<pre> //create an OMText node with the above DataHandler and set "optimized" to false
//This data will be send as Base64 encoded string regardless of MTOM is enabled or not
javax.activation.DataHandler dataHandler = new javax.activation.DataHandler(new FileDataSource("SomeFile"));
OMText textData = fac.createOMText(dataHandler, <strong>false</strong>);
image.addChild(textData);</pre>
+<a name="22"></a>
-</source><a name="22"></a>
-
-<h3>Enabling MTOM Optimization at Client Side</h3>
+<h3>Enabling MTOM Optimization on the Client Side</h3>
-<p>Set the "enableMTOM" property in the Options to true, when sending
+<p>In Options, set the "enableMTOM" property to True when sending
messages.</p>
-<source><pre> ServiceClient serviceClient = new ServiceClient ();
+
+<p></p>
+<pre> ServiceClient serviceClient = new ServiceClient ();
Options options = new Options();
options.setTo(targetEPR);
<strong>options.setProperty(Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);</strong>
serviceClient .setOptions(options);</pre>
-</source>
-<p>When this property is set to true any SOAP envelope, regardless whether it
-contains optimizable content or not, will be serialized as a MTOM optimized
-MIME message.</p>
+
+<p>When this property is set to True, any SOAP envelope, regardless of
+whether it contains optimizable content or not, will be serialized as an MTOM
+optimized MIME message.</p>
<p>Axis2 serializes all binary content nodes as Base64 encoded strings
-regardless of they are qualified to be optimize or not, if,</p>
+regardless of whether they are qualified to be optimized or not</p>
<ul>
- <li>"enableMTOM" property is set to false.</li>
- <li>If envelope contains any element information items of name xop:Include
- (see <a href="#XOP">[XML-binary Optimized Packaging] </a><a
+ <li>if the "enableMTOM" property is set to False.</li>
+ <li>if the envelope contains any element information items of the name
+ xop:Include (see <a href="#XOP">[XML-binary Optimized Packaging] </a><a
href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_infosets">3. XOP
Infosets Constructs </a>).</li>
</ul>
-<p>User does <strong>not</strong> have to specify anything in order for Axis2
-to receive MTOM optimised messages. Axis2 will automatically identify and
-de-serialize accordingly as and when a MTOM message arrives.</p>
-
+<p>The user does <strong>not</strong> have to specify anything in order for
+Axis2 to receive MTOM optimised messages. Axis2 will automatically identify
+and de-serialize accordingly, as and when an MTOM message arrives.</p>
<a name="23"></a>
-<h3>Enabling MTOM Optimization at Server Side</h3>
+<h3>Enabling MTOM Optimization on the Server Side</h3>
-<p>Axis 2 server automatically identifies incoming MTOM optimized messages
-based on the content-type and de-serializes accordingly. User can enableMTOM
-in the server side for outgoing messages,</p>
+<p>The Axis 2 server automatically identifies incoming MTOM optimized
+messages based on the content-type and de-serializes them accordingly. The
+user can enableMTOM on the server side for outgoing messages,</p>
<blockquote>
- <p>To enableMTOM globally for all services users can set the "enableMTOM"
- parameter to true in the Axis2.xml. When it is set, all outgoing messages
- will be serialized and send as MTOM optimized MIME messages. If it is not
- set all the binary data in binary content nodes will be serialized as
+ <p>To enableMTOM globally for all services, users can set the "enableMTOM"
+ parameter to True in the Axis2.xml. When it is set, all outgoing messages
+ will be serialized and sent as MTOM optimized MIME messages. If it is not
+ set, all the binary data in the binary content nodes will be serialized as
Base64 encoded strings. This configuration can be overriden in services.xml
- for per service and per operation basis.</p>
+ on the basis of per service and per operation.</p>
</blockquote>
<pre><parameter name="enableMTOM" locked="false">true</parameter></pre>
-<p>User must restart the server after setting this parameter.</p>
+<p>You must restart the server after setting this parameter.</p>
<a name="24"></a>
<h3>Accessing Received Binary Data (Sample Code)</h3>
+<a name="241"></a>
<ul>
- <a name="241"></a>
- <ul>
- <li><strong>Service</strong></li>
- </ul>
-
+ <li><strong>Service</strong></li>
</ul>
-<source><pre>public class MTOMService {
+
+<p></p>
+<pre>public class MTOMService {
public void uploadFileUsingMTOM(OMElement element) throws Exception {
<strong>OMText binaryNode = (OMText) (element.getFirstElement()).getFirstOMChild();
@@ -278,14 +277,13 @@
... <em>Do whatever you need with the DataHandler</em> ...
}
}</pre>
-</source><ul>
- <a name="242"></a>
- <ul>
- <li><strong>Client</strong></li>
-
- </ul>
+<a name="242"></a>
+<ul>
+ <li><strong>Client</strong></li>
</ul>
-<source><pre> ServiceClient sender = new ServiceClient();
+
+<p></p>
+<pre> ServiceClient sender = new ServiceClient();
Options options = new Options();
options.setTo(targetEPR);
// enabling MTOM
@@ -300,19 +298,19 @@
DataHandler actualDH;
actualDH = binaryNode.getDataHandler();
.............</pre>
-</source><a name="25"></a>
+<a name="25"></a>
<h3>MTOM Databinding</h3>
-<p>You can defining a binary element in the schema using the schema
+<p>You can define a binary element in the schema using the schema
type="xsd:base64Binary". Having an element with the type "xsd:base64Binary"
-is enough for the Axis2 code generators to identify possible MTOM attachments
-and to generate code accordingly.</p>
+is enough for the Axis2 code generators to identify possible MTOM
+attachments, and to generate code accordingly.</p>
-<p>Going a little bit further you can use the xmime schema
+<p>Going a little further, you can use the xmime schema
(http://www.w3.org/2005/05/xmlmime) to describe the binary content more
-precisely. With xmime schema you can indicate the type of content in the
-element at runtime using an MTOM attribute extension, xmime:contentType.
+precisely. With the xmime schema, you can indicate the type of content in the
+element at runtime using an MTOM attribute extension xmime:contentType.
Furthermore, you can identify what type of data might be expected in the
element using the xmime:expectedContentType. Putting it all together, our
example element becomes:</p>
@@ -325,212 +323,207 @@
</extension>
</simpleContent>
</complexType>
- </element>
-</pre>
+ </element></pre>
</source>
-
<p>You can also use the xmime:base64Binary type to express the above
-mentioned data much more cleanly.</p>
+mentioned data much clearly.</p>
<source><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' type="xmime:base64Binary"/></pre>
-</source>
-<a name="251"></a>
+</source><a name="251"></a>
+
<h3>MTOM Databinding Using ADB</h3>
<p>Let's define a full, validated doc/lit style WSDL that uses the xmime
-schema, has a service that receives a file and saves it in the server using the given path.
-</p>
-<source><pre>
-<wsdl:definitions xmlns:tns="http://ws.apache.org/axis2/mtomsample/"
- xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
- xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
- xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
- xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
- xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
- xmlns:xsd="http://www.w3.org/2001/XMLSchema"
- xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
- xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
- xmlns="http://schemas.xmlsoap.org/wsdl/"
- targetNamespace="http://ws.apache.org/axis2/mtomsample/">
-
- <wsdl:types>
- <xsd:schema xmlns="http://schemas.xmlsoap.org/wsdl/"
- attributeFormDefault="qualified" elementFormDefault="qualified"
- targetNamespace="http://ws.apache.org/axis2/mtomsample/">
-
- <xsd:import namespace="http://www.w3.org/2005/05/xmlmime"
- schemaLocation="http://www.w3.org/2005/05/xmlmime" />
- <xsd:complexType name="AttachmentType">
- <xsd:sequence>
- <xsd:element minOccurs="0" name="fileName"
- type="xsd:string" />
- <xsd:element minOccurs="0" name="binaryData"
- type="xmime:base64Binary" />
- </xsd:sequence>
- </xsd:complexType>
- <xsd:element name="AttachmentRequest" type="tns:AttachmentType" />
- <xsd:element name="AttachmentResponse" type="xsd:string" />
- </xsd:schema>
- </wsdl:types>
- <wsdl:message name="AttachmentRequest">
- <wsdl:part name="part1" element="tns:AttachmentRequest" />
- </wsdl:message>
- <wsdl:message name="AttachmentResponse">
- <wsdl:part name="part1" element="tns:AttachmentResponse" />
- </wsdl:message>
- <wsdl:portType name="MTOMServicePortType">
- <wsdl:operation name="attachment">
- <wsdl:input message="tns:AttachmentRequest"
- wsaw:Action="attachment" />
- <wsdl:output message="tns:AttachmentResponse"
- wsaw:Action="http://schemas.xmlsoap.org/wsdl/MTOMServicePortType/AttachmentResponse" />
- </wsdl:operation>
- </wsdl:portType>
- <wsdl:binding name="MTOMServiceSOAP11Binding"
- type="tns:MTOMServicePortType">
- <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
- style="document" />
- <wsdl:operation name="attachment">
- <soap:operation soapAction="attachment" style="document" />
- <wsdl:input>
- <soap:body use="literal" />
- </wsdl:input>
- <wsdl:output>
- <soap:body use="literal" />
- </wsdl:output>
- </wsdl:operation>
- </wsdl:binding>
- <wsdl:binding name="MTOMServiceSOAP12Binding"
- type="tns:MTOMServicePortType">
- <soap12:binding transport="http://schemas.xmlsoap.org/soap/http"
- style="document" />
- <wsdl:operation name="attachment">
- <soap12:operation soapAction="attachment" style="document" />
- <wsdl:input>
- <soap12:body use="literal" />
- </wsdl:input>
- <wsdl:output>
- <soap12:body use="literal" />
- </wsdl:output>
- </wsdl:operation>
- </wsdl:binding>
- <wsdl:service name="MTOMSample">
- <wsdl:port name="MTOMSampleSOAP11port_http"
- binding="tns:MTOMServiceSOAP11Binding">
- <soap:address
- location="http://localhost:8080/axis2/services/MTOMSample" />
- </wsdl:port>
- <wsdl:port name="MTOMSampleSOAP12port_http"
- binding="tns:MTOMServiceSOAP12Binding">
- <soap12:address
- location="http://localhost:8080/axis2/services/MTOMSample" />
- </wsdl:port>
- </wsdl:service>
-</wsdl:definitions>
-</pre></source>
+schema, has a service that receives a file, and saves it in the server using
+the given path.</p>
+<source><pre><wsdl:definitions xmlns:tns="http://ws.apache.org/axis2/mtomsample/"
+ xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
+ xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
+ xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
+ xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
+ xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns="http://schemas.xmlsoap.org/wsdl/"
+ targetNamespace="http://ws.apache.org/axis2/mtomsample/">
+
+ <wsdl:types>
+ <xsd:schema xmlns="http://schemas.xmlsoap.org/wsdl/"
+ attributeFormDefault="qualified" elementFormDefault="qualified"
+ targetNamespace="http://ws.apache.org/axis2/mtomsample/">
+
+ <xsd:import namespace="http://www.w3.org/2005/05/xmlmime"
+ schemaLocation="http://www.w3.org/2005/05/xmlmime" />
+ <xsd:complexType name="AttachmentType">
+ <xsd:sequence>
+ <xsd:element minOccurs="0" name="fileName"
+ type="xsd:string" />
+ <xsd:element minOccurs="0" name="binaryData"
+ type="xmime:base64Binary" />
+ </xsd:sequence>
+ </xsd:complexType>
+ <xsd:element name="AttachmentRequest" type="tns:AttachmentType" />
+ <xsd:element name="AttachmentResponse" type="xsd:string" />
+ </xsd:schema>
+ </wsdl:types>
+ <wsdl:message name="AttachmentRequest">
+ <wsdl:part name="part1" element="tns:AttachmentRequest" />
+ </wsdl:message>
+ <wsdl:message name="AttachmentResponse">
+ <wsdl:part name="part1" element="tns:AttachmentResponse" />
+ </wsdl:message>
+ <wsdl:portType name="MTOMServicePortType">
+ <wsdl:operation name="attachment">
+ <wsdl:input message="tns:AttachmentRequest"
+ wsaw:Action="attachment" />
+ <wsdl:output message="tns:AttachmentResponse"
+ wsaw:Action="http://schemas.xmlsoap.org/wsdl/MTOMServicePortType/AttachmentResponse" />
+ </wsdl:operation>
+ </wsdl:portType>
+ <wsdl:binding name="MTOMServiceSOAP11Binding"
+ type="tns:MTOMServicePortType">
+ <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
+ style="document" />
+ <wsdl:operation name="attachment">
+ <soap:operation soapAction="attachment" style="document" />
+ <wsdl:input>
+ <soap:body use="literal" />
+ </wsdl:input>
+ <wsdl:output>
+ <soap:body use="literal" />
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+ <wsdl:binding name="MTOMServiceSOAP12Binding"
+ type="tns:MTOMServicePortType">
+ <soap12:binding transport="http://schemas.xmlsoap.org/soap/http"
+ style="document" />
+ <wsdl:operation name="attachment">
+ <soap12:operation soapAction="attachment" style="document" />
+ <wsdl:input>
+ <soap12:body use="literal" />
+ </wsdl:input>
+ <wsdl:output>
+ <soap12:body use="literal" />
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+ <wsdl:service name="MTOMSample">
+ <wsdl:port name="MTOMSampleSOAP11port_http"
+ binding="tns:MTOMServiceSOAP11Binding">
+ <soap:address
+ location="http://localhost:8080/axis2/services/MTOMSample" />
+ </wsdl:port>
+ <wsdl:port name="MTOMSampleSOAP12port_http"
+ binding="tns:MTOMServiceSOAP12Binding">
+ <soap12:address
+ location="http://localhost:8080/axis2/services/MTOMSample" />
+ </wsdl:port>
+ </wsdl:service>
+</wsdl:definitions></pre>
+</source>
<p>The important point here is we import http://www.w3.org/2005/05/xmlmime
-and define an element, 'binaryData' , that utilizes MTOM.</p>
+and define the element 'binaryData' that utilizes MTOM.</p>
-<p>The next step is using the Axis2 tool 'WSDL2Java' to generate java source
-files from this WSDL. See the 'Code Generator Tool' guide for more info.
-Here, we define an ant task that chooses ADB (Axis2 Data Binding) as the databinding
-implementation. The name we list for the WSDL above is MTOMSample.wsdl, and
-we define our package name for our generated source files to be
-'sample.mtom.service' . Our ant task for this example is:</p>
-<source><pre>
+<p>The next step is using the Axis2 tool 'WSDL2Java' to generate Java source
+files from this WSDL. See the 'Code Generator Tool' guide for more
+information. Here, we define an Ant task that chooses ADB (Axis2 Data
+Binding) as the databinding implementation. The name we list for the WSDL
+above is MTOMSample.wsdl, and we define our package name for our generated
+source files to 'sample.mtom.service' . Our Ant task for this example is:</p>
+<source><pre>
<target name="generate.service">
- <java classname="org.apache.axis2.wsdl.WSDL2Java">
- <arg value="-uri" />
- <arg value="${basedir}/resources/MTOMSample.wsdl" />
- <arg value="-ss" />
- <arg value="-sd" />
- <arg value="-g"/>
- <arg value="-p" />
- <arg value="sample.mtom.service" />
- <arg value="-o" />
- <arg value="${service.dir}" />
- <classpath refid="class.path" />
- </java>
- </target></pre>
+ <java classname="org.apache.axis2.wsdl.WSDL2Java">
+ <arg value="-uri" />
+ <arg value="${basedir}/resources/MTOMSample.wsdl" />
+ <arg value="-ss" />
+ <arg value="-sd" />
+ <arg value="-g"/>
+ <arg value="-p" />
+ <arg value="sample.mtom.service" />
+ <arg value="-o" />
+ <arg value="${service.dir}" />
+ <classpath refid="class.path" />
+ </java>
+ </target></pre>
</source>
-<p>Now we are ready to code. Lets edit
-output/src/sample/mtom/service/MTOMSampleSkeleton.java and fill in the business logic. Following is an example:</p>
-<source><pre>
- public org.apache.ws.axis2.mtomsample.AttachmentResponse attachment(
- org.apache.ws.axis2.mtomsample.AttachmentRequest param0) throws Exception
- {
- AttachmentType attachmentRequest = param0.getAttachmentRequest();
- Base64Binary binaryData = attachmentRequest.getBinaryData();
- DataHandler dataHandler = binaryData.getBase64Binary();
- File file = new File(
- attachmentRequest.getFileName());
- FileOutputStream fileOutputStream = new FileOutputStream(file);
- dataHandler.writeTo(fileOutputStream);
- fileOutputStream.flush();
- fileOutputStream.close();
-
- AttachmentResponse response = new AttachmentResponse();
- response.setAttachmentResponse("File saved succesfully.");
- return response;
- }
-</pre></source>
-<p>The code above receives a file and writes it to disk using the given file name. It returns a message
-on success.
-Now lets define the client:</p>
-<source><pre> public static void transferFile(File file, String destination)
- throws RemoteException {
- MTOMSampleStub serviceStub = new MTOMSampleStub();
-
- // Enable MTOM in the client side
- serviceStub._getServiceClient().getOptions().setProperty(
- Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);
- //Increase the time out when sending large attachments
- serviceStub._getServiceClient().getOptions().setTimeOutInMilliSeconds(10000);
-
- // Populating the code generated beans
- AttachmentRequest attachmentRequest = new AttachmentRequest();
- AttachmentType attachmentType = new AttachmentType();
- Base64Binary base64Binary = new Base64Binary();
-
- // Creating a javax.activation.FileDataSource from the input file.
- FileDataSource fileDataSource = new FileDataSource(file);
-
- // Create a dataHandler using the fileDataSource. Any implementation of
- // javax.activation.DataSource interface can fit here.
- DataHandler dataHandler = new DataHandler(fileDataSource);
- base64Binary.setBase64Binary(dataHandler);
- base64Binary.setContentType(dataHandler.getContentType());
- attachmentType.setBinaryData(base64Binary);
- attachmentType.setFileName(destination);
- attachmentRequest.setAttachmentRequest(attachmentType);
-
- AttachmentResponse response = serviceStub.attachment(attachmentRequest);
- System.out.println(response.getAttachmentResponse());
- }</pre>
-
+<p>Now we are ready to code. Let's edit
+output/src/sample/mtom/service/MTOMSampleSkeleton.java and fill in the
+business logic. Here is an example:</p>
+<source><pre> public org.apache.ws.axis2.mtomsample.AttachmentResponse attachment(
+ org.apache.ws.axis2.mtomsample.AttachmentRequest param0) throws Exception
+ {
+ AttachmentType attachmentRequest = param0.getAttachmentRequest();
+ Base64Binary binaryData = attachmentRequest.getBinaryData();
+ DataHandler dataHandler = binaryData.getBase64Binary();
+ File file = new File(
+ attachmentRequest.getFileName());
+ FileOutputStream fileOutputStream = new FileOutputStream(file);
+ dataHandler.writeTo(fileOutputStream);
+ fileOutputStream.flush();
+ fileOutputStream.close();
+
+ AttachmentResponse response = new AttachmentResponse();
+ response.setAttachmentResponse("File saved succesfully.");
+ return response;
+ }</pre>
</source>
-<p>The last step is to create an AAR with our Skeleton and the services.xml, and then deploy the service. You can find the completed sample in the Axis2 standard binary distribution under the samples/mtom directory</p>
-
-<a name="252"></a>
-<a name="3"></a>
+<p>The code above receives a file and writes it to the disk using the given
+file name. It returns a message once it is successful. Now let's define the
+client:</p>
+<source><pre> public static void transferFile(File file, String destination)
+ throws RemoteException {
+ MTOMSampleStub serviceStub = new MTOMSampleStub();
+
+ // Enable MTOM in the client side
+ serviceStub._getServiceClient().getOptions().setProperty(
+ Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);
+ //Increase the time out when sending large attachments
+ serviceStub._getServiceClient().getOptions().setTimeOutInMilliSeconds(10000);
+
+ // Populating the code generated beans
+ AttachmentRequest attachmentRequest = new AttachmentRequest();
+ AttachmentType attachmentType = new AttachmentType();
+ Base64Binary base64Binary = new Base64Binary();
+
+ // Creating a javax.activation.FileDataSource from the input file.
+ FileDataSource fileDataSource = new FileDataSource(file);
+
+ // Create a dataHandler using the fileDataSource. Any implementation of
+ // javax.activation.DataSource interface can fit here.
+ DataHandler dataHandler = new DataHandler(fileDataSource);
+ base64Binary.setBase64Binary(dataHandler);
+ base64Binary.setContentType(dataHandler.getContentType());
+ attachmentType.setBinaryData(base64Binary);
+ attachmentType.setFileName(destination);
+ attachmentRequest.setAttachmentRequest(attachmentType);
+
+ AttachmentResponse response = serviceStub.attachment(attachmentRequest);
+ System.out.println(response.getAttachmentResponse());
+ }</pre>
+</source>
+<p>The last step is to create an AAR with our Skeleton and the services.xml
+and then deploy the service. You can find the completed sample in the Axis2
+standard binary distribution under the samples/mtom directory</p>
+<a name="252"></a> <a name="3"></a>
<h2>SOAP with Attachments (SwA) with Axis2</h2>
<a name="31"></a>
-<h3>Receiving SwA type attachments</h3>
+<h3>Receiving SwA Type Attachments</h3>
<p>Axis2 automatically identifies SwA messages based on the content type.
-Axis2 stores the references to the received attachment parts (MIME parts) in
+Axis2 stores the references on the received attachment parts (MIME parts) in
the Message Context. Axis2 preserves the order of the received attachments
when storing them in the MessageContext. Users can access binary attachments
-using the attachement API given in the Message Context using content-id of
-the mime part as the key. Care needs be taken to rip off the "cid" prefix
-when content-id is taken from the "Href" attributes. Users can access the the
+using the attachement API given in the Message Context using the content-id
+of the mime part as the key. Care needs be taken to rip off the "cid" prefix
+when content-id is taken from the "Href" attributes. Users can access the
message context from whithin a service implementation class using the
"setOperationContext()" method as shown in the following example.</p>
<p>Note: Axis2 supports content-id based referencing only. Axis2 does not
support Content Location based referencing of MIME parts.</p>
-
<ul>
<li><strong>Sample service which accesses a received SwA type
attachment</strong></li>
@@ -560,9 +553,10 @@
<h3>Sending SwA Type Attachments</h3>
-<p>User need to set the "enableSwA" property to true in order to be able to
-send SwA messages. Axis2 user is <strong>not</strong> expected to enable MTOM
-& SwA together. In such a situation MTOM will get priority over SwA.</p>
+<p>The user needs to set the "enableSwA" property to True in order to be able
+to send SwA messages. The Axis2 user is <strong>not</strong> expected to
+enable MTOM and SwA together. In such a situation, MTOM will get priority
+over SwA.</p>
<p>This can be set using the axis2.xml as follows.</p>
<source><pre>
@@ -577,7 +571,6 @@
outgoing message as SwA type attachments. Client side SwA capability can be
used only with the OperationClient api, since the user needs the ability to
access the MessageContext.</p>
-
<ul>
<li><strong>Sample client which sends a message with SwA type
attachments</strong></li>
@@ -611,13 +604,12 @@
<p>MTOM specification is designed to be backward compatible with the SOAP
with Attachments specification. Even though the representation is different,
both technologies have the same wire format. We can safely assume that any
-SOAP with Attachments endpoint can accept a MTOM optimized messages and treat
-them as SOAP with Attachment messages - Any MTOM optimized message is a valid
+SOAP with Attachments endpoint can accept MTOM optimized messages and treat
+them as SOAP with Attachment messages - any MTOM optimized message is a valid
SwA message.</p>
<p>Note : Above backword compatibility was succesfully tested against Axis
1.x</p>
-
<ul>
<li><strong>A sample SwA message from Axis 1.x</strong></li>
</ul>
@@ -647,7 +639,6 @@
</source><ul>
<li><strong>Corresponding MTOM message from Axis2</strong></li>
</ul>
-
<source><pre>Content-Type: multipart/related; boundary=MIMEBoundary4A7AE55984E7438034;
type="application/xop+xml"; start="<0....@apache.org>";
start-info="text/xml; charset=utf-8"
@@ -682,15 +673,16 @@
<p>Axis2 comes handy with a file caching mechanism for incoming attachments,
which gives Axis2 the ability to handle very large attachments without
-buffering them in memory at any time. Axis2 file caching streams the incoming
-MIME parts directly in to files, after reading the MIME part headers.</p>
+buffering them in the memory at any time. Axis2 file caching streams the
+incoming MIME parts directly into the files, after reading the MIME part
+headers.</p>
-<p>Also a user can specify a size threshold for the File caching (in bytes).
+<p>Also, a user can specify a size threshold for the File caching (in bytes).
When this threshold value is specified, only the attachments whose size is
-bigger than the threshold value will get cached in files. Smaller attachments
-will remain in Memory.</p>
+bigger than the threshold value will get cached in the files. Smaller
+attachments will remain in the memory.</p>
-<p><em>NOTE</em> : It is a must to specify a directory to temporary store the
+<p>Note : It is a must to specify a directory to temporarily store the
attachments. Also care should be taken to <strong>clean that
directory</strong> from time to time.</p>
@@ -714,6 +706,5 @@
<source><pre>options.setProperty(Constants.Configuration.CACHE_ATTACHMENTS,Constants.VALUE_TRUE);
options.setProperty(Constants.Configuration.ATTACHMENT_TEMP_DIR,<em>TempDir</em>);
options.setProperty(Constants.Configuration.FILE_SIZE_THRESHOLD, <em>"4000"</em>);</pre>
-
</source></body>
</html>
Modified: webservices/axis2/trunk/java/xdocs/1_1/pojoguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/1_1/pojoguide.html?view=diff&rev=508372&r1=508371&r2=508372
==============================================================================
--- webservices/axis2/trunk/java/xdocs/1_1/pojoguide.html (original)
+++ webservices/axis2/trunk/java/xdocs/1_1/pojoguide.html Fri Feb 16 03:31:36 2007
@@ -2,19 +2,20 @@
<head>
<meta http-equiv="content-type" content="">
<title>POJO Web Services using Axis2</title>
- <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
</head>
<body lang="en">
<h1>POJO Web Services using Apache Axis2</h1>
-<p>Want a quick way to get a Web service up and running in no time? Well
-then, you should consider creating a Plain Old Java Object (POJO) to deploy
+<p>Want a quick way to get a Web service up and running in no time? Then you
+should consider creating a Plain Old Java Object (POJO) that you can deploy
using Apache Axis2 on Apache Tomcat. POJOs are fast to build and easy to
-maintain, meaning you'll save a lot of time building and debugging your code.
-This document shows you how to take a simple POJO, and deploy it on Apache
-Tomcat as a Web service in the exploded directory format. You'll also be
-shown how to take a POJO based on the Spring Framework, and deploy that as an
+maintain, which means you'll save a lot of time building and debugging your
+code. This document shows you how to take a simple POJO, and deploy it on
+Apache Tomcat as a Web service in the exploded directory format. You'll also
+learn how to take a POJO based on the Spring Framework, and deploy that as an
AAR packaged Web service on Tomcat.</p>
<h2>Content</h2>
@@ -54,8 +55,8 @@
<p>The task of building a Web service can sometimes be overwhelming, but not
with POJOs! The old-school Plain Old Java Object is a simple and quick way to
get most, if not all, of your currently existing Java classes up on the Web
-as readily accessible Web services. This document will show you how to build
-a POJO-style Web service with Apache Axis2 and Tomcat, organized as
+as readily accessible Web services. This document describes how to build a
+POJO-style Web service with Apache Axis2 and Tomcat. It is organized as
follows:</p>
<ul>
<li>The POJO: This is the Java class that you'll use throughout this
@@ -66,11 +67,11 @@
<li>Spring-based POJO Web service and deployment</li>
</ul>
-<p>The code for the document can be found at Axis2_HOME/samples/pojoguide
-& Axis2_HOME/samples/pojoguidespring once you extract the <a
-href="../../download/1_1_1/download.html#std-bin">Axis2 Stadard
-Distribution</a>, and it might help to go grab it now to help you as you
-follow along. Let's get started.</p>
+<p>The code for the document can be found at Axis2_HOME/samples/pojoguide and
+Axis2_HOME/samples/pojoguidespring once you extract the <a
+href="../../download/1_1_1/download.html#std-bin">Axis2 Standard
+Distribution</a>. (It is better to get it now as it will help you to follow
+along.) Let's get started.</p>
<a name="pojo"></a>
<h2>The POJO</h2>
@@ -181,38 +182,40 @@
<p>The name of the service is specified as WeatherService and the scope of
the service is application. As you can see in the WeatherService POJO, there
-are two methods, an IN-ONLY method and a IN-OUT method, hence the ordering
-for the messageReceiver elements within the messageReceivers tag. Lastly, the
+are two methods: IN-ONLY method and IN-OUT method. Hence the messageReceiver
+elements are ordered within the messageReceivers tag. Lastly, the
ServiceClass parameter specifies the class of the Web service, which is
sample.pojo.service.WeatherService. When operations of your Web service get
-called, the methods of the WeatherService class will be called. Next you'll
+called, the methods of the WeatherService class will be called. Next let usl
take a look at an easy method of building your application using Ant.</p>
<a name="buildpojows"></a>
<h2>Building the POJO Web Service Using Apache Ant</h2>
<p><a href="http://ant.apache.org/">Ant</a> is a slick build tool. It helps
-reduce time to build applications, and several of the Axis2 command-line
-tools create build.xml files for you, so that's why we'll use it here. We
-won't go into the build.xml file that you'll be using in too much detail, so
-here are the main Ant tasks you'll be using:</p>
+reduce the time to build the applications, and several of the Axis2
+command-line tools create the build.xml files for you. (We will not be going
+into too much detail on the build.xml file that you'll be using.) </p>
+
+<p>Here are the main Ant tasks you'll be using:</p>
<ul>
- <li>generate.service -- This Ant task builds all the service relevant
- source and copies the files to build/WeatherService</li>
+ <li>generate.service -- This Ant task builds the service relevant source,
+ and copies the files to build/WeatherService</li>
<li>rpc.client -- This task builds the client relevant files, builds a JAR
at <em>build/lib/rpc-client.jar</em>, and then runs the client</li>
</ul>
-<p>Before you can build the source, however, you'll need to download the
-Axis2 1.1.1-bin and 1.1.1-war distributions <a
+<p>Before you can build the source, you'll need to download the Axis2
+1.1.1-bin and 1.1.1-war distributions from <a
href="../../download/1_1_1/download.html">here</a>. Then modify the following
line inside the build.xml file (in the Axis2_HOME/samples/pojoguide directory
in the extracted Axis2 1.1.1 Standard Binary (bin) Distribution) :</p>
<pre><property name="axis2.home" value="c:\apps\axis2" /></pre>
<p>This modification contains the path to the root of the unzipped Axis2
-1.1.1-bin <a href="../../download/1_1_1/download.html#std-bin">download</a>. With
-that explanation, you'll now build the source by typing the following: ant</p>
+1.1.1-bin <a href="../../download/1_1_1/download.html#std-bin">download</a>.
+With that explanation, you'll now build the source by typing the following:
+ant</p>
<p>The following directory format should now exist at
build/WeatherService:</p>
@@ -233,11 +236,11 @@
used v5.5), and start it up by running <em>bin/startup.bat</em> or
<em>bin/startup.sh</em>. Once it's running, deploy the Axis2 1.1.1-war by
copying the axis2.war file to Tomcat's webapps directory. Tomcat will proceed
-by deploying axis2 and un-archive it into the webapps directory. Now copy the
-WeatherService directory created when building our project to:
-<em><tomcat-home>/webapps/axis2/WEB-INF/services</em>.</p>
+by deploying axis2 and un-archiving it into the webapps directory. Now copy
+the WeatherService directory that was created at the time of building our
+project to: <em><tomcat-home>/webapps/axis2/WEB-INF/services</em>.</p>
-<p>The service should quickly deploy, and you'll test the Web service using
+<p>The service should deploy quickly. You willl test the Web service using
the RPCServiceClient in the next section.</p>
<a name="testingpojows"></a>
@@ -249,6 +252,7 @@
values of the Weather class within the Web service (See Code Listing 4).</p>
<p><b>Code Listing 4: Setting the weather</b></p>
+
<p><pre>package sample.pojo.rpcclient;
import javax.xml.namespace.QName;
@@ -297,12 +301,13 @@
http://localhost:8080/axis2/services/listServices.</p>
<p>Next the opSetWeather variable gets setup, pointing to the setWeather
-operation. Then the Weather data gets created and initialized. Lastly, you
+operation. Then the Weather data is created and initialized. Lastly, you
invoke the Web service, which initializes the weather data (you'll verify
this soon). Next you get back the weather data (see Code Listing 5).</p>
<p><b>Code Listing 5: Getting the weather data</b></p>
-<p><pre>...
+<p>
+<pre>...
serviceClient.invokeRobust(opSetWeather, opSetWeatherArgs);
// Getting the weather
@@ -324,16 +329,18 @@
...</pre></p>
<p>First you set the operation in opGetWeather to getWeather. Then you create
-an empty argument list. Note this time you expect something back from the Web
-service, and so you create a list of return types. Then you invoke the Web
-service using a blocking call and wait for the weather data to be returned to
-you, and you place it in the result variable. Lastly, you make sure it isn't
-null and that it was successfully initialized by the previous call to
-setWeather. Now display the data to verify that it is indeed what you set it
-to (see Code Listing 6).</p>
+an empty argument list. Note that this time you expect something back from
+the Web service, and so you create a list of return types. Then you invoke
+the Web service using a blocking call and wait for the weather data to be
+returned to you, and you place it in the result variable. Lastly, you make
+sure it isn't null and that it was successfully initialized by the previous
+call to setWeather. Now display the data to verify it. (see Code Listing
+6).</p>
<p><b>Code Listing 6: Displaying the data</b></p>
-<p><pre>...
+
+<p>
+<pre>...
return;
}
@@ -359,7 +366,7 @@
[java] Rain : true
[java] How much rain (in inches) : 4.5</pre>
-<p>Excellent, you have a working POJO Web service! Next you'll quickly morph
+<p>Excellent! You have a working POJO Web service! Next you'll quickly morph
this one into a Spring based POJO.</p>
<a name="limitationspojo"></a>
@@ -369,16 +376,15 @@
about any limitations? One main limitation of POJO based Web services is the
lack of initialization support (meaning that you have to go into your Web
service and initialize the values before the Web service is completely
-useful), but you'll soon see how to overcome that limitation with a Spring
-based POJO, covered next.</p>
+useful). However, you'll soon see how to overcome that limitation with a
+Spring based POJO, which is covered next.</p>
<a name="springpojows"></a>
<h2>Spring-based POJO Web Service</h2>
<p>Spring is a hot framework for J2EE and makes bean usage a breeze. You'll
use it in this section to create a Spring based POJO Web service. For this
-section you'll need the spring.jar from the latest 1.x Spring download.</p>
-
+section, you'll need the spring.jar from the latest 1.x Spring download.</p>
<a name="quickintro"></a>
<h3>Quick Introduction</h3>
@@ -390,11 +396,10 @@
WeatherSpringService.</p>
<p>You'll also notice an applicationContext.xml file, which we'll cover
-later: it's used to setup the beans used in our Web service.</p>
+later. It is used to setup the beans used in our Web service.</p>
-<p>Now you might wonder what the SpringInit.java class is for: This service
-is necessary, however, to initialize the Spring Framework's application
-context.</p>
+<p>Now you might wonder what the SpringInit.java class is for. This service
+is necessary to initialize the Spring Framework's application context.</p>
<p>The client is pretty much the same, except you won't use it to initialize
the Weather data in the Web service, since Spring does that for you using
@@ -403,11 +408,12 @@
<h3>The Service Definition: services.xml</h3>
-<p>Because the core POJOs didn't change, you'll move straight to the
-services.xml file. It's a bit longer this time because it instantiates two
-services in one file (see Code Listing 7).</p>
+<p>Since the core POJOs didn't change, you move straight to the services.xml
+file. It's a bit longer this time because it instantiates two services in one
+file (see Code Listing 7).</p>
<p><b>Code Listing 7: Defining the services: services.xml</b></p>
+
<p><pre><serviceGroup>
<service <b>name="SpringInit"
class="sample.spring.service.SpringInit</b>">
@@ -452,21 +458,23 @@
for the Web service, allowing it to properly instantiate the Spring
application context. The load-on-startup variable is a must-have so that the
service loads up immediately on startup, creating the Spring application
-context. The WeatherSpringService stays mostly the same to the WeatherService
-previously with a couple additions: The ServiceObjectSupplier provides the
+context. The WeatherSpringService stays similar to the WeatherService
+previously with a couple of additions: The ServiceObjectSupplier provides the
service with the Spring application context, making it "Spring Aware."</p>
<p>Lastly, the SpringBeanName points to the name of the bean associated with
this Web service, which is defined in the applicationContext.xml file
(essentially the WeatherSpringService). We'll cover the
-applicationContext.xml file next. The application context:
-applicationContext.xml file tells the Spring Framework, what beans are
+applicationContext.xml file next. The application context,
+applicationContext.xml file tells the Spring Framework what beans are
defined. For this example, you'll define three of them (see Code Listing
8).</p>
<p><b>Code Listing 8: Defining the application context:
applicationContext.xml</b></p>
-<p><pre><?xml version="1.0" encoding="UTF-8"?>
+
+<p>
+<pre><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
"http://www.springframework.org/dtd/spring-beans.dtd">
@@ -489,30 +497,32 @@
<p>The first one is Axis2's hook into Spring's application context (needed
since AAR deployment is quite different from regular WAR deployment). Next,
-you define the bean pointed to by the services.xml file, the
+you define the bean to which the services.xml file points, which is the
weatherSpringService bean that points to the WeatherSpringService class. It
-has one field property that gets initialized by the Spring Framework,
-weather, which will be set to the weatherBean. The weatherBean is an
+has one field property that gets initialized by the Spring Framework -
+weather. This will be set to the weatherBean. The weatherBean is an
instantiation of the Weather class that holds information on the weather.
Spring will initialize it to the values shown above, and set the Weather
-object in the WeatherSpringService class to this weatherBean instantiation.
-Thus, when you deploy the Web service you won't have to instantiate the
+object in the WeatherSpringService class to the weatherBean instantiation.
+Thus, when you deploy the Web service, you won't have to instantiate the
values because they'll already be set.</p>
<p>Next up is the SpringInit class.</p>
<a name="initializingspring"></a>
-<h3>Initializing the Spring application context: SpringInit</h3>
+<h3>Initializing the Spring Application Context: SpringInit</h3>
<p>Without the Spring application context being initialized quickly, you'll
run into problems. The SpringInit class initializes the Spring application
-context on startup because it is a ServiceLifeCycle class, whose startUp
+context on startup because it is a ServiceLifeCycle class whose startUp
method gets called upon loading the class (and because its load-on-startup
-property is set in the serices.xml file). The only code worth mentioning in
+property is set in the services.xml file). The only code worth mentioning in
this class is shown in Code Listing 9.</p>
<p><b>Code Listing 9: SpringInit's startUp method</b></p>
-<p><pre> public void startUp(ConfigurationContext ignore,
+
+<p>
+<pre> public void startUp(ConfigurationContext ignore,
AxisService service) {
<b>ClassLoader classLoader = service.getClassLoader();
ClassPathXmlApplicationContext appCtx = new
@@ -527,27 +537,28 @@
}
}</pre></p>
-<p>Note that this method retrieves the Spring class loader, creates an
+<p>Note that this method retrieves the Spring class loader, and creates an
application context with applicationContext.xml as the parameters. This new
application context then gets the Spring class loader as its class loader.
The Spring Framework is now up and ready for our WeatherSpringService.</p>
<h3>Build and Deploy Using Apache Axis2 and Tomcat</h3>
-<p>Great, your POJO is now ready for primetime within the Spring Framework.
-Before you build, you'll first need to make sure the axis2-spring-1.1.1.jar and
+<p> Your POJO is now ready for primetime within the Spring Framework. Before
+you build, you'll first need to make sure the axis2-spring-1.1.1.jar and
spring.jar files are in the project's <em>Axis2_HOME/lib</em> directory.</p>
-<p><strong>Note:</strong> The service will not deploy if you add the above jars files to the service archive due to cloass loding issues.</p>
-<p>Now build the source and create an AAR file by typing:
-ant</p>
+<p><strong>Note:</strong> The service will not deploy if you add the above
+.jar files to the service archive due to class loding issues.</p>
+
+<p>Now build the source and create an AAR file by typing: ant</p>
-<p>It'll be created at <em>target/WeatherSpringService.aar</em>. Copy it over
-to <em><tomcat-home>/webapps/axis2/WEB-INF/services</em>, and Axis2
-should deploy it quickly.</p>
+<p>It'll be created at <em>target/WeatherSpringService.aar</em>. Copy it to
+<em><tomcat-home>/webapps/axis2/WEB-INF/services</em>, and Axis2 should
+deploy it quickly.</p>
-<p>Next test the Web service to see if Spring really will initialize the
-weather data for you.</p>
+<p>Next, test the Web service to see whether Spring will really initialize
+the weather data for you.</p>
<a name="testingrpc"></a>
<h3>Testing Using an RPCServiceClient</h3>
@@ -557,26 +568,26 @@
<p>Feel free to browse the code for this client in
src/client/WeatherSpringRPCClient.java. Essentially, this client does the
-exact same thing as the client testing the WeatherService, except this one
-skips the "Setting the weather" task since the weather data should already
-have been set by the Spring framework at startup.</p>
+same thing as the client testing the WeatherService. Except that this one
+skips the "Setting the weather" task since the weather data should have
+already been set by the Spring framework at startup.</p>
<p>Thus, you should get the following as output from the client:</p>
-<pre>run.client:
+<p><pre>run.client:
[javac] Compiling 1 source file to C:\axis2-1.1.1\samples\pojoguidespring\build\cl
asses
<b>[java] Temperature : 89.9
[java] Forecast : Sunny
[java] Rain : false
- [java] How much rain (in inches) : 0.2</b></pre>
+ [java] How much rain (in inches) : 0.2</b></pre></p>
-<p>Which is exactly the values you set them to be in the
-applicationContext.xml file!</p>
+<p>Which are exactly the values you set in the applicationContext.xml
+file!</p>
<a name="summary"></a>
<h2>Summary</h2>
-<p>Apache Axis2 is an excellent way to expose your POJOs as Web services, and
+<p>Apache Axis2 is an excellent way to expose your POJOs as Web services.
Spring adds greater flexibility to your POJOs by adding beans support and
initialization abilities, along with all the other goodies provided by the
Spring framework.</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org