You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by de...@apache.org on 2007/08/13 12:13:23 UTC
svn commit: r565295 [8/14] - in /webservices/axis2/site/1_3: ./ adb/ jibx/
src/
Added: webservices/axis2/site/1_3/modules.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/modules.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/modules.html (added)
+++ webservices/axis2/site/1_3/modules.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,646 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+<html>
+ <head>
+ <title>Apache Axis2 - </title>
+ <style type="text/css" media="all">
+ @import url("../css/maven-base.css");
+ @import url("../css/maven-theme.css");
+ @import url("../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../css/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="../" id="bannerLeft">
+
+ <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+
+ </a>
+ <span id="bannerRight">
+
+ <img src="http://ws.apache.org/axis2/images/axis.jpg" alt="" />
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 08/13/2007
+ </div>
+ <div class="xright"> <a href="../index.html">Axis2/Java</a>
+ |
+ <a href="http://ws.apache.org/axis2/c">Axis2/C</a>
+ |
+ <a href="../../../">Apache WS</a>
+ |
+ <a href="http://www.apache.org">Apache</a>
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+
+
+
+
+
+ <h5>Axis2/Java</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../index.html">Home</a>
+ </li>
+ </ul>
+ <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>
+ <h5>Documentation</h5>
+ <ul>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../1_3/contents.html">Version 1.3</a>
+ <ul>
+
+ <li class="none">
+ <a href="../1_3/toc.html">Table of Contents</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/installationguide.html">Installation Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/quickstartguide.html">QuickStart Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/userguide.html">User Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/pojoguide.html">POJO Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/spring.html">Spring Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/webadminguide.html">Web Administrator's Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/migration.html">Migration Guide (from Axis1)</a>
+ </li>
+ </ul>
+ </li>
+
+ <li class="none">
+ <a href="../1_2/contents.html">Version 1.2</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_1_1/contents.html">Version 1.1.1</a>
+ </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>
+ <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/">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_3/api/index.html">Online Java Docs</a>
+ </li>
+ </ul>
+ <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="../release-process.html">Release Process</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>
+ <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">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">License</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy">
+ <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+ </a>
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org"></meta>
+<meta http-equiv="content-type" content=""></meta>
+Writing your Own Axis2 Module
+<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</head>
+
+<a name="Modules"></a>
+<h1>Writing Your Own Axis2 Module</h1>
+<p>Axis2 provides extended support for modules (See the <a href="Axis2ArchitectureGuide.html">Architecture
+Guide</a> for more details about modules in Axis2). Let's create a
+custom module and deploy it to MyService, which we created
+earlier.</p>
+<p>Send your feedback or questions to: <a href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a>.
+( Subscription details are available on the <a href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.)
+Kindly prefix subject with [Axis2].</p>
+<h2>Content List</h2>
+<ul>
+<li><a href="#MyService_with_a_Logging_Module">MyService with a
+Logging Module</a>
+<ul>
+<li><a href="#Step1_:_LoggingModule_Class">Step1 : LoggingModule
+Class</a></li>
+<li><a href="#Step2_:_LogHandler">Step2 : LogHandler</a></li>
+<li><a href="#Step3_:_module_xml">Step3 : module.xml</a></li>
+<li><a href="#Step_4:_Modify_the_"axis2_xml"">Step4:
+Modify the "axis2.xml"</a></li>
+<li><a href="#Step5_:_Modify_the_"services_xml"">Step5 :
+Modify the "services.xml</a></li>
+<li><a href="#Step6_:_Packaging">Step6 : Packaging</a></li>
+<li><a href="#Step7_:_Deploy_the_Module_in_Axis2">Step7 : Deploy
+the Module in Axis2</a></li>
+</ul>
+</li>
+</ul>
+The following steps show the actions that need to be performed
+to deploy a custom module for a given Web service:
+<ol type="1">
+<li>
+Create the Module Implementation
+</li>
+<li>
+Create the Handlers
+</li>
+<li>
+Create the module.xml
+</li>
+<li>
+Modify the "axis2.xml" (if you need
+custom phases)
+</li>
+<li>
+Modify the "services.xml" to engage
+modules at the deployment time.
+</li>
+<li>
+Package in a ".mar" (Module
+Archive)
+</li>
+<li>
+Deploy the module in Axis2
+</li>
+</ol>
+<a name="MyService_with_a_Logging_Module"></a>
+<h3>MyService with a Logging Module</h3>
+Let's write a simple logging module for our sample located at
+the <b>"samples\userguide\src"</b> directory of the binary
+distribution. This module contains one handler that just logs the
+message that is passed through it. Axis2 uses ".mar" (Module
+Archive) to deploy modules in Axis2. The following diagram shows
+the file structure inside which needs to be there in the ".mar"
+archive. Let's create all these and see how it works.
+<img src="images/userguide/ModuleView.jpg" name="Graphic5" align="bottom" border="0" id="Graphic5"></img>
+<a name="Step1_:_LoggingModule_Class"></a>
+<h4>Step1 : LoggingModule Class</h4>
+LoggingModule is the implementation class of the Axis2 module.
+Axis2 modules should implement the "<a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/modules/Module.java?rev=396785&view=log">org.apache.axis2.modules.Module</a>"
+interface with the following methods.
+<pre>
+public void init(ConfigurationContext configContext, AxisModule module) throws AxisFault;//Initialize the module
+public void shutdown(ConfigurationContext configurationContext) throws AxisFault;//End of module processing
+public void engageNotify(AxisDescription axisDescription) throws AxisFault;
+public String[] getPolicyNamespaces() throws AxisFault;
+public void applyPolicy(Policy policy, AxisDescription axisDescription) throws AxisFault ;
+public boolean canSupportAssertion(Assertion assertion) ;
+</pre>
+The first three methods can be used to control the module
+initialization and the termination, and the next three methods are
+used to perform policy related operations. With the input parameter
+AxisConfiguration, the user is provided with the complete
+configuration hierarchy. This can be used to fine-tune the module
+behavior by the module writers. For a simple logging service, we
+can keep these methods blank in our implementation class.
+<a name="Step2_:_LogHandler"></a>
+<h4>Step2 : LogHandler</h4>
+A module in Axis2 can contain, one or more handlers that perform
+various SOAP header processing at different phases. (See the
+<a href="Axis2ArchitectureGuide.html#incomingsoap">Architecture Guide</a> for more information on phases). To
+write a handler one should implement <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/engine/Handler.java?rev=357187&view=log">
+org.apache.axis2.engine.Handler</a>. But for convenience, <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/handlers/AbstractHandler.java?rev=396788&view=log">
+org.apache.axis2.handlers.AbstractHandler</a> provides an abstract
+implementation of the Handler interface.
+For the logging module, we will write a handler with the
+following methods. "public void invoke(MessageContext ctx);" is the
+method that is called by the Axis2 engine when the control is
+passed to the handler. "public void revoke(MessageContext ctx);" is
+called when the handlers are revoked by the Axis2 engine.
+<pre>
+public class LogHandler extends AbstractHandler implements Handler {
+ private static final Log log = LogFactory.getLog(LogHandler.class);
+ private String name;
+
+ public String getName() {
+ return name;
+ }
+
+ public InvocationResponse invoke(MessageContext msgContext) throws AxisFault {
+ log.info(msgContext.getEnvelope().toString());
+ return InvocationResponse.CONTINUE;
+ }
+
+ public void revoke(MessageContext msgContext) {
+ log.info(msgContext.getEnvelope().toString());
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+}
+</pre>
+<a name="Step3_:_module_xml"></a>
+<h4>Step3 : module.xml</h4>
+"module.xml" contains the deployment configurations for a
+particular module. It contains details such as the Implementation
+class of the module (in this example it is the "LoggingModule"
+class and various handlers that will run in different phases). The
+"module.xml" for the logging module will be as follows:
+<pre>
+<module name="logging" class="userguide.loggingmodule.LoggingModule">
+ <InFlow>
+ <handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase" />
+ </handler>
+ </InFlow>
+
+ <OutFlow>
+ <handler name="OutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </OutFlow>
+
+ <OutFaultFlow>
+ <handler name="FaultOutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </OutFaultFlow>
+
+ <InFaultFlow>
+ <handler name="FaultInFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </InFaultFlow>
+</module>
+</pre>
+<p>As you can see, there are four flows defined in the
+"module.xml"</p>
+<ol type="1">
+<li>InFlow Represents the handler chain that will run when a
+message is coming in.</li>
+<li>
+OutFlow Represents the handler chain
+that will run when the message is going out.
+</li>
+<li>
+OutFaultFlow - Represents the handler
+chain that will run when there is a fault, and the fault is going
+out.
+</li>
+<li>
+InFaultFlow - Represents the handler chain that will run when
+there is a fault, and the fault is coming in.
+</li>
+</ol>
+The following set of tags describe the name of the handler,
+handler class, and the phase in which this handler is going to run.
+"InFlowLogHandler" is the name given for the particular instance of
+this handler class. The value of the class attribute is the actual
+implementation class for this handler. Since we are writing a
+logging handler, we can reuse the same handler in all these phases.
+However, this may not be the same for all the modules. "<order
+phase="loggingPhase" />" describes the phase in which this
+handler runs.
+<pre>
+<handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+<order phase="loggingPhase" />
+</handler>
+</pre>
+<p>To learn more about Phase rules, check out the article <a href="http://www.developer.com/java/web/article.php/3529321">Axis2 Execution Framework</a></p>
+<a name="Step_4:_Modify_the_"axis2_xml""></a>
+<h4>Step 4: Modify the "axis2.xml"</h4>
+<p>In this handler, the "loggingPhase", is defined by the module
+writer. It is not a pre-defined handler phase, hence the module
+writer should introduce it to the "axis2.xml" (NOT the
+services.xml) so that the Axis2 engine knows where to place the
+handler in different "flows" (inFlow, outFlow, etc.). The following
+XML lines show the respective changes made to the "axis2.xml" in
+order to deploy the logging module in the Axis2 engine. This is an
+extract of the phase section of "axis2.xml".</p>
+<pre>
+<!-- ================================================= -->
+<!-- Phases -->
+<!-- ================================================= -->
+
+<phaseOrder type="inflow">
+ <!-- System pre defined phases -->
+ <phase name="TransportIn"/>
+ <phase name="PreDispatch"/>
+ <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">
+ <handler name="AddressingBasedDispatcher"
+ class="org.apache.axis2.dispatchers.AddressingBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="RequestURIBasedDispatcher"
+ class="org.apache.axis2.dispatchers.RequestURIBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPActionBasedDispatcher"
+ class="org.apache.axis2.dispatchers.SOAPActionBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPMessageBodyBasedDispatcher"
+ class="org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+ <handler name="InstanceDispatcher"
+ class="org.apache.axis2.engine.InstanceDispatcher">
+ <order phase="PostDispatch"/>
+ </handler>
+ </phase>
+ <!-- System pre defined phases -->
+ <!-- After Postdispatch phase module author or service author can add any phase he wants -->
+ <phase name="OperationInPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ </phaseOrder>
+ <phaseOrder type="outflow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ <!--system predefined phases-->
+ <!--these phases will run irrespective of the service-->
+ <phase name="PolicyDetermination"/>
+ <phase name="MessageOut"/>
+ </phaseOrder/>
+ <phaseOrder type="INfaultflow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationInFaultPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ </phaseOrder>
+ <phaseOrder type="Outfaultflow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutFaultPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ <phase name="PolicyDetermination"/>
+ <phase name="MessageOut"/>
+ </phaseOrder>
+
+</pre>
+<p>The text in green, the custom phase "loggingPhase" is placed in
+all the flows, hence that phase will be called in all the message
+flows in the engine. Since our module is associated with this
+phase, the LogHandler inside the module will now be executed in
+this phase.</p>
+<a name="Step5_:_Modify_the_"services_xml""></a>
+<h4>Step5 : Modify the "services.xml"</h4>
+<p>Up to this point, we have created the required classes and
+configuration descriptions for the logging module, and by changing
+the "axis2.xml" we created the required phases for the logging
+module.</p>
+<p>Next step is to "<b>engage</b>" (use) this module in one of our
+services. For this, let's use the same Web service that we have
+used throughout the user's guide- MyService. However, since we need
+to modify the "services.xml" of MyService in order to engage this
+module, we use a separate Web service, but with similar
+operations.</p>
+<p>The code for this service can be found in the
+"<strong>Axis2_HOME/samples/userguide/src/userguide/example2</strong>"
+directory. The simple changes that we have done to "services.xml'
+are shown in green in the following lines of xml.</p>
+<pre>
+<service name="<span style="color: rgb(36, 193, 19);">MyServiceWithModule</span>">
+ <description>
+ This is a sample Web service with a logging module engaged.
+ </description>
+ <span style="color: rgb(36, 193, 19);"><module ref="logging"/></span>
+ <parameter name="ServiceClass" locked="xsd:false">userguide.example2.MyService</parameter>
+ <operation name="echo">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ <operation name="ping">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+</service>
+</pre>
+<p>In this example, we have changed the service name (the
+implementation class is very similar to what we have used earlier,
+although it is in a different package). In addition we have added
+the line <b>"<module ref="logging"/>"</b> to "services.xml".
+This informs the Axis2 engine that the module "logging" should be
+engaged for this service. The handler inside the module will be
+executed in their respective phases as described by the
+"module.xml".</p>
+<a name="Step6_:_Packaging"></a>
+<h4>Step6 : Packaging</h4>
+<p>Before deploying the module, we need to create the ".mar" file
+for this module. This can be done, using the "jar" command and then
+renaming the created .jar file. Else, you can find the
+"logging.mar" that has already been created in the
+"<strong>Axis2_HOME/samples/userguide</strong>" directory.</p>
+<a name="Step7_:_Deploy_the_Module_in_Axis2"></a>
+<h4>Step7 : Deploy the Module in Axis2</h4>
+<p>Deploying a module in Axis2 requires the user to create a
+directory with the name "modules" in the "webapps/axis2/WEB-INF"
+directory of their servlet container, and then copying the ".mar"
+file to that directory. So let's first create the "modules"
+directory and drop the "logging.mar" into this directory.</p>
+<p>Although the required changes to the "services.xml" is very
+little, we have created a separate service archive
+(MyServiceWithModule.aar) for users to deploy the service..</p>
+<p>Deploy this service using the same steps used in the <a href="adv-userguide.html#Step5_Deploy_web_service">'Step 4: Deploy Web
+Service'</a> sub section in '<a href="userguide.html#ws_codegen">Writing a New Service using
+Codegeneration</a>', and copy the "logging.mar" file to the
+"modules" directory.</p>
+<p>Then run 'ant run.client.servicewithmodule' from
+<strong>axis2home/samples/userguide directory</strong></p>
+<p>Note: To see the logs, the user needs to modify the
+"log4j.properties" to log INFO. The property file is located in
+"<strong>webapps/axis2/WEB-INF/classes</strong>" of your servlet
+container. Change the line "log4j.rootCategory= ERROR, LOGFILE" to
+"log4j.rootCategory=INFO, ERROR, LOGFILE".</p>
+<p><font size="2"><b>Note (on samples):</b></font> All the samples
+mentioned in the user's guide are located at the
+<b>"samples\userguide\src"</b> directory of the binary
+distribution.</p>
+
+</html>
+ </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>
Added: webservices/axis2/site/1_3/mtom-guide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/mtom-guide.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/mtom-guide.html (added)
+++ webservices/axis2/site/1_3/mtom-guide.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,1000 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+<html>
+ <head>
+ <title>Apache Axis2 - </title>
+ <style type="text/css" media="all">
+ @import url("../css/maven-base.css");
+ @import url("../css/maven-theme.css");
+ @import url("../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../css/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="../" id="bannerLeft">
+
+ <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+
+ </a>
+ <span id="bannerRight">
+
+ <img src="http://ws.apache.org/axis2/images/axis.jpg" alt="" />
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 08/13/2007
+ </div>
+ <div class="xright"> <a href="../index.html">Axis2/Java</a>
+ |
+ <a href="http://ws.apache.org/axis2/c">Axis2/C</a>
+ |
+ <a href="../../../">Apache WS</a>
+ |
+ <a href="http://www.apache.org">Apache</a>
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+
+
+
+
+
+ <h5>Axis2/Java</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../index.html">Home</a>
+ </li>
+ </ul>
+ <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>
+ <h5>Documentation</h5>
+ <ul>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../1_3/contents.html">Version 1.3</a>
+ <ul>
+
+ <li class="none">
+ <a href="../1_3/toc.html">Table of Contents</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/installationguide.html">Installation Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/quickstartguide.html">QuickStart Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/userguide.html">User Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/pojoguide.html">POJO Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/spring.html">Spring Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/webadminguide.html">Web Administrator's Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/migration.html">Migration Guide (from Axis1)</a>
+ </li>
+ </ul>
+ </li>
+
+ <li class="none">
+ <a href="../1_2/contents.html">Version 1.2</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_1_1/contents.html">Version 1.1.1</a>
+ </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>
+ <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/">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_3/api/index.html">Online Java Docs</a>
+ </li>
+ </ul>
+ <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="../release-process.html">Release Process</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>
+ <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">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">License</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy">
+ <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+ </a>
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <html>
+<head>
+ <meta http-equiv="content-type" content=""></meta>
+ Handling Binary data with Axis2 (MTOM/SwA)
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</head>
+
+
+<h1>Handling Binary Data with Axis2 (MTOM/SwA)</h1>
+
+<p>This document describes how to use the Axis2 functionality to send/receive
+binary data with SOAP.</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#1">Introduction</a>
+ <ul>
+ <li><a href="#11">Where Does MTOM Come In?</a></li>
+ </ul>
+ </li>
+ <li><a href="#2">MTOM with Axis2 </a>
+ <ul>
+ <li><a href="#21">Programming Model</a></li>
+ <li><a href="#22">Enabling MTOM Optimization at Client Side</a></li>
+ <li><a href="#23">Enabling MTOM Optimization at Server Side</a></li>
+ <li><a href="#24">Accessing Received Binary Data (Sample Code) </a>
+ <ul>
+ <li><a href="#241">Service</a></li>
+ <li><a href="#242">Client</a></li>
+ </ul>
+ </li>
+ <li><a href="#25">MTOM Databinding</a>
+ <ul>
+ <li><a href="#251">Using ADB</a></li>
+
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#3">SOAP with Attachments with Axis2</a>
+ <ul>
+ <li><a href="#31">Sending SwA Type Attachments</a></li>
+ <li><a href="#32">Receiving SwA Type Attachments</a></li>
+ <li><a href="#33">MTOM Backward Compatibility with SwA</a></li>
+ </ul>
+ </li>
+ <li><a href="#4">Advanced Topics </a>
+ <ul>
+ <li><a href="#41">File Caching for Attachments</a></li>
+ </ul>
+ </li>
+</ul>
+<a name="1"></a>
+
+<h2>Introduction</h2>
+
+Despite the flexibility, interoperability, and global acceptance of XML,
+there are times when serializing data into XML does not make sense. Web
+services users may want to transmit binary attachments of various sorts like
+images, drawings, XML docs, etc., together with a SOAP message. Such data is
+often in a particular binary format.<br></br>
+
+
+Traditionally, two techniques have been used in dealing with opaque data
+in XML;
+<ol type="1">
+ <li><strong>"By value"</strong></li>
+
+ <blockquote>
+ Sending binary data by value is achieved by embedding opaque data (of
+ course after some form of encoding) as an element or attribute content of
+ the XML component of data. The main advantage of this technique is that
+ it gives applications the ability to process and describe data, based
+ only on the XML component of the data.
+
+ XML supports opaque data as content through the use of either base64
+ or hexadecimal text encoding. Both techniques bloat the size of the data.
+ For UTF-8 underlying text encoding, base64 encoding increases the size of
+ the binary data by a factor of 1.33x of the original size, while
+ hexadecimal encoding expands data by a factor of 2x. The above factors
+ will be doubled if UTF-16 text encoding is used. Also of concern is the
+ overhead in processing costs (both real and perceived) for these formats,
+ especially when decoding back into raw binary.
+ </blockquote>
+ <li><strong>"By reference"</strong>
+
+ <blockquote>
+ Sending binary data by reference is achieved by attaching pure
+ binary data as external unparsed general entities outside the XML
+ document and then embedding reference URIs to those entities as
+ elements or attribute values. This prevents the unnecessary bloating of
+ data and wasting of processing power. The primary obstacle for using
+ these unparsed entities is their heavy reliance on DTDs, which impedes
+ modularity as well as the use of XML namespaces.
+ 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, therefore creating two data models.
+ This scenario is like sending attachments with an e-mail message. Even
+ though those attachments are related to the message content they are
+ not inside the message. This causes the technologies that process and
+ describe the data based on the XML component of the data to
+ malfunction. One example is WS-Security.
+ </blockquote>
+ </li>
+</ol>
+<a name="11"></a>
+
+<h3>Where Does MTOM Come In?</h3>
+
+<a href="http://www.w3.org/TR/2004/PR-soap12-mtom-20041116/">MTOM (SOAP
+Message Transmission Optimization Mechanism)</a> is another specification
+that focuses on solving the "Attachments" problem. MTOM tries to leverage the
+advantages of the above two techniques by trying to merge the two techniques.
+MTOM is actually a "by reference" method. The wire format of a MTOM optimized
+message is the same as the SOAP with Attachments message, which also makes it
+backward compatible with SwA endpoints. The most notable feature of MTOM is
+the use of the XOP:Include element, which is defined in the <a href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XML Binary Optimized
+Packaging (XOP)</a> specification to reference the binary attachments
+(external unparsed general entities) of the message. With the use of this
+exclusive element, the attached binary content logically becomes inline (by
+value) with the SOAP document even though it is actually attached separately.
+This merges the two realms by making it possible to work only with one data
+model. This allows the applications to process and describe by only looking
+at the XML part, making the reliance on DTDs obsolete. On a lighter note,
+MTOM has standardized the referencing mechanism of SwA. The following is an
+extract from the <a href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XOP</a> specification.
+
+<em>At the conceptual level, this binary data can be thought of as being
+base64-encoded in the XML Document. As this conceptual form might be needed
+during some processing of the XML document (e.g., for signing the XML
+document), it is necessary to have a one-to-one correspondence between XML
+Infosets and XOP Packages. Therefore, the conceptual representation of such
+binary data is as if it were base64-encoded, using the canonical lexical form
+of the XML Schema base64Binary datatype (see <a href="#XMLSchemaP2">[XML
+Schema Part 2: Datatypes Second Edition] </a> <a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#base64Binary">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>
+
+Apache Axis2 supports <strong>Base64 encoding</strong>, <strong>SOAP with
+Attachments</strong> and <strong>MTOM (SOAP Message Transmission Optimization
+Mechanism).</strong>
+<a name="2"></a>
+
+<h2>MTOM with Axis2</h2>
+<a name="21"></a>
+
+<h3>Programming Model</h3>
+
+AXIOM is (and may be the first) Object Model that has the ability to hold
+binary data. It has this ability as OMText can hold raw binary content in the
+form of javax.activation.DataHandler. OMText has been chosen for this purpose
+with two reasons. One is that XOP (MTOM) is capable of optimizing only
+base64-encoded Infoset data that is in the canonical lexical form of XML
+Schema base64Binary datatype. Other one is to preserve the infoset in both
+the sender and receiver. (To store the binary content in the same kind of
+object regardless of whether it is optimized or not).
+
+MTOM allows to selectively encode portions of the message, which allows us
+to send base64encoded data as well as externally attached raw binary data
+referenced by the "XOP" element (optimized content) to be sent in a SOAP
+message. You can specify whether an OMText node that contains raw binary data
+or base64encoded binary data is qualified to be optimized at the time of
+construction of that node or later. For optimum efficiency of MTOM, a user is
+advised to send smaller binary attachments using base64encoding
+(non-optimized) and larger attachments as optimized content.
+
+
+<pre> OMElement imageElement = fac.createOMElement("image", omNs);
+
+ // Creating the Data Handler for the file. Any implementation of
+ // javax.activation.DataSource interface can fit here.
+ javax.activation.DataHandler dataHandler = new javax.activation.DataHandler(new FileDataSource("SomeFile"));
+
+ //create an OMText node with the above DataHandler and set optimized to true
+ OMText textData = <strong>fac.createOMText(dataHandler, true);</strong>
+
+ imageElement.addChild(textData);
+
+ //User can set optimized to false by using the following
+ //textData.doOptimize(false);</pre>
+
+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.
+
+
+<pre> String base64String = "some_base64_encoded_string";
+ OMText binaryNode =<strong>fac.createOMText(base64String,"image/jpg",true);</strong></pre>
+
+Axis2 uses javax.activation.DataHandler to handle the binary data. All the
+optimized binary content nodes will be serialized as Base64 Strings if "MTOM
+is not enabled". You can also create binary content nodes, which will not be
+optimized at any case. They will be serialized and sent as Base64 Strings.
+
+
+<pre> //create an OMText node with the above DataHandler and set "optimized" to false
+ //This data will be send as Base64 encoded string regardless of MTOM is enabled or not
+ javax.activation.DataHandler dataHandler = new javax.activation.DataHandler(new FileDataSource("SomeFile"));
+ OMText textData = fac.createOMText(dataHandler, <strong>false</strong>);
+ image.addChild(textData);</pre>
+<a name="22"></a>
+
+<h3>Enabling MTOM Optimization on the Client Side</h3>
+
+In Options, set the "enableMTOM" property to True when sending
+messages.
+
+
+<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>
+
+When this property is set to True, any SOAP envelope, regardless of
+whether it contains optimizable content or not, will be serialized as an MTOM
+optimized MIME message.
+
+<p>Axis2 serializes all binary content nodes as Base64 encoded strings
+regardless of whether they are qualified to be optimized or not</p>
+<ul>
+ <li>if the "enableMTOM" property is set to False.</li>
+ <li>if the envelope contains any element information items of the name
+ xop:Include (see <a href="#XOP">[XML-binary Optimized Packaging] </a><a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_infosets">3. XOP
+ Infosets Constructs </a>).</li>
+</ul>
+
+The user does <strong>not</strong> have to specify anything in order for
+Axis2 to receive MTOM optimised messages. Axis2 will automatically identify
+and de-serialize accordingly, as and when an MTOM message arrives.
+<a name="23"></a>
+
+<h3>Enabling MTOM Optimization on the Server Side</h3>
+
+The Axis 2 server automatically identifies incoming MTOM optimized
+messages based on the content-type and de-serializes them accordingly. The
+user can enableMTOM on the server side for outgoing messages,
+
+<blockquote>
+ <p>To enableMTOM globally for all services, users can set the "enableMTOM"
+ parameter to True in the Axis2.xml. When it is set, all outgoing messages
+ will be serialized and sent as MTOM optimized MIME messages. If it is not
+ set, all the binary data in the binary content nodes will be serialized as
+ Base64 encoded strings. This configuration can be overriden in services.xml
+ on the basis of per service and per operation.</p>
+</blockquote>
+<pre><parameter name="enableMTOM">true</parameter></pre>
+
+<p>You must restart the server after setting this parameter.</p>
+<a name="24"></a>
+
+<h3>Accessing Received Binary Data (Sample Code)</h3>
+<a name="241"></a>
+<ul>
+ <li><strong>Service</strong></li>
+</ul>
+
+
+<pre>public class MTOMService {
+ public void uploadFileUsingMTOM(OMElement element) throws Exception {
+
+ <strong>OMText binaryNode = (OMText) (element.getFirstElement()).getFirstOMChild();
+ DataHandler actualDH;
+ actualDH = (DataHandler) binaryNode.getDataHandler();</strong>
+
+ ... <em>Do whatever you need with the DataHandler</em> ...
+ }
+ }</pre>
+<a name="242"></a>
+<ul>
+ <li><strong>Client</strong></li>
+</ul>
+
+
+<pre> ServiceClient sender = new ServiceClient();
+ Options options = new Options();
+ options.setTo(targetEPR);
+ // enabling MTOM
+ <strong>options.set(Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);</strong>
+ ............
+
+ OMElement result = sender.sendReceive(payload);
+ OMElement ele = result.getFirstElement();
+ OMText binaryNode = (OMText) ele.getFirstOMChild();
+
+ // Retrieving the DataHandler & then do whatever the processing to the data
+ DataHandler actualDH;
+ actualDH = binaryNode.getDataHandler();
+ .............</pre>
+<a name="25"></a>
+
+<h3>MTOM Databinding</h3>
+
+<p>You can define a binary element in the schema using the schema
+type="xsd:base64Binary". Having an element with the type "xsd:base64Binary"
+is enough for the Axis2 code generators to identify possible MTOM
+attachments, and to generate code accordingly.</p>
+
+<p>Going a little further, you can use the xmime schema
+(http://www.w3.org/2005/05/xmlmime) to describe the binary content more
+precisely. With the xmime schema, you can indicate the type of content in the
+element at runtime using an MTOM attribute extension xmime:contentType.
+Furthermore, you can identify what type of data might be expected in the
+element using the xmime:expectedContentType. Putting it all together, our
+example element becomes:</p>
+<div class="source"><pre><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' >
+ <complexType>
+ <simpleContent>
+ <extension base="base64Binary" >
+
+ <attribute ref="xmime:contentType" use="required"/>
+ </extension>
+ </simpleContent>
+ </complexType>
+ </element></pre>
+</pre></div>
+<p>You can also use the xmime:base64Binary type to express the above
+mentioned data much clearly.</p>
+<div class="source"><pre><pre> <element name="MyBinaryData" xmime:expectedContentTypes='image/jpeg' type="xmime:base64Binary"/></pre>
+</pre></div><a name="251"></a>
+
+<h3>MTOM Databinding Using ADB</h3>
+
+<p>Let's define a full, validated doc/lit style WSDL that uses the xmime
+schema, has a service that receives a file, and saves it in the server using
+the given path.</p>
+<div class="source"><pre><pre><wsdl:definitions xmlns:tns="http://ws.apache.org/axis2/mtomsample/"
+ xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
+ xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
+ xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
+ xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
+ xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns="http://schemas.xmlsoap.org/wsdl/"
+ targetNamespace="http://ws.apache.org/axis2/mtomsample/">
+
+ <wsdl:types>
+ <xsd:schema xmlns="http://schemas.xmlsoap.org/wsdl/"
+ attributeFormDefault="qualified" elementFormDefault="qualified"
+ targetNamespace="http://ws.apache.org/axis2/mtomsample/">
+
+ <xsd:import namespace="http://www.w3.org/2005/05/xmlmime"
+ schemaLocation="http://www.w3.org/2005/05/xmlmime" />
+ <xsd:complexType name="AttachmentType">
+ <xsd:sequence>
+ <xsd:element minOccurs="0" name="fileName"
+ type="xsd:string" />
+ <xsd:element minOccurs="0" name="binaryData"
+ type="xmime:base64Binary" />
+ </xsd:sequence>
+ </xsd:complexType>
+ <xsd:element name="AttachmentRequest" type="tns:AttachmentType" />
+ <xsd:element name="AttachmentResponse" type="xsd:string" />
+ </xsd:schema>
+ </wsdl:types>
+ <wsdl:message name="AttachmentRequest">
+ <wsdl:part name="part1" element="tns:AttachmentRequest" />
+ </wsdl:message>
+ <wsdl:message name="AttachmentResponse">
+ <wsdl:part name="part1" element="tns:AttachmentResponse" />
+ </wsdl:message>
+ <wsdl:portType name="MTOMServicePortType">
+ <wsdl:operation name="attachment">
+ <wsdl:input message="tns:AttachmentRequest"
+ wsaw:Action="attachment" />
+ <wsdl:output message="tns:AttachmentResponse"
+ wsaw:Action="http://schemas.xmlsoap.org/wsdl/MTOMServicePortType/AttachmentResponse" />
+ </wsdl:operation>
+ </wsdl:portType>
+ <wsdl:binding name="MTOMServiceSOAP11Binding"
+ type="tns:MTOMServicePortType">
+ <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
+ style="document" />
+ <wsdl:operation name="attachment">
+ <soap:operation soapAction="attachment" style="document" />
+ <wsdl:input>
+ <soap:body use="literal" />
+ </wsdl:input>
+ <wsdl:output>
+ <soap:body use="literal" />
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+ <wsdl:binding name="MTOMServiceSOAP12Binding"
+ type="tns:MTOMServicePortType">
+ <soap12:binding transport="http://schemas.xmlsoap.org/soap/http"
+ style="document" />
+ <wsdl:operation name="attachment">
+ <soap12:operation soapAction="attachment" style="document" />
+ <wsdl:input>
+ <soap12:body use="literal" />
+ </wsdl:input>
+ <wsdl:output>
+ <soap12:body use="literal" />
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+ <wsdl:service name="MTOMSample">
+ <wsdl:port name="MTOMSampleSOAP11port_http"
+ binding="tns:MTOMServiceSOAP11Binding">
+ <soap:address
+ location="http://localhost:8080/axis2/services/MTOMSample" />
+ </wsdl:port>
+ <wsdl:port name="MTOMSampleSOAP12port_http"
+ binding="tns:MTOMServiceSOAP12Binding">
+ <soap12:address
+ location="http://localhost:8080/axis2/services/MTOMSample" />
+ </wsdl:port>
+ </wsdl:service>
+</wsdl:definitions></pre>
+</pre></div>
+<p>The important point here is we import http://www.w3.org/2005/05/xmlmime
+and define the element 'binaryData' that utilizes MTOM.</p>
+
+<p>The next step is using the Axis2 tool 'WSDL2Java' to generate Java source
+files from this WSDL. See the 'Code Generator Tool' guide for more
+information. Here, we define an Ant task that chooses ADB (Axis2 Data
+Binding) as the databinding implementation. The name we list for the WSDL
+above is MTOMSample.wsdl, and we define our package name for our generated
+source files to 'sample.mtom.service' . Our Ant task for this example is:</p>
+<div class="source"><pre><pre>
+<target name="generate.service">
+ <java classname="org.apache.axis2.wsdl.WSDL2Java">
+ <arg value="-uri" />
+ <arg value="${basedir}/resources/MTOMSample.wsdl" />
+ <arg value="-ss" />
+ <arg value="-sd" />
+ <arg value="-g"/>
+ <arg value="-p" />
+ <arg value="sample.mtom.service" />
+ <arg value="-o" />
+ <arg value="${service.dir}" />
+ <classpath refid="class.path" />
+ </java>
+ </target></pre>
+</pre></div>
+<p>Now we are ready to code. Let's edit
+output/src/sample/mtom/service/MTOMSampleSkeleton.java and fill in the
+business logic. Here is an example:</p>
+<div class="source"><pre><pre> public org.apache.ws.axis2.mtomsample.AttachmentResponse attachment(
+ org.apache.ws.axis2.mtomsample.AttachmentRequest param0) throws Exception
+ {
+ AttachmentType attachmentRequest = param0.getAttachmentRequest();
+ Base64Binary binaryData = attachmentRequest.getBinaryData();
+ DataHandler dataHandler = binaryData.getBase64Binary();
+ File file = new File(
+ attachmentRequest.getFileName());
+ FileOutputStream fileOutputStream = new FileOutputStream(file);
+ dataHandler.writeTo(fileOutputStream);
+ fileOutputStream.flush();
+ fileOutputStream.close();
+
+ AttachmentResponse response = new AttachmentResponse();
+ response.setAttachmentResponse("File saved succesfully.");
+ return response;
+ }</pre>
+</pre></div>
+<p>The code above receives a file and writes it to the disk using the given
+file name. It returns a message once it is successful. Now let's define the
+client:</p>
+<div class="source"><pre><pre> public static void transferFile(File file, String destination)
+ throws RemoteException {
+ MTOMSampleStub serviceStub = new MTOMSampleStub();
+
+ // Enable MTOM in the client side
+ serviceStub._getServiceClient().getOptions().setProperty(
+ Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);
+ //Increase the time out when sending large attachments
+ serviceStub._getServiceClient().getOptions().setTimeOutInMilliSeconds(10000);
+
+ // Populating the code generated beans
+ AttachmentRequest attachmentRequest = new AttachmentRequest();
+ AttachmentType attachmentType = new AttachmentType();
+ Base64Binary base64Binary = new Base64Binary();
+
+ // Creating a javax.activation.FileDataSource from the input file.
+ FileDataSource fileDataSource = new FileDataSource(file);
+
+ // Create a dataHandler using the fileDataSource. Any implementation of
+ // javax.activation.DataSource interface can fit here.
+ DataHandler dataHandler = new DataHandler(fileDataSource);
+ base64Binary.setBase64Binary(dataHandler);
+ base64Binary.setContentType(dataHandler.getContentType());
+ attachmentType.setBinaryData(base64Binary);
+ attachmentType.setFileName(destination);
+ attachmentRequest.setAttachmentRequest(attachmentType);
+
+ AttachmentResponse response = serviceStub.attachment(attachmentRequest);
+ System.out.println(response.getAttachmentResponse());
+ }</pre>
+</pre></div>
+<p>The last step is to create an AAR with our Skeleton and the services.xml
+and then deploy the service. You can find the completed sample in the Axis2
+standard binary distribution under the samples/mtom directory</p>
+<a name="252"></a> <a name="3"></a>
+
+<h2>SOAP with Attachments (SwA) with Axis2</h2>
+<a name="31"></a>
+
+<h3>Receiving SwA Type Attachments</h3>
+
+<p>Axis2 automatically identifies SwA messages based on the content type.
+Axis2 stores the references on the received attachment parts (MIME parts) in
+the Message Context. Axis2 preserves the order of the received attachments
+when storing them in the MessageContext. Users can access binary attachments
+using the attachement API given in the Message Context using the content-id
+of the mime part as the key. Care needs be taken to rip off the "cid" prefix
+when content-id is taken from the "Href" attributes. Users can access the
+message context from whithin a service implementation class using the
+"setOperationContext()" method as shown in the following example.</p>
+
+<p>Note: Axis2 supports content-id based referencing only. Axis2 does not
+support Content Location based referencing of MIME parts.</p>
+<ul>
+ <li><strong>Sample service which accesses a received SwA type
+ attachment</strong></li>
+</ul>
+<div class="source"><pre><pre>public class SwA {
+ public SwA() {
+ }
+
+ public void uploadAttachment(OMElement omEle) throws AxisFault {
+ OMElement child = (OMElement) omEle.getFirstOMChild();
+ OMAttribute attr = child.getAttribute(new QName("href"));
+
+ //Content ID processing
+ String contentID = attr.getAttributeValue();
+ contentID = contentID.trim();
+ if (contentID.substring(0, 3).equalsIgnoreCase("cid")) {
+ contentID = contentID.substring(4);
+ }
+
+ MessageContext msgCtx = MessageContext.getCurrentMessageContext();
+ Attachments attachment = msgCtx.getAttachmentMap();
+ DataHandler dataHandler = attachment.getDataHandler(contentID);
+ ...........
+ }
+}</pre>
+</pre></div><a name="32"></a>
+
+<h3>Sending SwA Type Attachments</h3>
+
+The user needs to set the "enableSwA" property to True in order to be able
+to send SwA messages. The Axis2 user is <strong>not</strong> expected to
+enable MTOM and SwA together. In such a situation, MTOM will get priority
+over SwA.
+
+<p>This can be set using the axis2.xml as follows.</p>
+<div class="source"><pre><pre>
+ <parameter name="enableSwA">true</parameter></pre>
+</pre></div>
+<p>"enableSwA" can also be set using the client side Options as follows</p>
+<div class="source"><pre><pre>
+ options.setProperty(Constants.Configuration.ENABLE_SwA, Constants.VALUE_TRUE);</pre>
+</pre></div>
+<p>Users are expected to use the attachment API provided in the
+MessageContext to specify the binary attachments needed to be attached to the
+outgoing message as SwA type attachments. Client side SwA capability can be
+used only with the OperationClient api, since the user needs the ability to
+access the MessageContext.</p>
+<ul>
+ <li><strong>Sample client which sends a message with SwA type
+ attachments</strong></li>
+</ul>
+<div class="source"><pre><pre> public void uploadFileUsingSwA(String fileName) throws Exception {
+
+ Options options = new Options();
+ options.setTo(targetEPR);
+ options.setProperty(Constants.Configuration.ENABLE_SWA, Constants.VALUE_TRUE);
+ options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
+ options.setSoapVersionURI(SOAP11Constants.SOAP_ENVELOPE_NAMESPACE_URI);
+ options.setTo(targetEPR);
+
+ ServiceClient sender = new ServiceClient(null,null);
+ sender.setOptions(options);
+ OperationClient mepClient = sender.createClient(ServiceClient.ANON_OUT_IN_OP);
+
+ MessageContext mc = new MessageContext();
+ mc.setEnvelope(createEnvelope());
+ FileDataSource fileDataSource = new FileDataSource("test-resources/mtom/test.jpg");
+ DataHandler dataHandler = new DataHandler(fileDataSource);
+ mc.addAttachment("FirstAttachment",dataHandler);
+
+ mepClient.addMessageContext(mc);
+ mepClient.execute(true);
+ }</pre>
+</pre></div><a name="33"></a>
+
+<h3>MTOM Backward Compatibility with SwA</h3>
+
+MTOM specification is designed to be backward compatible with the SOAP
+with Attachments specification. Even though the representation is different,
+both technologies have the same wire format. We can safely assume that any
+SOAP with Attachments endpoint can accept MTOM optimized messages and treat
+them as SOAP with Attachment messages - any MTOM optimized message is a valid
+SwA message.
+
+<p>Note : Above backword compatibility was succesfully tested against Axis
+1.x</p>
+<ul>
+ <li><strong>A sample SwA message from Axis 1.x</strong></li>
+</ul>
+<div class="source"><pre><pre>Content-Type: multipart/related; type="text/xml";
+ start="<9D645C8EBB837CE54ABD027A3659535D>";
+ boundary="----=_Part_0_1977511.1123163571138"
+
+------=_Part_0_1977511.1123163571138
+Content-Type: text/xml; charset=UTF-8
+Content-Transfer-Encoding: binary
+Content-Id: <9D645C8EBB837CE54ABD027A3659535D>
+
+<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="...."....>
+ ........
+ <source href="cid:3936AE19FBED55AE4620B81C73BDD76E" xmlns="/>
+
+ ........
+</soapenv:Envelope>
+------=_Part_0_1977511.1123163571138
+Content-Type: text/plain
+Content-Transfer-Encoding: binary
+Content-Id: <3936AE19FBED55AE4620B81C73BDD76E>
+
+<em>Binary Data.....</em>
+------=_Part_0_1977511.1123163571138--</pre>
+</pre></div><ul>
+ <li><strong>Corresponding MTOM message from Axis2</strong></li>
+</ul>
+<div class="source"><pre><pre>Content-Type: multipart/related; boundary=MIMEBoundary4A7AE55984E7438034;
+ type="application/xop+xml"; start="<0.09BC7F4BE2E4D3EF1B@apache.org>";
+ start-info="text/xml; charset=utf-8"
+
+--MIMEBoundary4A7AE55984E7438034
+content-type: application/xop+xml; charset=utf-8; type="application/soap+xml;"
+content-transfer-encoding: binary
+content-id: <0.09BC7F4BE2E4D3EF1B@apache.org>
+
+<?xml version='1.0' encoding='utf-8'?>
+<soapenv:Envelope xmlns:soapenv="...."....>
+ ........
+ <xop:Include href="cid:1.A91D6D2E3D7AC4D580@apache.org"
+ xmlns:xop="http://www.w3.org/2004/08/xop/include">
+ </xop:Include>
+ ........
+
+</soapenv:Envelope>
+--MIMEBoundary4A7AE55984E7438034
+content-type: application/octet-stream
+content-transfer-encoding: binary
+content-id: <1.A91D6D2E3D7AC4D580@apache.org>
+
+<em>Binary Data.....</em>
+--MIMEBoundary4A7AE55984E7438034--</pre>
+</pre></div><a name="4"></a>
+
+<h2>Advanced Topics</h2>
+<a name="41"></a>
+
+<h3>File Caching for Attachments</h3>
+
+Axis2 comes handy with a file caching mechanism for incoming attachments,
+which gives Axis2 the ability to handle very large attachments without
+buffering them in the memory at any time. Axis2 file caching streams the
+incoming MIME parts directly into the files, after reading the MIME part
+headers.
+
+Also, a user can specify a size threshold for the File caching (in bytes).
+When this threshold value is specified, only the attachments whose size is
+bigger than the threshold value will get cached in the files. Smaller
+attachments will remain in the memory.
+
+<p>Note : It is a must to specify a directory to temporarily store the
+attachments. Also care should be taken to <strong>clean that
+directory</strong> from time to time.</p>
+
+<p>The following parameters need to be set in Axis2.xml in order to enable
+file caching.</p>
+<div class="source"><pre><pre><axisconfig name="AxisJava2.0">
+
+ <!-- ================================================= -->
+ <!-- Parameters -->
+ <!-- ================================================= -->
+ <parameter name="cacheAttachments">true</parameter>
+ <parameter name="attachmentDIR"><em>temp directory</em></parameter>
+
+ <parameter name="sizeThreshold"><em>4000</em></parameter>
+ .........
+ .........
+</axisconfig></pre>
+</pre></div>
+<p>Enabling file caching for client side receiving can be done for the by
+setting the Options as follows.</p>
+<div class="source"><pre><pre>options.setProperty(Constants.Configuration.CACHE_ATTACHMENTS,Constants.VALUE_TRUE);
+options.setProperty(Constants.Configuration.ATTACHMENT_TEMP_DIR,<em>TempDir</em>);
+options.setProperty(Constants.Configuration.FILE_SIZE_THRESHOLD, <em>"4000"</em>);</pre>
+</pre></div>
+</html>
+ </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