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 de...@apache.org on 2007/04/27 14:39:46 UTC
svn commit: r533081 [8/23] - in /webservices/axis2/site: ./ 1_2/ 1_2/adb/
1_2/adb/images/ 1_2/images/ 1_2/images/archi-guide/ 1_2/images/userguide/
1_2/jibx/ 1_2/resources/ 1_2/resources/schemas/ 1_2/src/ css/ download/0_9/
download/0_91/ download/0_92...
Added: webservices/axis2/site/1_2/mtom-guide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/mtom-guide.html?view=auto&rev=533081
==============================================================================
--- webservices/axis2/site/1_2/mtom-guide.html (added)
+++ webservices/axis2/site/1_2/mtom-guide.html Fri Apr 27 05:39:33 2007
@@ -0,0 +1,618 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/Java - Handling Binary data with Axis2 (MTOM/SwA)</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-theme.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 April 2007
+ | Doc for 1.2</div><div class="xright">
+
+ <a href="../index.html">Axis2/Java</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Axis2/C</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org" class="externalLink" title="External Link">Apache WS</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://www.apache.org" class="externalLink" title="External Link">Apache </a>
+ </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_Java"><h5>Axis2/Java</h5><ul><li class="none"><a href="../index.html">Home</a></li></ul></div><div id="menuDownloads"><h5>Downloads</h5><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="../modules/index.html">Modules</a></li><li class="none"><a href="../tools/index.html">Tools</a></li></ul></div><div id="menuDocumentation"><h5>Documentation</h5><ul><li class="expanded"><a href="../1_2/contents.html">Version 1.2</a><ul><li class="none"><a href="../1_2/toc.html">Table of Contents</a></li><li class="none"><a href="../1_2/installationguide.html">Installation Guide</a></li><li class="none"><a href="../1_2/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../1_2/userguide.html">User Guide</a></li><li class="none"><a href="../1_2/pojoguide.html">POJO Guide</a></li><li class="none"><a href="../1_2/spring.html">
Spring Guide</a></li><li class="none"><a href="../1_2/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../1_2/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../1_1_1/index.html">Version 1.0</a></li><li class="none"><a href="../1_1/index.html">Version 1.0</a></li><li class="none"><a href="../1_0/index.html">Version 1.0</a></li><li class="none"><a href="../0_95/index.html">Version 0.95</a></li><li class="none"><a href="../0_94/index.html">Version 0.94</a></li><li class="none"><a href="../0_93/index.html">Version 0.93</a></li></ul></div><div id="menuResources"><h5>Resources</h5><ul><li class="none"><a href="../faq.html">FAQ</a></li><li class="none"><a href="../articles.html">Articles</a></li><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="../refLib.html">Reference Library</a></li><li class="none"><a href
="http://ws.apache.org/axis2/1_2/api/index.html" class="externalLink" title="External Link">Online Java Docs</a></li></ul></div><div id="menuGet_Involved"><h5>Get Involved</h5><ul><li class="none"><a href="../overview.html">Overview</a></li><li class="none"><a href="../svn.html">Checkout the Source</a></li><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../siteHowTo.html">Build the Site</a></li></ul></div><div id="menuProject_Information"><h5>Project Information</h5><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li><li class="none"><a href="../thanks.html">Acknowledgements</a></li><li class="none"><a hr
ef="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Handling_Binary_Data_with_Axis2__MTOM_SwA_"></a><h2>Handling Binary Data with Axis2 (MTOM/SwA)</h2><p>This document describes how to use the Axis2 functionality to send/receive
+binary data with SOAP.</p><div class="subsection"><a name="Content"></a><h3>Content</h3><ul>
+ <li><a href="#1">Introduction</a>
+ <ul>
+ <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>
+ </ul>
+ </li>
+ <li><a href="#25">MTOM Databinding</a>
+ <ul>
+ <li><a href="#251">Using ADB</a></li>
+
+ </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="#33">MTOM Backward Compatibility with SwA</a></li>
+ </ul>
+ </li>
+ <li><a href="#4">Advanced Topics </a>
+ <ul>
+ <li><a href="#41">File Caching for Attachments</a></li>
+ </ul>
+ </li>
+</ul><p><a name="1"></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><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 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></br>
+</p><p>Traditionally, two techniques have been used in dealing with opaque data
+in XML;</p><ol>
+ <li><strong>"By value"</strong></li>
+
+ <blockquote>
+ <p>Sending binary data by value is achieved by embedding opaque data (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
+ 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 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>
+ <li><strong>"By reference"</strong>
+
+ <blockquote>
+ <p>Sending binary data by reference is achieved by attaching pure
+ 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 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" class="externalLink" title="External Link">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, 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><p><a name="11"></a></p></div><div class="subsection"><a name="Where_Does_MTOM_Come_In_"></a><h3>Where Does MTOM Come In?</h3><p><a href="http://www.w3.org/TR/2004/PR-soap12-mtom-20041116/" class="externalLink" title="External Link">MTOM (SOAP
+Message Transmission Optimization Mechanism)</a> is another specification
+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/" class="externalLink" title="External Link">XML Binary Optimized
+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 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 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/" class="externalLink" title="External Link">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
+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 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" class="externalLink" title="External Link">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> and <strong>MTOM (SOAP Message Transmission Optimization
+Mechanism).</strong></p><p><a name="2"></a></p></div><div class="subsection"><a name="MTOM_with_Axis2"></a><h3>MTOM with Axis2</h3><p><a name="21"></a></p></div><div class="subsection"><a name="Programming_Model"></a><h3>Programming Model</h3><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 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>
+ <div class="source"><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.DataHandler dataHandler = new javax.activation.DataHandler(new FileDataSource("SomeFile"));
+
+ //create an OMText node with the above DataHandler and set optimized to true
+ OMText textData =
+
+ imageElement.addChild(textData);
+
+ //User can set optimized to false by using the following
+ //textData.doOptimize(false);
+
+</pre></div>
+ <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><p></p>
+ <div class="source"><pre> String base64String = "some_base64_encoded_string";
+ OMText binaryNode =
+
+</pre></div>
+ <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". 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>
+ <div class="source"><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, );
+ image.addChild(textData);
+</pre></div>
+ <p><a name="22"></a></p></div><div class="subsection"><a name="Enabling_MTOM_Optimization_on_the_Client_Side"></a><h3>Enabling MTOM Optimization on the Client Side</h3><p>In Options, set the "enableMTOM" property to True when sending
+messages.</p><p></p>
+ <div class="source"><pre> ServiceClient serviceClient = new ServiceClient ();
+ Options options = new Options();
+ options.setTo(targetEPR);
+
+ serviceClient .setOptions(options);
+
+</pre></div>
+ <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 whether they are qualified to be optimized or not</p><ul>
+ <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" class="externalLink" title="External Link">3. XOP
+ Infosets Constructs </a>).</li>
+</ul><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><p><a name="23"></a></p></div><div class="subsection"><a name="Enabling_MTOM_Optimization_on_the_Server_Side"></a><h3>Enabling MTOM Optimization on the Server Side</h3><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 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
+ on the basis of per service and per operation.</p>
+</blockquote>
+ <div class="source"><pre><parameter name="enableMTOM" locked="false">true</parameter>
+
+</pre></div>
+ <p>You must restart the server after setting this parameter.</p><p><a name="24"></a></p></div><div class="subsection"><a name="Accessing_Received_Binary_Data__Sample_Code_"></a><h3>Accessing Received Binary Data (Sample Code)</h3><p><a name="241"></a><ul>
+ <li><strong>Service</strong></li>
+</ul></p><p></p>
+ <div class="source"><pre>public class MTOMService {
+ public void uploadFileUsingMTOM(OMElement element) throws Exception {
+
+
+
+ ... ...
+ }
+ }
+</pre></div>
+ <p><a name="242"></a><ul>
+ <li><strong>Client</strong></li>
+</ul></p><p></p>
+ <div class="source"><pre> ServiceClient sender = new ServiceClient();
+ Options options = new Options();
+ options.setTo(targetEPR);
+ // enabling MTOM
+
+ ............
+
+ OMElement result = sender.sendReceive(payload);
+ OMElement ele = result.getFirstElement();
+ OMText binaryNode = (OMText) ele.getFirstOMChild();
+
+ // Retrieving the DataHandler & then do whatever the processing to the data
+ DataHandler actualDH;
+ actualDH = binaryNode.getDataHandler();
+ .............
+</pre></div>
+ <p><a name="25"></a></p></div><div class="subsection"><a name="MTOM_Databinding"></a><h3>MTOM Databinding</h3><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><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 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>
+ <div class="source"><pre><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' >
+ <complexType>
+ <simpleContent>
+ <extension base="base64Binary" >
+
+ <attribute ref="xmime:contentType" use="required"/>
+ </extension>
+ </simpleContent>
+ </complexType>
+ </element></pre>
+</pre></div>
+ <p>You can also use the xmime:base64Binary type to express the above
+mentioned data much clearly.</p>
+ <div class="source"><pre><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' type="xmime:base64Binary"/></pre>
+</pre></div>
+ <p><a name="251"></a></p></div><div class="subsection"><a name="MTOM_Databinding_Using_ADB"></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>
+ <div class="source"><pre><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>
+</pre></div>
+ <p>The important point here is we import http://www.w3.org/2005/05/xmlmime
+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
+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>
+ <div class="source"><pre><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>
+</pre></div>
+ <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>
+ <div class="source"><pre><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>
+</pre></div>
+ <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>
+ <div class="source"><pre><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>
+</pre></div>
+ <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><p><a name="252"></a><a name="3"></a></p></div><div class="subsection"><a name="SOAP_with_Attachments__SwA__with_Axis2"></a><h3>SOAP with Attachments (SwA) with Axis2</h3><p><a name="31"></a></p></div><div class="subsection"><a name="Receiving_SwA_Type_Attachments"></a><h3>Receiving SwA Type Attachments</h3><p>Axis2 automatically identifies SwA messages based on the content type.
+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 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>
+</ul>
+ <div class="source"><pre><pre>public class SwA {
+ public SwA() {
+ }
+
+ public void uploadAttachment(OMElement omEle) throws AxisFault {
+ OMElement child = (OMElement) omEle.getFirstOMChild();
+ OMAttribute attr = child.getAttribute(new QName("href"));
+
+ //Content ID processing
+ String contentID = attr.getAttributeValue();
+ contentID = contentID.trim();
+ if (contentID.substring(0, 3).equalsIgnoreCase("cid")) {
+ contentID = contentID.substring(4);
+ }
+
+ MessageContext msgCtx = MessageContext.getCurrentMessageContext();
+ Attachments attachment = msgCtx.getAttachmentMap();
+ DataHandler dataHandler = attachment.getDataHandler(contentID);
+ ...........
+ }
+}</pre>
+</pre></div>
+ <p><a name="32"></a></p></div><div class="subsection"><a name="Sending_SwA_Type_Attachments"></a><h3>Sending SwA Type Attachments</h3><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>
+ <div class="source"><pre><pre>
+ <parameter name="enableSwA" locked="false">true</parameter></pre>
+</pre></div>
+ <p>"enableSwA" can also be set using the client side Options as follows</p>
+ <div class="source"><pre><pre>
+ options.setProperty(Constants.Configuration.ENABLE_SwA, Constants.VALUE_TRUE);</pre>
+</pre></div>
+ <p>Users are expected to use the attachment API provided in the
+MessageContext to specify the binary attachments needed to be attached to the
+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>
+</ul>
+ <div class="source"><pre><pre> public void uploadFileUsingSwA(String fileName) throws Exception {
+
+ Options options = new Options();
+ options.setTo(targetEPR);
+ options.setProperty(Constants.Configuration.ENABLE_SWA, Constants.VALUE_TRUE);
+ options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
+ options.setSoapVersionURI(SOAP11Constants.SOAP_ENVELOPE_NAMESPACE_URI);
+ options.setTo(targetEPR);
+
+ ServiceClient sender = new ServiceClient(null,null);
+ sender.setOptions(options);
+ OperationClient mepClient = sender.createClient(ServiceClient.ANON_OUT_IN_OP);
+
+ MessageContext mc = new MessageContext();
+ mc.setEnvelope(createEnvelope());
+ FileDataSource fileDataSource = new FileDataSource("test-resources/mtom/test.jpg");
+ DataHandler dataHandler = new DataHandler(fileDataSource);
+ mc.addAttachment("FirstAttachment",dataHandler);
+
+ mepClient.addMessageContext(mc);
+ mepClient.execute(true);
+ }</pre>
+</pre></div>
+ <p><a name="33"></a></p></div><div class="subsection"><a name="MTOM_Backward_Compatibility_with_SwA"></a><h3>MTOM Backward Compatibility with SwA</h3><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 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>
+ <div class="source"><pre><pre>Content-Type: multipart/related; type="text/xml";
+ start="<9D645C8EBB837CE54ABD027A3659535D>";
+ boundary="----=_Part_0_1977511.1123163571138"
+
+------=_Part_0_1977511.1123163571138
+Content-Type: text/xml; charset=UTF-8
+Content-Transfer-Encoding: binary
+Content-Id: <9D645C8EBB837CE54ABD027A3659535D>
+
+<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="...."....>
+ ........
+ <source href="cid:3936AE19FBED55AE4620B81C73BDD76E" xmlns="/>
+
+ ........
+</soapenv:Envelope>
+------=_Part_0_1977511.1123163571138
+Content-Type: text/plain
+Content-Transfer-Encoding: binary
+Content-Id: <3936AE19FBED55AE4620B81C73BDD76E>
+
+<em>Binary Data.....</em>
+------=_Part_0_1977511.1123163571138--</pre>
+</pre></div>
+ <ul>
+ <li><strong>Corresponding MTOM message from Axis2</strong></li>
+</ul>
+ <div class="source"><pre><pre>Content-Type: multipart/related; boundary=MIMEBoundary4A7AE55984E7438034;
+ type="application/xop+xml"; start="<0.09BC7F4BE2E4D3EF1B@apache.org>";
+ start-info="text/xml; charset=utf-8"
+
+--MIMEBoundary4A7AE55984E7438034
+content-type: application/xop+xml; charset=utf-8; type="application/soap+xml;"
+content-transfer-encoding: binary
+content-id: <0.09BC7F4BE2E4D3EF1B@apache.org>
+
+<?xml version='1.0' encoding='utf-8'?>
+<soapenv:Envelope xmlns:soapenv="...."....>
+ ........
+ <xop:Include href="cid:1.A91D6D2E3D7AC4D580@apache.org"
+ xmlns:xop="http://www.w3.org/2004/08/xop/include">
+ </xop:Include>
+ ........
+
+</soapenv:Envelope>
+--MIMEBoundary4A7AE55984E7438034
+content-type: application/octet-stream
+content-transfer-encoding: binary
+content-id: <1.A91D6D2E3D7AC4D580@apache.org>
+
+<em>Binary Data.....</em>
+--MIMEBoundary4A7AE55984E7438034--</pre>
+</pre></div>
+ <p><a name="4"></a></p></div><div class="subsection"><a name="Advanced_Topics"></a><h3>Advanced Topics</h3><p><a name="41"></a></p></div><div class="subsection"><a name="File_Caching_for_Attachments"></a><h3>File Caching for Attachments</h3><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 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).
+When this threshold value is specified, only the attachments whose size is
+bigger than the threshold value will get cached in the files. Smaller
+attachments will remain in the memory.</p><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><p>The following parameters need to be set in Axis2.xml in order to enable
+file caching.</p>
+ <div class="source"><pre><pre><axisconfig name="AxisJava2.0">
+
+ <!-- ================================================= -->
+ <!-- Parameters -->
+ <!-- ================================================= -->
+ <parameter name="cacheAttachments" locked="false">true</parameter>
+ <parameter name="attachmentDIR" locked="false"><em>temp directory</em></parameter>
+
+ <parameter name="sizeThreshold" locked="false"><em>4000</em></parameter>
+ .........
+ .........
+</axisconfig></pre>
+</pre></div>
+ <p>Enabling file caching for client side receiving can be done for the by
+setting the Options as follows.</p>
+ <div class="source"><pre><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>
+</pre></div>
+ </div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/1_2/pojoguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/pojoguide.html?view=auto&rev=533081
==============================================================================
--- webservices/axis2/site/1_2/pojoguide.html (added)
+++ webservices/axis2/site/1_2/pojoguide.html Fri Apr 27 05:39:33 2007
@@ -0,0 +1,459 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/Java - POJO Web Services using Axis2</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-theme.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 April 2007
+ | Doc for 1.2</div><div class="xright">
+
+ <a href="../index.html">Axis2/Java</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Axis2/C</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org" class="externalLink" title="External Link">Apache WS</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://www.apache.org" class="externalLink" title="External Link">Apache </a>
+ </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_Java"><h5>Axis2/Java</h5><ul><li class="none"><a href="../index.html">Home</a></li></ul></div><div id="menuDownloads"><h5>Downloads</h5><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="../modules/index.html">Modules</a></li><li class="none"><a href="../tools/index.html">Tools</a></li></ul></div><div id="menuDocumentation"><h5>Documentation</h5><ul><li class="expanded"><a href="../1_2/contents.html">Version 1.2</a><ul><li class="none"><a href="../1_2/toc.html">Table of Contents</a></li><li class="none"><a href="../1_2/installationguide.html">Installation Guide</a></li><li class="none"><a href="../1_2/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../1_2/userguide.html">User Guide</a></li><li class="none"><a href="../1_2/pojoguide.html">POJO Guide</a></li><li class="none"><a href="../1_2/spring.html">
Spring Guide</a></li><li class="none"><a href="../1_2/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../1_2/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../1_1_1/index.html">Version 1.0</a></li><li class="none"><a href="../1_1/index.html">Version 1.0</a></li><li class="none"><a href="../1_0/index.html">Version 1.0</a></li><li class="none"><a href="../0_95/index.html">Version 0.95</a></li><li class="none"><a href="../0_94/index.html">Version 0.94</a></li><li class="none"><a href="../0_93/index.html">Version 0.93</a></li></ul></div><div id="menuResources"><h5>Resources</h5><ul><li class="none"><a href="../faq.html">FAQ</a></li><li class="none"><a href="../articles.html">Articles</a></li><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="../refLib.html">Reference Library</a></li><li class="none"><a href
="http://ws.apache.org/axis2/1_2/api/index.html" class="externalLink" title="External Link">Online Java Docs</a></li></ul></div><div id="menuGet_Involved"><h5>Get Involved</h5><ul><li class="none"><a href="../overview.html">Overview</a></li><li class="none"><a href="../svn.html">Checkout the Source</a></li><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../siteHowTo.html">Build the Site</a></li></ul></div><div id="menuProject_Information"><h5>Project Information</h5><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li><li class="none"><a href="../thanks.html">Acknowledgements</a></li><li class="none"><a hr
ef="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="POJO_Web_Services_using_Apache_Axis2"></a><h2>POJO Web Services using Apache Axis2</h2><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, 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><div class="subsection"><a name="Content"></a><h3>Content</h3><ul>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#pojo">The POJO</a></li>
+ <li><a href="#pojows">POJO Web service using Apache Axis2 and Tomcat</a>
+ <ul>
+ <li><a href="#definingservice">Defining the Service:
+ services.xml</a></li>
+ </ul>
+ </li>
+ <li><a href="#buildpojows">Building the POJO Web Service Using Ant</a></li>
+ <li><a href="#testingpojows">Testing the POJO Web Service Using
+ RPCServiceClient</a>
+ <ul>
+ <li><a href="#limitationspojo">Limitations and Strengths of
+ POJO</a></li>
+ </ul>
+ </li>
+ <li><a href="#springpojows">Spring-based POJO Web Service</a>
+ <ul>
+ <li><a href="#quickintro">Quick Introduction</a></li>
+ <li><a href="#servicedef">The Service Definition: services.xml</a></li>
+ <li><a href="#initializingspring">Initializing the Spring application
+ context: SpringInit</a></li>
+ <li><a href="#testingrpc">Testing Using an RPCServiceClient</a></li>
+ </ul>
+ </li>
+ <li><a href="#summary">Summary</a></li>
+ <li><a href="#furtherstudy">For Further Study</a></li>
+</ul><p><a name="introduction"></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><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 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
+ document</li>
+ <li>POJO deployment</li>
+ <li>Test the POJO Web service using an RPC based client</li>
+ <li>Limitations of straight POJO</li>
+ <li>Spring-based POJO Web service and deployment</li>
+</ul><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_2/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><p><a name="pojo"></a></p></div><div class="subsection"><a name="The_POJO"></a><h3>The POJO</h3><p>The POJO you'll be using throughout this document is a Weather service
+POJO that consists of two classes: WeatherService and Weather. Weather
+contains the Weather data: Temperature, forecast, rain (will it rain?), and
+howMuchRain (See Code Listing 1).</p><p><b>Code Listing 1: The Weather POJO</b></p>
+ <div class="source"><pre>package sample.pojo.data;
+
+public class Weather{
+ float temperature;
+ String forecast;
+ boolean rain;
+ float howMuchRain;
+
+ public void setTemperature(float temp){
+ temperature = temp;
+ }
+
+ public float getTemperature(){
+ return temperature;
+ }
+
+ public void setForecast(String fore){
+ forecast = fore;
+ }
+
+ public String getForecast(){
+ return forecast;
+ }
+
+ public void setRain(boolean r){
+ rain = r;
+ }
+
+ public boolean getRain(){
+ return rain;
+ }
+
+ public void setHowMuchRain(float howMuch){
+ howMuchRain = howMuch;
+ }
+
+ public float getHowMuchRain(){
+ return howMuchRain;
+ }
+}
+
+</pre></div>
+ <p>And here's the WeatherService class, shown in Code Listing 2.</p><p><b>Code Listing 2: The WeatherService class</b></p>
+ <div class="source"><pre>package sample.pojo.service;
+
+import sample.pojo.data.Weather;
+
+public class WeatherService{
+ Weather weather;
+
+ public void setWeather(Weather weather){
+ this.weather = weather;
+ }
+
+ public Weather getWeather(){
+ return this.weather;
+ }
+}
+
+</pre></div>
+ <p>Note that it's all just straight POJOs with field items and
+<code>getter</code> and <code>setter</code> methods for each field. Next,
+you'll take a look at what you need to do to make it ready for deployment on
+Apache Axis2 and Tomcat.</p><p><a name="pojows"></a></p></div><div class="subsection"><a name="POJO_Web_Service_Using_Apache_Axis2_and_Tomcat"></a><h3>POJO Web Service Using Apache Axis2 and Tomcat</h3><p>Got the POJOs? Great. This section will show you how to package them in
+the exploded directory format for easy deployment. First you'll look at the
+services.xml file that defines the Web service, and then you'll build the
+files using <a href="http://ant.apache.org/" class="externalLink" title="External Link">Apache Ant</a>, and deploy the
+Web service on Tomcat.</p><p><a name="definingservice"></a></p></div><div class="subsection"><a name="Defining_the_Service:_services_xml"></a><h3>Defining the Service: services.xml</h3><p>Before Axis2 can understand what is going on, you have to tell it to use
+the services.xml file. Let's get right into it (see Code Listing 3).</p><p><b>Code Listing 3: The service definition file: services.xml</b></p>
+ <div class="source"><pre><service name="WeatherService" scope="application">
+ <description>
+ Weather POJO Service
+ </description>
+ <messageReceivers>
+ <messageReceiver
+ mep="http://www.w3.org/2004/08/wsdl/in-only"
+ class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
+ <messageReceiver
+ mep="http://www.w3.org/2004/08/wsdl/in-out"
+ class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
+ </messageReceivers>
+ <parameter name="ServiceClass">
+ sample.pojo.service.WeatherService
+ </parameter>
+</service>
+
+</pre></div>
+ <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: 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 let usl
+take a look at an easy method of building your application using Ant.</p><p><a name="buildpojows"></a></p></div><div class="subsection"><a name="Building_the_POJO_Web_Service_Using_Apache_Ant"></a><h3>Building the POJO Web Service Using Apache Ant</h3><p><a href="http://ant.apache.org/" class="externalLink" title="External Link">Ant</a> is a slick build tool. It helps
+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 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, you'll need to download the Axis2
+1.2-bin and 1.2-war distributions from <a href="../../download/1_2/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.2 Standard Binary (bin) Distribution) :</p>
+ <div class="source"><pre><property name="axis2.home" value="c:\apps\axis2" />
+
+</pre></div>
+ <p>This modification contains the path to the root of the unzipped Axis2
+1.2-bin <a href="../../download/1_2/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>
+ <div class="source"><pre> - WeatherService
+ - META-INF
+ - services.xml
+ - sample
+ - pojo
+ - data
+ - Weather.class
+ - service
+ - WeatherService.class
+
+</pre></div>
+ <p>Simple isn't it? An excellent way to dive into Web services
+development.</p><p>Now get a <a href="http://tomcat.apache.org/" class="externalLink" title="External Link">Tomcat</a> distribution (I
+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.2-war by
+copying the axis2.war file to Tomcat's webapps directory. Tomcat will proceed
+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 deploy quickly. You willl test the Web service using
+the RPCServiceClient in the next section.</p><p><a name="testingpojows"></a></p></div><div class="subsection"><a name="Testing_the_POJO_Web_Service_Using_RPCServiceClient"></a><h3>Testing the POJO Web Service Using RPCServiceClient</h3><p>OK, so the Web service should be running on Tomcat. Now you'll build a
+simple RPCServiceClient and test the POJO Web service. You'll first start out
+with the class constructs, creating the RPCServiceClient and initializing the
+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;
+
+import org.apache.axis2.AxisFault;
+import org.apache.axis2.addressing.EndpointReference;
+import org.apache.axis2.client.Options;
+import org.apache.axis2.rpc.client.RPCServiceClient;
+
+import sample.pojo.data.Weather;
+
+
+public class WeatherRPCClient {
+
+ public static void main(String[] args1) throws AxisFault {
+
+ RPCServiceClient serviceClient = new RPCServiceClient();
+
+ Options options = serviceClient.getOptions();
+
+ EndpointReference targetEPR = new EndpointReference(
+ <b>"http://localhost:8080/axis2/services/WeatherService");</b>
+ options.setTo(targetEPR);
+
+ // Setting the weather
+ QName opSetWeather =
+ new QName("http://service.pojo.sample/xsd", "<b>setWeather");
+
+ Weather w = new Weather();
+
+ w.setTemperature((float)39.3);
+ w.setForecast("Cloudy with showers");
+ w.setRain(true);
+ w.setHowMuchRain((float)4.5);
+
+ Object[] opSetWeatherArgs = new Object[] { w };
+
+ serviceClient.invokeRobust(opSetWeather, opSetWeatherArgs);</b>
+...</pre></p><p>The most interesting code to note is in bold font. Notice the targetEPR
+variable you create, setting the endpoint reference to
+http://localhost:8080/axis2/services/WeatherService. This is where you
+deployed it on Axis2. You can also verify this by asking Axis2 to list its
+services by going to the following URL:
+http://localhost:8080/axis2/services/listServices.</p><p>Next the opSetWeather variable gets setup, pointing to the setWeather
+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>...
+ serviceClient.invokeRobust(opSetWeather, opSetWeatherArgs);
+
+ // Getting the weather
+ QName opGetWeather =
+ new QName("http://service.pojo.sample/xsd", "<b>getWeather");
+
+ Object[] opGetWeatherArgs = new Object[] { };
+ Class[] returnTypes = new Class[] { Weather.class };
+
+ Object[] response = serviceClient.invokeBlocking(opGetWeather,
+ opGetWeatherArgs, returnTypes);
+
+ Weather result = (Weather) response[0];
+
+ if (result == null) {
+ System.out.println("Weather didn't initialize!");
+ return;
+ }</b>
+...</pre></p><p>First you set the operation in opGetWeather to getWeather. Then you create
+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>...
+ return;
+ }
+
+ // Displaying the result
+ <b>System.out.println("Temperature : " +
+ result.getTemperature());
+ System.out.println("Forecast : " +
+ result.getForecast());
+ System.out.println("Rain : " +
+ result.getRain());
+ System.out.println("How much rain (in inches) : " +
+ result.getHowMuchRain());
+
+ }</b>
+}</pre></p><p>You should receive the data shown in Code Listing 7.</p><p><b>Code Listing 7: Output from running the client</b></p>
+ <div class="source"><pre>rpc.client.run:
+ [java] Temperature : 39.3
+ [java] Forecast : Cloudy with showers
+ [java] Rain : true
+ [java] How much rain (in inches) : 4.5
+
+</pre></div>
+ <p>Excellent! You have a working POJO Web service! Next you'll quickly morph
+this one into a Spring based POJO.</p><p><a name="limitationspojo"></a></p></div><div class="subsection"><a name="Limitations_and_Strengths_of_POJO"></a><h3>Limitations and Strengths of POJO</h3><p>We've covered the strengths of using POJO based Web services, but what
+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). However, you'll soon see how to overcome that limitation with a
+Spring based POJO, which is covered next.</p><p><a name="springpojows"></a></p></div><div class="subsection"><a name="Spring-based_POJO_Web_Service"></a><h3>Spring-based POJO Web Service</h3><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><p><a name="quickintro"></a></p></div><div class="subsection"><a name="Quick_Introduction"></a><h3>Quick Introduction</h3><p>If you take a look at the source code of this document in
+Axis2_HOME/samples/pojoguidespring (to see how the Spring based POJO Web
+service is coded), you can see that the Weather class didn't change at all
+and the WeatherService class only got its name changed to
+WeatherSpringService.</p><p>You'll also notice an applicationContext.xml file, which we'll cover
+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 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
+Inversion of Control (IoC), which is covered next.</p><p><a name="servicedef"></a></p></div><div class="subsection"><a name="The_Service_Definition:_services_xml"></a><h3>The Service Definition: services.xml</h3><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>">
+ <description>
+ This web service initializes Spring.
+ </description>
+ <b><parameter name="ServiceClass">
+ sample.spring.service.SpringInit
+ </parameter>
+ <parameter name="ServiceTCCL">composite</parameter>
+ <parameter name="load-on-startup">true</parameter></b>
+ <operation name="springInit">
+ <messageReceiver
+ class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ </service>
+ <service <b>name="WeatherSpringService</b>">
+ <description>
+ Weather Spring POJO Axis2 AAR deployment
+ </description>
+ <b><parameter name="ServiceClass">
+ sample.spring.service.WeatherSpringService
+ </parameter>
+ <parameter name="ServiceObjectSupplier">
+org.apache.axis2.extensions.spring.receivers.SpringAppContextAwareObjectSupplier
+ </parameter>
+ <parameter name="SpringBeanName">
+ weatherSpringService
+ </parameter></b>
+ <messageReceivers>
+ <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"
+ class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
+ <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
+ class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
+ </messageReceivers>
+ </service>
+</serviceGroup></pre></p><p>You'll see a few familiar items in the above listing, and several changes.
+Once again, the items in bold are most important. The ServiceTCCL property
+under the SpringInit service makes sure that the Spring class loader is used
+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 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
+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"?>
+<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
+"http://www.springframework.org/dtd/spring-beans.dtd">
+
+<beans>
+ <bean id="<b>applicationContext</b>" class=
+"org.apache.axis2.extensions.spring.receivers.ApplicationContextHolder" />
+
+ <b><bean id="weatherSpringService"
+ class="sample.spring.service.WeatherSpringService">
+ <property name="weather" ref="weatherBean"/>
+ </bean>
+
+ <bean id="weatherBean" class="sample.spring.bean.Weather">
+ <property name="temperature" value="89.9"/>
+ <property name="forecast" value="Sunny"/>
+ <property name="rain" value="false"/>
+ <property name="howMuchRain" value="0.2"/>
+ </bean></b>
+</beans></pre></p><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 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. 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 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><p><a name="initializingspring"></a></p></div><div class="subsection"><a name="Initializing_the_Spring_Application_Context:_SpringInit"></a><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
+method gets called upon loading the class (and because its load-on-startup
+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,
+ AxisService service) {
+ <b>ClassLoader classLoader = service.getClassLoader();
+ ClassPathXmlApplicationContext appCtx = new
+ ClassPathXmlApplicationContext</b>(new String[]
+ {"<b>applicationContext.xml</b>"},
+ false);
+ <b>appCtx.setClassLoader(classLoader);
+ appCtx.refresh();</b>
+ if (logger.isDebugEnabled()) {
+ logger.debug("\n\nstartUp() set spring classloader " +
+ "via axisService.getClassLoader() ... ");
+ }
+ }</pre></p><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></div><div class="subsection"><a name="Build_and_Deploy_Using_Apache_Axis2_and_Tomcat"></a><h3>Build and Deploy Using Apache Axis2 and Tomcat</h3><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.2.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
+.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 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 whether Spring will really initialize
+the weather data for you.</p><p><a name="testingrpc"></a></p></div><div class="subsection"><a name="Testing_Using_an_RPCServiceClient"></a><h3>Testing Using an RPCServiceClient</h3><p>It's as simple as it was for the other Web service, except this time type:
+ant rpc.client</p><p>Feel free to browse the code for this client in
+src/client/WeatherSpringRPCClient.java. Essentially, this client does the
+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><p><pre>run.client:
+ [javac] Compiling 1 source file to C:\axis2-1.2\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></p><p>Which are exactly the values you set in the applicationContext.xml
+file!</p><p><a name="summary"></a></p></div><div class="subsection"><a name="Summary"></a><h3>Summary</h3><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><p><a name="furtherstudy"></a></p></div><div class="subsection"><a name="For_Further_Study"></a><h3>For Further Study</h3><p>Apache Axis2-<a href="http://ws.apache.org/axis2/" class="externalLink" title="External Link">http://ws.apache.org/axis2/</a></p><p>Axis2 Architecture-<a href="http://ws.apache.org/axis2/1_0/Axis2ArchitectureGuide.html" class="externalLink" title="External Link">http://ws.apache.org/axis2/1_0/Axis2ArchitectureGuide.html</a></p><p>Introduction to Apache Axis2-<a href="http://www.redhat.com/magazine/021jul06/features/apache_axis2/" class="externalLink" title="External Link">http://www.redhat.com/magazine/021jul06/features/apache_axis2/</a></p><p>Working With Apache Axis2-<a href="http://www.wso2.net/articles/axis2/java/2006/09/13/working-with-axis2" class="externalLink" title="External Link">http://www.wso2.net/articles/axis2/java/2006/09/13/working-with-axis2</a></p><p>Apache Tomcat-<a href="http://tomcat.apache.org/" class="externa
lLink" title="External Link">http://tomcat.apache.org</a></p><p>Spring Framework-<a href="http://www.springframework.org/" class="externalLink" title="External Link">http://www.springframework.org/</a></p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org