You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2006/10/05 11:56:40 UTC
svn commit: r453167 [5/6] - in /webservices/axis2/trunk/java/xdocs: ./ adb/
adb/images/ images/ images/archi-guide/ images/userguide/ jibx/ resources/
resources/schemas/
Added: webservices/axis2/trunk/java/xdocs/rest-ws.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/rest-ws.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/rest-ws.html (added)
+++ webservices/axis2/trunk/java/xdocs/rest-ws.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,149 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>RESTful Web Services Support</title>
+</head>
+
+<body lang="en">
+<h1>RESTful Web Services Support</h1>
+
+<p>This document presents introduction on REST and REST with HTTP POST &
+GET.</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#rest_with_post">Doing REST Web Services with HTTP POST</a>
+ <ul>
+ <li><a href="#sample">Sample REST - HTTP POST Client</a></li>
+ </ul>
+ </li>
+ <li><a href="#rest_with_get">Access a REST Web Service via HTTP GET</a></li>
+</ul>
+<a name="intro"></a>
+
+<h2>Introduction</h2>
+
+<p>REST (Representational State Transfer) 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>
+<a name="rest_with_post"></a>
+
+<h2>Doing REST Web Services with HTTP POST</h2>
+
+<p>Axis will 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.<br>
+Set a property in the client api.<br>
+<source></p>
+<pre>...
+Options options = new Options();
+options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);
+...</pre>
+</source><a name="sample"></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</p>
+<pre>userguide.example1.MyService </pre>
+
+<p>of the samples.The class source will be as follows:</p>
+<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.setTransportInProtocol(Constants.TRANSPORT_HTTP);
+
+ options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);
+
+ ServiceClient sender = new ServiceClient();
+ sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
+ sender.setOptions(options);
+ OMElement result = sender.sendReceive(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>
+</source><a name="rest_with_get"></a>
+
+<h2>Access a REST Web Service via HTTP GET</h2>
+
+<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>
+<source><pre>http://127.0.0.1:8080/axis2/services/version/getVersion</pre>
+</source>
+<p>Result can be shown in the browser as follows:</p>
+<img src="images/userguide/http-get-ws.jpg" alt="">
+
+<p>For example, the following request,</p>
+<source><pre>http://127.0.0.1:8080/axis2/services/version/getVersion</pre>
+</source>will be converted to the following SOAP Message for processing by
+Axis2.<source>
+<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>
+</source>
+<h2>Resources</h2>
+
+<p>How I Explained REST to My Wife, By Ryan Tomayko -<a
+href="http://naeblis.cx/articles/2004/12/12/rest-to-my-wife">http://naeblis.cx/articles/2004/12/12/rest-to-my-wife</a></p>
+
+<p>Building Web Services the REST Way, By Roger L. Costello -<a
+href="http://www.xfront.com/REST-Web-Services.html">
+http://www.xfront.com/REST-Web-Services.html</a></p>
+
+<p>Resource-oriented vs. activity-oriented Web services, By James Snell- <a
+href="http://www-128.ibm.com/developerworks/webservices/library/ws-restvsoap/">http://www-128.ibm.com/developerworks/webservices/library/ws-restvsoap/</a></p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/soapmonitor-module.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/soapmonitor-module.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/soapmonitor-module.html (added)
+++ webservices/axis2/trunk/java/xdocs/soapmonitor-module.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,137 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>The SOAP Monitor Module</title>
+</head>
+
+<body>
+<h1>Using the SOAP Monitor</h1>
+
+<p>Web service developers often have the need to see the SOAP messages being
+used to invoke Web services along with the results of those messages. The
+goal of the SOAP Monitor utility is to provide a way for these developers to
+monitor the SOAP messages being used without requiring any special
+configuration or restarting of the server.</p>
+
+<p>In this utility, a handler has been written and added to the global
+handler chain. As SOAP requests and responses are received, the SOAP message
+information is forwarded to a SOAP monitor service where it can be displayed
+using a Web browser interface. The SOAP message information is accessed by a
+Web browser by going to http://localhost:8080/axis2/SOAPMonitor (where 8080
+is the port number where the application server is running). The SOAP message
+information is displayed through a Web browser by using an applet that opens
+a socket connection to the SOAP monitor service. This applet requires a Java
+plug-in 1.3 or higher to be installed in your browser. If you do not have a
+correct plug-in, the browser should prompt you to install one. The port used
+by the SOAP monitor service to communicate with applets is configurable. Edit
+the web.xml file to change the port used by Axis2 Web application.</p>
+
+<p>The SOAP Monitor module (soapmonitor.mar) is available in the axis2.war
+but it is not engaged by default. The SOAP Monitor is NOT enabled by default
+for security reasons.</p>
+
+<p>The SOAP Monitor can be engaged by inserting the following in the
+axis2.xml file.</p>
+<source><pre> <module ref="soapmonitor"/></pre>
+</source>
+<p>Then in the axis2.xml file define your phase orders for 'soapmonitorPhase'
+referenced in the module.xml of soapmonitor.mars. Below is an example which
+should NOT be copied exactly, since the default phases change occasionally.
+The important point here is that 'soapmonitorPhase' should be placed under
+the 'user can add his own phases to this area' comment in the 'inflow',
+'outflow', 'INfaultflow', and 'Outfaultflow' sections.</p>
+<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="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"/>
+ <phase name="soapmonitorPhase"/>
+ </phaseOrder>
+ <phaseOrder type="outflow">
+ <!--user can add his own phases to this area-->
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ <!--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"/>
+ <phase name="soapmonitorPhase"/>
+ </phaseOrder>
+ <phaseOrder type="Outfaultflow">
+ <!--user can add his own phases to this area-->
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ <phase name="PolicyDetermination"/>
+ <phase name="MessageOut"/>
+ </phaseOrder></pre>
+
+<p>To configure the servlet to communicate with the applet, add the following
+to web.xml (the SOAPMonitorPort is configurable) :</p>
+<pre> <servlet>
+ <servlet-name>SOAPMonitorService</servlet-name>
+ <display-name>SOAPMonitorService</display-name>
+ <servlet-class>
+ org.apache.axis2.soapmonitor.servlet.SOAPMonitorService
+ </servlet-class>
+ <init-param>
+ <param-name>SOAPMonitorPort</param-name>
+ <param-value>5001</param-value>
+ </init-param>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>SOAPMonitorService</servlet-name>
+ <url-pattern>/SOAPMonitor</url-pattern>
+ </servlet-mapping></pre>
+
+<p>Finally, compile the applet classes and place them at the root of the war
+- for example axis2/SOAPMonitorApplet*.class/WEB-INF :</p>
+<pre>javac -classpath axis2-soapmonitor.jar SOAPMonitorApplet.java</pre>
+
+<p>You can find the SOAPMonitorApplet.java in the source distribution. </p>
+
+<p>Alternatively, you can get the compiled applet classes from the
+axis2-soapmonitor-*.jar from inside the expanded axis2.war under WEB-INF/lib
+. Simply execute 'jar -xf axis2-soapmonitor-*.jar' and place the applet
+classes as axis2/SOAPMonitorApplet*.class/WEB-INF. </p>
+
+<p>Using a Web browser, go to http[s]://host[:port][/webapp]/SOAPMonitor
+(e.g. http://localhost:8080/axis2/SOAPMonitor) substituting the correct
+values for your Web application. This will show the SOAP Monitor applet for
+viewing service requests and responses. Any requests to services that have
+been configured and deployed correctly should show up in the applet.</p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/spring.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/spring.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/spring.html (added)
+++ webservices/axis2/trunk/java/xdocs/spring.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,468 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Axis2 integration with the Spring Framework</title>
+</head>
+
+<body lang="en">
+<h1>Axis2 Integration With The Spring Framework</h1>
+
+<p>This document is a guide on how to use Axis2 with the Spring Framework</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#1">Introduction</a></li>
+ <li><a href="#2">Configuring Axis2 to be Spring aware</a>
+ <ul>
+ <li><a href="#21">Programming Model</a></li>
+ <li><a href="#22">Simple Spring config example</a></li>
+ <li><a href="#23">Inside a Servlet Container</a></li>
+ <li><a href="#24">Outside a Servlet Container</a></li>
+ <li><a href="#25">Putting it all together</a></li>
+ <li><a href="#26">Spring inside an AAR </a>
+ <ul>
+ <li><a href="#261">The Spring inside an AAR layout</a></li>
+ <li><a href="#262">The Spring inside an AAR init class</a></li>
+ <li><a href="#263">Known issues running Spring inside the AAR</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+</ul>
+<a name="1"></a>
+
+<h2>Introduction</h2>
+
+<p>The idea behind Axis2 and Spring integration is that Axis2 simply needs to
+have Spring supply in one of its pre-loaded beans to the Axis2 Message
+Receiver defined in the AAR services.xml . While Axis2 typically uses
+reflection to instantiate the ServiceClass defined in the services.xml that
+the Message Receiver will use, alternatively one can define a
+ServiceObjectSupplier that will supply the Object.</p>
+
+<p>This guide will show how to use two separate ServiceObjectSupplier classes
+that are part of the Axis2 standard distribution: One for use with a servlet
+container, and one without. Once configured, the web service itself acts like
+any other Spring wired bean. These Spring beans can be loaded any way desired,
+as Axis2 has no configuration file dependencies from Spring. Spring
+versions 1.2.6 and 1.2.8 have been tested, but probably any version would
+work as only core functionality is required.</p>
+
+<p>This guide assumes some basic knowledge of Axis2. See the <a
+href="userguide.html">User's Guide</a> for more information.</p>
+<a name="2"></a>
+
+<h2>Configuring Axis2 to be Spring Aware</h2>
+<a name="21"></a>
+
+<h3>Programming Model</h3>
+
+<p>From an Axis2 standpoint, two hooks are needed to be placed into the AAR
+services.xml: The ServiceObjectSupplier that hooks Axis2 and Spring together,
+and the name of Spring bean that Axis2 will use as the service. All Message
+Receivers are currently supported, as would be any Message Receiver that
+extends org.apache.axis2.receivers.AbstractMessageReceiver .</p>
+<a name="22"></a>
+
+<h3>Simple Spring Config Example</h3>
+
+<p>For the purpose of this example, and for no other reason besides
+simplicity, we'll configure Spring via a WAR file's web.xml. Lets add a
+context-param and a listener:</p>
+<pre><listener>
+ <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
+</listener>
+<context-param>
+ <param-name>contextConfigLocation</param-name>
+ <param-value>/WEB-INF/applicationContext.xml</param-value>
+ </context-param></pre>
+
+<p>Next we will show two examples of Spring's /WEB-INF/applicationContext.xml
+referenced in the web.xml listener - one with a servlet container, and one
+without.</p>
+<a name="23"></a>
+
+<h3>Inside a Servlet Container</h3>
+
+<p>This 'inside a servlet container' example applicationContext.xml should be
+familiar to any Spring user:</p>
+<pre> <?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
+
+<beans>
+ <!-- Axis2 Web Service, but to Spring, its just another bean that has dependencies -->
+ <bean id="springAwareService" class="spring.SpringAwareService">
+ <property name="myBean" ref="myBean"/>
+ </bean>
+
+ <!-- just another bean / interface with a wired implementation, that's injected by Spring
+ into the Web Service -->
+ <bean id="myBean" class="spring.MyBeanImpl">
+ <property name="val" value="Spring, emerge thyself" />
+ </bean>
+</beans></pre>
+
+<p>If the service is running in a Servlet Container, i.e., Axis2 will be able
+to get a hold of ServletContext, the services.xml for the example would be
+using SpringServletContextObjectSupplier such as:</p>
+<pre> <service name="SpringAwareService">
+ <description>
+ simple spring example
+ </description>
+ <parameter name="ServiceObjectSupplier" locked="false">org.apache.axis2.extensions.spring.receivers.SpringServletContextObjectSupplier</parameter>
+ <parameter name="SpringBeanName" locked="false">springAwareService</parameter>
+ <operation name="getValue">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+</service> </pre>
+
+<p>While the above example uses RawXMLINOutMessageReceiver as its
+messageReceiver class, all Message Receivers are currently supported, as
+would be any Message Receiver that extends
+org.apache.axis2.receivers.AbstractMessageReceiver .</p>
+<a name="24"></a>
+
+<h3>Outside a Servlet Container</h3>
+
+<p>In the case Axis2 can't get a ServletContext, you have the option of
+defining a bean that takes advantage of Spring's internal abilities
+(ApplicationContextAware interface, specifically) to provide an Application
+Context to Axis2, with a bean ref 'applicationContext' :</p>
+<pre><?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
+
+<beans>
+ <!-- Configure spring to give a hook to axis2 without a ServletContext -->
+ <bean id="applicationContext"
+ class="org.apache.axis2.extensions.spring.receivers.ApplicationContextHolder" />
+
+ <!-- Axis2 Web Service, but to Spring, its just another bean that has dependencies -->
+ <bean id="springAwareService"
+ class="spring.SpringAwareService">
+ <property name="myBean" ref="myBean" />
+ </bean>
+
+ <!-- just another bean with a wired implementation, that's injected by Spring
+ into the Web Service -->
+ <bean id="myBean"
+ class="spring.MyBeanImpl">
+ <property name="val" value="Spring, emerge thyself" />
+ </bean>
+</beans></pre>
+
+<p>If the service is _NOT_ running in a Servlet Container, i.e., Axis2 will
+_NOT_ be able to get a hold of ServletContext, the services.xml for the
+example would be using SpringAppContextAwareObjectSupplier such as:</p>
+<pre> <service name="SpringAwareService">
+ <description>
+ simple spring example
+ </description>
+ <parameter name="ServiceObjectSupplier" locked="false">org.apache.axis2.extensions.spring.receivers.SpringAppContextAwareObjectSupplier</parameter>
+ <parameter name="SpringBeanName" locked="false">springAwareService</parameter>
+ <operation name="getValue">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+</service> </pre>
+
+<p>While the above example uses RawXMLINOutMessageReceiver as its
+messageReceiver class, all Message Receivers are currently supported, as
+would be any Message Receiver that extends
+org.apache.axis2.receivers.AbstractMessageReceiver .</p>
+
+<p>In a non-servlet container environment, one way you could load the
+applicationContext.xml file is in a place that will be run once, upon
+start-up, execute:</p>
+<pre>import org.springframework.context.support.ClassPathXmlApplicationContext;
+
+ public void createSpringAppCtx(ClassLoader cl)
+ throws Exception {
+
+ ClassPathXmlApplicationContext ctx = new
+ ClassPathXmlApplicationContext(new String[] {Constants.MY_PATH +
+ "spring/applicationContext.xml"}, false);
+ ctx.setClassLoader(cl);
+ ctx.refresh();</pre>
+} <a name="25"></a>
+
+<h3>Putting It All Together</h3>
+
+<p>From here, its just standard Axis2 coding, only now the service has Spring
+wiring capabilities. The implementation is the same whether using either
+SpringServletContextObjectSupplier or SpringAppContextAwareObjectSupplier.
+The service is below:</p>
+<pre>package spring;
+
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.om.OMNamespace;
+import org.apache.axiom.om.OMText;
+
+public class SpringAwareService {
+
+ private MyBean myBean = null;
+
+ //spring 'injects' this implementation
+ public void setMyBean(MyBean myBean) {
+ this.myBean = myBean;
+ }
+
+ // The web service
+ public OMElement getValue(OMElement ignore) {
+ OMFactory factory=
+ OMAbstractFactory.getOMFactory();
+ OMNamespace payloadNs= factory.createOMNamespace(
+ "http://springExample.org/example1", "example1");
+ OMElement payload =
+ factory.createOMElement("string", payloadNs);
+ OMText response = factory.createOMText(this.myBean.emerge());
+ payload.addChild(response);
+ return payload;
+ }
+} </pre>
+
+<p>For those new to Spring, one of the ideas is that you program to an
+Interface, and the implementation is pluggable. This idea is referenced in
+the Spring config file above. Below is the interface:</p>
+<pre>package spring;
+
+/** Interface for Spring aware Bean */
+public interface MyBean {
+ String emerge();
+}</pre>
+
+<p>Here's the implementation:</p>
+<pre>/** Spring wired implementation */
+public class MyBeanImpl implements MyBean {
+
+ String str = null;
+ // spring 'injects' this value
+ public void setVal(String s) {
+ str = s;
+ }
+ // web service gets this value
+ public String emerge() {
+ return str;
+ }
+}</pre>
+
+<p>Lastly here's the client - not really necessary for the example, other
+than for completeness:</p>
+<pre>package client;
+
+import java.io.StringWriter;
+
+import javax.xml.stream.XMLOutputFactory;
+
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.om.OMNamespace;
+import org.apache.axis2.addressing.EndpointReference;
+import org.apache.axis2.client.Options;
+import org.apache.axis2.client.ServiceClient;
+
+public class TestClient {
+ /** Access point inside the servlet container. **/
+ private static EndpointReference targetEPR =
+ new EndpointReference(
+ "http://localhost:8080/axis2/services/springExample");
+
+ /**
+ * Simple axis2 client.
+ *
+ * @param args Main
+ */
+ public static void main(String[] args) {
+ try {
+ OMFactory factory = OMAbstractFactory.getOMFactory();
+ OMNamespace omNs = factory.createOMNamespace(
+ "http://springExample.org/example1", "example1");
+
+ OMElement method = factory.createOMElement("getValue", omNs);
+ OMElement value = factory.createOMElement("Text", omNs);
+ value.addChild(factory.createOMText(value, "Some String "));
+ method.addChild(value);
+
+ ServiceClient serviceClient = new ServiceClient();
+
+ Options options = new Options();
+ serviceClient.setOptions(options);
+ options.setTo(targetEPR);
+
+ //Blocking invocation
+ OMElement result = serviceClient.sendReceive(method);
+
+ StringWriter writer = new StringWriter();
+ result.serialize(XMLOutputFactory.newInstance()
+ .createXMLStreamWriter(writer));
+ writer.flush();
+
+ System.out.println("Response: " + writer.toString());
+ } catch (Exception ex) {
+ ex.printStackTrace();
+ }
+ }
+} </pre>
+
+<p>To run this example, make sure you have the axis2-spring*.jar that comes
+from the axis2-std-*-bin distro in the server side WEB-INF/lib, as well as
+the appropriate Spring jar - most will use the full spring.jar, but the
+minimum requirements are spring-core, spring-beans, spring-context and
+spring-web. Running the client, you should see this output:</p>
+<pre>Response: <example1:string xmlns:example1="http://springExample.org/example1"
+ xmlns:tns="http://ws.apache.org/axis2">Spring, emerge thyself</example1:string></pre>
+<a name="26"></a>
+
+<h3>Spring Inside an AAR</h3>
+
+<p>Frequently Axis2 users wish to run Spring inside the AAR. Here we show you
+how. There are four points to be aware of here:</p>
+
+<p>(A) You need to configure Spring to use the Axis2 Service Classloader. See the
+ <a href="#263">Known issues running Spring inside the AAR</a> area. </p>
+
+<p>(B) Its up to you to load Spring, though we give an example below.</p>
+
+<p>(C) For reasons such as classloader isolation the
+SpringAppContextAwareObjectSupplier is the best choice.</p>
+
+<p>(D) The springframework jar and axis2-spring-*.jar will be placed inside
+the AAR under the lib directory.</p>
+<ul>
+ <li><strong><a name="261"></a>The Spring inside an AAR layout</strong>
+</ul>
+ <source>
+ <pre>./springExample.aar
+./META-INF
+./META-INF/MANIFEST.MF
+./META-INF/services.xml
+./applicationContext.xml
+./lib
+./lib/axis2-spring-SNAPSHOT.jar
+./lib/spring.jar
+./spring
+./spring/MyBean.class
+./spring/MyBeanImpl.class
+./spring/SpringAwareService.class
+./spring/SpringInit.class </pre> </source>
+<ul>
+ <li><strong><a name="262"></a>The Spring inside an AAR init class</strong></li>
+</ul>
+ <p>One way to initialize Spring is to use the
+ org.apache.axis2.engine.Service. </p>
+ <p>IMPORTANT: this interface at the time of this writing is being
+ discussed for refactoring. We'll update the Spring documents as soon as
+ possible. Be aware that this interface name perhaps will change, though
+ the functionality will probably be in place, somewhere. The important
+ part for us is the startUp() method and setting Spring to use the Service
+ classloader:</p>
+ <source><pre>package spring;
+
+import org.apache.axiom.om.OMElement;
+import org.apache.axis2.engine.Service;
+import org.apache.axis2.context.ConfigurationContext;
+import org.apache.axis2.context.OperationContext;
+import org.apache.axis2.context.ServiceContext;
+import org.apache.axis2.description.AxisService;
+import org.springframework.context.support.ClassPathXmlApplicationContext;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+public class SpringInit implements Service {
+
+ private static Log logger = LogFactory
+ .getLog(SpringInit .class);
+
+ // The web service
+ public OMElement springInit(OMElement ignore) {
+
+ return null;
+ }
+
+ public void init(ServiceContext serviceContext) {
+
+ }
+
+ public void setOperationContext(OperationContext arg0) {
+
+ }
+
+ public void destroy(ServiceContext arg0) {
+
+ }
+
+ /**
+ * this will be called during the deployement time of the service. irrespective
+ * of the service scope this method will be called
+ */
+ public void startUp(ConfigurationContext ignore, AxisService service) {
+
+ ClassLoader classLoader = service.getClassLoader();
+ ClassPathXmlApplicationContext appCtx = new
+ ClassPathXmlApplicationContext(new String[] {"applicationContext.xml"}, false);
+ appCtx.setClassLoader(classLoader);
+ appCtx.refresh();
+ if (logger.isDebugEnabled()) {
+ logger.debug("\n\nstartUp() set spring classloader via axisService.getClassLoader() ... ");
+ }
+ }
+}</pre>
+ </source>
+ <p>Here's the services.xml that now includes SpringInit and the
+ needed load-on-startup parameter. There is also the forceTCCL parameter which is needed
+ when loading Spring in the AAR - see the <a href="#263">Known issues running Spring inside the AAR</a>
+ area. </p>
+ <source><pre><serviceGroup>
+ <service name="SpringInit">
+ <description>
+ This is a spring sample Web Service with two operations.
+ </description>
+ <parameter name="ServiceClass" locked="false">spring.SpringInit</parameter>
+ <parameter name="forceTCCL" locked="false">true</parameter>
+ <parameter name="load-on-startup" locked="false">true</parameter>
+ <operation name="springInit">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ </service>
+ <service name="SpringAwareService">
+ <description>
+ simple spring example
+ </description>
+ <parameter name="ServiceObjectSupplier" locked="false">org.apache.axis2.extensions.spring.receivers.SpringAppContextAwareObjectSupplier</parameter>
+ <parameter name="SpringBeanName" locked="false">springAwareService</parameter>
+ <operation name="getValue">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ </service>
+</serviceGroup></pre>
+</source>
+<ul>
+ <li>
+ <strong><a name="263"></a>Known issues running Spring inside the AAR</strong>
+ </li>
+</ul>
+ <p>The Axis2 classloader strategy by default does not permit Spring to run inside the AAR. To allow
+ Spring to run inside the AAR, the forceTCCL parameter is used in the services.xml as shown in the example
+ above. The behavior of forceTCCL was the default in the developement cycle in between 1.0 and 1.1, but
+ it resulted in the JIRA issue AXIS2-1214 - essentially problems with getting an initContext.lookup()
+ handle inside the AAR. Spring users typically have little desire to use initContext.lookup() however,
+ as they get their Datasources via org.springframework.jdbc.datasource.DriverManagerDataSource in an
+ xml file or with annotations. For ejb home references and the like, Spring provides JndiObjectFactoryBean.
+ While fully testing JndiObjectFactoryBean with ejb has not been done yet - if you do, please send a message
+ to the axis users list - Datasources via Spring inside the AAR have been tested. Basically it works as
+ typically done with Spring, though if you are passing Hibernate XML files you need to put them in a
+ place where Spring will find them. The most flexible way is as follows, using logging in DEBUG mode
+ to see where Spring will look in your jar / class locations: </p>
+ <source><pre>
+ <bean id="mySessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
+ <property name="mappingLocations">
+ <value>classpath*:**/Asset.hbm.xml</value>
+ </property>
+ ...
+ </bean>
+</pre> </source>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/tcp-transport.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/tcp-transport.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/tcp-transport.html (added)
+++ webservices/axis2/trunk/java/xdocs/tcp-transport.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,119 @@
+<html>
+<head>
+ <meta content="">
+ <meta content="">
+ <meta content="">
+ <meta http-equiv="content-type" content="">
+ <title>TCP transport</title>
+</head>
+
+<body lang="en">
+<h1>TCP Transport</h1>
+This document will explain how to send and receive SOAP Messages via TCP in
+Axis2.
+
+<p><i>Send your feedback or questions to: <a
+href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
+subject with [Axis2]. To subscribe to mailing list see <a
+href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#start">How to Start the TCPServer</a></li>
+ <li><a href="#send">How to Send SOAP Messages Using TCP Transport</a></li>
+ <li><a href="#samples">Samples</a></li>
+ <li><a href="#components">Transport Components</a></li>
+</ul>
+<a name="intro"></a>
+
+<h2>Introduction</h2>
+
+<p>Axis2 supports TCP as a transport. It has support for both send and
+receive SOAP Messages via TCP. TCP transport does not have any application
+level headers and the SOAP Message that is sent should be self contained.
+This makes the interaction fast and simple. However since there are no
+application headers, it does not have the privilege of having request URI,
+and Service dispatching should be done by an alternative method. Thus,
+RequestURIBasedDispatcher can not be used. Following are the two main
+alternatives available for dispatching in the Axis2 environment.</p>
+<ol>
+ <li>Use the name space URI of the first child element of SOAPBody.
+ (SOAPMessageBodyBasedDispatcher)</li>
+ <li>Enable WS-Addressing. In the case of version 1.1 release Addressing is
+ default (SOAPActionBasedDispatcher)</li>
+</ol>
+
+<p>When the TCP request is sent it is the user's responsibility to use either
+Addressing or SOAP body base mechanism.</p>
+<a name="start"></a>
+
+<h2>How to Start the TCPServer</h2>
+
+<p>The TCP server can be started by running the class
+org.apache.axis2.transport.tcp.TCPServer with two parameters - <a
+href="../faq.html#c5">repository</a> and port number, as arguments. This
+class needs all the Axis dependency jars in the classpath. New services can
+be added in the usual way by dropping the archives to the repository (See <a
+href="userguide.html">User's Guide</a> for more information)</p>
+
+<p>Alternatively the TCP Server can run with tcp-server.bat/ tcp-server.sh
+file in the bin directory of the Binary distribution of TCP Server.</p>
+<a name="send"></a>
+
+<h2>How to Send SOAP Messages Using TCP Transport</h2>
+
+<p>TCP transport can be enabled easily from the call API. Following code
+segment demonstrate how it can be done.</p>
+<source><pre>OMElement payload = ...
+
+ServiceClient serviceClient = new ServiceClient();
+Options options = new Options();
+options.setTo(targetEPR);
+options.useSeperateListener(false);
+serviceClient.setOptions(options);
+
+OMElement response =
+ serviceClient.sendReceive(payload);</pre>
+</source>
+<p>The transport that should be invoked is inferred from the targetEPR
+(tcp://...). In this case it is TCP and the listener, also TCP . SOAP Message
+has to be self contained in order to use Addressing. The other option 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>
+<a name="sample"></a>
+
+<h2>Sample</h2>
+
+<p>Sample for a TCP Client can be found from the
+samples/userguide/src/userguide/clients/TCPClient.java in the binary
+distribution. This accesses the same Web service explained in the <a
+href="userguide.html">Axis2 User's Guide</a>. The client first starts the
+TCPServer with the same repository used for the <a
+href="userguide.html">Axis2 User's Guide</a> samples. Since sample is already
+deployed in the repository while trying the userguide it will be
+automatically available.</p>
+<a name="components"></a>
+
+<h2>Transport Components</h2>
+
+<p>Axis2 TCP transport has two components, 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 the two TCP transport components would look as
+follows.</p>
+
+<p>If the TCP server is started manually this configuration does not take
+effect. In return this effects the transport Listener's start by Axis2. (e.g.
+Listener started by the Complete Async interaction)</p>
+
+<p>Following xml lines initializes the TCPTransport Receiver:</p>
+<source><pre><transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPServer">
+ <parameter name="port" locked="false">6060</parameter>
+</transportReceiver></pre>
+</source>
+<p>Following xml lines adds the TCPTransport Sender:</p>
+<source><pre><transportSender name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportSender"/></pre>
+</source></body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/transport_howto.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/transport_howto.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/transport_howto.html (added)
+++ webservices/axis2/trunk/java/xdocs/transport_howto.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,218 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title></title>
+</head>
+
+<body>
+<h1>How To Write Your Own Axis2 Transport</h1>
+
+<h2>Prologue</h2>
+
+<p>To stop you from reinventing the wheel, before we get started, I will
+quickly list the transports that are already supported in Axis2 with a small
+description. </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 thread 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. If you are not familiar with the Axis2
+architecture, please go through the <a
+href="Axis2ArchitectureGuide.html">Axis2 Architecture Guide</a> before you
+read any further.</p>
+
+<h2>Introduction</h2>
+
+<p>Broadly speaking, a transport inside Axis2 can be classified as a way of
+getting 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.
+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. I will take you through the process of adding the entries
+in relevent sections.</p>
+
+<h2>Transport Receiver</h2>
+
+<p>Any message that is coming into Axis2 needs to go through 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, without further delay lets 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><source></p>
+<pre>try {
+ //Create a factory
+ ConfigurationContextFactory factory = new ConfigurationContextFactory();
+ //Use the factory and an Axis2 repository to create a new Configuration Context
+ configurationContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(repository_directory,
+axis2xmllocation);
+} catch (Exception e) {
+ log.info(e.getMessage());
+}</pre>
+</source>
+<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 the engine.receive(msgContext) method.{Following code
+snippet is extracted from MailListener as an example}</p>
+<source><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>
+</source>
+<p>Now that we have the coding in place, we need to let Axis2 know about our
+new transport receiver. We do this by adding 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>
+<source><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>
+</source>
+<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>As you can see getting a new transport receiver up and running is a task
+that requires very little effort.</p>
+
+<h2>Transport Sender</h2>
+
+<p>Any message that is to be sent out of 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>
+<source><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>
+</source>
+<p>Therefor, depending on if 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>
+<source><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>
+</source>
+<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>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org