axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From thil...@apache.org
Subject svn commit: r232233 - /webservices/axis/trunk/java/xdocs/mtom-guide.html
Date Fri, 12 Aug 2005 08:20:42 GMT
Author: thilina
Date: Fri Aug 12 01:20:36 2005
New Revision: 232233

URL: http://svn.apache.org/viewcvs?rev=232233&view=rev
Log:
Some changes to the MTOM doc

Modified:
    webservices/axis/trunk/java/xdocs/mtom-guide.html

Modified: webservices/axis/trunk/java/xdocs/mtom-guide.html
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/mtom-guide.html?rev=232233&r1=232232&r2=232233&view=diff
==============================================================================
--- webservices/axis/trunk/java/xdocs/mtom-guide.html (original)
+++ webservices/axis/trunk/java/xdocs/mtom-guide.html Fri Aug 12 01:20:36 2005
@@ -23,8 +23,10 @@
 Traditionally, two techniques for dealing with opaque data in XML have been used;</p><ol>
   <li><strong> "By value"</strong>  </li>
   <blockquote>
-    <p>Sending binary data by value is achieved by embedding opaque data(ofcource after
some form of encoding) as element or attribute content of the XML component of data.Main advantage
of this  technique is this gives applications the ability to process and describe data based
and looking only on XML component of the data. </p>
-    <p>XML supports opaque data as content through the use of either base64 or hexadecimal
text encoding. Both these techniques bloats the size of the data. For UTF-8 underlying text
encoding, base64 encoding increases the size of the binary data by a factor of 1.33x of the
original size, while hexadecimal encoding expands data by a factor of 2x. Above factors will
be doubled if UTF-16 text encoding is used. Also of concern is the overhead in processing
costs (both real and perceived) for these formats, especially when decoding back into raw
binary.</p>
+    <p>Sending binary data by value is achieved by embedding opaque data(of course
after some form of encoding) as element or attribute content of the XML component of data.
+    The main advantage of this technique is that it give applications the ability to process
and describe data based and looking only on XML component of the data. </p>
+    <p>XML supports opaque data as content through the use of either base64 or hexadecimal
text encoding. 
+    Both these techniques bloat the size of the data. For UTF-8 underlying text encoding,
base64 encoding increases the size of the binary data by a factor of 1.33x of the original
size, while hexadecimal encoding expands data by a factor of 2x. Above factors will be doubled
if UTF-16 text encoding is used. Also of concern is the 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>
@@ -37,7 +39,7 @@
           
 
           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">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 scenerio is like sending attachments with an e-mail
message. Even though those attachements are related to the message content they are not inside
the message.  This causes the technologies 
+      <p>There were several specifications introduced in the web services world to
deal with this binary attachment problem using the "by reference" technique. <a href="http://www.w3.org/TR/SOAP-attachments">SOAP
with Attachments</a> is one such example. Since SOAP prohibits document type declarations
(DTD) in messages, this leads to the  problem of not  representing data as part of the message
infoset, creating two data models. This scenerio 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>
@@ -46,7 +48,7 @@
 </ol><p><a href="http://www.w3.org/TR/2004/PR-soap12-mtom-20041116/">MTOM

 
 
