Added: webservices/site/trunk/targets/axis2/0_93/security-module.html URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_93/security-module.html?rev=366125&view=auto ============================================================================== --- webservices/site/trunk/targets/axis2/0_93/security-module.html (added) +++ webservices/site/trunk/targets/axis2/0_93/security-module.html Thu Jan 5 00:55:38 2006 @@ -0,0 +1,143 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html><head><title>The Security Module - Axis 2.0</title><style type="text/css" media="all"> + @import url("./style/maven-base.css"); + + @import url("./style/maven-theme.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/"; id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif";></img></a><a href="http://ws.apache.org/axis2/"; id="projectLogo"><img alt="Apache Axis 2.0" src="http://ws.apache.org/axis2/images/axis.jpg";></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 20 December 2005 + <span class="separator">|</span> Doc for 0.94-dev + </div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis_2_0"><h5>Axis 2.0</h5><ul><li class="none"><a href="index.html">Home</a></li><li class="expanded"><a href="">Download Axis2</a><ul><li class="none"><a href="download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN"; class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2"; class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api.html">Online Java Docs</a></li><li class="none"><a href="adb/adb-howto.html">ADB How-to</a></li><li class="none"><a href="security-module.html">WS-Security How-to</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowT o.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li class="none"><a href="refLib.html">Reference Library</a></li><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="faq.html">FAQ</a></li><li class="none"><a href="thanks.html">Thanks</a></li></ul></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/"; title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section">< a name="Securing_SOAP_Messages_with_WSS4J"></a><h2>Securing SOAP Messages with WSS4J</h2><p>Axis2 comes with a module based on WSS4J [1] to provide WS-Security features. This section explains how to engage and configure the security module. Since the security module inserts handlers in the system specific pre-dispatch phase, it must be engaged globally. But it is possible to activate the security module for the inflow or the outflow when required by the service or the clients.</p><p>The security module (security.mar) is available in the axis2.war but it is not engaged by default.</p><p>First it should be engaged by inserting the following in the axis2.xml file.</p> + <div class="source"><pre><pre> + <module ref="security"/> +</pre></pre></div> + <p>The web admin interface can be used when Axis2 is deployed in a servlet container such as Apache Tomcat.</p><p>At the server it is possible to provide security on a per service basis. The configuration parameters should be set in the service.xml file of the service. The client side config parameters should be set in the axis2.xml of the client's Axis2 repository.</p><p>The security module uses two parameters:</p><ul> +<li>OutflowSecurity</li> +<li>InflowSecurity</li> +</ul><p> + +The configuration that can go in each of these parameters are described below: + +</p><div class="subsection"><a name="OutflowSecurity_parameter"></a><h3>OutflowSecurity parameter</h3><p> + +This parameter is used to configure the outflow security handler. The outflow + handler can be invoked more than once in the outflow one can provide + configuration for each of these invocations. The 'action' element describes + one of these configurations. Therefore the 'OutflowSecurity' parameter can + contain more than one 'action' elements. The schema of this 'action' element + is available <a href="sec-conf/out-action.xsd">here</a>. +</p><p>An outflow configuration to add a timestamp, sing and encrypt + the message once, is shown in<a href="#ex1"> Example 1</a> and <a href="#ex1"> + Example 2</a> shows how to sign the message twice by chaining the outflow + handler (using two 'action' elements)</p><p>Following is a description of the elements that can go in an 'action' +element of the OutflowSecurity parameter</p><br></br><table class="bodyTable"> +<tr class="a"> +<td><b>Parameter</b></td> +<td><b>Description</b></td> +<td><b>Example</b></td> +</tr> +<tr class="b"> +<td>items</td> +<td>Security actions for the inflow</td> +<td>Add a Timestamp, Sign the SOAP body and Encrypt the SOAP body <br></br><items> Timestamp Signature Encrypt</items></td> +</tr> +<tr class="a"> +<td>user</td> +<td>The user's name</td> +<td>Set alias of the key to be used to sign<br></br><user> bob</user></td> +</tr> +<tr class="b"> +<td>passwordCallbackClass</td> +<td>Callback class used to provide the password required to create the UsernameToken or to sign the message</td> +<td><passwordCallbackClass> org.apache.axis2.security.PWCallback</passwordCallbackClass></td> +</tr> +<tr class="a"> +<td>signaturePropFile</td> +<td>property file used to get the signature parameters such as crypto provider, keystore and its password</td> +<td>Set example.properties file as the signature property file<br></br><signaturePropFile> example.properties</signaturePropFile></td> +</tr> +<tr class="b"> +<td>signatureKeyIdentifier</td> +<td>Key identifier to be used in referring the key in the signature</td> +<td>Use the serial number of the certificate<br></br><signatureKeyIdentifier> IssuerSerial</signatureKeyIdentifier></td> +</tr> +<tr class="a"> +<td>encryptionKeyIdentifier</td> +<td>Key identifier to be used in referring the key in encryption</td> +<td>Use the serial number of the certificate <br></br><encryptionKeyIdentifier>IssuerSerial</encryptionKeyIdentifier></td> +</tr> +<tr class="b"> +<td>encryptionUser</td> +<td>The user's name for encryption.</td> +<td><br></br><encryptionUser>alice</encryptionUser></td> +</tr> +<tr class="a"> +<td>encryptionSymAlgorithm</td> +<td>Symmetric algorithm to be used for encryption</td> +<td>Use AES-128<br></br><encryptionSymAlgorithm> http://www.w3.org/2001/04/xmlenc#aes128-cbc</encryptionSymAlgorithm></td> +</tr> +<tr class="b"> +<td>encryptionKeyTransportAlgorithm</td> +<td>Key encryption algorithm</td> +<td>Use RSA-OAEP<br></br><parameter name="encryptionSymAlgorithm"> http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p</parameter></td> +</tr> +<tr class="a"> +<td>signatureParts</td> +<td>Sign multiple parts in the SOAP message</td> +<td>Sign Foo and Bar elements qualified by "http://app.ns/ns";<br></br><signatureParts> {Element}{http://app.ns/ns}Foo;{Element}{http://app.ns/ns}Bar </signatureParts></td> +</tr> +<tr class="b"> +<td>optimizeParts</td> +<td>MTOM Optimize the elements specified by the XPath query</td> +<td>Optimize the CipherValue<br></br><optimizeParts> //xenc:EncryptedData/xenc:CipherData/xenc:CipherValue </optimizeParts></td> +</tr> +</table><br></br></div><div class="subsection"><a name="InflowSecurity_parameter"></a><h3>InflowSecurity parameter</h3><p>This parameter is used to configure the inflow security handler. The 'action' element is used to +encapsulate the configuration elements here as well. The schema of the 'action' element is available here. +<a href="#ex3">Example 3</a> shows the configuration to decrypt, verify signature and validate timestamp.</p><table class="bodyTable"> +<tr class="a"> +<td><b>Parameter</b></td> +<td><b>Description</b></td> +<td><b>Example</b></td> +</tr> +<tr class="b"> +<td>items</td> +<td>Security actions for the inflow</td> +<td>first the incoming message should be decrypted and then the signatures should be verified and should be checked for the availability of the Timestamp <br></br><items> Timestamp Signature Encrypt</items></td> +</tr> +<tr class="a"> +<td>passwordCallbackClass</td> +<td>Callback class used to obtain password for decryption and UsernameToken verification</td> +<td><br></br><passwordCallbackClass> org.apache.axis2.security.PWCallback</passwordCallbackClass></td> +</tr> +<tr class="b"> +<td>signaturePropFile</td> +<td>Property file used for signature verification</td> +<td><br></br><signaturePropFile> sig.properties</signaturePropFile></td> +</tr> +<tr class="a"><td>decryptionPropFile</td> +<td>Property file used for decryption</td> +<td> <br></br><decryptionPropFile> dec.properties</decryptionPropFile></td> +</tr> + +</table><br></br><p>Please note that the '.properties' files used in properties such as OutSignaturePropFile are the same property files that are using in the WSS4J project. +Following shows the properties defined in a sample property file</p> + <div class="source"><pre> +<pre> +org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=pkcs12 +org.apache.ws.security.crypto.merlin.keystore.password=security +org.apache.ws.security.crypto.merlin.keystore.alias=16c73ab6-b892-458f-abf5-2f875f74882e +org.apache.ws.security.crypto.merlin.alias.password=security +org.apache.ws.security.crypto.merlin.file=keys/x509.PFX.MSFT +</pre> +</pre></div> + <p> + +org.apache.ws.security.crypto.provider defines the implementation of the org.apache.ws.security.components.crypto.Crypto +interface to provide the crypto information required by WSS4J. The other properties defined are the configuration + properties used by the implementation class (org.apache.ws.security.components.crypto.Merlin). + +</p><p><b>References</b></p><p>1. <a href="http://ws.apache.org/wss4j"; class="externalLink" title="External Link">Apache WSS4J</a></p><br></br><p><b>Examples</b></p><p id="ex1">Example 1: An outflow configuration to add a timestamp, sing and encrypt + the message once</p><p><iframe frameborder="0" src="sec-conf/out-sample.xml" width="800" height="400"> +</iframe> +</p><p id="ex2">Example 2: An outflow configuration to sign the message twice and add a timestamp</p><p><iframe frameborder="0" src="sec-conf/out-sample2.xml" width="800" height="400"> +</iframe> +</p><p id="ex3">Example 3: An inflow configuration to decrypt, verify signature and validate timestamp</p><p><iframe frameborder="0" src="sec-conf/in-sample.xml" width="800" height="400"> +</iframe> +</p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2005, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html> \ No newline at end of file
Added: webservices/site/trunk/targets/axis2/0_93/tcp-transport.html URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_93/tcp-transport.html?rev=366125&view=auto ============================================================================== --- webservices/site/trunk/targets/axis2/0_93/tcp-transport.html (added) +++ webservices/site/trunk/targets/axis2/0_93/tcp-transport.html Thu Jan 5 00:55:38 2006 @@ -0,0 +1,57 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html><head><title>TCP transport - Axis 2.0</title><style type="text/css" media="all"> + @import url("./style/maven-base.css"); + + @import url("./style/maven-theme.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/"; id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif";></img></a><a href="http://ws.apache.org/axis2/"; id="projectLogo"><img alt="Apache Axis 2.0" src="http://ws.apache.org/axis2/images/axis.jpg";></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 20 December 2005 + <span class="separator">|</span> Doc for 0.94-dev + </div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis_2_0"><h5>Axis 2.0</h5><ul><li class="none"><a href="index.html">Home</a></li><li class="expanded"><a href="">Download Axis2</a><ul><li class="none"><a href="download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN"; class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2"; class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api.html">Online Java Docs</a></li><li class="none"><a href="adb/adb-howto.html">ADB How-to</a></li><li class="none"><a href="security-module.html">WS-Security How-to</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowT o.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li class="none"><a href="refLib.html">Reference Library</a></li><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="faq.html">FAQ</a></li><li class="none"><a href="thanks.html">Thanks</a></li></ul></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/"; title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section">< a name="TCP_transport"></a><h2>TCP transport</h2><p>Axis2 supports TCP as a transport. Axis2 has support for both send and +receive SOAP Messages via TCP. TCP transports do not have any Application +level Headers and the SOAP Message that sends should be self contained. This +make the interaction fast and simple. Yet the main limitation of the TCP +transport is absence of the request URI, and the Service dispatching should +use a alternative method. There is two main alternatives methods.</p><ol> + <li>Use the name space URI of the first child element for the + dispatching</li> + <li>Enable the WS-Addressing, in the case of Alpha release, Addressing is + default</li> +</ol><p>When the TCP request is sent, it is users responsibility either to use +addressing or use alternative method.</p><div class="subsection"><a name="How_to_start_the_TCPServer"></a><h3>How to start the TCPServer</h3><p>The TCP server can be started by running the class +org.apache.axis2.transport.tcp.TCPServer with two parameters <a href="faq.html#b5">repository</a> and port number as argument. This class +needed all the axis dependency jars in the classpath. New Services can be +added in the usual way by droping the archives to repository, read the <a href="userguide.html">User Guide</a> for more information</p><p>Alternatively the TCP Server can be run with tcp-server.bat/ tcp-server.sh +file in the bin directory of the Binary distribution of TCP Server.</p></div><div class="subsection"><a name="How_send_SOAP_Messages_with_TCP_transport"></a><h3>How send SOAP Messages with TCP transport</h3><p>The TCP transport can be enabled very easily from the call API, following +code segment demonstrate how it can be done.</p> + <div class="source"><pre><pre>OMElement payload = ... + +Call call = new Call(serviceContext); +Options options = new Options(); +options.setTo(targetEPR); +options.useSeperateListener(false); +call.setClientOptions(options); + +OMElement result = + (OMElement) call.invokeBlocking("operation", payload); +call.close();</pre> +</pre></div> + <p>The tranport that should be invoked is inferred from the targetEPR +(tcp://...) in this case it is TCP and the listener also TCP . Since the +addressing is engage SOAP Message itself contained. Only other option I can +think of is to use the URI of the first child of the SOAP Body to dispatch +the service. The Parameter is of the type <a href="faq.html#a2">OMElement</a>, the XML representation of Axis2.</p></div><div class="subsection"><a name="Sample"></a><h3>Sample</h3><p>Sample for a TCP Client can be found from the +samples/userguide/src/userguide/clients/TCPClient.java in the binary +distribution, this access the same web service explained in the userguide. To +try the client first starts the TCPServer with the same repository used for +the userguide samples. Since sample is already deployed in the repository +while trying the userguide it will be automatically avaliable.</p></div><div class="subsection"><a name="Advanced_Topics"></a><h3>Advanced Topics</h3><p>Axis2 TCP transport has two parts, a transport Listener for receiving the +Messages and transport Sender to send the SOAP Messages. Axis2 installation +has both the components built in to itself by default. In the axis2.xml +configuration file, two would look like follows.</p><p>If the TCP server is started manually this configuration does not take +effect, this affect the transport Listeners starts by Axis2. (e.g. Listener +started by the Complete Async interaction)</p> + <div class="source"><pre><pre><transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPServer"> + <parameter name="port" locked="false">6060</parameter> +</transportReceiver></pre> +</pre></div> + <p>Following add the TCPTransport Sender</p> + <div class="source"><pre><pre><transportSender name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportSender"/></pre> +</pre></div> + </div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2005, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html> \ No newline at end of file Added: webservices/site/trunk/targets/axis2/0_93/transport_howto.html URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_93/transport_howto.html?rev=366125&view=auto ============================================================================== --- webservices/site/trunk/targets/axis2/0_93/transport_howto.html (added) +++ webservices/site/trunk/targets/axis2/0_93/transport_howto.html Thu Jan 5 00:55:38 2006 @@ -0,0 +1,175 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html><head><title> - Axis 2.0</title><style type="text/css" media="all"> + @import url("./style/maven-base.css"); + + @import url("./style/maven-theme.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/"; id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif";></img></a><a href="http://ws.apache.org/axis2/"; id="projectLogo"><img alt="Apache Axis 2.0" src="http://ws.apache.org/axis2/images/axis.jpg";></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 20 December 2005 + <span class="separator">|</span> Doc for 0.94-dev + </div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis_2_0"><h5>Axis 2.0</h5><ul><li class="none"><a href="index.html">Home</a></li><li class="expanded"><a href="">Download Axis2</a><ul><li class="none"><a href="download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN"; class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2"; class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api.html">Online Java Docs</a></li><li class="none"><a href="adb/adb-howto.html">ADB How-to</a></li><li class="none"><a href="security-module.html">WS-Security How-to</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowT o.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li class="none"><a href="refLib.html">Reference Library</a></li><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="faq.html">FAQ</a></li><li class="none"><a href="thanks.html">Thanks</a></li></ul></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/"; title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section">< a name="How_to_write_your_own_Axis2_transport"></a><h2>How to write your own Axis2 transport</h2><div class="subsection"><a name="Prologue"></a><h3>Prologue</h3><p>To stop you from reinventing the wheel I will quickly list the transports +that are already supported in Axis2 with a small description before we get +started.</p><p></p><ul> + <li><b>HTTP</b> - In the HTTP transport, the transport Listener is a + Servlet or a Simple HTTP server provided by Axis2. The transport Sender + uses sockets to connect and send the SOAP Message. Currently we have the + commons-HTTP-client based HTTP Transport sender as the default + transport.</li> + <li><b>TCP</b> This is the most simple transport, but needs addressing + support to be functional.</li> + <li><b>SMTP</b> This can work off a single email account or a mailserver. + The Mail Transport Receiver is a tread that checks for emails in fixed + time intervals.</li> +</ul><p>To understand the rest of this document you will need some understanding +of the Architecture of Axis2. Therefor if you are not familiar with the +Architecture of Axis2 you will have to first read the <a href="Axis2ArchitectureGuide.html">Axis2 Architecture Guide</a> before you +read any further.</p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p>Broadly speaking a transport inside Axis2 can be classified as a way of +getting a messages that arrive though some channel into the Axis2 engine. The +core of Axis2 is a transport agnostic one. All data that is transport +specific is striped out of the incoming message and inserted into the +MessageContext and on the outgoing message all transport specific information +like headers are added and sent.</p><p>To write your own transport you will need to primarily write two classes, +one is the TransportSender and the other is the TransportReceiver. To +register a transport with Axis2 you will need to put two entries in the +axis2.xml file. One for the transport receiver and the other for the +transport sender. We will walk though the process of adding the entries in +the relevent sections.</p></div><div class="subsection"><a name="Transport_Receiver"></a><h3>Transport Receiver</h3><p>Any message that is comming into Axis2 needs to go though a transport +receiver. All information about how the message is received at the Axis2 +server from the wire [or by snail mail for that matter:)] is isolated inside +the transport receiver. It extracts the data that is coming on the wire and +transforms it into a state that the Axis2 server understands.</p><p>So now that we have some background information about how transports work +inside Axis2 with out further delay why don't we dive into some coding and +start building out own transport.</p><p></p><p>To get things stared you will first need to extend from the +org.apache.Axis2.transport.TransportListener class and write you own +transport listener. To create an engine to process the MessageContext we need +a configuration context. The following code fragment will do this. This +should ideally be only done once for the lifetime of the Transport +receiver.</p><p> + <div class="source"><pre></pre></div> + </p> + <div class="source"><pre>try { + //Create a factory + ConfigurationContextFactory factory = new ConfigurationContextFactory(); + //Use the factory and an Axis2 repository to create a new Configuration Context + configurationContext = factory.buildConfigurationContext(repository_directory); +} catch (Exception e) { + log.info(e.getMessage()); +} + +</pre></div> + <p>Now we need some kind of a listener to listen to the requests that come +in. This you will need to implement according to the transport that you are +trying to build. After a message is received at the receiver you can use the +following code to process the request and then forward the message context to +the engine using thing the engine.receive(msgContext) method.</p> + <div class="source"><pre><pre>AxisEngine engine = new AxisEngine(configurationContext); +MessageContext msgContext = null; +// create and initialize a message context +try { + TransportInDescription transportIn = + reg.getAxisConfiguration().getTransportIn(new QName(Constants.TRANSPORT_NAME)); + TransportOutDescription transportOut = + reg.getAxisConfiguration().getTransportOut(new QName(Constants.TRANSPORT_NAME)); + if (transportIn != null && transportOut != null) { + //create Message Context + msgContext = new MessageContext(configurationContext, transportIn, transportOut); + msgContext.setServerSide(true); + msgContext.setProperty(MailSrvConstants.CONTENT_TYPE, message.getContentType()); + msgContext.setProperty(MessageContext.CHARACTER_SET_ENCODING, message.getEncoding()); + + String soapAction = message.getSOAPActionHeader(); + msgContext.setWSAAction(soapAction); + msgContext.setSoapAction(soapAction); + + // Here we are trying to set the reply to if it is present in the transport information. + msgContext.setReplyTo(new EndpointReference(message.getReplyTo()); + + //Create the SOAP Message -- This code in from the mail transport and will change depending + //on how the data is handled in each transport. + ByteArrayInputStream bais = new ByteArrayInputStream(message.getContent().toString().getBytes()); + XMLStreamReader reader = XMLInputFactory.newInstance().createXMLStreamReader(bais); + + String soapNamespaceURI = ""; + if(message.getContentType().indexOf(SOAP12Constants.SOAP_12_CONTENT_TYPE) > -1){ + soapNamespaceURI = SOAP12Constants.SOAP_ENVELOPE_NAMESPACE_URI; + }else if(message.getContentType().indexOf(SOAP11Constants.SOAP_11_CONTENT_TYPE) > -1){ + soapNamespaceURI = SOAP11Constants.SOAP_ENVELOPE_NAMESPACE_URI; + } + + StAXBuilder builder = new StAXSOAPModelBuilder(reader, soapNamespaceURI); + + SOAPEnvelope envelope = (SOAPEnvelope) builder.getDocumentElement(); + msgContext.setEnvelope(envelope); + if (envelope.getBody().hasFault()) { + engine.receiveFault(msgContext); + } else { + engine.receive(msgContext); + } + } else { + throw new AxisFault(Messages.getMessage("unknownTransport",Constants.TRANSPORT_NAME)); + } + +} catch (Exception e) { + try { + if (msgContext != null) { + MessageContext faultContext = engine.createFaultMessageContext(msgContext, e); + engine.sendFault(faultContext); + } else { + log.error(e); + } + } catch (AxisFault e1) { + log.error(e); + } +}</pre> +</pre></div> + <p>Now we have the coding in place and we need to let Axis2 know about our +new transport receiver. How we do this is by addind an entry into the +axis2.xml file. If you need to pass any properties for the transport to +operate it can also be done through the axis2.xml file.</p> + <div class="source"><pre><pre> <transportReceiver name="TRANSPORT_NAME" class="org.apache.Axis2.transport.TRANSPORT_NAME.TRANSPORT_LISTNER_CLASS"> + <parameter name="PROPERTY_NAME" locked="false">PROPERTY_VALUE</parameter> + <parameter name="PROPERTY_NAME_2" locked="false">PROPERTY_VALUE_2</parameter> + </transportReceiver> + </pre> +</pre></div> + <p>Using a code fragment like +Utils.getParameterValue(transportOut.getParameter(MailSrvConstants.SMTP_USER)) +we can extract the parameters that we insert into the axis2.xml file.</p><p>So as you can see getting a new transport receiver up and running is a +task that requires very little effort.</p></div><div class="subsection"><a name="Transport_Sender"></a><h3>Transport Sender</h3><p>Any message that is to be sent out from Axis2 is sent through the +Transport Sender. The Transport Sender needs to be extended from the +org.apache.Axis2.transport.AbstractTransportSender class.</p><p>The following bit of code from the abstract transport sender will call the +Transport Sender that you wrote.</p> + <div class="source"><pre><pre>// If an EPR is present then the message is going on a diffrent channel. +if (epr != null) { + out = openTheConnection(epr, msgContext); + OutputStream newOut = startSendWithToAddress(msgContext, out); + if (newOut != null) { + out = newOut; + } + writeMessage(msgContext, out); + finalizeSendWithToAddress(msgContext, out); + } else { + out = (OutputStream) msgContext.getProperty(MessageContext.TRANSPORT_OUT); + if (out != null) { + startSendWithOutputStreamFromIncomingConnection(msgContext, out); + writeMessage(msgContext, out); + finalizeSendWithOutputStreamFromIncomingConnection(msgContext, out); + } else { + throw new AxisFault( + "Both the TO and Property MessageContext.TRANSPORT_WRITER is Null, No way to send response."); + } +}</pre> +</pre></div> + <p>So depending on whether your transport is using the same channel to send +the responce or using a different channel you will need to implement a +sub-set of the methods from the abstract class.</p><p>After implementing the necessary methods you can let Axis2 know about your +new transport sender by adding an entry to the axis2.xml file like you did +for the Transport Receiver.</p> + <div class="source"><pre><pre> <transportSender name="TRANSPORT_NAME" class="org.apache.Axis2.transport.TRANSPORT_NAME.TRANSPORT_SENDER_CLASS"> + <parameter name="PROPERTY_NAME" locked="false">PROPERTY_VALUE</parameter> + <parameter name="PROPERTY_NAME_2" locked="false">PROPERTY_VALUE_2</parameter> + </transportSender> + </pre> +</pre></div> + <p>Have a look at org.apache.Axis2.transport.mail.MailTransportSender for a +very simple Transport Sender. Also have a look at +org.apache.Axis2.transport.http.CommonsHTTPTransportSender which is used to +send HTTP responses.</p><p>Once we have written our transport receiver and our transport sender, and +inserted the needed entries into the axis2.xml file we are done. It is as +simple as that. :-)</p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2005, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html> \ No newline at end of file
![http://www.apache.org/images/asf-logo.gif"](http://www.apache.org/images/asf-logo.gif"){kind=link}
![http://ws.apache.org/axis2/images/axis.jpg"](http://ws.apache.org/axis2/images/axis.jpg"){kind=link}