You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by de...@apache.org on 2006/01/12 06:10:33 UTC
svn commit: r368278 [2/3] - in /webservices/axis2/trunk/java/xdocs/0_94: ./
tools/idea/
Modified: webservices/axis2/trunk/java/xdocs/0_94/axis2config.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/axis2config.html?rev=368278&r1=368277&r2=368278&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/axis2config.html (original)
+++ webservices/axis2/trunk/java/xdocs/0_94/axis2config.html Wed Jan 11 21:10:09 2006
@@ -1,354 +1,343 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
-<html>
-<head>
-<title>Axis2 Configuration Documents</title>
-</head>
-<body>
-<p>In Axis2 there are three kinds of configuration files to configure the system.
-First one configuration file is to configure whole system, second one is to
-configure a service and the third one is to configure a module.
-<ul>
-<li><a href="#global">Global Configuration (axis2.xml)</a></li>
-<li><a href="#service">Service Configuration (services.xml)</a></li>
-<li><a href="#module">Module Configuration (module.xml)</a></li>
-</ul>
-</p>
-<br>
-
-<font color="blue"><b>Global Configuration </b></font>
-<li><a name="global"></a>Writing axis2.xml</li>
-<p>
- All the configuration that requires starting axis2 is obtained from axis2.xml.
- The way of specifying them is very simple and easy. The document is all about
- the proper way of specifying the configurations in axis2.xml.
- There are six top level elements that can be seen in the configuration
- file and those can be listed as follows;
-</p>
-<ul>
-<li>Parameter</li>
-<li>Transport Receiver</li>
-<li>Transport Sender</li>
-<li>Phase Order</li>
-<li>Module References</li>
-<li>Listeners (Observers)</li>
-</ul>
-
-<p><b>Parameter </b>
-<br>
-In axis2 a parameter is nothing but name value pair, each and every top level
-parameter available in the axis2.xml (direct sub elements of root element) will
-be transformed into properties in AxisConfiguration. Therefore the top level
-parameters in configuration document can be accessed via AxisConfiguration in
-the running system. The correct way of defining a parameter looks like what is shown below;
-<source><pre>
- <parameter name="name of the parameter" >parameter value </parameter>
-</pre></source>
-</p>
-<p>
-<b>Transport Receiver</b><br>
-Depending on the underline transport that axis going to be run ,
-need to have different transport receivers so the way of adding
-them to the system can be done as follows;
-<source><pre>
-<transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer">
- <parameter name="port" >6060</parameter>
- </transportReceiver>
- </pre></source>
-
-The above elements shows the way of defining transport receivers in axis2.xml ,
-here name attribute of the 'transportReceiver' element is the name of transport
-it can be http, tcp , smtp , commonshttp stc , and when the system starts up or
-when setting transport at the client side one can use these transport names to
- load the appropriate transport. Class attribute is to specify actual java
- class which implements required interfaces for the transport. Any transport
- can have zero or more parameters, and if there are any, then those parameters
- can be accessed via the corresponding transport receiver.
-</p>
-
-<p>
-<b>Transport Senders</b><br>
-As same as transport receivers it is possible to register transport senders in the
-system, and latter at the run time those senders can be used to send the messages.
-As an example consider Axis2 running under tomcat, then axis can use TCP transport
-senders to send message rather than HTTP. The way of specifying transport senders is as follows:
-<source><pre>
-<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
- <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0</parameter>
- </transportSender>
- </pre></source>
-name: Name of the transport (it is possible to have http and http1 as transport name)
-Class: Implementation class of the corresponding transport.
-
-As same as transport receivers, transport senders can have zero or more parameters,
-and if there is any then it can be accessed via corresponding transport sender.
-</p>
-<p>
-<b>Phase Order</b><br>
-The specifying order of phases in execution chain has to be done using phase
-order element and it will be look like below;
-<source><pre>
-<phaseOrder type="inflow">
- <phase name="TransportIn"/>
-
-
.
-</phaseOrder>
-</pre></source>
-
-The most interesting thing is that you can add handlers here as well , if you want to add a handler which should go in to that phase you can directly do that by adding a handler element into it . In addition to that there is no any hard coding stuffs for handler chain in anywhere in Axis2 (at any Axis*) , so all those configuration are also done here in phase order element. The complete configuration will look like as follows;
-
-<source><pre>
-<phaseOrder type="inflow"">
- <!-- System pre defined phases --">
- <phase name="TransportIn"/">
- <phase name="PreDispatch"/">
- <phase name="Dispatch"">
- <handler name="AddressingBasedDispatcher"
- class="org.apache.axis2.engine.AddressingBasedDispatcher"">
- <order phase="Dispatch"/">
- </handler">
- <handler name="RequestURIBasedDispatcher"
- class="org.apache.axis2.engine.RequestURIBasedDispatcher"">
- <order phase="Dispatch"/">
- </handler">
- <handler name="SOAPActionBasedDispatcher"
- class="org.apache.axis2.engine.SOAPActionBasedDispatcher"">
- <order phase="Dispatch"/">
- </handler">
- <handler name="SOAPMessageBodyBasedDispatcher"
- class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"">
- <order phase="Dispatch"/">
- </handler">
- </phase">
- <phase name="PostDispatch"">
- <handler name="DispatchPostConditionsEvaluator"
- class="org.apache.axis2.engine.DispatchingChecker"">
- <order phase="PostDispatch"/">
- </handler">
- <handler name="InstanceDispatcher"
- class="org.apache.axis2.engine.InstanceDispatcher"">
- <order phase="PostDispatch"/">
- </handler">
- <handler name="SOAPProcessingModelChecker"
- class="org.apache.axis2.engine.SOAPProcessingModelChecker"">
- <order phase="PostDispatch"/">
- </handler">
- </phase">
- <!-- System pre defined phases --">
- <!-- After Postdispatch phase module author or or service author can add any phase he want --">
- <phase name="userphase1"/">
- </phaseOrder">
- <phaseOrder type="outflow"">
- <!-- user can add his own phases to this area --">
- <phase name="userphase1"/">
- <!--system predefined phase--">
- <!--these phase 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="userphase1"/">
- </phaseOrder">
- <phaseOrder type="Outfaultflow"">
- <!-- user can add his own phases to this area --">
- <phase name="userphase1"/">
- <phase name="PolicyDetermination"/">
- <phase name="MessageOut"/">
- </phaseOrder">
-</pre></source>
-
-type: the attribute represent type of the flow and which can only be one of the following
-</p>
-<ul>
-<li>inflow</li>
-<li>outflow</li>
-<li>INfaultflow</li>
-<li>Outfaultflow</li>
-</ul>
-
-<p>In addition to that only child element allowed inside pahseOrder is phase
-element, which represents available phases in the execution chain.
-The way of specifying phase inside phaseOrder has to be done as follows;
-<source><pre>
- <phase name="TransportIn"/>
-</pre></source>
-name: Name of the phase.
-<br>
-There are number of things that one has to keep in mind when changing pahseOrder,
-<ul>
-<ol>there are phases called system pre-defined phases in all four flows;</ol>
-<ol>You are not allowed change those , and you can add new phase after system pre-defined phase</ol
-<ol>If you closely look at the default axis2.xml can clearly identify that. </ol>
-</ul>
-</p>
-<p>
-<b>Module References</b><br>
-If you want to engage a module system wide you can do it by adding top
-level module element in axis2.xml. It should be look like following:
-<source><pre>
-<module ref="addressing"/>
-</pre></source>
-ref: the module name which is going to be engage, system wide.
-
-Listeners (Observers)
-In Axis2 AxisConfiguration is observable so that one can register observers into
-that, and they will be automatically informed whenever a change occurs in
-AxisConfiuration. In the current implementation the observers are informed of the following events
-
-<ul>
-<li>Deploying a Service</li>
-<li>Removing a service</li>
-<li>Changing a service</li>
-</ul>
-Registering Observers is very useful for additional features such as RSS feed
-generation which will provide service information to subscribers. The correct
- way of registering observers should be like below;
-<source><pre>
-<listener class="org.apache.axis2.ObserverIMPL">
- <parameter name="RSS_URL" >http://127.0.0.1/rss</parameter>
- </listener>
-</pre></source>
-class: Represent an Implementation class of observer, and it should be note
- that the implementation class should implement AxisObserver interface,
- and the class has to be available in the classpath.
-</p>
-
-<br>
-
-<font color="blue"><b>Service Configuration</b></font>
-<li><a name="service"></a>Writing services.xml</li>
-<p>
-The description of service is specified using services.xml, each service archive
-file need to have services.xml in order to be a valid service. And which has to be
-available in META-INF directory of the archive file.
-<br>
-A very simple services.xml is shown below:
-<source><pre>
-<service >
- <description> The description of the service </description>
-
- <parameter name="ServiceClass" locked="xsd:false">org.apache.axis2.sample.echo.EchoImpl</parameter>
-
- <operation name="echoString">
- <module ref=" a module name "/>
- <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
- </operation>
- </service>
-</source></pre>
-
-service name: the service name will be the name of the archive file.
-<br>
-description: This is an optional element if you want to display any description
-about the service via Axis2 web-admin module then the description can be specified here.
-</p>
-<p>
-<b>Parameter:</b><br>
-services.xml can have any number of top level parameters and all the specified
-parameters will be transformed into service properties in corresponding ServiceDescrption.
-There is a compulsory parameter in a services.xml called ServiceClass which specify the
-java class which really does the job and the class will be loaded by MessageReceiver.
-</p>
-<p>
-<b>Handler</b><br>
-Handler element consists of compulsory and optional attribute and the way of defining a handler will be look like follows;
-<source><pre>
-<handler name="handler1" class="handlerClass ">
- <order phase="userphase1" />
- </handler>
-</source></pre>
-
-<b><i>Compulsory attributes</i></b> <br>
-name: name of the handler<br>
-nlass: handler implementation class<br>
-phase: name of the phase that the handler should stay in the execution chain
-<br><br>
-<i><b>Optional attributes :</b></i><br>
-phaseLast: to indicate the handler is last handler of the phase<br>
-phaseFirst: to indicate the handler is first handler of the phase.<br>
-before : the handler should be invoked before the handler specified by before handler<br>
-after: the handler should be invoked after the handler specified by after handler<br>
-</p>
-<p>
-<b>Operations</b><br>
-All the operations you are going to exposeby the service has to be indicated in the services.xml and the correct way of specifying that should be as follows:
- <source><pre>
- <operation name="echoString">
- <module ref=" a module name "/>
- <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
- </operation>
-</source></pre>
-Only compulsory attribute here is name, which represent the operation name that is going to be exposed. Any operation can contains module references, any number of parameters. The most interesting is that one can register custom message receiver per operation, then the registered message receiver will be the message receiver for the corresponding operation. If one does not specify the message receiver then the default message receiver will do the job.
-</p>
-<br>
-
-<font color="blue"><b>Module Configuration</b></font>
-<li><a name="module"></a>Writing module.xml</li>
-<p>
-The description of module is specified using module.xml, each module archive file need to have module.xml in order to be a valid module. And which has to be available in META-INF directory of the archive file.
-<br>
-A very simple module.xml is shown below:
-<source><pre>
-<module name="module1" class="org.apache.module.Module1Impl">
- <inflow>
-
.
- </inflow>
- <outflow>
-
- </outflow>
-
- <Outfaultflow>
-
..
- </Outfaultflow>
-
- <INfaultflow>
-
.
- </INfaultflow>
-
- <operation name="creatSeq" mep="MEP_URI_IN_OUT">
- <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
- <parameter name="para1" locked="xsd:true">10</parameter>
- </operation>
-</module>
-</source></pre>
-
-name: This is a compulsory attribute and which indicates the name of the module
-<br>
-class: This is an optional attribute which indicate module implementation class, a module may or may not contain module implementation class since the module can also be a collection of handlers. If a module contains an implementation class which implements the org.apache.axis2.modules.Module inteface where at the deployment time its init(); method will be called.
-</p>
-
-<p>
-<b>parameter:</b>
-Module can contains any number of parameters and all the listed parameters in the module.xml will be transformed into corresponding ModuleDescription of the module.
-</p
-<p>
-<b>Flow :</b><br>
-It is possible to add handlers into a flow directly form services.xml rather than
-engaging a modules and the way of doing that is through flow elements.
-It is possible to add any number of handlers into a flow and those handlers
-will be available in corresponding operations flows in the service
-(inflow consist of two parts, one part is up to post dispatch phase and other
-part is consisting of operation handlers)
-<br>
-There are four types of valid flows that can be available in services.xml,
- and the adding the handles into them can be done by following the above procedure.
-<br>
-Valid flows:
-<ul>
-<li>Inflow</li>
-<li>outflow</li>
-<li>INfaultflow</li>
-<li>Outfaultflow</li>
-</ul>
-</p>
-
-<p>
-<b>operations</b>
-If a module wants to add an operation when it is engaged into a service it can be done by adding operation tag in module.xml and the way of specifying the operation is same as operation in services.xml.
-
-</p>
-<br>
-
-
-</body>
-</html>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Axis2 Configuration Documents</title>
+</head>
+
+<body>
+<p>In Axis2 there are three kinds of configuration files to configure the
+system. First one configuration file is to configure whole system, second one
+is to configure a service and the third one is to configure a module.</p>
+<ul>
+ <li><a href="#Global_Configuration">Global Configuration
+ (axis2.xml)</a></li>
+ <li><a href="#Service_Configuration">Service Configuration
+ (services.xml)</a></li>
+ <li><a href="#Module_Configuration">Module Configuration
+ (module.xml)</a></li>
+</ul>
+
+<h2><a name="Global_Configuration">Global Configuration</a></h2>
+<ul>
+ <li>Writing axis2.xml</li>
+</ul>
+
+<p>All the configuration that requires starting axis2 is obtained from
+axis2.xml. The way of specifying them is very simple and easy. The document
+is all about the proper way of specifying the configurations in axis2.xml.
+There are six top level elements that can be seen in the configuration file
+and those can be listed as follows;</p>
+<ul>
+ <li>Parameter</li>
+ <li>Transport Receiver</li>
+ <li>Transport Sender</li>
+ <li>Phase Order</li>
+ <li>Module References</li>
+ <li>Listeners (Observers)</li>
+</ul>
+
+<p><b>Parameter </b> <br>
+In axis2 a parameter is nothing but name value pair, each and every top level
+parameter available in the axis2.xml (direct sub elements of root element)
+will be transformed into properties in AxisConfiguration. Therefore the top
+level parameters in configuration document can be accessed via
+AxisConfiguration in the running system. The correct way of defining a
+parameter looks like what is shown below; <source></p>
+<pre>
+ <parameter name="name of the parameter" >parameter value </parameter></pre>
+</source>
+<p><b>Transport Receiver</b><br>
+Depending on the underline transport that axis going to be run , need to have
+different transport receivers so the way of adding them to the system can be
+done as follows; <source></p>
+<pre>
+<transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer">
+ <parameter name="port" >6060</parameter>
+ </transportReceiver>
+ </pre>
+</source>The above elements shows the way of defining transport receivers in
+axis2.xml , here name attribute of the 'transportReceiver' element is the
+name of transport it can be http, tcp , smtp , commonshttp stc , and when the
+system starts up or when setting transport at the client side one can use
+these transport names to load the appropriate transport. Class attribute is
+to specify actual java class which implements required interfaces for the
+transport. Any transport can have zero or more parameters, and if there are
+any, then those parameters can be accessed via the corresponding transport
+receiver.
+
+<p><b>Transport Senders</b><br>
+As same as transport receivers it is possible to register transport senders
+in the system, and latter at the run time those senders can be used to send
+the messages. As an example consider Axis2 running under tomcat, then axis
+can use TCP transport senders to send message rather than HTTP. The way of
+specifying transport senders is as follows: <source></p>
+<pre>
+<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+ <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0</parameter>
+ </transportSender>
+ </pre>
+</source>name: Name of the transport (it is possible to have http and http1
+as transport name) Class: Implementation class of the corresponding
+transport. As same as transport receivers, transport senders can have zero or
+more parameters, and if there is any then it can be accessed via
+corresponding transport sender.
+
+<p><b>Phase Order</b><br>
+The specifying order of phases in execution chain has to be done using phase
+order element and it will be look like below; <source></p>
+<pre><phaseOrder type="inflow">
+ <phase name="TransportIn"/>
+ .
+ .
+</phaseOrder> </pre>
+</source>The most interesting thing is that you can add handlers here as well
+, if you want to add a handler which should go in to that phase you can
+directly do that by adding a handler element into it . In addition to that
+there is no any hard coding stuffs for handler chain in anywhere in Axis2
+(at any Axis*) , so all those configuration are also done here in phase order
+element. The complete configuration will look like as follows; <source>
+<pre><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.engine.AddressingBasedDispatcher"">
+ <order phase="Dispatch"/">
+ </handler">
+ <handler name="RequestURIBasedDispatcher"
+ class="org.apache.axis2.engine.RequestURIBasedDispatcher"">
+ <order phase="Dispatch"/">
+ </handler">
+ <handler name="SOAPActionBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPActionBasedDispatcher"">
+ <order phase="Dispatch"/">
+ </handler">
+ <handler name="SOAPMessageBodyBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"">
+ <order phase="Dispatch"/">
+ </handler">
+ <handler name="InstanceDispatcher"
+ class="org.apache.axis2.engine.InstanceDispatcher"">
+ <order phase="Dispatch"/">
+ </handler">
+ </phase">
+ <!-- Sysem pre defined phases --">
+ <!-- After Postdispatch phase module author or or service author can add any phase he want --">
+ <phase name="userphase1"/">
+ </phaseOrder">
+ <phaseOrder type="outflow"">
+ <!-- user can add his own phases to this area --">
+ <phase name="userphase1"/">
+ <!--system predefined phase--">
+ <!--these phase 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="userphase1"/">
+ </phaseOrder">
+ <phaseOrder type="Outfaultflow"">
+ <!-- user can add his own phases to this area --">
+ <phase name="userphase1"/">
+ <phase name="PolicyDetermination"/">
+ <phase name="MessageOut"/">
+ </phaseOrder"></pre>
+</source>type: the attribute represent type of the flow and which can only be
+one of the following
+<ul>
+ <li>inflow</li>
+ <li>outflow</li>
+ <li>INfaultflow</li>
+ <li>Outfaultflow</li>
+</ul>
+
+<p>In addition to that only child element allowed inside pahseOrder is phase
+element, which represents available phases in the execution chain. The way of
+specifying phase inside phaseOrder has to be done as follows; <source></p>
+<pre> <phase name="TransportIn"/></pre>
+</source>name: Name of the phase. <br>
+There are number of things that one has to keep in mind when changing
+pahseOrder,
+<ul>
+</ul>
+<ol>
+ there are phases called system pre-defined phases in all four flows;</ol>
+<ol>
+ You are not allowed change those , and you can add new phase after system
+ pre-defined phase</ol>
+<ol>
+ If you closely look at the default axis2.xml can clearly identify that.</ol>
+
+<p><b>Module References</b><br>
+If you want to engage a module system wide you can do it by adding top level
+module element in axis2.xml. It should be look like following: <source></p>
+<pre><module ref="addressing"/> </pre>
+</source>ref: the module name which is going to be engage, system wide.
+Listeners (Observers) In Axis2 AxisConfiguration is observable so that one
+can register observers into that, and they will be automatically informed
+whenever a change occurs in AxisConfiuration. In the current implementation
+the observers are informed of the following events
+<ul>
+ <li>Deploying a Service</li>
+ <li>Removing a service</li>
+ <li>Changing a service</li>
+</ul>
+Registering Observers is very useful for additional features such as RSS feed
+generation which will provide service information to subscribers. The correct
+way of registering observers should be like below; <source>
+<pre><listener class="org.apache.axis2.ObserverIMPL">
+ <parameter name="RSS_URL" >http://127.0.0.1/rss</parameter>
+ </listener></pre>
+</source>class: Represent an Implementation class of observer, and it should
+be note that the implementation class should implement AxisObserver
+interface, and the class has to be available in the classpath.
+
+<h2><font><a name="Service_Configuration">Service
+Configuration</a></font></h2>
+<ul>
+ <li><font>Writing services.xml</font></li>
+</ul>
+
+<p><font>The description of service is specified using services.xml, each
+service archive file need to have services.xml in order to be a valid
+service. And which has to be available in META-INF directory of the archive
+file. <br>
+A very simple services.xml is shown below: </font><font><source></font></p>
+<pre><font><service >
+ <description> The description of the service </description>
+
+ <parameter name="ServiceClass" locked="xsd:false">org.apache.axis2.sample.echo.EchoImpl</parameter>
+
+ <operation name="echoString">
+ <module ref=" a module name "/>
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ </service>
+</font><font></source></font></pre>
+<font>service name: the service name will be the name of the archive file.
+<br>
+description: This is an optional element if you want to display any
+description about the service via Axis2 web-admin module then the description
+can be specified here.</font>
+
+<p><b>Parameter:</b><br>
+services.xml can have any number of top level parameters and all the
+specified parameters will be transformed into service properties in
+corresponding ServiceDescrption. There is a compulsory parameter in a
+services.xml called ServiceClass which specify the java class which really
+does the job and the class will be loaded by MessageReceiver.</p>
+
+<p><b>Handler</b><br>
+Handler element consists of compulsory and optional attribute and the way of
+defining a handler will be look like follows; <source></p>
+<pre><handler name="handler1" class="handlerClass ">
+ <order phase="userphase1" />
+ </handler>
+</source></pre>
+<b><i>Compulsory attributes</i></b> <br>
+name: name of the handler<br>
+nlass: handler implementation class<br>
+phase: name of the phase that the handler should stay in the execution chain
+<br>
+<br>
+<i><b>Optional attributes :</b></i><br>
+phaseLast: to indicate the handler is last handler of the phase<br>
+phaseFirst: to indicate the handler is first handler of the phase.<br>
+before : the handler should be invoked before the handler specified by before
+handler<br>
+after: the handler should be invoked after the handler specified by after
+handler<br>
+
+
+<p><b>Operations</b><br>
+All the operations you are going to exposeby the service has to be indicated
+in the services.xml and the correct way of specifying that should be as
+follows: <source></p>
+<pre> <operation name="echoString">
+ <module ref=" a module name "/>
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+</source></pre>
+Only compulsory attribute here is name, which represent the operation name
+that is going to be exposed. Any operation can contains module references,
+any number of parameters. The most interesting is that one can register
+custom message receiver per operation, then the registered message receiver
+will be the message receiver for the corresponding operation. If one does not
+specify the message receiver then the default message receiver will do the
+job. <br>
+
+
+<h2><a name="Module_Configuration">Module Configuration</a></h2>
+<ul>
+ <li>Writing module.xml</li>
+</ul>
+
+<p>The description of module is specified using module.xml, each module
+archive file need to have module.xml in order to be a valid module. And which
+has to be available in META-INF directory of the archive file. <br>
+A very simple module.xml is shown below: <source></p>
+<pre><module name="module1" class="org.apache.module.Module1Impl">
+ <inflow>
+ .
+ .
+ </inflow>
+ <outflow>
+ .
+ .
+ </outflow>
+
+ <Outfaultflow>
+ .
+ .
+ </Outfaultflow>
+
+ <INfaultflow>
+ .
+ .
+ </INfaultflow>
+
+ <operation name="creatSeq" mep="MEP_URI_IN_OUT">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ <parameter name="para1" locked="xsd:true">10</parameter>
+ </operation>
+</module>
+</source></pre>
+name: This is a compulsory attribute and which indicates the name of the
+module <br>
+class: This is an optional attribute which indicate module implementation
+class, a module may or may not contain module implementation class since the
+module can also be a collection of handlers. If a module contains an
+implementation class which implements the org.apache.axis2.modules.Module
+inteface where at the deployment time its init(); method will be called.
+
+<p><b>parameter:</b> Module can contains any number of parameters and all the
+listed parameters in the module.xml will be transformed into corresponding
+ModuleDescription of the module.</p>
+
+<p><b>Flow :</b><br>
+It is possible to add handlers into a flow directly form services.xml rather
+than engaging a modules and the way of doing that is through flow elements.
+It is possible to add any number of handlers into a flow and those handlers
+will be available in corresponding operations flows in the service (inflow
+consist of two parts, one part is up to post dispatch phase and other part is
+consisting of operation handlers) <br>
+There are four types of valid flows that can be available in services.xml,
+and the adding the handles into them can be done by following the above
+procedure. <br>
+Valid flows:</p>
+<ul>
+ <li>Inflow</li>
+ <li>outflow</li>
+ <li>INfaultflow</li>
+ <li>Outfaultflow</li>
+</ul>
+
+<p><b>operations</b> If a module wants to add an operation when it is engaged
+into a service it can be done by adding operation tag in module.xml and the
+way of specifying the operation is same as operation in services.xml.</p>
+<br>
+</body>
+</html>
Modified: webservices/axis2/trunk/java/xdocs/0_94/index.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/index.html?rev=368278&r1=368277&r2=368278&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/index.html (original)
+++ webservices/axis2/trunk/java/xdocs/0_94/index.html Wed Jan 11 21:10:09 2006
@@ -1,69 +1,77 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-"http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-<title>Axis2 0.94 Documentation</title>
-</head>
-
-<body>
-<h2>Getting Started Guides for Axis2 - 0.94 </h2>
-<ul>
- <li><a href="installationguide.html">Installation Guide</a></li>
- <li><a href="userguide.html">User's Guide</a></li>
- <li><a href="webadminguide.html">Web Administration Guide </a></li>
-</ul>
-<h2>Additional References</h2>
-<ul>
- <li><a href="http://wiki.apache.org/ws/FrontPage/Axis2">Axis2 Wiki</a></li>
- <li><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li>
- <li><a href="OMTutorial.html">AXIOM Tutorial</a></li>
- <li><a href="CodegenToolReference.html">Code Generation Tutorial</a></li>
- <li><a href="rest-ws.html">REST Support</a></li>
- <li> <a href="mtom-guide.html">Handling Binary Data with Axis2</a></li>
- <li> <a href="axis2config.html">Axis2 Configuration Guide</a></li>
- <li> <a href="api/index.html">Online Java Docs</a></li>
- <li> <a href="adb/adb-howto.html">ADB How-to</a></li>
- <li> <a href="security-module.html">WS-Security How-to</a></li>
-</ul>
-<h2>Other Tutorials </h2>
-<h3>Axis2</h3>
-<ul>
- <li><a
- href="http://www.jaxmagazine.com/itr/online_artikel/psecom,id,747,nodeid,147.html">Axis2
- - The Future of Web Services</a>
- </li>
- <li>
- <a
- href="http://www.developer.com/services/article.php/3525481">Introducing
- Axis2</a>
- </li>
- <li><a href="http://www.onjava.com/pub/a/onjava/2005/07/27/axis2.html">Web
- Services Messaging with Apache Axis2: Concepts and Techniques</a></li>
- <li><a href="http://developer.com/java/web/article.php/3529321">Axis2
- Execution Framework</a>
- </li>
- <li><a
- href="http://jaxmag.com/itr/online_artikel/psecom,id,757,nodeid,147.html">Axis2
- Deployment Model</a>
- </li>
- <li><a
- href="http://www.developer.com/open/article.php/3557741">Undertanding Axis2 Deployment Architecture</a>
- </li>
-
-</ul>
-
-<h3>AXIOM</h3>
-<ul>
- <li><a
- href="http://www.jaxmag.com/itr/online_artikel/psecom,id,726,nodeid,147.html">Fast
- and Lightweight Object Model for XML </a> - An Introduction to AXIOM, the
- Open Source API for Working with XML
- </li>
- <li><a href="http://www-128.ibm.com/developerworks/library/x-axiom/">Get
- the most out of XML processing with AXIOM</a> - Explaining the
- flexibilities of AXIOM in developerworks.
- </li>
-</ul>
-</body>
-</html>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+ <title>Axis2 0.94 Documentation</title>
+</head>
+
+<body>
+<h2>Getting Started Guides for Axis2 - 0.94</h2>
+<ul>
+ <li><a href="installationguide.html">Installation Guide</a></li>
+ <li><a href="userguide.html">User's Guide</a></li>
+ <li><a href="webadminguide.html">Web Administration Guide</a></li>
+</ul>
+
+<h2>Tools References</h2>
+<ul>
+ <li><a href="CodegenToolReference.html">Code Generator Wizard - Command
+ Line Tool</a></li>
+ <li><a href="CodegenTools-EclipsePlugin.html">Code Generator Wizard -
+ Eclipse Plug-in</a></li>
+ <li><a href="ServiceArchiveToolReference.html">Service Archive Wizard -
+ Eclipse Plug-in</a></li>
+ <li><a href="tools\idea\Idea_plug-in_userguide.html">IntelliJ IDEA
+ Plug-ins</a></li>
+</ul>
+
+<h2>Additional References</h2>
+<ul>
+ <li><a href="http://wiki.apache.org/ws/FrontPage/Axis2">Axis2 Wiki</a></li>
+ <li><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li>
+ <li><a href="OMTutorial.html">AXIOM Tutorial</a></li>
+ <li><a href="CodegenToolReference.html">Code Generation Tutorial</a></li>
+ <li><a href="rest-ws.html">REST Support</a></li>
+ <li><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li>
+ <li><a href="axis2config.html">Axis2 Configuration Guide</a></li>
+ <li><a href="api/index.html">Online Java Docs</a></li>
+ <li><a href="adb/adb-howto.html">ADB How-to</a></li>
+ <li><a href="security-module.html">WS-Security How-to</a></li>
+</ul>
+
+<h2>Other Tutorials</h2>
+
+<h3>Axis2</h3>
+<ul>
+ <li><a>Axis2 - The Future of Web Services</a></li>
+ <li><a
+ href="http://www.developer.com/services/article.php/3525481">Introducing
+ Axis2</a></li>
+ <li><a href="http://www.onjava.com/pub/a/onjava/2005/07/27/axis2.html">Web
+ Services Messaging with Apache Axis2: Concepts and Techniques</a></li>
+ <li><a href="http://developer.com/java/web/article.php/3529321">Axis2
+ Execution Framework</a></li>
+ <li><a
+ href="http://jaxmag.com/itr/online_artikel/psecom,id,757,nodeid,147.html">Axis2
+ Deployment Model</a></li>
+ <li><a
+ href="http://www.developer.com/open/article.php/3557741">Undertanding
+ Axis2 Deployment Architecture</a></li>
+ <li><a
+ href="http://www.developer.com/java/other/article.php/3570031">Utilizing
+ a Non-Java Web Servive with Axis2</a></li>
+</ul>
+
+<h3>AXIOM</h3>
+<ul>
+ <li><a
+ href="http://www.jaxmag.com/itr/online_artikel/psecom,id,726,nodeid,147.html">Fast
+ and Lightweight Object Model for XML </a> - An Introduction to AXIOM, the
+ Open Source API for Working with XML</li>
+ <li><a href="http://www-128.ibm.com/developerworks/library/x-axiom/">Get
+ the most out of XML processing with AXIOM</a> - Explaining the
+ flexibilities of AXIOM in developerworks.</li>
+</ul>
+</body>
+</html>
Modified: webservices/axis2/trunk/java/xdocs/0_94/mtom-guide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/mtom-guide.html?rev=368278&r1=368277&r2=368278&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/mtom-guide.html (original)
+++ webservices/axis2/trunk/java/xdocs/0_94/mtom-guide.html Wed Jan 11 21:10:09 2006
@@ -1,459 +1,445 @@
-<html>
-<head>
- <meta http-equiv="content-type" content="">
- <title>Sending Binary data with SOAP</title>
-</head>
-
-<body>
-<h1>Sending Binary Data with SOAP</h1>
-<ul>
- <li><a href="#1">Introduction</a></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>
- </ul>
- </li>
- <li><a href="#3">SOAP with Attachments with Axis2</a></li>
- <li><a href="#4">Advanced Topics </a>
- <ul>
- <li><a href="#41">File Caching for Attachments</a></li>
- </ul>
- </li>
-</ul>
-
-<p><a name="1"></a></p>
-
-<h2>Introduction</h2>
-
-<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>
-Traditionally, two techniques have been used in dealing with opaque data in
-XML;</p>
-<ol>
- <li><strong>"By value"</strong></li>
-
- <blockquote>
- <p>Sending binary data by value is achieved by embedding opaque data (of
- course after some form of encoding) as 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 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>
- <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
- 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">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>
- </blockquote>
- </li>
-</ol>
-
-<p><a href="http://www.w3.org/TR/2004/PR-soap12-mtom-20041116/">MTOM (SOAP
-Message Transmission Optimization Mechanism)</a> is another specification
-which focuses on solving the "Attachments" problem. MTOM tries to leverage
-the advantages of above two techniques by trying to merge the two techniques.
-MTOM is actually a "by reference" method. Wire format of a MTOM optimized
-message is same as the Soap with Attachments message, which also makes it
-backward compatible with SwA endpoints. The most notable feature of MTOM is
-the use of XOP:Include element, which is defined in <a
-href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XML Binary Optimized
-Packaging (XOP)</a> specification to reference the binary attachments
-(external unparsed general entities) of the message. With the use of this
-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. 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> & <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 (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
-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
-base64encoded binary data is qualified to be optimized or not at the
-construction time of that node or later. To take the optimum efficiency of
-MTOM a user is advised to send smaller binary attachments using
-base64encoding (None optimized) and larger attachments as optimized
-content.</p>
-<source><pre> OMElement imageElement = fac.createOMElement("image", omNs);
-
- // Creating the Data Handler for the image.
- // User has the option to use a FileDataSource or a ImageDataSource
- // in this scenario...
- Image image;
- image = new ImageIO()
- .loadImage(new FileInputStream(inputImageFileName));
- ImageDataSource dataSource = new ImageDataSource("test.jpg",image);
- DataHandler dataHandler = new DataHandler(dataSource);
-
- //create an OMText node with the above DataHandler and set optimized to true
- OMText textData = fac.createText(dataHandler, true);
- imageElement.addChild(textData);
-
- //User can set optimized to false by using the following
- //textData.doOptimize(false);</pre>
-</source>
-<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>
-<source><pre> String base64String = "some_string";
- OMText binaryNode = fac.createText(base64String,"image/jpg",true);</pre>
-</source>
-<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>
-<source><pre> //create an OMText node with the above DataHandler and set "optimized" to false
- //This data will be send as Base64 encoded string regardless of MTOM is enabled or not
- javax.activation.DataHandler dataHandler = new javax.activation.DataHandler(new FileDataHandler("someLocation"));
- OMText textData = fac.createText(dataHandler, false);
- image.addChild(textData);</pre>
-</source>
-<p></p>
-
-<p><a name="22"></a></p>
-
-<h2>Enabling MTOM optimization at client side</h2>
-
-<p>Set the "enableMTOM" property in the call to true, when sending
-messages.</p>
-<source><pre> ServiceClient serviceClient = new ServiceClient ();
- Options options = new Options();
- options.setTo(targetEPR);
- options.setProperty(Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);
- serviceClient .setOptions(options);</pre>
-</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 serialized 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. But due considering the policy assertions, there may
-be a policy saying, all the request should be optimized eventhough there are
-any optimized contents. To support this phenomenon there is an entry called
-"forced mime" which has to be set as</p>
-<source><pre> ServiceClient serviceClient = new ServiceClient ();
- Options options = new Options();
- options.setTo(targetEPR);
- options.setProperty(Constants.Configuration.FORCE_MIME, Constants.VALUE_TRUE);
- serviceClient.setOptions(options);</pre>
-</source>
-<p></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-serialize any MTOM message 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. User can enableMTOM
-in the server side for outgoing messages,</p>
-<ul>
- <li>Globally for all services
-
- <blockquote>
- <p>add and set 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 MTOM optimized messages. If it
- is not set all the binary data in binary content nodes will be
- serialized as Base64 encoded strings.</p>
- </blockquote>
- </li>
-</ul>
-
-<p><source></p>
-<pre><parameter name="enableMTOM" locked="false">true</parameter></pre>
-</source><ul>
- <ul>
- <p>User must restart the server after setting this parameter.</p>
- </ul>
-</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>public class MTOMService {
- public OMElement mtomSample(OMElement element) throws Exception {
- OMElement imageEle = element.getFirstElement();
- OMElement imageName = (OMElement) imageEle.getNextSibling();
- OMText binaryNode = (OMText) imageEle.getFirstChild();
- String fileName = imageName.getText();
-
- //Extracting the data and saving
- DataHandler actualDH;
- actualDH = binaryNode.getDataHandler();
- Image actualObject = new ImageIO().loadImage(actualDH.getDataSource()
- .getInputStream());
- FileOutputStream imageOutStream = new FileOutputStream(fileName);
- new JDK13IO().saveImage("image/jpeg", actualObject, imageOutStream);
-
- //setting response
- OMFactory fac = OMAbstractFactory.getOMFactory();
- OMNamespace ns = fac.createOMNamespace("urn://fakenamespace", "ns");
- OMElement ele = fac.createOMElement("response", ns);
- ele.setText("Image Saved");
- return ele;
- }
-}</pre>
-</source><ul>
- <li><strong><a name="242"></a>Client</strong></li>
-</ul>
-<source><pre> Options options = new Options();
- options.setTo(targetEPR);
- // enabling MTOM
- options.set(Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);
- options.setTransportInfo(Constants.TRANSPORT_HTTP,
- Constants.TRANSPORT_HTTP, false);
- options.setSoapVersionURI(SOAP12Constants.SOAP_ENVELOPE_NAMESPACE_URI);
-
- OMElement result = (OMElement) call.invokeBlocking(operationName.
- getLocalPart(),payload);
- OMElement ele = (OMElement) result.getFirstChild();
- OMText binaryNode = (OMText) ele.getFirstChild();
-
- // Retrieving the DataHandler & then do whatever the processing to the data
- DataHandler actualDH;
- actualDH = binaryNode.getDataHandler();
- Image actualObject = new ImageIO().loadImage(actualDH.getDataSource()
- .getInputStream());</pre>
-</source>
-<p><a name="3"></a></p>
-
-<h1>SOAP with Attachments (SwA) with Axis2</h1>
-
-<p>Axis2 Handles SwA messages at the inflow only. When Axis2 receives a SwA
-message it extracts the binary attachment parts and puts a reference to those
-parts in the Message Context. Users can access binary attachments using the
-content-id. Care should be taken to rip off the "cid" prefix when content-id
-is taken from the "Href" attributes. When accessing the message context from
-a service users need to use the message context injection mechanism by
-introducing an "init" method to the service class.(see the following service
-example)</p>
-
-<p>Note: Axis2 supports content-id referencing only. Axis2 does not support
-Content Location referencing of MIME parts.</p>
-<ul>
- <li><strong>Sample service which accepts a SwA message</strong></li>
-</ul>
-<source><pre>public class EchoSwA {
- private MessageContext msgcts;
-
- public void init(MessageContext msgcts) {
- this.msgcts = msgcts;
- }
-
- public OMElement echoAttachment(OMElement omEle) {
- OMElement child = (OMElement)omEle.getFirstChild();
- //retreiving the Href attribute which contains the Content Id
- OMAttribute attr = (OMAttribute)child.getFirstAttribute(new QName("href"));
- String contentID = attr.getValue();
- //content-id processing to remove the "cid" prefix
- contentID = contentID.trim();
- if (contentID.substring(0, 3).equalsIgnoreCase("cid")) {
- contentID = contentID.substring(4);
- }
-
- // Retrieving the MIMEHelper instance (which contains reference to attachments)
- // from the Message Context
- MIMEHelper attachments = (MIMEHelper)msgcts.getProperty(MIMEHelper.ATTACHMENTS);
- // Retrieving the respective DataHandler referenced by the content-id
- DataHandler dataHandler = attachments.getDataHandler(contentID);
-
- // Echoing back the attachment. Sends out MTOM message
- OMText textNode = new OMTextImpl(dataHandler);
- omEle.build();
- child.detach();
- omEle.addChild(textNode);
- return omEle;
- }
-}</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 optimized message is a valid
-SwA message. Because of that Axis2 does not define a separate 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>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>
-</source><ul>
- <li><strong>Corresponding MTOM message from Axis2</strong></li>
-</ul>
-<source><pre>Content-Type: multipart/related; boundary=MIMEBoundary4A7AE55984E7438034;
- type="application/xop+xml"; start="<0....@apache.org>";
- start-info="text/xml; charset=utf-8"
-
---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....@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 bigger than
-the threshold value will get cached in files. Smaller attachments will remain
-in Memory.</p>
-
-<p>NOTE : It is a must to specify a directory to temporary store the
-attachments. Also care should be taken to *clean that directory* from time to
-time.</p>
-
-<p>The following parameters need to be set in Axis2.xml in order to enable
-file caching.</p>
-<source><pre><em><axisconfig name="AxisJava2.0">
- <!-- ================================================= -->
- <!-- Parameters -->
- <!-- ================================================= --></em>
- <parameter name="cacheAttachments" locked="xsd:false">true</parameter>
- <parameter name="attachmentDIR" locked="xsd:false"><em>temp directory</em></parameter>
- <parameter name="sizeThreshold" locked="xsd:false">4000</parameter>
- .........
- .........
-</axisconfig></pre>
-</source></body>
-</html>
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Sending Binary data with SOAP</title>
+</head>
+
+<body>
+<h1>Sending Binary Data with SOAP</h1>
+<ul>
+ <li><a href="#1">Introduction</a></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>
+ </ul>
+ </li>
+ <li><a href="#3">SOAP with Attachments with Axis2</a></li>
+ <li><a href="#4">Advanced Topics </a>
+ <ul>
+ <li><a href="#41">File Caching for Attachments</a></li>
+ </ul>
+ </li>
+</ul>
+
+<h2>Introduction</h2>
+
+<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>
+Traditionally, two techniques have been used in dealing with opaque data in
+XML;</p>
+<ol>
+ <li><strong>"By value"</strong></li>
+
+ <blockquote>
+ <p>Sending binary data by value is achieved by embedding opaque data (of
+ course after some form of encoding) as 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 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>
+ <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
+ 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">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>
+ </blockquote>
+ </li>
+</ol>
+
+<p><a href="http://www.w3.org/TR/2004/PR-soap12-mtom-20041116/">MTOM (SOAP
+Message Transmission Optimization Mechanism)</a> is another specification
+which focuses on solving the "Attachments" problem. MTOM tries to leverage
+the advantages of above two techniques by trying to merge the two techniques.
+MTOM is actually a "by reference" method. Wire format of a MTOM optimized
+message is same as the Soap with Attachments message, which also makes it
+backward compatible with SwA endpoints. The most notable feature of MTOM is
+the use of XOP:Include element, which is defined in <a
+href="http://www.w3.org/TR/2004/PR-xop10-20041116/">XML Binary Optimized
+Packaging (XOP)</a> specification to reference the binary attachments
+(external unparsed general entities) of the message. With the use of this
+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. 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> & <strong>MTOM (SOAP Message Transmission
+Optimization Mechanism).</strong></p>
+
+<h1>MTOM with Axis2</h1>
+
+<h2>Programming Model</h2>
+
+<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
+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
+base64encoded binary data is qualified to be optimized or not at the
+construction time of that node or later. To take the optimum efficiency of
+MTOM a user is advised to send smaller binary attachments using
+base64encoding (None optimized) and larger attachments as optimized
+content.</p>
+<source><pre> OMElement imageElement = fac.createOMElement("image", omNs);
+
+ // Creating the Data Handler for the image.
+ // User has the option to use a FileDataSource or a ImageDataSource
+ // in this scenario...
+ Image image;
+ image = new ImageIO()
+ .loadImage(new FileInputStream(inputImageFileName));
+ ImageDataSource dataSource = new ImageDataSource("test.jpg",image);
+ DataHandler dataHandler = new DataHandler(dataSource);
+
+ //create an OMText node with the above DataHandler and set optimized to true
+ OMText textData = fac.createText(dataHandler, true);
+ imageElement.addChild(textData);
+
+ //User can set optimized to false by using the following
+ //textData.doOptimize(false);</pre>
+</source>
+<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>
+<source><pre> String base64String = "some_string";
+ OMText binaryNode = fac.createText(base64String,"image/jpg",true);</pre>
+</source>
+<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>
+<source><pre> //create an OMText node with the above DataHandler and set "optimized" to false
+ //This data will be send as Base64 encoded string regardless of MTOM is enabled or not
+ javax.activation.DataHandler dataHandler = new javax.activation.DataHandler(new FileDataHandler("someLocation"));
+ OMText textData = fac.createText(dataHandler, false);
+ image.addChild(textData);</pre>
+</source>
+<h2>Enabling MTOM optimization at client side</h2>
+
+<p>Set the "enableMTOM" property in the call to true, when sending
+messages.</p>
+<source><pre> ServiceClient serviceClient = new ServiceClient ();
+ Options options = new Options();
+ options.setTo(targetEPR);
+ options.setProperty(Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);
+ serviceClient .setOptions(options);</pre>
+</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 serialized 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. But due considering the policy assertions, there may
+be a policy saying, all the request should be optimized eventhough there are
+any optimized contents. To support this phenomenon there is an entry called
+"forced mime" which has to be set as</p>
+<source><pre> ServiceClient serviceClient = new ServiceClient ();
+ Options options = new Options();
+ options.setTo(targetEPR);
+ options.setProperty(Constants.Configuration.FORCE_MIME, Constants.VALUE_TRUE);
+ serviceClient.setOptions(options);</pre>
+</source>
+<p></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-serialize any MTOM message 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. User can enableMTOM
+in the server side for outgoing messages,</p>
+<ul>
+ <li>Globally for all services
+
+ <blockquote>
+ <p>add and set 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 MTOM optimized messages. If it
+ is not set all the binary data in binary content nodes will be
+ serialized as Base64 encoded strings.</p>
+ </blockquote>
+ </li>
+</ul>
+
+<p><source></p>
+<pre><parameter name="enableMTOM" locked="false">true</parameter></pre>
+</source><ul>
+ <ul>
+ <p>User must restart the server after setting this parameter.</p>
+ </ul>
+</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>public class MTOMService {
+ public OMElement mtomSample(OMElement element) throws Exception {
+ OMElement imageEle = element.getFirstElement();
+ OMElement imageName = (OMElement) imageEle.getNextSibling();
+ OMText binaryNode = (OMText) imageEle.getFirstChild();
+ String fileName = imageName.getText();
+
+ //Extracting the data and saving
+ DataHandler actualDH;
+ actualDH = binaryNode.getDataHandler();
+ Image actualObject = new ImageIO().loadImage(actualDH.getDataSource()
+ .getInputStream());
+ FileOutputStream imageOutStream = new FileOutputStream(fileName);
+ new JDK13IO().saveImage("image/jpeg", actualObject, imageOutStream);
+
+ //setting response
+ OMFactory fac = OMAbstractFactory.getOMFactory();
+ OMNamespace ns = fac.createOMNamespace("urn://fakenamespace", "ns");
+ OMElement ele = fac.createOMElement("response", ns);
+ ele.setText("Image Saved");
+ return ele;
+ }
+}</pre>
+</source><ul>
+ <li><strong><a name="242"></a>Client</strong></li>
+</ul>
+<source><pre> Options options = new Options();
+ options.setTo(targetEPR);
+ // enabling MTOM
+ options.set(Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);
+ options.setTransportInfo(Constants.TRANSPORT_HTTP,
+ Constants.TRANSPORT_HTTP, false);
+ options.setSoapVersionURI(SOAP12Constants.SOAP_ENVELOPE_NAMESPACE_URI);
+
+ OMElement result = (OMElement) call.invokeBlocking(operationName.
+ getLocalPart(),payload);
+ OMElement ele = (OMElement) result.getFirstChild();
+ OMText binaryNode = (OMText) ele.getFirstChild();
+
+ // Retrieving the DataHandler & then do whatever the processing to the data
+ DataHandler actualDH;
+ actualDH = binaryNode.getDataHandler();
+ Image actualObject = new ImageIO().loadImage(actualDH.getDataSource()
+ .getInputStream());</pre>
+</source>
+<p><a name="3"></a></p>
+
+<h1>SOAP with Attachments (SwA) with Axis2</h1>
+
+<p>Axis2 Handles SwA messages at the inflow only. When Axis2 receives a SwA
+message it extracts the binary attachment parts and puts a reference to those
+parts in the Message Context. Users can access binary attachments using the
+content-id. Care should be taken to rip off the "cid" prefix when content-id
+is taken from the "Href" attributes. When accessing the message context from
+a service users need to use the message context injection mechanism by
+introducing an "init" method to the service class.(see the following service
+example)</p>
+
+<p>Note: Axis2 supports content-id referencing only. Axis2 does not support
+Content Location referencing of MIME parts.</p>
+<ul>
+ <li><strong>Sample service which accepts a SwA message</strong></li>
+</ul>
+<source><pre>public class EchoSwA {
+ private MessageContext msgcts;
+
+ public void init(MessageContext msgcts) {
+ this.msgcts = msgcts;
+ }
+
+ public OMElement echoAttachment(OMElement omEle) {
+ OMElement child = (OMElement)omEle.getFirstChild();
+ //retreiving the Href attribute which contains the Content Id
+ OMAttribute attr = (OMAttribute)child.getFirstAttribute(new QName("href"));
+ String contentID = attr.getValue();
+ //content-id processing to remove the "cid" prefix
+ contentID = contentID.trim();
+ if (contentID.substring(0, 3).equalsIgnoreCase("cid")) {
+ contentID = contentID.substring(4);
+ }
+
+ // Retrieving the MIMEHelper instance (which contains reference to attachments)
+ // from the Message Context
+ MIMEHelper attachments = (MIMEHelper)msgcts.getProperty(MIMEHelper.ATTACHMENTS);
+ // Retrieving the respective DataHandler referenced by the content-id
+ DataHandler dataHandler = attachments.getDataHandler(contentID);
+
+ // Echoing back the attachment. Sends out MTOM message
+ OMText textNode = new OMTextImpl(dataHandler);
+ omEle.build();
+ child.detach();
+ omEle.addChild(textNode);
+ return omEle;
+ }
+}</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 optimized message is a valid
+SwA message. Because of that Axis2 does not define a separate 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>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>
+</source><ul>
+ <li><strong>Corresponding MTOM message from Axis2</strong></li>
+</ul>
+<source><pre>Content-Type: multipart/related; boundary=MIMEBoundary4A7AE55984E7438034;
+ type="application/xop+xml"; start="<0....@apache.org>";
+ start-info="text/xml; charset=utf-8"
+
+--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....@apache.org>
+
+<em>Binary Data.....</em>
+--MIMEBoundary4A7AE55984E7438034--</pre>
+</source>
+<h1>Advanced Topics</h1>
+
+<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 bigger than
+the threshold value will get cached in files. Smaller attachments will remain
+in Memory.</p>
+
+<p>NOTE : It is a must to specify a directory to temporary store the
+attachments. Also care should be taken to *clean that directory* from time to
+time.</p>
+
+<p>The following parameters need to be set in Axis2.xml in order to enable
+file caching.</p>
+<source><pre><em><axisconfig name="AxisJava2.0">
+ <!-- ================================================= -->
+ <!-- Parameters -->
+ <!-- ================================================= --></em>
+ <parameter name="cacheAttachments" locked="xsd:false">true</parameter>
+ <parameter name="attachmentDIR" locked="xsd:false"><em>temp directory</em></parameter>
+ <parameter name="sizeThreshold" locked="xsd:false">4000</parameter>
+ .........
+ .........
+</axisconfig></pre>
+</source></body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/0_94/svn.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/svn.html?rev=368278&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/svn.html (added)
+++ webservices/axis2/trunk/java/xdocs/0_94/svn.html Wed Jan 11 21:10:09 2006
@@ -0,0 +1,91 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title></title>
+</head>
+
+<body>
+<h1>Developing Apache Axis2</h1>
+
+<h2>Working with Subversion</h2>
+
+<p>The Axis2 development team uses Subversion for source control. Subversion
+is a compelling replacement for CVS, developed under the auspices of the
+Tigris community and is licensed under an Apache compatible license. To learn
+more about Subversion or to download the latest distribution, visit the <a
+href="http:///subversion.tigris.org">Subversion project site</a>. If you are
+looking for guidance on setting up and installing Subversion, please read the
+ASF <a href="http://www.apache.org/dev/version-control.html">Source Code
+Repositories page</a>.</p>
+
+<h2>Checkout Axis2 from Subversion</h2>
+
+<p>When checking out the latest version of Axis from the Foundation's
+Subversion repository you must use one of the following URLs depending on
+your level of access to the Axis2 source code:</p>
+<ul>
+ <li><b>If you are not a committer:</b> Use <a
+ href="http://svn.apache.org/repos/asf/webservices/axis2/trunk/java">http://svn.apache.org/repos/asf/webservices/axis2/trunk/java</a></li>
+ <li><b>If you are a committer:</b> Use <a
+ href="https://svn.apache.org/repos/asf/webservices/axis2/trunk/java">https://svn.apache.org/repos/asf/webservices/axis2/trunk/java</a></li>
+</ul>
+If you are a committer, make sure that you have selected an svnpasswd. To do
+this you must log into svn.apache.org. For more information, please read the
+ASF <a href="http://www.apache.org/dev/version-control.html">Source Code
+Repositories page</a>.
+
+<p>Once you have successfully installed Subversion, you can check out Axis2
+trunk by following these steps:</p>
+<ol type="1">
+ <li>Run <strong>svn co <repository URL> axis2</strong> where
+ repository URL is one of the URLs from the previous list.</li>
+ <li>This step will check out the latest version of the Axis2 Java codebase
+ to a directory named "axis2". The second parameter to the svn co selects
+ a directory to create on your local machine. If you want to checkout
+ Axis2 to a different directory, feel free to change axis2 to any other
+ directory name.</li>
+ <li>To update your working copy to the latest version from the repository.
+ Execute the <strong>svn update</strong> command.</li>
+ <li>If you would like to submit a patch, you can execute <strong>svn
+ diff</strong> to create a unified diff for submission to the Axis JIRA
+ issue tracker.</li>
+</ol>
+
+<h2>Installing Maven 1</h2>
+
+<p>Axis2's build is based on Maven 1. Maven is a build system that allows
+for the reuse of common build projects across multiple projects. For
+information about obtaining, installing, and configuring Maven 1, please see
+the <a href="http://maven.apache.org">Maven project page</a>. To use Maven
+to build the Axis2 project, follow these simple steps:</p>
+<ol type="1">
+ <li>Install <a href="http://maven.apache.org/">Maven</a>. See <a
+ href="http://maven.apache.org/start/install.html">here</a> for
+ instructions.
+ <ul>
+ <li>Create a MAVEN_HOME environment variable.</li>
+ <li>Add MAVEN_HOME/bin to your PATH</li>
+ </ul>
+ </li>
+ <li>Go to the axis2 folder in the command prompt and type
+ <strong>maven<strong>.</strong></strong></li>
+ <li>Maven will then automatically download all the jars, compile, test and
+ build the Axis2 deliverables.</li>
+</ol>
+
+<h2>Configuring your IDE</h2>
+
+<p>The Axis2 development team uses a variety of development tools from vi to
+emacs to Eclipse to Intellij/IDEA. The following section is not an
+endorsement of a specific set of tools, it is simply meant as a pointer to
+ease the process of getting started with Axis2 development.</p>
+<ul>
+ <li><strong>Intellij IDEA </strong>: type <strong>maven
+ idea:multiproject</strong>. This will generate the necessary IDEA .ipr,
+ .iml and .iws project files</li>
+ <li><strong>eclipse</strong>: The Maven eclipse plugin does not support
+ Maven multiprojects. You will need to execute <strong>maven
+ eclipse</strong> from each of the module directories.</li>
+</ul>
+</body>
+</html>
Modified: webservices/axis2/trunk/java/xdocs/0_94/tools/idea/Idea_plug-in_userguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/tools/idea/Idea_plug-in_userguide.html?rev=368278&r1=368277&r2=368278&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/tools/idea/Idea_plug-in_userguide.html (original)
+++ webservices/axis2/trunk/java/xdocs/0_94/tools/idea/Idea_plug-in_userguide.html Wed Jan 11 21:10:09 2006
@@ -9,7 +9,9 @@
</head>
<body lang="en">
-<h1>Code generation IDEA plug-in</h1>
+<h1>IntelliJ IDEA Plug-ins</h1>
+
+<p><a href="http://ws.apache.org/axis2/download.cgi">[Download]</p>
<h2>Introduction</h2>
@@ -39,13 +41,13 @@
<p>When you click on either one of them a window will appear asking you to
select one of the following two options.</p>
<ol>
- <li><a href="#IDEA">Create a service archive</a></li>
- <li><a href="#WSDL2Java">WSDL2Java code generation</a></li>
+ <li><a href="#Create_Service_Archive">Create a service archive</a></li>
+ <li><a href="#WSDL2Java_Code_Generation">WSDL2Java code generation</a></li>
</ol>
<p><img alt="Figure3" src="images/fig1.jpg"></p>
-<h2><a name="WSDL2Java">WSDL2Java codegeneration</a></h2>
+<h2><a name="WSDL2Java_Code_Generation">WSDL2Java Code Generation</a></h2>
<p>Select WSDL2Java codegenaration and click OK to generate code from a WSDL
file. Then the following window will appear.</p>
@@ -87,7 +89,7 @@
<p>If everything has gone well you will see the above message.</p>
-<h2><a name="IDEA">IDEA</a> service archive generation plug-in</h2>
+<h2><a name="Create_Service_Archive">Ceate Service Archive</a></h2>
<p>First step is to click on Axis2 IDEA plug-in icon and select 'create a
service archive' radio button.</p>
@@ -131,7 +133,7 @@
select service specific external libraries and service WSDL file. In the case
of service group you can add any number of WSDL files depending on the
services in the service group. If you want to add multiple WSDL files to a
-single service type you can do that as well. </p>
+single service type you can do that as well.</p>
<p><img alt="fig8" src="images/fig8.jpg"></p>