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 th...@apache.org on 2006/11/10 16:45:07 UTC
svn commit: r473372 -
/webservices/axis2/branches/java/1_1/xdocs/1_1/mtom-guide.html
Author: thilina
Date: Fri Nov 10 07:45:07 2006
New Revision: 473372
URL: http://svn.apache.org/viewvc?view=rev&rev=473372
Log:
fixing http://issues.apache.org/jira/browse/AXIS2-892
adding ADB MTOM data binding section to the mtom_guide.. Copied most of the things from the xmlbeans section :)..
Needs bit more work..
Modified:
webservices/axis2/branches/java/1_1/xdocs/1_1/mtom-guide.html
Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/mtom-guide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/mtom-guide.html?view=diff&rev=473372&r1=473371&r2=473372
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/mtom-guide.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/mtom-guide.html Fri Nov 10 07:45:07 2006
@@ -1,16 +1,13 @@
<html>
-
<head>
- <meta http-equiv="content-type" content="">
<title>Handling Binary data with Axis2 (MTOM/SwA)</title>
</head>
<body>
-
<h1>Handling Binary data with Axis2 (MTOM/SwA)</h1>
-<p>This document will describe how to use Axis2 functionality to send/receive binary data
-with SOAP.</p>
+<p>This document will describe how to use Axis2 functionality to send/receive
+binary data with SOAP.</p>
<h2>Content</h2>
<ul>
@@ -19,34 +16,39 @@
<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>
+ <li><a href="#25">MTOM Databinding</a></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="#3">SOAP with Attachments with Axis2</a></li>
- <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><a href="#4">Advanced Topics </a>
<ul>
<li><a href="#41">File Caching for Attachments</a></li>
</ul>
</li>
</ul>
-
<a name="1"></a>
+
<h2>Introduction</h2>
<p>Despite the flexibility, interoperability and global acceptance of XML,
@@ -91,6 +93,7 @@
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
@@ -102,18 +105,18 @@
</blockquote>
</li>
</ol>
-
<a name="11"></a>
+
<h3>Where Does MTOM Come In?</h3>
<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
+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
href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XML Binary Optimized
Packaging (XOP)</a> specification to reference the binary attachments
(external unparsed general entities) of the message. With the use of this
@@ -122,8 +125,9 @@
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>
+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
@@ -133,8 +137,8 @@
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 href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#base64Binary">3.2.16
+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>
@@ -144,9 +148,10 @@
Optimization Mechanism).</strong></p>
<a name="2"></a>
-<h2>MTOM with Axis2</h2>
+<h2>MTOM with Axis2</h2>
<a name="21"></a>
+
<h3>Programming Model</h3>
<p>AXIOM is (and may be the first) Object Model which has the ability to hold
@@ -180,6 +185,7 @@
//create an OMText node with the above DataHandler and set optimized to true
OMText textData = <strong>fac.createOMText(dataHandler, true);</strong>
+
imageElement.addChild(textData);
//User can set optimized to false by using the following
@@ -200,9 +206,9 @@
javax.activation.DataHandler dataHandler = new javax.activation.DataHandler(new FileDataSource("someLocation"));
OMText textData = fac.createOMText(dataHandler, <strong>false</strong>);
image.addChild(textData);</pre>
-</source>
-<a name="22"></a>
+</source><a name="22"></a>
+
<h3>Enabling MTOM Optimization at Client Side</h3>
<p>Set the "enableMTOM" property in the Options to true, when sending
@@ -213,8 +219,9 @@
<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>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>Axis2 serializes all binary content nodes as Base64 encoded strings
regardless of they are qualified to be optimize or not, if,</p>
@@ -226,38 +233,45 @@
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>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>
<a name="23"></a>
+
<h3>Enabling MTOM Optimization at 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>
- <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 Base64 encoded strings. This configuration can be overriden in services.xml for per service and per operation
- basis.</p>
- </blockquote>
+<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
+ Base64 encoded strings. This configuration can be overriden in services.xml
+ for per service and per operation basis.</p>
+</blockquote>
<pre><parameter name="enableMTOM" locked="false">true</parameter></pre>
+
<p>User must restart the server after setting this parameter.</p>
-
<a name="24"></a>
+
<h3>Accessing Received Binary Data (Sample Code)</h3>
<ul>
- <a name="241"></a>
- <li><strong>Service</strong></li>
+ <a name="241"></a>
+ <ul>
+ <li><strong>Service</strong></li>
+ </ul>
+
</ul>
<source><pre>public class MTOMService {
public void uploadFileUsingMTOM(OMElement element) throws Exception {
Iterator itr = element.getChildElements();
folder = (OMElement) itr.next();
- ....
+ ....
images = (OMElement) itr.next();
itr = images.getChildElements();
@@ -275,15 +289,15 @@
... <em>Do whatever you need with the DataHandler</em> ...
}
}
- }
-</pre>
-</source>
+ }</pre>
+</source><ul>
+ <a name="242"></a>
<ul>
- <a name="242"></a>
<li><strong>Client</strong></li>
+
</ul>
-<source><pre>
- ServiceClient sender = new ServiceClient();
+</ul>
+<source><pre> ServiceClient sender = new ServiceClient();
Options options = new Options();
options.setTo(targetEPR);
// enabling MTOM
@@ -298,35 +312,224 @@
DataHandler actualDH;
actualDH = binaryNode.getDataHandler();
.............</pre>
-</source>
+</source><a name="25"></a>
-<a name="25"></a>
<h3>MTOM Databinding</h3>
-<p>When using MTOM, you simply define the binary file as part of your SOAP message as
-type="xsd:base64Binary" or type="xsd:hexBinary". You 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>
-
-<source><pre>
- <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' >
+<p>You can defining 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 bit 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.
+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>
+<source><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' >
<complexType>
<simpleContent>
<extension base="base64Binary" >
+
<attribute ref="xmime:contentType" use="required"/>
</extension>
</simpleContent>
</complexType>
- </element></pre>
+ </element>
+</pre>
</source>
-<p>Lets define a full, validated doc / lit style WSDL that imports the xmime schema, has a service that
- receives a jpeg and returns a pass / fail status to the client:</p>
+<p>You can also use the xmime:base64Binary type to express the above
+mentioned data much more cleanly.</p>
+<source><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' type="xmime:base64Binary"/></pre>
+</source>
+<h3>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>
-<?xml version="1.0" encoding="UTF-8"?>
+<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/">
+ <import namespace="http://www.w3.org/2005/05/xmlmime"
+ schemaLocation="http://www.w3.org/2005/05/xmlmime"/>
+ <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="xmime.xsd" />
+ <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>
+
+<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. We also choose to generate an interface which our Skeleton
+will implement. 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> <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>
+</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>
+
+</source>
+<p>The last step is to create an AAR with our Skeleton and the services.xml, and then deploy the service. See the user guide
+for more info. You can find the completed sample in the Axis2 standard binary distribution under the samples/mtom directory</p>
+
+<h3>Using Xml Beans</h3>
+
+<p>Lets define a full, validated doc / lit style WSDL that imports the xmime
+schema, has a service that receives a jpeg and returns a pass / fail status
+to the client:</p>
+<source><pre><?xml version="1.0" encoding="UTF-8"?>
<definitions name="MyMTOMService" targetNamespace="http://myMtomNS" xmlns:tns="http://myMtomNS" xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns2="http://myMtomNS/types">
@@ -335,6 +538,7 @@
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xmime="http://www.w3.org/2005/05/xmlmime">
<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
+
<import namespace="http://www.w3.org/2005/05/xmlmime"
schemaLocation="http://www.w3.org/2005/05/xmlmime"/>
<complexType name="ReturnWebBase">
@@ -342,80 +546,95 @@
<element name="errorMessage" type="xsd:string"/>
<element name="successErrorCode" type="xsd:int"/>
</sequence>
+
</complexType>
<element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' >
<complexType>
<simpleContent>
<extension base="base64Binary" >
<attribute ref="xmime:contentType" use="required"/>
+
</extension>
</simpleContent>
</complexType>
</element>
<element name="sendData">
<complexType>
+
<sequence>
<element ref='tns:MyBinaryData' minOccurs="1" maxOccurs="1" />
</sequence>
</complexType>
</element>
<element name="sendDataResponse">
+
<complexType>
<sequence>
<element minOccurs="1" maxOccurs="1" name="sendDataResult" type="tns:ReturnWebBase" />
</sequence>
</complexType>
</element>
+
</schema>
</types>
<message name="MyMTOMEndpoint_sendData">
<part name="parameters" element="ns2:sendData"/>
</message>
<message name="MyMTOMEndpoint_sendDataResponse">
+
<part name="result" element="ns2:sendDataResponse"/>
</message>
<portType name="MyMTOMEndpoint">
<operation name="sendData">
<input message="tns:MyMTOMEndpoint_sendData" name="MyMTOMEndpoint_sendData"/>
<output message="tns:MyMTOMEndpoint_sendDataResponse" name="MyMTOMEndpoint_sendDataResponse"/>
+
</operation>
</portType>
<binding name="MyMTOMEndpointBinding" type="tns:MyMTOMEndpoint">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
<operation name="sendData">
<soap:operation soapAction="sendData"/>
+
<input name="MyMTOMEndpoint_sendData">
<soap:body use="literal"/>
</input>
<output name="MyMTOMEndpoint_sendDataResponse">
<soap:body use="literal"/>
</output>
+
</operation>
</binding>
<service name="MyMTOMService">
<port name="MyMTOMEndpointPort" binding="tns:MyMTOMEndpointBinding">
<soap:address location="http://localhost:8080/axis2/services/MyMTOMService"/></port></service></definitions>
+
</pre>
</source>
-<p>The important point here is we import http://www.w3.org/2005/05/xmlmime and define an element, 'MyBinaryData' , 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 XMLBeans as the databinding implementation. We also choose to generate an interface which our
-Skeleton will implement. The name we list for the WSDL above is mtomExample.wsdl, and we define our package name for our generated source files to be
-'org.apache.axis2.samples.mtomDatabinding.endpoint' . Our ant task for this example is:
-</p>
+<p>The important point here is we import http://www.w3.org/2005/05/xmlmime
+and define an element, 'MyBinaryData' , 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 XMLBeans as the databinding
+implementation. We also choose to generate an interface which our Skeleton
+will implement. The name we list for the WSDL above is mtomExample.wsdl, and
+we define our package name for our generated source files to be
+'org.apache.axis2.samples.mtomDatabinding.endpoint' . Our ant task for this
+example is:</p>
<source><pre><target name="wsdl2java" depends="clean,prepare">
<delete dir="output" />
<java classname="org.apache.axis2.wsdl.WSDL2Java" fork="true">
<classpath refid="axis.classpath"/>
<arg value="-d"/>
+
<arg value="xmlbeans"/>
<arg value="-uri"/>
<arg file="wsdl/mtomExample.wsdl"/>
<arg value="-ss"/>
<arg value="-ssi"/>
<arg value="-g"/>
+
<arg value="-sd"/>
<arg value="-o"/>
<arg file="output"/>
@@ -429,13 +648,14 @@
<include name="*schema*/**/*.class"/>
<include name="*schema*/**/*.xsb"/>
</fileset>
+
</move>
</target></pre>
</source>
-<p>Now we are ready to code. Lets edit output/src/org/apache/axis2/samples/mtomDatabinding/endpoint/MyMTOMServiceSkeleton.java
-and fill in the business logic. The end result becomes: </p>
-
+<p>Now we are ready to code. Lets edit
+output/src/org/apache/axis2/samples/mtomDatabinding/endpoint/MyMTOMServiceSkeleton.java
+and fill in the business logic. The end result becomes:</p>
<source><pre>/**
* MyMTOMServiceSkeleton.java
*
@@ -522,10 +742,9 @@
}</pre>
</source>
-
-<p>The code above receives a jpeg file and writes it to disk.
-It returns zero on success and in the case of an error, returns -1 along with a stacktrace. Now lets define the client:</p>
-
+<p>The code above receives a jpeg file and writes it to disk. It returns zero
+on success and in the case of an error, returns -1 along with a stacktrace.
+Now lets define the client:</p>
<source><pre>package client;
import java.io.File;
@@ -584,31 +803,36 @@
}
}
}</pre>
-</source>
-
-<p>The last step is to create an AAR with our Skeleton and the generated interface and services.xml, and then deploy the service. See the user guide for more info. </p>
+</source>
+<p>The last step is to create an AAR with our Skeleton and the generated
+interface and services.xml, and then deploy the service. See the user guide
+for more info.</p>
<a name="3"></a>
-<h2>SOAP with Attachments (SwA) with Axis2</h2>
+<h2>SOAP with Attachments (SwA) with Axis2</h2>
<a name="31"></a>
+
<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 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 message context from whithin a service
-implementation class using the "setOperationContext()" method as shown in the following example.</p>
+<p>Axis2 automatically identifies SwA messages based on the content type.
+Axis2 stores the references to 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
+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>
-<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>
+ <li><strong>Sample service which accesses a received SwA type
+ attachment</strong></li>
</ul>
-<source><pre>
-public class SwA {
+<source><pre>public class SwA {
private OperationContext operationContext;
public SwA() {
@@ -633,33 +857,34 @@
DataHandler dataHandler = attachment.getDataHandler(contentID);
...........
}
-}
-</pre>
-</source>
+}</pre>
+</source><a name="32"></a>
+
+<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>
-<a name="32"></a>
-<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>This can be set using the axis2.xml as follows.</p>
<source><pre>
- <parameter name="enableSwA" locked="false">true</parameter>
-</pre></source>
-
+ <parameter name="enableSwA" locked="false">true</parameter></pre>
+</source>
<p>"enableSwA" can also be set using the client side Options as follows</p>
<source><pre>
- options.setProperty(Constants.Configuration.ENABLE_SwA, Constants.VALUE_TRUE);
-</pre></source>
+ options.setProperty(Constants.Configuration.ENABLE_SwA, Constants.VALUE_TRUE);</pre>
+</source>
+<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>
-<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>
+ <li><strong>Sample client which sends a message with SwA type
+ attachments</strong></li>
</ul>
-<source><pre>
- public void uploadFileUsingSwA(String fileName) throws Exception {
+<source><pre> public void uploadFileUsingSwA(String fileName) throws Exception {
Options options = new Options();
options.setTo(targetEPR);
@@ -680,12 +905,11 @@
mepClient.addMessageContext(mc);
mepClient.execute(true);
- }
-</pre>
-</source>
+ }</pre>
+</source><a name="33"></a>
-<a name="33"></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
@@ -693,7 +917,9 @@
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>
+<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>
@@ -710,6 +936,7 @@
<soapenv:Envelope xmlns:soapenv="...."....>
........
<source href="cid:3936AE19FBED55AE4620B81C73BDD76E" xmlns="/>
+
........
</soapenv:Envelope>
------=_Part_0_1977511.1123163571138
@@ -722,6 +949,7 @@
</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"
@@ -738,6 +966,7 @@
xmlns:xop="http://www.w3.org/2004/08/xop/include">
</xop:Include>
........
+
</soapenv:Envelope>
--MIMEBoundary4A7AE55984E7438034
content-type: application/octet-stream
@@ -746,12 +975,11 @@
<em>Binary Data.....</em>
--MIMEBoundary4A7AE55984E7438034--</pre>
-</source>
+</source><a name="4"></a>
-<a name="4"></a>
<h2>Advanced Topics</h2>
-
<a name="41"></a>
+
<h3>File Caching for Attachments</h3>
<p>Axis2 comes handy with a file caching mechanism for incoming attachments,
@@ -759,35 +987,35 @@
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>
-<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>
+<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>
<p><em>NOTE</em> : It is a must to specify a directory to temporary store the
-attachments. Also care should be taken to <strong>clean that directory</strong> from time to
-time.</p>
+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>
<source><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>
</source>
-<p>Enabling file caching for client side receiving can be done for the by setting the Options as follows.</p>
-<source><pre>
-options.setProperty(Constants.Configuration.CACHE_ATTACHMENTS,Constants.VALUE_TRUE);
+<p>Enabling file caching for client side receiving can be done for the by
+setting the Options as follows.</p>
+<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>
+options.setProperty(Constants.Configuration.FILE_SIZE_THRESHOLD, <em>"4000"</em>);</pre>
+</source></body>
</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org