You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2007/04/19 09:05:36 UTC
svn commit: r530290 - /webservices/axis2/site/1_1_1/mtom-guide.html
Author: chatra
Date: Thu Apr 19 00:05:36 2007
New Revision: 530290
URL: http://svn.apache.org/viewvc?view=rev&rev=530290
Log:
correcting issue in https://issues.apache.org/jira/browse/AXIS2-2136
Modified:
webservices/axis2/site/1_1_1/mtom-guide.html
Modified: webservices/axis2/site/1_1_1/mtom-guide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_1_1/mtom-guide.html?view=diff&rev=530290&r1=530289&r2=530290
==============================================================================
--- webservices/axis2/site/1_1_1/mtom-guide.html (original)
+++ webservices/axis2/site/1_1_1/mtom-guide.html Thu Apr 19 00:05:36 2007
@@ -1,47 +1,166 @@
-<!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">
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!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: 12 January 2007
- | Doc for 1.1.1</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_1_1/contents.html">Version 1.1.1</a><ul><li class="none"><a href="../1_1_1/toc.html">Table of Contents</a></li><li class="none"><a href="../1_1_1/installationguide.html">Installation Guide</a></li><li class="none"><a href="../1_1_1/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../1_1_1/userguide.html">User Guide</a></li><li class="none"><a href="../1_1_1/pojoguide.html">POJO Guide</a></li><li class="none"><a href="../1_1
_1/spring.html">Spring Guide</a></li><li class="none"><a href="../1_1_1/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../1_1_1/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../1_1/contents.html">Version 1.1</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_1_1/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 href="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 will describe how to use Axis2 functionality to send/receive
-binary data with SOAP.</p><div class="subsection"><a name="Content"></a><h3>Content</h3><ul>
+ @import url("../style/maven-theme.css");</style>
+ <link rel="stylesheet" href="../style/print.css" type="text/css"
+ media="print" />
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+</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" /></a><a
+href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2"
+src="http://ws.apache.org/axis2/images/axis.jpg" /></a>
+
+<div class="clear">
+<hr />
+</div>
+</div>
+
+<div id="breadcrumbs">
+
+<div class="xleft">
+Last published: 12 January 2007 | Doc for 1.1.1</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 />
+</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_1_1/contents.html">Version 1.1.1</a>
+ <ul>
+ <li class="none"><a href="../1_1_1/toc.html">Table of Contents</a></li>
+ <li class="none"><a href="../1_1_1/installationguide.html">Installation
+ Guide</a></li>
+ <li class="none"><a href="../1_1_1/quickstartguide.html">QuickStart
+ Guide</a></li>
+ <li class="none"><a href="../1_1_1/userguide.html">User Guide</a></li>
+ <li class="none"><a href="../1_1_1/pojoguide.html">POJO Guide</a></li>
+ <li class="none"><a href="../1_1_1/spring.html">Spring Guide</a></li>
+ <li class="none"><a href="../1_1_1/webadminguide.html">Web
+ Administrator's Guide</a></li>
+ <li class="none"><a href="../1_1_1/migration.html">Migration Guide
+ (from Axis1)</a></li>
+ </ul>
+ </li>
+ <li class="none"><a href="../1_1/contents.html">Version 1.1</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_1_1/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 href="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" /></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 will describe how to use 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>
+ <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>
-
+ <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>
@@ -50,11 +169,9 @@
<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>
@@ -62,20 +179,32 @@
<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>
+ <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,
+</ul>
+
+<p><a name="1" id="_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 need to transmit binary attachments of various sorts like
images, drawings, xml docs, etc together with SOAP message. Such data are
-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>
+often in a particular binary format.<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>
@@ -99,63 +228,100 @@
<blockquote>
<p>Sending binary data by reference is achieved by attaching pure
binary data as external unparsed general entities outside of the XML
- document and then embedding reference URI's to those entities as
+ document and then embedding reference URI's to those entities as
elements or attribute values. This prevents the unnecessary bloating of
data and wasting of processing power. The primary obstacle for using
these unparsed entities is their heavy reliance on DTDs, which impedes
modularity as well as use of XML namespaces.</p>
<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, creating two data models. This scenario
- is like sending attachments with an e-mail message. Even though those
+ 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, creating two data models. This scenario is like
+ sending attachments with an e-mail message. Even though those
attachments are related to the message content they are not inside the
- message. This causes the technologies for processing and description
- of data based on XML component of the data, to malfunction. One example
- is WS-Security.</p>
+ message. This causes the technologies for processing and description of
+ data based on XML component of the data, to malfunction. One example is
+ WS-Security.</p>
</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
-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 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 become inline (by
-value) with the SOAP document even though actually it is attached separately.
-This merges the two realms by making it possible to work only with one data
-model. This allows the applications to process and describe by only looking
-at XML part making reliance on DTDs obsolete. On a lighter note, MTOM has
-standardized the referencing mechanism of SwA. The following is an extract
-from the <a href="http://www.w3.org/TR/2004/PR-xop10-20041116/" class="externalLink" title="External Link">XOP</a>
+</ol>
+
+<p><a name="11" id="_11"></a></p>
+</div>
+
+<div class="subsection">
+<a name="Where_Does_MTOM_Come_In_"></a>
-specification.</p><p><em>At the conceptual level, this binary data can be thought of as being
+<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 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
+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 become inline (by value) with the SOAP document even though
+actually it is attached separately. This merges the two realms by making it
+possible to work only with one data model. This allows the applications to
+process and describe by only looking at XML part making reliance on DTDs
+obsolete. On a lighter note, MTOM has standardized the referencing mechanism
+of SwA. The following is an extract from the <a
+href="http://www.w3.org/TR/2004/PR-xop10-20041116/" 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 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
+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> & <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 which has the ability to hold
+Optimization Mechanism).</strong></p>
+
+<p><a name="2" id="_2"></a></p>
+</div>
+
+<div class="subsection">
+<a name="MTOM_with_Axis2"></a>
+
+<h3>MTOM with Axis2</h3>
+
+<p><a name="21" id="_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 which has the ability to hold
binary data. It has been given this ability by allowing OMText to hold raw
binary content in the form of javax.activation.DataHandler. OMText has been
chosen for this purpose with two reasons. One is that XOP (MTOM) is capable
of optimizing only base64-encoded Infoset data that is in the canonical
lexical form of XML Schema base64Binary datatype. Other one is to preserve
the infoset in both sender and receiver (To store the binary content in the
-same kind of object regardless of whether it is optimized or not).</p><p>MTOM allows to selectively encode portions of the message, which allows us
+same kind of object regardless of whether it is optimized or not).</p>
+
+<p>MTOM allows to selectively encode portions of the message, which allows us
to send base64encoded data as well as externally attached raw binary data
referenced by "XOP" element (optimized content) to be send in a SOAP message.
User can specify whether an OMText node which contains raw binary data or
@@ -164,13 +330,14 @@
MTOM a user is advised to send smaller binary attachments using
base64encoding (None optimized) and larger attachments as optimized
content.</p>
- <div class="source"><pre><pre> OMElement imageElement = fac.createOMElement("image", omNs);
+
+<div class="source">
+<pre><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"));
- DataHandler dataHandler = new DataHandler(dataSource);
-
+
//create an OMText node with the above DataHandler and set optimized to true
OMText textData = <strong>fac.createOMText(dataHandler, true);</strong>
@@ -178,45 +345,85 @@
//User can set optimized to false by using the following
//textData.doOptimize(false);</pre>
-</pre></div>
- <p>Also a user can create an optimizable binary content node using a base64
+</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>
- <div class="source"><pre><pre> String base64String = "some_base64_encoded_string";
+
+<div class="source">
+<pre><pre> String base64String = "some_base64_encoded_string";
OMText binaryNode =<strong>fac.createOMText(base64String,"image/jpg",true);</strong></pre>
-</pre></div>
- <p>Axis2 uses javax.activation.DataHandler to handle the binary data. All
+</pre>
+</div>
+
+<p>Axis2 uses javax.activation.DataHandler to handle the binary data. All
optimized binary content nodes will be serialized as Base64 Strings if "MTOM
is not enabled". One can also create binary content nodes which will not be
optimized at any case. They will be serialized and send as Base64 Strings.</p>
- <div class="source"><pre><pre> //create an OMText node with the above DataHandler and set "optimized" to false
+
+<div class="source">
+<pre><pre> //create an OMText node with the above DataHandler and set "optimized" to false
//This data will be send as Base64 encoded string regardless of MTOM is enabled or not
javax.activation.DataHandler dataHandler = new javax.activation.DataHandler(new FileDataSource("SomeFile"));
OMText textData = fac.createOMText(dataHandler, <strong>false</strong>);
image.addChild(textData);</pre>
+</pre>
+</div>
+
+<p><a name="22" id="_22"></a></p>
+</div>
-</pre></div>
- <p><a name="22"></a></p></div><div class="subsection"><a name="Enabling_MTOM_Optimization_at_Client_Side"></a><h3>Enabling MTOM Optimization at Client Side</h3><p>Set the "enableMTOM" property in the Options to true, when sending
+<div class="subsection">
+<a name="Enabling_MTOM_Optimization_at_Client_Side"></a>
+
+<h3>Enabling MTOM Optimization at Client Side</h3>
+
+<p>Set the "enableMTOM" property in the Options to true, when sending
messages.</p>
- <div class="source"><pre><pre> ServiceClient serviceClient = new ServiceClient ();
+
+<div class="source">
+<pre><pre> ServiceClient serviceClient = new ServiceClient ();
Options options = new Options();
options.setTo(targetEPR);
<strong>options.setProperty(Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);</strong>
serviceClient .setOptions(options);</pre>
-</pre></div>
- <p>When this property is set to true any SOAP envelope, regardless whether it
+</pre>
+</div>
+
+<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><ul>
+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>
+<ul>
<li>"enableMTOM" property is set to false.</li>
<li>If envelope contains any element information items of name xop:Include
- (see <a href="#XOP">[XML-binary Optimized Packaging] </a><a 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>User does <strong>not</strong> have to specify anything in order for Axis2
+ (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>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><a name="23"></a></p></div><div class="subsection"><a name="Enabling_MTOM_Optimization_at_Server_Side"></a><h3>Enabling MTOM Optimization at Server Side</h3><p>Axis 2 server automatically identifies incoming MTOM optimized messages
+de-serialize accordingly as and when a MTOM message arrives.</p>
+
+<p><a name="23" id="_23"></a></p>
+</div>
+
+<div class="subsection">
+<a name="Enabling_MTOM_Optimization_at_Server_Side"></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>
+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
@@ -224,17 +431,29 @@
Base64 encoded strings. This configuration can be overriden in services.xml
for per service and per operation basis.</p>
</blockquote>
- <div class="source"><pre><parameter name="enableMTOM" locked="false">true</parameter>
-</pre></div>
- <p>User 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><ul>
- <a name="241"></a>
+<div class="source">
+<pre><parameter name="enableMTOM" locked="false">true</parameter></pre>
+</div>
+
+<p>User must restart the server after setting this parameter.</p>
+
+<p><a name="24" id="_24"></a></p>
+</div>
+
+<div class="subsection">
+<a name="Accessing_Received_Binary_Data__Sample_Code_"></a>
+
+<h3>Accessing Received Binary Data (Sample Code)</h3>
+<ul>
+ <a name="241" id="_241"></a>
<ul>
<li><strong>Service</strong></li>
</ul>
-
</ul>
- <div class="source"><pre><pre>public class MTOMService {
+
+<div class="source">
+<pre><pre>public class MTOMService {
public void uploadFileUsingMTOM(OMElement element) throws Exception {
<strong>OMText binaryNode = (OMText) (element.getFirstElement()).getFirstOMChild();
@@ -244,15 +463,17 @@
... <em>Do whatever you need with the DataHandler</em> ...
}
}</pre>
-</pre></div>
- <ul>
- <a name="242"></a>
+</pre>
+</div>
+<ul>
+ <a name="242" id="_242"></a>
<ul>
<li><strong>Client</strong></li>
-
</ul>
</ul>
- <div class="source"><pre><pre> ServiceClient sender = new ServiceClient();
+
+<div class="source">
+<pre><pre> ServiceClient sender = new ServiceClient();
Options options = new Options();
options.setTo(targetEPR);
// enabling MTOM
@@ -267,18 +488,32 @@
DataHandler actualDH;
actualDH = binaryNode.getDataHandler();
.............</pre>
-</pre></div>
- <p><a name="25"></a></p></div><div class="subsection"><a name="MTOM_Databinding"></a><h3>MTOM Databinding</h3><p>You can defining a binary element in the schema using the schema
+</pre>
+</div>
+
+<p><a name="25" id="_25"></a></p>
+</div>
+
+<div class="subsection">
+<a name="MTOM_Databinding"></a>
+
+<h3>MTOM Databinding</h3>
+
+<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
+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>
- <div class="source"><pre><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' >
+
+<div class="source">
+<pre><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' >
<complexType>
<simpleContent>
<extension base="base64Binary" >
@@ -287,18 +522,32 @@
</extension>
</simpleContent>
</complexType>
- </element>
+ </element></pre>
</pre>
-</pre></div>
- <p>You can also use the xmime:base64Binary type to express the above
+</div>
+
+<p>You can also use the xmime:base64Binary type to express the above
mentioned data much more cleanly.</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/"
+
+<div class="source">
+<pre><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' type="xmime:base64Binary"/></pre>
+</pre>
+</div>
+
+<p><a name="251" id="_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/"
@@ -383,16 +632,22 @@
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 an element, 'binaryData' , that utilizes MTOM.</p><p>The next step is using the Axis2 tool 'WSDL2Java' to generate java source
+</wsdl:definitions></pre>
+</pre>
+</div>
+
+<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. 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>
- <div class="source"><pre><pre>
+Here, we define an ant task that chooses ADB (Axis2 Data Binding) as the
+databinding implementation. The name we list for the WSDL above is
+MTOMSample.wsdl, and we define our package name for our generated source
+files to be 'sample.mtom.service' . Our ant task for this example is:</p>
+
+<div class="source">
+<pre><pre>
<target name="generate.service">
<java classname="org.apache.axis2.wsdl.WSDL2Java">
<arg value="-uri" />
@@ -407,11 +662,15 @@
<classpath refid="class.path" />
</java>
</target></pre>
-</pre></div>
- <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>
- <div class="source"><pre><pre>
- public org.apache.ws.axis2.mtomsample.AttachmentResponse attachment(
+</pre>
+</div>
+
+<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>
+
+<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();
@@ -427,12 +686,15 @@
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 disk using the given file name. It returns a message
-on success.
-Now lets define the client:</p>
- <div class="source"><pre><pre> public static void transferFile(File file, String destination)
+ }</pre>
+</pre>
+</div>
+
+<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>
+
+<div class="source">
+<pre><pre> public static void transferFile(File file, String destination)
throws RemoteException {
MTOMSampleStub serviceStub = new MTOMSampleStub();
@@ -462,9 +724,30 @@
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" id="_252"></a><a name="3" id="_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" id="_31"></a></p>
+</div>
+
+<div class="subsection">
+<a name="Receiving_SwA_type_attachments"></a>
+
+<h3>Receiving SwA type attachments</h3>
-</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.
+<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
@@ -472,12 +755,17 @@
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><ul>
+"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 {
+
+<div class="source">
+<pre><pre>public class SwA {
public SwA() {
}
@@ -498,26 +786,49 @@
...........
}
}</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>User need to set the "enableSwA" property to true in order to be able to
+</pre>
+</div>
+
+<p><a name="32" id="_32"></a></p>
+</div>
+
+<div class="subsection">
+<a name="Sending_SwA_Type_Attachments"></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>
- <div class="source"><pre><pre>
+& 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>
+</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
+</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>
+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 {
+
+<div class="source">
+<pre><pre> public void uploadFileUsingSwA(String fileName) throws Exception {
Options options = new Options();
options.setTo(targetEPR);
@@ -539,17 +850,32 @@
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
+</pre>
+</div>
+
+<p><a name="33" id="_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 a 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>
+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";
+
+<div class="source">
+<pre><pre>Content-Type: multipart/related; type="text/xml";
start="<9D645C8EBB837CE54ABD027A3659535D>";
boundary="----=_Part_0_1977511.1123163571138"
@@ -572,11 +898,14 @@
<em>Binary Data.....</em>
------=_Part_0_1977511.1123163571138--</pre>
-</pre></div>
- <ul>
+</pre>
+</div>
+<ul>
<li><strong>Corresponding MTOM message from Axis2</strong></li>
</ul>
- <div class="source"><pre><pre>Content-Type: multipart/related; boundary=MIMEBoundary4A7AE55984E7438034;
+
+<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"
@@ -601,18 +930,44 @@
<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,
+</pre>
+</div>
+
+<p><a name="4" id="_4"></a></p>
+</div>
+
+<div class="subsection">
+<a name="Advanced_Topics"></a>
+
+<h3>Advanced Topics</h3>
+
+<p><a name="41" id="_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 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).
+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><em>NOTE</em> : It is a must to specify a directory to temporary store the
+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><p>The following parameters need to be set in Axis2.xml in order to enable
+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">
+
+<div class="source">
+<pre><pre><axisconfig name="AxisJava2.0">
<!-- ================================================= -->
<!-- Parameters -->
@@ -624,12 +979,35 @@
.........
.........
</axisconfig></pre>
-</pre></div>
- <p>Enabling file caching for client side receiving can be done for the by
+</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);
+
+<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
+</pre>
+</div>
+</div>
+</div>
+</div>
+</div>
+
+<div class="clear">
+<hr />
+</div>
+
+<div id="footer">
+
+<div class="xright">
+© 2004-2007, Apache Software Foundation</div>
+
+<div class="clear">
+<hr />
+</div>
+</div>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org