-(SOAP Message Transmission Optimization Mechanism)</a> is an another specification
to which focuses on solving the "Attachments" problem. MTOM tries to leverage the advantages
of above two techniques by trying to merge the above two techniques. MTOM is actually a "by
reference" method. Wire format of a MTOM optimised message is same as the Soap with Attachments
message , which also makes it backward compatible with SwA endpoints. 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 exclusive element
the attached binary content logically become inline(by value) with the SOAP document even
though actually it is attached seperately. This merges the two realms by making it possible
to work only with one data model. This allows the apllications to process and describe by
only looking at XML part making reliance on DTDs obsolute. On a very lighter note MTOM has
standarized the referencing mechanism of SwA. Following is an extract from the <a href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XOP</a>
specification.</p><p><em> At the conceptual level, this binary data can
be thought of as being base64-encoded in the XML Document. As this conceptual form might be
needed during some processing of the XML Document (e.g., for signing the XML 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">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>
&amp; <strong>MTOM (SOAP Message Transmission Optimization Mechanism).</strong></p><p><a
name="2"></a></p><h1>MTOM with Axis2</h1><p><a name="21"></a></p><h2>Programming
Model</h2><p>AXIOM is an (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 
+(SOAP Message Transmission Optimization Mechanism)</a> is another specification which
focuses on solving the "Attachments" problem. MTOM tries to leverage the advantages of above
two techniques by trying to merge the above two techniques. MTOM is actually a "by reference"
method. Wire format of a MTOM optimised 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 exclusive element
the attached binary content logically become inline(by value) with the SOAP document even
though actually it is attached seperately. This merges the two realms by making it possible
to work only with one data model. This allows the apllications to process and describe by
only looking at XML part making reliance on DTDs obsolute. On a lighter note MTOM has standarized
the referencing mechanism of SwA. Following is an extract from the <a href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XOP</a>
specification.</p><p><em> At the conceptual level, this binary data can
be thought of as being base64-encoded in the XML Document. As this conceptual form might be
needed during some processing of the XML Document (e.g., for signing the XML 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">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>
&amp; <strong>MTOM (SOAP Message Transmission Optimization Mechanism).</strong></p><p><a
name="2"></a></p><h1>MTOM with Axis2</h1><p><a name="21"></a></p><h2>Programming
Model</h2><p>AXIOM is an (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 to send base64encoded data as
well as externally attached raw binary data referenced by "XOP" element (Optimised content)
to be send in a SOAP message.
@@ -84,13 +86,13 @@
 </source><p> When this property is set to true any SOAP envelope which contains
optimizable content (OMText nodes containing binary content with optimizable flag "true")
will be serialised as a MTOM optimized message. Messages will not be packaged as MTOM if they
did not contain any optimizable content even though MTOM is enabled. </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">3.
XOP Infosets Constructs </a>). </li>
-</ul><p>MTOM is always enabled in Axis2 when it comes to receiving messages.
Axis2 will automatically identify and de-serilize any MTOM messge it receives. </p><p></p><p><a
name="23"></a></p>
+</ul><p>MTOM is *always enabled* in Axis2 when it comes to receiving messages.
Axis2 will automatically identify and de-serilize any MTOM messge it receives. </p><p></p><p><a
name="23"></a></p>
 <h2>Enabling MTOM optimization in the Server side</h2>
 <p>Axis 2 server automatically identifies incoming MTOM optimized messages based on
the content-type and de-serializes accordingly. One can enableMTOM in the server side for
outgoing messages,</p><ul>
   <li> Globally for all services 
     <blockquote>
       <p>by adding and setting the "enableMTOM" parameter to true in the Axis2.xml.
-        When it is set,  outgoing messages *which contains optimizable content* will be serialized
and send as a MTOM optimized messages. If it is not set all the binary content nodes will
be serialized as Base64 encoded strings. </p>
+        When it is set,  *outgoing* messages *which contains optimizable content* will be
serialized and send as a MTOM optimized messages. If it is not set all the binary content
nodes will be serialized as Base64 encoded strings. </p>
     </blockquote>
   </li>
 </ul><p><source><pre>&lt;parameter name="enableMTOM" locked="xsd:false"&gt;true&lt;/parameter&gt;</pre>
@@ -98,7 +100,6 @@
   <ul>
       <p>User might need to restart the server after setting this parameter.</p>
   </ul>
-  <li>For individual services ???</li>
 </ul><p><a name="24"></a></p><h2>Accessing received Binary
Data</h2><ul>
   <li><strong><a name="241"></a>Service </strong></li>
 </ul><source><pre>
@@ -183,7 +184,7 @@
     }
 }
 
-</pre></source><p>MTOM specification is designed to be backward compatible
with the SOAP with Attachements 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 optimised message is a valid SwA message. Because of that Axis2 does not define
a seperate programming model or serialization for SwA. Users can use the MTOM programming
model and serialization to send messages to SwA endpoints. </p><p>Note : Above
is tested with Axis 1.x</p><ul>
+</pre></source><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 optimised message is a valid SwA message. Because of that Axis2 does not define
a seperate programming model or serialization for SwA. Users can use the MTOM programming
model and serialization to send messages to SwA endpoints. </p><p>Note : Above
is tested with Axis 1.x</p><ul>
   <li><strong>A sample SwA message from Axis 1.x </strong></li>
 </ul><source>
 <pre>
@@ -212,7 +213,50 @@
 </pre>
 </source><ul>
   <li><strong>Corresponding MTOM message from Axis2</strong></li>
-</ul><p><a name="4"></a></p><h1>Advanced Topics</h1><p><a
name="41"></a></p><h2>File Caching For Attachments</h2><p>Axis2
comes handy with a fie 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>Following parameters needs to be set in Axis2.xml in order to enable
file caching.</p><source><pre>
-&lt;parameter name="cacheAttachments" locked="xsd:false"&gt;true&lt;/parameter&gt;
-&lt;parameter name="attachmentDIR" locked="xsd:false"&gt;<em>temp directory</em>&lt;/parameter&gt;
+</ul>
+<source>
+<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: &lt;0.09BC7F4BE2E4D3EF1B@apache.org&gt;
+
+&lt;?xml version='1.0' encoding='utf-8'?&gt;
+&lt;soapenv:Envelope xmlns:soapenv="...."....&gt;
+  ........
+	 &lt;xop:Include href="cid:1.A91D6D2E3D7AC4D580@apache.org" 
+			xmlns:xop="http://www.w3.org/2004/08/xop/include"&gt;
+	 &lt;/xop:Include&gt;
+  ........
+&lt;/soapenv:Envelope&gt;
+--MIMEBoundary4A7AE55984E7438034
+content-type: application/octet-stream
+content-transfer-encoding: binary
+content-id: <1.A91D6D2E3D7AC4D580@apache.org>
+
+<em>Binary Data.....</em>
+--MIMEBoundary4A7AE55984E7438034--
+</pre>
+</source>
+<p><a name="4"></a></p><h1>Advanced Topics</h1><p><a
name="41"></a></p><h2>File Caching For Attachments</h2>
+<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.When this threshold
value is specified, only the attachments whose size is bigget than the threshold value will
get 
+cached in files. Smaller attachmments will remain in Memory. </p>
+<p>The following parameters needs to be set in Axis2.xml in order to enable file caching.</p><source><pre>
+<em>&lt;axisconfig name="AxisJava2.0"&gt;
+    &lt;!-- ================================================= --&gt;
+    &lt;!-- Parameters --&gt;
+    &lt;!-- ================================================= --&gt;</em>
+    &lt;parameter name="cacheAttachments" locked="xsd:false"&gt;true&lt;/parameter&gt;
+    &lt;parameter name="attachmentDIR" locked="xsd:false"&gt;<em>temp directory</em>&lt;/parameter&gt;
+    &lt;parameter name="sizeThreshold" locked="xsd:false"&gt;4000&lt;/parameter&gt;
+    .........
+    .........
+&lt;/axisconfig&gt;
+
 </pre></source></body></html>



Mime
View raw message