Added: webservices/site/trunk/targets/axis2/0_94/rest-ws.html URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/rest-ws.html?rev=366133&view=auto ============================================================================== --- webservices/site/trunk/targets/axis2/0_94/rest-ws.html (added) +++ webservices/site/trunk/targets/axis2/0_94/rest-ws.html Thu Jan 5 01:17:47 2006 @@ -0,0 +1,110 @@ +<!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 - RESTful Web Services Support</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: 05 January 2006 + | Doc for 0.94</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="">Documentation</a><ul><li class="none"><a href="0_93/index.html">Version 0.93</a></li><li class="none"><a href="0_94/index.html">Version 0.94</a></li></ul></li><li class="expanded"><a href="overview.html">Get Involved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowTo.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li cl ass="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></ul></li><li class="none"><a href="thanks.html">Ackknowledgements</a></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></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="RESTful_Web_services_Support"></a><h2>RESTful Web services Support</h2><p>REST provides access to resources through the two methods GET and POST. +REST Web services are a reduced subset of the usual Web service stack.</p><p>The Axis2 REST implementation assumes the following properties:</p><ol> + <li>REST Web services are Synchronous and Request Response in nature.</li> + <li>When REST Web services are accessed via GET, the service and the + operations are identified based on the URL. The parameters are assumed as + parameters of the Web service. In this case the GET based REST Web + services supports only simple types as arguments.</li> + <li>POST based web services do not need a SOAP Envelope or a SOAP Body. + REST Web Services do not have Headers and the payload is sent + directly.</li> +</ol><p>Axis2 can be configured as a REST Container and can be used to send and +receive RESTful Web services requests and responses. REST Web services can be +accessed in two ways, i.e. using HTTP GET and POST.</p><div class="subsection"><a name="Doing_REST_web_services_with_HTTP_POST"></a><h3>Doing REST web services with HTTP POST</h3><p>The REST default HTTP interface is POST. It can be enabled in the +Server/Client side by adding the following line to the axis2.xml file.</p><font color="blue">< parameter name="enableREST" locked="false" > true +</parameter> </font><p>It however acts as both a REST endpoint and SOAP endpoint. When a Message +is received, if the content type is text/xml and if the SOAP Action Headers +are missing, then the Message is treated as a RESTful Message. Else it is +treated as a usual SOAP Message.</p><p>On sending a message out, the fact that the message is RESTful or not, can +be decided from the client API or by deployment descriptor of the client.</p><ol> + <li>By adding an entry in the client repositories axis2.xml file.</li> + <li>Setting as a property in client API e.g. + <div class="source"><pre> + <pre>... +Options options = new Options(); +options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE); +...</pre> + </pre></div> + </li> +</ol></div><div class="subsection"><a name="Sample_REST_-_HTTP_POST_Client"></a><h3>Sample REST - HTTP POST Client</h3><p>There is an example named, userguide.clients.RESTClient.java which +demonstrates the usage of the above, using the "echo"operation of the + + <div class="source"><pre></pre></div> + </p> + <div class="source"><pre>userguide.example1.MyService + +</pre></div> + <p>of the samples.The class source will be as follows:</p><p> + <div class="source"><pre></pre></div> + </p> + <div class="source"><pre>public class RESTClient { + + private static String toEpr = "http://localhost:8080/axis2/services/MyService";; + + public static void main(String[] args) throws AxisFault { + + Options options = new Options(); + options.setTo(new EndpointReference(toEpr)); + options.setListenerTransportProtocol(Constants.TRANSPORT_HTTP); + options.setUseSeparateListener(false); + options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE); + + Call call = new Call(); + call.setClientOptions(options); + + OMElement result = call.invokeBlocking("echo", getPayload()); + + try { + XMLStreamWriter writer = XMLOutputFactory.newInstance() + .createXMLStreamWriter(System.out); + result.serialize(writer); + writer.flush(); + } catch (XMLStreamException e) { + e.printStackTrace(); + } catch (FactoryConfigurationError e) { + e.printStackTrace(); + } + } + + private static OMElement getPayload() { + OMFactory fac = OMAbstractFactory.getOMFactory(); + OMNamespace omNs = fac.createOMNamespace( + "http://example1.org/example1";, "example1"); + OMElement method = fac.createOMElement("echo", omNs); + OMElement value = fac.createOMElement("Text", omNs); + value.addChild(fac.createText(value, "Axis2 Echo String ")); + method.addChild(value); + + return method; + } +} + +</pre></div> + </div><div class="subsection"><a name="Access_a_REST_Web_Service_Via_HTTP_GET"></a><h3>Access a REST Web Service Via HTTP GET</h3><p>Axis2 allow users to access Web services that have simple type parameters +via HTTP GET. For example the following URL requests the Version Service via +HTTP GET. But the Web service arriving via GET assumes REST. Other parameters +are converted in to XML and put in to the SOAP Body.</p> + <div class="source"><pre><pre>http://127.0.0.1:8080/axis2/services/version/getVersion</pre> +</pre></div> + <p>Result can be shown in the browser as follows:</p><img src="images/userguide/http-get-ws.png" alt=""></img><p>For example, the following request, + <div class="source"><pre></pre></div> + </p> + <div class="source"><pre>http://127.0.0.1:8080/axis2/services/version/getVersion +</pre></div> + <p>will be converted to the following SOAP Message for processing by +Axis2. + <div class="source"><pre> +<pre> + <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> + <soapenv:Body> + <axis2:getVersion xmlns:axis2="http://ws.apache.org/goGetWithREST"; /> + </soapenv:Body> + </soapenv:Envelope> + </pre> +</pre></div> + </p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2006, 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_94/sec-conf/in-sample.png URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/sec-conf/in-sample.png?rev=366133&view=auto ============================================================================== Binary file - no diff available. Propchange: webservices/site/trunk/targets/axis2/0_94/sec-conf/in-sample.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: webservices/site/trunk/targets/axis2/0_94/sec-conf/in.action.xsd URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/sec-conf/in.action.xsd?rev=366133&view=auto ============================================================================== --- webservices/site/trunk/targets/axis2/0_94/sec-conf/in.action.xsd (added) +++ webservices/site/trunk/targets/axis2/0_94/sec-conf/in.action.xsd Thu Jan 5 01:17:47 2006 @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8"?> +<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"; elementFormDefault="qualified" attributeFormDefault="unqualified"> + <xs:element name="action"> + <xs:annotation> + <xs:documentation>Inflow security 'action' configuration</xs:documentation> + </xs:annotation> + <xs:complexType> + <xs:sequence> + <xs:element name="items" type="xs:string"/> + <xs:element name="passwordCallbackClass" type="xs:string" minOccurs="0"/> + <xs:element name="signaturePropFile" type="xs:string" minOccurs="0"/> + <xs:element name="decryptionPropFile" type="xs:string" minOccurs="0"/> + </xs:sequence> + </xs:complexType> + </xs:element> +</xs:schema> Added: webservices/site/trunk/targets/axis2/0_94/sec-conf/out-action.xsd URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/sec-conf/out-action.xsd?rev=366133&view=auto ============================================================================== --- webservices/site/trunk/targets/axis2/0_94/sec-conf/out-action.xsd (added) +++ webservices/site/trunk/targets/axis2/0_94/sec-conf/out-action.xsd Thu Jan 5 01:17:47 2006 @@ -0,0 +1,27 @@ +<?xml version="1.0" encoding="UTF-8"?> +<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"; elementFormDefault="qualified" attributeFormDefault="unqualified"> + <xs:element name="action"> + <xs:annotation> + <xs:documentation>Outflow security 'action' configuration</xs:documentation> + </xs:annotation> + <xs:complexType> + <xs:sequence> + <xs:element name="items" type="xs:string"/> + <xs:element name="user" type="xs:string"/> + <xs:element name="passwordCallbackClass" type="xs:string" minOccurs="0"/> + <xs:element name="signaturePropFile" type="xs:string" minOccurs="0"/> + <xs:element name="encryptionPropFile" type="xs:string" minOccurs="0"/> + <xs:element name="signatureKeyIdentifier" type="xs:string" minOccurs="0"/> + <xs:element name="encryptionKeyIdentifier" type="xs:string" minOccurs="0"/> + <xs:element name="encryptionUser" type="xs:string" minOccurs="0"/> + <xs:element name="signatureParts" type="xs:string" minOccurs="0"/> + <xs:element name="encryptionParts" type="xs:string" minOccurs="0"/> + <xs:element name="optimizeParts" type="xs:string" minOccurs="0"/> + <xs:element name="encryptionSymAlgorithm" type="xs:string" minOccurs="0"/> + <xs:element name="EmbeddedKeyCallbackClass" type="xs:string" minOccurs="0"/> + <xs:element name="encryptionKeyTransportAlgorithm" type="xs:string" minOccurs="0"/> + <xs:element name="EmbeddedKeyName" type="xs:string" minOccurs="0"/> + </xs:sequence> + </xs:complexType> + </xs:element> +</xs:schema> Added: webservices/site/trunk/targets/axis2/0_94/sec-conf/out-sample.png URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/sec-conf/out-sample.png?rev=366133&view=auto ============================================================================== Binary file - no diff available. Propchange: webservices/site/trunk/targets/axis2/0_94/sec-conf/out-sample.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: webservices/site/trunk/targets/axis2/0_94/sec-conf/out-sample2.png URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/sec-conf/out-sample2.png?rev=366133&view=auto ============================================================================== Binary file - no diff available. Propchange: webservices/site/trunk/targets/axis2/0_94/sec-conf/out-sample2.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: webservices/site/trunk/targets/axis2/0_94/security-module.html URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/security-module.html?rev=366133&view=auto ============================================================================== --- webservices/site/trunk/targets/axis2/0_94/security-module.html (added) +++ webservices/site/trunk/targets/axis2/0_94/security-module.html Thu Jan 5 01:17:47 2006 @@ -0,0 +1,53 @@ +<!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 - The Security Module</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: 05 January 2006 + | Doc for 0.94</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="">Documentation</a><ul><li class="none"><a href="0_93/index.html">Version 0.93</a></li><li class="none"><a href="0_94/index.html">Version 0.94</a></li></ul></li><li class="expanded"><a href="overview.html">Get Involved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowTo.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li cl ass="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></ul></li><li class="none"><a href="thanks.html">Ackknowledgements</a></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></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 spe cific 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 pr operty 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></t d></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>decrypti onPropFile</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><img src="sec-conf/out-sample.png" alt=""></img> +</p><p id="ex2">Example 2: An outflow configuration to sign the message twice and add a timestamp</p><p><img src="sec-conf/out-sample2.png" alt=""></img> +</p><p id="ex3">Example 3: An inflow configuration to decrypt, verify signature and validate timestamp</p><p><img src="sec-conf/in-sample.png" alt=""></img> +</p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2006, 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_94/tcp-transport.html URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/tcp-transport.html?rev=366133&view=auto ============================================================================== --- webservices/site/trunk/targets/axis2/0_94/tcp-transport.html (added) +++ webservices/site/trunk/targets/axis2/0_94/tcp-transport.html Thu Jan 5 01:17:47 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>Axis 2.0 - TCP transport</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: 05 January 2006 + | Doc for 0.94</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="">Documentation</a><ul><li class="none"><a href="0_93/index.html">Version 0.93</a></li><li class="none"><a href="0_94/index.html">Version 0.94</a></li></ul></li><li class="expanded"><a href="overview.html">Get Involved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowTo.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li cl ass="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></ul></li><li class="none"><a href="thanks.html">Ackknowledgements</a></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></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-2006, 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_94/transport_howto.html URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/transport_howto.html?rev=366133&view=auto ============================================================================== --- webservices/site/trunk/targets/axis2/0_94/transport_howto.html (added) +++ webservices/site/trunk/targets/axis2/0_94/transport_howto.html Thu Jan 5 01:17:47 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: 05 January 2006 + | Doc for 0.94</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="">Documentation</a><ul><li class="none"><a href="0_93/index.html">Version 0.93</a></li><li class="none"><a href="0_94/index.html">Version 0.94</a></li></ul></li><li class="expanded"><a href="overview.html">Get Involved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowTo.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li cl ass="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></ul></li><li class="none"><a href="thanks.html">Ackknowledgements</a></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></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-httpclient 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 transport independent. 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.{Following code snippet extracted from MailListener as an example}</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-2006, 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}
