You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ch...@apache.org on 2007/05/25 10:09:37 UTC
svn commit: r541579 [9/18] - in /webservices/axis2/trunk/java/xdocs: ./
@axis2_version_dir@/ @axis2_version_dir@/adb/
@axis2_version_dir@/adb/images/ @axis2_version_dir@/images/
@axis2_version_dir@/images/archi-guide/ @axis2_version_dir@/images/usergui...
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/spring.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/spring.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/spring.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/spring.html Fri May 25 01:09:03 2007
@@ -0,0 +1,469 @@
+<!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>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</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">With a ServletContext</a></li>
+ <li><a href="#24">Without a ServletContext</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>Axis2 and Spring integration takes place when Spring supplies one of its
+pre-loaded beans to the Axis2 Message Receiver defined in the AAR
+services.xml. Axis2 typically uses reflection to instantiate the ServiceClass
+defined in the services.xml used by the Message Receiver. Alternatively, you
+can define a ServiceObjectSupplier that will supply the Object.</p>
+
+<p>This guide describes how to use two separate ServiceObjectSupplier classes
+that are a part of the Axis2 standard distribution - one for use with a
+ServletContext, 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, 1.2.8 and 2.0 have been tested, but probably any version
+would work as only the 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>
+
+<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 the 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, we'll configure Spring via a WAR file's
+web.xml. Let's 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 using a ServletContext, and one
+without.</p>
+<a name="23"></a>
+
+<h3>With a ServletContext</h3>
+
+<p>This example (with a ServletContext) 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 the 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>Without a ServletContext</h3>
+
+<p>In case Axis2 can't get a ServletContext, (i.e., uses a different
+transport or is running Axis2 inside the AAR etc,) 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 <strong>not</strong> running in a Servlet Container,
+i.e., Axis2 will not be able to get a hold of ServletContext or you prefer
+not to, the services.xml for the example will 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 an environment <strong>without a ServletContext</strong>, one way you
+could load the applicationContext.xml file is in a place that will be run
+once. Upon start-up, execute the following:</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, it's 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 as follows:</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 who are new to Spring, one of the ideas is that you program an
+Interface, as 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 {
+ private static EndpointReference targetEPR =
+ new EndpointReference(
+ "http://localhost:8080/axis2/services/SpringAwareService");
+
+ /**
+ * 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>The examples above assume that both the spring framework .jar and the
+axis2-spring-*.jar are under WEB-INF/lib. In such a case, the classes shown
+in this tutorial need to be placed in a JAR under WEB-INF/lib. In this
+example the JAR layout is:</p>
+<source><pre>./mySpring.jar
+./META-INF
+./META-INF/MANIFEST.MF
+./spring
+./spring/MyBean.class
+./spring/MyBeanImpl.class
+./spring/SpringAwareService.class</pre>
+</source>
+<p>Since all the user classes are in mySpring.jar in this example, the AAR
+merely contains the services.xml file:</p>
+<source><pre>./springExample.aar
+./META-INF
+./META-INF/MANIFEST.MF
+./META-INF/services.xml</pre>
+</source>
+<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. When 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>Axis2 users frequently want to run Spring inside the AAR. Here we show you
+how it is done. There are four points to be aware of:</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) It's 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. Please <strong>move</strong> the
+axis2-spring-*.jar from WEB-INF/lib to inside the AAR, as shown below - it
+will <strong>not</strong> work otherwise.</p>
+<ul>
+ <li><strong><a name="261"></a>The Spring inside an AAR layout</strong></li>
+</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>
+<p>As explained in the <a href="#24">Without a ServletContext</a> section,
+the 'Spring inside an AAR' config needs to hook Axis2 and Spring together via
+a Spring bean. Place the following in your Spring config file:</p>
+<pre> <!-- Configure spring to give a hook to axis2 without a ServletContext -->
+ <bean id="applicationContext"
+ class="org.apache.axis2.extensions.spring.receivers.ApplicationContextHolder" /></pre>
+<ul>
+ <li><strong><a name="262"></a>The Spring inside an AAR init
+ class</strong></li>
+</ul>
+
+<p>One way to initialize Spring inside the AAR is to use the
+org.apache.axis2.engine.ServiceLifeCycle interface. Here we give an
+example:</p>
+<source><pre>package spring;
+
+import org.apache.axis2.engine.ServiceLifeCycle;
+import org.apache.axis2.context.ConfigurationContext;
+import org.apache.axis2.description.AxisService;
+import org.springframework.context.support.ClassPathXmlApplicationContext;
+
+public class SpringInit implements ServiceLifeCycle {
+
+ /**
+ * 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) {
+
+ try {
+ System.out.println("Starting spring init");
+ ClassLoader classLoader = service.getClassLoader();
+ ClassPathXmlApplicationContext appCtx = new
+ ClassPathXmlApplicationContext(new String[] {"applicationContext.xml"}, false);
+ appCtx.setClassLoader(classLoader);
+ appCtx.refresh();
+ System.out.println("spring loaded");
+ } catch (Exception ex) {
+ ex.printStackTrace();
+ }
+ }
+
+ /**
+ * This will be called during the system shut down time.
+ * irrespective
+ * of the service scope this method will be called
+ */
+ public void shutDown(ConfigurationContext ctxIgnore, AxisService ignore) {
+ }
+}</pre>
+</source>
+<p>Here's the services.xml that now includes SpringInit and the
+SpringAwareService shown above. There is also the composite 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>
+ <!-- Invoke SpringInit on server startup and shutdown -->
+ <service name="SpringAwareService" class="spring.SpringInit">
+ <description>
+ simple spring example - inside the AAR
+ </description>
+ <!-- need the TCCL param when using spring inside the AAR -->
+ <parameter name="ServiceTCCL" locked="false">composite</parameter>
+ <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>By default, the Axis2 classloader strategy does not permit Spring to run
+inside the AAR. To allow Spring to run inside the AAR, the 'composite'
+parameter is used in the services.xml as shown in the example above. There
+was default behavior of 'composite' in the development cycle in between 1.0
+and 1.1, but it resulted in the JIRA issue AXIS2-1214 -problems with getting
+an initContext.lookup() handle inside the AAR. Spring users typically have
+little desire to use initContext.lookup(), 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*:**/MyEntity.hbm.xml</value>
+ </property>
+ ...
+ </bean> </pre>
+</source></body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/src/Axis2SampleDocLitServiceCode.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/src/Axis2SampleDocLitServiceCode.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/src/Axis2SampleDocLitServiceCode.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/src/Axis2SampleDocLitServiceCode.html Fri May 25 01:09:03 2007
@@ -0,0 +1,171 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title></title>
+ <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+</head>
+
+<body lang="en">
+<h1>Code Listing For Axis2SampleDocLitService Service</h1>
+
+<h2>Server:</h2>
+
+<h3>echoString</h3>
+
+<p>Locate the following code segment in "Axis2SampleDocLitServiceSkeleton.java".<br>
+</p>
+<source><pre>public org.apache.axis2.userguide.xsd.EchoStringReturnDocument
+ echoString(org.apache.axis2.userguide.xsd.EchoStringParamDocument param4 ){
+ //Todo: fill this with the necessary business logic
+ throw new java.lang.UnsupportedOperationException();
+ }
+</pre></source>
+
+<p>Then complete the code by adding the business logic as shown below:</p>
+<source>
+<pre>public org.apache.axis2.userguide.xsd.EchoStringReturnDocument
+ echoString(org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) throws Exception {
+ //Use the factory to create the output document
+ org.apache.axis2.userguide.xsd.EchoStringReturnDocument retDoc =
+ org.apache.axis2.userguide.xsd.EchoStringReturnDocument.Factory.newInstance();
+ //send the string back.
+ retDoc.setEchoStringReturn(param4.getEchoStringParam());
+ return retDoc;
+ }</pre>
+</source>
+
+<h3>echoStringArray</h3>
+
+<p>The code segment for echoStringArray is shown below:</p>
+<source>
+<pre>public org.apache.axis2.userguide.xsd.EchoStringArrayReturnDocument
+ echoStringArray(org.apache.axis2.userguide.xsd.EchoStringArrayParamDocument param0) throws Exception {
+ //Use the factory to create the output document.
+ org.apache.axis2.userguide.xsd.EchoStringArrayReturnDocument retDoc =
+ org.apache.axis2.userguide.xsd.EchoStringArrayReturnDocument.Factory.newInstance();
+ //Get the String array from the input parameters.
+ String[] inParams = param0.getEchoStringArrayParam().getStringArray();
+ org.apache.axis2.userguide.xsd.ArrayOfstringLiteral retParams =
+ org.apache.axis2.userguide.xsd.ArrayOfstringLiteral.Factory.newInstance();
+ //Set the input parameters to the output parameters for echoing.
+ for (int i = 0; i < inParams.length; i++) {
+ retParams.addString(inParams[i]);<br> }
+ //return the output document.
+ retDoc.setEchoStringArrayReturn(retParams);
+ return retDoc;
+ }</pre>
+</source>
+
+<h3>echoStruct</h3>
+
+<p>The code segment for echoStruct is shown below:</p>
+<source><pre>
+ public org.apache.axis2.userguide.xsd.EchoStructReturnDocument
+ echoStruct(org.apache.axis2.userguide.xsd.EchoStructParamDocument param2) throws Exception {
+ //Use the factory to create the output document.
+ org.apache.axis2.userguide.xsd.EchoStructReturnDocument retDoc =
+ org.apache.axis2.userguide.xsd.EchoStructReturnDocument.Factory.newInstance();
+ //Get the SOAPStrcut from the incoming parameters
+ org.apache.axis2.userguide.xsd.SOAPStruct inStruct = param2.getEchoStructParam();
+ //Struct for the sending back
+ org.apache.axis2.userguide.xsd.SOAPStruct outStruct =
+ org.apache.axis2.userguide.xsd.SOAPStruct.Factory.newInstance();
+ //Fill the outgoing struct
+ outStruct.setVarFloat(inStruct.getVarFloat());
+ outStruct.setVarInt(inStruct.getVarInt());
+ outStruct.setVarString(inStruct.getVarString());
+ //Set the outgoing document.
+ retDoc.setEchoStructReturn(outStruct);
+ return retDoc;
+ }
+</pre></source>
+
+<h2>Client:</h2>
+
+<h3>Client for echoString Operation</h3>
+
+<p>The following code fragment shows the necessary code for utilizing the
+echoString operation of the Axis2SampleDocLitService that we have already
+deployed. The code is very simple to understand and the explanations are in
+the form of comments.</p>
+<source><pre> try {
+ org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub
+ = new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+ //Create the request document to be sent.
+ org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc =
+ org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();
+ reqDoc.setEchoStringParam("Axis2 Echo");
+ //invokes the Web service.
+ org.apache.axis2.userguide.xsd.EchoStringReturnDocument resDoc =
+ stub.echoString(reqDoc);
+ System.out.println(resDoc.getEchoStringReturn());
+ } catch (java.rmi.RemoteException e) {
+ e.printStackTrace();
+ }
+</pre></source>
+
+<p>Similarly the following code fragments show client side code for
+echoStringArray operation and echoStruct operation respectively.</p>
+
+<h3>Client for echoStringArray Operation</h3>
+<source><pre> try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub =
+ new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+ //Create the request document to be sent.
+ org.apache.axis2.userguide.xsd.EchoStringArrayParamDocument reqDoc =
+ org.apache.axis2.userguide.xsd.EchoStringArrayParamDocument.Factory.newInstance();
+ org.apache.axis2.userguide.xsd.ArrayOfstringLiteral paramArray =
+ org.apache.axis2.userguide.xsd.ArrayOfstringLiteral.Factory.newInstance();
+ paramArray.addString("Axis2");
+ paramArray.addString("Echo");
+ reqDoc.setEchoStringArrayParam(paramArray);
+ org.apache.axis2.userguide.xsd.EchoStringArrayReturnDocument resDoc =
+ stub.echoStringArray(reqDoc);
+ //Get the response params
+ String[] resParams = resDoc.getEchoStringArrayReturn().getStringArray();
+ for (int i = 0; i < resParams.length; i++) {
+ System.out.println(resParams[i]);
+ }
+ } catch (java.rmi.RemoteException e) {
+ e.printStackTrace();
+ }
+ </pre>
+ </source>
+
+<h3>Client for echoStruct Operation</h3>
+<source><pre>try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub =
+ new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+ //Create the request Document
+ org.apache.axis2.userguide.xsd.EchoStructParamDocument reqDoc =
+ org.apache.axis2.userguide.xsd.EchoStructParamDocument.Factory.newInstance();
+ //Create the complex type
+ org.apache.axis2.userguide.xsd.SOAPStruct reqStruct =
+ org.apache.axis2.userguide.xsd.SOAPStruct.Factory.newInstance();
+ reqStruct.setVarFloat(100.50F);
+ reqStruct.setVarInt(10);
+ reqStruct.setVarString("High");
+ reqDoc.setEchoStructParam(reqStruct);
+ //Service invocation
+ org.apache.axis2.userguide.xsd.EchoStructReturnDocument resDoc =
+ stub.echoStruct(reqDoc);
+ org.apache.axis2.userguide.xsd.SOAPStruct resStruct =
+ resDoc.getEchoStructReturn();
+ System.out.println("floot Value :" + resStruct.getVarFloat());
+ System.out.println("int Value :" + resStruct.getVarInt());
+ System.out.println("String Value :" + resStruct.getVarString());
+ } catch (java.rmi.RemoteException e) {
+ e.printStackTrace();
+ }
+</pre></source>
+
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/tcp-transport.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/tcp-transport.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/tcp-transport.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/tcp-transport.html Fri May 25 01:09:03 2007
@@ -0,0 +1,125 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>TCP transport</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<body lang="en">
+<h1>TCP Transport</h1>
+This document explains 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?subject=[Axis2]">axis-dev@ws.apache.org</a></i>.
+Prefix subject with [Axis2]. Subscription details are available on the <a
+href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</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 supports both sending and receiving SOAP
+messages via TCP. A 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 a request URI, and Service
+dispatching should be done by an alternative method. Thus,
+RequestURIBasedDispatcher cannot be used. The 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 and 1.1.1 releases
+ Addressing is default (SOAPActionBasedDispatcher).</li>
+</ol>
+
+<p>When the TCP request is sent, it is the user's responsibility to use
+either Addressing or the 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="adv-userguide.html">Advanced 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. The following code
+segment demonstrates how this can be done.</p>
+<source><pre>OMElement payload = ...
+ServiceClient serviceClient = new ServiceClient();
+Options options = new Options();
+options.setTo(targetEPR);
+<!--options.useSeperateListener(false);-->
+
+<!--commented off as there is an error: "The method useSeperateListener(boolean)is undefined for the type Options"-->
+
+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 is also TCP. The 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="samples"></a>
+
+<h2>Samples</h2>
+
+<p>A 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="adv-userguide.html">Axis2 Advanced User's Guide</a>. The client first
+starts the TCPServer with the same repository used for the <a
+href="adv-userguide.html">Axis2 Advanced User's Guide</a> samples. Since the
+sample is already deployed in the repository, as per the userguide, it will
+be automatically available.</p>
+
+<p>In order to run the TCPClient.java, addressing should be engaged both in
+the client and server sides. On the client side, you can engage addressing by
+copying the addressing-@axis2_version@.mar (AXIS2_HOME/repository/module) to
+AXIS2_HOME/lib directory.</p>
+<a name="components"></a>
+
+<h2>Transport Components</h2>
+
+<p>The Axis2 TCP transport has two components, a transport Listener for
+receiving the messages and a transport Sender to send the SOAP Messages. The
+Axis2 installation has both the components built into itself by default. In
+the axis2.xml configuration file, the two TCP transport components can be
+configured as shown below.</p>
+
+<p>The following XML lines initialize 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>The following XML lines add the TCPTransport Sender:</p>
+<source><pre><transportSender name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportSender"/></pre>
+</source>
+
+<p>Note: If the TCP server is started manually, this configuration does not take
+effect. In return, this affects the transport Listener's start by Axis2.
+(e.g. Listener started by the Complete Async interaction)</p>
+
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/toc.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/toc.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/toc.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/toc.html Fri May 25 01:09:03 2007
@@ -0,0 +1,138 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title></title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+ <style type="text/css" media="screen">
+<!--
+ul { list-style-type: none; margin: 0 0 0 5px; padding: 0; border-width: 0; list-style-position: outside; }
+-->
+
+
+
+
+
+
+ </style>
+</head>
+
+<body lang="en-US" dir="ltr">
+<h1>Table of Contents</h1>
+<ol>
+ <li><a href="contents.html" target="mainFrame">Introduction</a></li>
+ <li><a href="installationguide.html" target="mainFrame">Installation
+ Guide</a></li>
+ <li><a href="../modules/index.html" target="mainFrame">Add-on
+ Modules</a></li>
+ <li><a href="app_server.html" target="mainFrame">Application Server
+ Specific Configuration Guide</a></li>
+ <li><a href="quickstartguide.html" target="mainFrame">Quick Start
+ Guide</a></li>
+ <li><a href="userguide.html" target="mainFrame">User's Guide</a></li>
+ <li><a href="adv-userguide.html" target="mainFrame">Advanced User's
+ Guide</a></li>
+ <li><a href="axis2config.html" target="mainFrame">Configuration
+ Guide</a></li>
+ <li><a href="webadminguide.html" target="mainFrame">Web Administrator's
+ Guide</a></li>
+ <li><a href="Axis2ArchitectureGuide.html" target="mainFrame">Architecture
+ Guide</a></li>
+ <li><a href="pojoguide.html" target="mainFrame">POJO Guide</a></li>
+ <li><a href="spring.html" target="mainFrame">Spring Guide</a></li>
+ <li><a href="modules.html" target="mainFrame">Modules Guide</a></li>
+ <li>ADB Data Binding
+ <ul>
+ <li>14.1 <a href="adb/adb-howto.html"
+ target="mainFrame">Architecture</a></li>
+ <li>14.2 <a href="adb/adb-advanced.html" target="mainFrame">Advanced
+ Features</a></li>
+ <li>14.3 <a href="adb/adb-codegen-integration.html"
+ target="mainFrame">Code Generation Integration</a></li>
+ <li>14.4 <a href="adb/adb-tweaking.html"
+ target="mainFrame">Tweaking</a></li>
+ </ul>
+ </li>
+ <li>JiBX Data Binding
+ <ul>
+ <li>15.1 <a href="jibx/jibx-codegen-integration.html"
+ target="mainFrame">Code Generation Integration</a></li>
+ <li>15.2 <a href="jibx/jibx-doclit-example.html"
+ target="mainFrame">doc/lit Example</a></li>
+ <li>15.3 <a href="jibx/jibx-unwrapped-example.html"
+ target="mainFrame">unwrapped Example</a></li>
+ </ul>
+ </li>
+ <li>Advanced
+ <ul>
+ <li>16.1 <a href="xmlbased-server.html" target="mainFrame">AXIOM Based
+ Service</a></li>
+ <li>16.2 <a href="dii.html" target="mainFrame">AXIOM Based
+ Client</a></li>
+ </ul>
+ </li>
+ <li><a href="mtom-guide.html" target="mainFrame">Attachments/MTOM
+ Guide</a></li>
+ <li>Transports
+ <ul>
+ <li>18.1 <a href="http-transport.html" target="mainFrame">HTTP
+ Transport</a></li>
+ <li>18.2 <a href="jms-transport.html" target="mainFrame">JMS
+ Transport</a></li>
+ <li>18.3 <a href="tcp-transport.html" target="mainFrame">TCP
+ Transport</a></li>
+ <li>18.4 <a href="mail-transport.html" target="mainFrame">Mail
+ Transport</a> / <a href="mail-configuration.html"
+ target="mainFrame">(Configuration)</a></li>
+ <li>18.5 <a href="transport_howto.html" target="mainFrame">Custom
+ Transport</a></li>
+ </ul>
+ </li>
+ <li><a href="WS_policy.html" target="mainFrame">WS-Policy Support</a></li>
+ <li><a href="rest-ws.html" target="mainFrame">REST Support</a></li>
+ <li><a href="json_support.html" target="mainFrame">JSON Support</a></li>
+ <li><a href="ejb-provider.html" target="mainFrame">Guide to using EJB
+ Provider in Axis2</a></li>
+ <li><a href="soapmonitor-module.html" target="mainFrame">SOAP
+ Monitor</a></li>
+ <li><a href="reference.html" target="mainFrame">Command Line Tools</a></li>
+ <li><a href="../tools/index.html" target="mainFrame">Tools/Plug-ins</a>
+ <ul>
+ <li>25.1 <a
+ href="../tools/@axis2_version_dir@/CodegenToolReference.html"
+ target="mainFrame">Code Generator Tool - Command Line and Ant
+ Task</a></li>
+ <li>25.2 <a
+ href="../tools/@axis2_version_dir@/idea/Idea_plug-in_userguide.html"
+ target="mainFrame">Axis2 Plug-in for IntelliJ IDEA</a></li>
+ <li>25.3 <a
+ href="../tools/@axis2_version_dir@/eclipse/servicearchiver-plugin.html"
+ target="mainFrame">Service Archive Generator Wizard - Eclipse
+ Plug-in</a></li>
+ <li>25.4 <a
+ href="../tools/@axis2_version_dir@/eclipse/wsdl2java-plugin.html"
+ target="mainFrame">Code Generator Wizard - Eclipse Plug-in</a></li>
+ <li>25.5 <a
+ href="../tools/@axis2_version_dir@/maven-plugins/maven-aar-plugin.html"
+ target="mainFrame">AAR Maven2 Plug-in</a></li>
+ <li>25.6 <a
+ href="../tools/@axis2_version_dir@/maven-plugins/maven-java2wsdl-plugin.html"
+ target="mainFrame">Java2WSDL Maven2 Plug-in</a></li>
+ <li>25.7 <a
+ href="../tools/@axis2_version_dir@/maven-plugins/maven-wsdl2code-plugin.html"
+ target="mainFrame">WSDL2Code Maven2 Plug-in</a></li>
+ <li>25.8 <a href="../tools/previous.html" target="mainFrame">Tools
+ Archive</a></li>
+ </ul>
+ </li>
+ <li><a href="migration.html" target="mainFrame">Migration Guide (from
+ Axis1)</a></li>
+ <li>Design Notes
+ <ul>
+ <li>27.1 <a href="Axis2-rpc-support.html" target="mainFrame">RPC
+ Support</a></li>
+ </ul>
+ </li>
+</ol>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/transport_howto.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/transport_howto.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/transport_howto.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/transport_howto.html Fri May 25 01:09:03 2007
@@ -0,0 +1,217 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title></title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<body>
+<h1>How to Write Your Own Axis2 Transport</h1>
+
+<h2>Prologue</h2>
+
+<p>To stop you from re-inventing 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 either 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 mail
+ server. 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 stripped out of the incoming message and inserted into the MessageContext.
+In the outgoing message, all transport specific information, like headers,
+are added and sent.</p>
+
+<p>To write your own transport, you will primarily need to write two classes:
+one is the TransportSender and the other is the TransportReceiver. To
+register a transport with Axis2 you will need to put entries corresponding
+to these two classes in the axis2.xml file. I will take you through the
+process of adding the entries in the relevant 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 via an e-mail) 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 our 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 your 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. You need to implement this 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. (The following code
+is extracted from the 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);
+ 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>By using a code fragment like
+<code>Utils.getParameterValue(transportOut.getParameter(MailSrvConstants.SMTP_USER))</code>
+we can extract the parameters that we inserted 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 different 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>Therefore, depending on whether your transport is using the same channel
+to send the response 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 TransportReceiver.</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 required entries into the axis2.xml file, we are done. It is as
+simple as that!</p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/userguide-buildingservices.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/userguide-buildingservices.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/userguide-buildingservices.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/userguide-buildingservices.html Fri May 25 01:09:03 2007
@@ -0,0 +1,601 @@
+<?xml version="1.0" encoding=""?>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta http-equiv="content-type" content="" />
+ <title>Introducing Axis2</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all" />
+</head>
+
+<body>
+<a name="buildservices"></a>
+
+<h1>Apache Axis2 User's Guide -Building Services</h1>
+
+<p>Now that you know how to use Axis2 to generate clients from WSDL, this
+section digs a little deeper showing you how to create services, and also how
+to create services and clients "from scratch", so to speak.</p>
+<ul>
+ <li><a href="userguide.html#intro">Introducing Axis2</a><br />
+
+ <ul>
+ <li><a href="userguide.html#whatis">What is Axis2?</a></li>
+ <li><a href="userguide.html#underhood">What's Under the Hood?</a></li>
+ <li><a href="userguide.html#handlessoap">How Axis2 Handles SOAP
+ Messages</a></li>
+ <li><a href="userguide.html#distributions">Axis2 Distributions</a></li>
+ <li><a href="userguide.html#sbd">The Axis2 Standard Binary
+ Distribution</a></li>
+ <li><a href="userguide.html#hierarchy">Axis2.war Directory
+ Hierarchy</a></li>
+ <li><a href="userguide.html#docs">Axis2 Documents Distribution</a></li>
+ <li><a href="userguide.html#clients">Axis2 and Clients</a></li>
+ </ul>
+ </li>
+ <li><a href="userguide-installingtesting.html#installingtesting">Installing
+ and Testing Client Code</a></li>
+ <li><a href="userguide-introtoservices.html#introservices">Introduction to
+ Services</a><br />
+
+ <ul>
+ <li><a href="userguide-introtoservices.html#messageexchange">Message
+ Exchange Patterns</a></li>
+ </ul>
+ </li>
+ <li><a href="userguide-creatingclients.html#createclients">Creating
+ Clients</a><br />
+
+ <ul>
+ <li><a href="userguide-creatingclients.html#choosingclient">Choosing a
+ Client Generation Method</a></li>
+ <li><a href="userguide-creatingclients.html#generating">Generating
+ Clients</a></li>
+ <li><a href="userguide-creatingclients.html#adb">Axis Data Binding
+ (ADB)</a></li>
+ </ul>
+ </li>
+ <li><a
+ href="userguide-buildingservices.html#buildservices"><strong>Building
+ Services</strong></a><br />
+
+ <ul>
+ <li><a
+ href="userguide-buildingservices.html#getcomfortable"><strong>Getting
+ Comfortable with Available Options</strong></a></li>
+ <li><a
+ href="userguide-buildingservices.html#createscratch"><strong>Creating
+ a Service from Scratch</strong></a></li>
+ <li><a
+ href="userguide-buildingservices.html#deploypojo"><strong>Deploying
+ Plain Old Java Objects</strong></a></li>
+ <li><a
+ href="userguide-buildingservices.html#deployrun"><strong>Deploying
+ and Running an Axis2 Service Created from WSDL</strong></a></li>
+ </ul>
+ </li>
+ <li><a href="userguide-samples.html">Samples</a></li>
+ <li><a href="userguide-forfurtherstudy.html">For Further Study</a></li>
+</ul>
+
+<p><a name="getcomfortable"></a></p>
+
+<h2>Getting Comfortable with the Available Options</h2>
+
+<p>Axis2 provides a number of ways to create a service, such as:</p>
+<ul>
+ <li>Create a service and build it from scratch. In this case, you build
+ your service class to specifically access AXIOM OMElement objects, then
+ create the services.xml file and package it for deployment.</li>
+ <li>Deploy Plain Old Java Objects (POJOs) as a service.</li>
+ <li>Generate the service from WSDL. Just as you can generate clients with
+ WSDL, you can also generate the skeleton of a service.</li>
+</ul>
+
+<p>Let's look at these three options.</p>
+<a name="createscratch"></a>
+
+<h2>Creating a Service from Scratch</h2>
+
+<p>Creating a service from scratch is not the most convenient way to do it,
+but it does give you the most control. The process involves several steps.</p>
+
+<p><b>The short story:</b></p>
+<ol>
+ <li>Create the service class with each operation that is represented by a
+ method that takes an org.apache.axiom.om.OMElement object as its
+ argument. (An OMElement is how the AXIs2 Object Model (AXIOM) represents
+ an XML element.)</li>
+ <li>Create the service descriptor, services.xml, which defines the class to
+ be used by the service and the appropriate message receivers.</li>
+ <li>Create the .aar file, with the classes in their proper locations based
+ on the package and the services.xml file in the META-INF directory.</li>
+ <li>Deploy the .aar file by using the <a href="webadminguide.html">Web
+ Administration application</a> or by copying it to the Axis2 services
+ directory.</li>
+</ol>
+
+<p><b>The long story:</b></p>
+
+<p>Start by creating the service class, a plain Java class that uses classes
+from the Axis2 libraries (see Code Listing 8).</p>
+
+<h3>Code Listing 8-Creating the Service Class</h3>
+<pre>package org.apache.axis2.axis2userguide;
+
+import javax.xml.stream.XMLStreamException;
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.om.OMNamespace;
+
+public class SampleService {
+
+ public OMElement sayHello(OMElement element)
+ throws XMLStreamException {
+ element.build();
+ element.detach();
+
+ String rootName = element.getLocalName();
+ System.out.println("Reading "+rootName+" element");
+
+ OMElement childElement = element.getFirstElement();
+ String personToGreet = childElement.getText();
+
+ OMFactory fac = OMAbstractFactory.getOMFactory();
+ OMNamespace omNs = fac.createOMNamespace(
+ "http://example1.org/example1", "example1");
+ OMElement method = fac.createOMElement("sayHelloResponse",
+omNs);
+ OMElement value = fac.createOMElement("greeting", omNs);
+ value.addChild(fac.createOMText(value, "Hello,
+"+personToGreet));
+ method.addChild(value);
+
+ return method;
+ }
+
+ private void ping(){
+ }
+
+}</pre>
+
+<p>Make sure to include Axis2 libraries in your class path when compiling the
+source.</p>
+
+<p>Axis2 uses AXIOM, or the AXIs Object Model, a DOM (Document Object Model)
+-like structure that is based on the StAX API ( Streaming API for XML).
+Methods that act as services must take an OMElement as their argument, which
+represents the payload of the incoming SOAP message. (An OMElement is just
+AXIOM's way of representing an XML element, like a DOM Element object.) In
+this case, you're extracting the contents of the first child of the payload
+element, adding text to it, and using it as content for the return OMElement.
+Unless this is an "in only" service, these methods must return an OMElement,
+because that becomes the payload of the return SOAP message.</p>
+
+<p>To turn this class into a service, create the service description file,
+services.xml, as in Code Listing 9.</p>
+
+<h3>Code Listing 9 - Create the Service Description</h3>
+<pre><service name="UserGuideSampleService">
+ <description>
+ This is a sample service created in the Axis2 User's Guide
+ </description>
+
+ <parameter name="ServiceClass"
+locked="false">org.apache.axis2.axis2userguide.SampleService
+</parameter>
+
+ <operation name="sayHello">
+ <messageReceiver
+class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ <operation name="ping">
+ <messageReceiver
+class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>
+ </operation>
+</service></pre>
+
+<p>This document defines the service, called by the <a
+href="webadminguide.html">Web Administration Application</a>, and the class
+used to serve requests. For each operation, it defines the appropriate
+message receiver class.</p>
+
+<p>Create a new directory, META-INF, in the main directory for the class. (In
+this case, that's the same directory that contains the org directory) and
+place the services.xml file in it.</p>
+
+<p>Create the .aar file by typing: jar cvf SampleService.aar ./*</p>
+
+<p>Deploy the SampleService.aar file by using the <a
+href="webadminguide.html">Web Administration application</a> or by copying it
+to the Axis2 services directory.</p>
+
+<p>Now you can create a client class that accesses the service directly (see
+Code Listing 10).</p>
+
+<h3>Code Listing 10 - Create a Client Class that Accesses the Service
+Directly</h3>
+<pre>package org.apache.axis2.axis2userguide;
+
+import javax.xml.stream.XMLStreamException;
+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.Constants;
+import org.apache.axis2.client.ServiceClient;
+
+public class SampleClient {
+
+ private static EndpointReference targetEPR =
+ new EndpointReference(
+ "http://localhost:8080/axis2/services/UserGuideSampleService");
+
+ public static OMElement greetUserPayload(String personToGreet) {
+ OMFactory fac = OMAbstractFactory.getOMFactory();
+ OMNamespace omNs = fac.createOMNamespace(
+ "http://example1.org/example1", "example1");
+ OMElement method = fac.createOMElement("sayHello", omNs);
+ OMElement value = fac.createOMElement("personToGreet",
+omNs);
+ value.addChild(fac.createOMText(value, personToGreet));
+ method.addChild(value);
+ return method;
+ }
+
+ public static void main(String[] args) {
+ try {
+ OMElement payload =
+SampleClient.greetUserPayload("John");
+ Options options = new Options();
+ options.setTo(targetEPR);
+
+options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
+
+ ServiceClient sender = new ServiceClient();
+ sender.setOptions(options);
+ OMElement result = sender.sendReceive(payload);
+
+ String response = result.getFirstElement().getText();
+ System.out.println(response);
+
+ } catch (Exception e) { //(XMLStreamException e) {
+ System.out.println(e.toString());
+ }
+ }
+
+}</pre>
+
+<p>This class uses the same technique of sending and receiving OMElements,
+but it's also important to note the use of the Options class. This class
+enables you to determine properties such as the transport used for the return
+message (the transport used for the outgoing message can be inferred from the
+URL of the destination) and the SOAP version to use. In addition to providing
+setter and getter methods of specific properties that affect how the client
+interacts with the service, the Options class enables you to create
+inheritance relationships between Options objects. So if a property is not
+found in the current Options object used, the client can check the parent
+Options object of the current Options object.</p>
+
+<p>Compile and run the above SampleClient.java. Make sure to have all axis2
+libraries in your class path. If all has gone well, 'Hello, John' will be
+shown as the output in the console.</p>
+<a name="deploypojo"></a>
+
+<h2>Deploying Plain Old Java Objects (POJOs)</h2>
+
+<p>One very easy way to create a Web service is simply to deploy the Java
+objects that represent the service. Start with the class, shown in Code
+Listing 11.</p>
+
+<h3><b>Code Listing 11 - Creating the Class SampleService</b></h3>
+<pre>package org.apache.axis2.axis2userguide;
+
+public class SampleService {
+
+ public void doInOnly(){
+ return;
+ }
+
+ public String noParameters(){
+ return "Hello";
+ }
+
+ public String twoWayOneParameterEcho(String toEcho){
+ return toEcho;
+ }
+
+ public boolean multipleParametersAdd(float price, int itemId,
+ String description, String itemName){
+ //Code to handle the logic
+ return true;
+ }
+
+}</pre>
+
+<p>Next, you'll need to tell Axis2 what class corresponds with what Web
+service calls. Do this by creating a file called services.xml and adding the
+following shown in Code Listing 12.</p>
+
+<h3><b>Code Listing 12 - Creating services.xml</b></h3>
+<pre><service name="SampleService" scope="application">
+ <description>
+ Sample Service
+ </description>
+ <messageReceivers>
+ <messageReceiver
+ mep="http://www.w3.org/2004/08/wsdl/in-only"
+ class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
+ <messageReceiver
+ mep="http://www.w3.org/2004/08/wsdl/in-out"
+ class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
+ </messageReceivers>
+ <parameter name="ServiceClass">
+ org.apache.axis2.axis2userguide.SampleService
+ </parameter>
+</service></pre>
+
+<p>This file makes the InOnly and InOut MEPs available to the service and
+tells Axis2 which class to call; operations must match method names. In other
+words, Axis2 automatically sends a call to the multipleParametersAdd
+operation to the
+org.apache.axis2.axis2userguide.SampleService.multipleParametersAdd()
+method.</p>
+
+<p>Now it's time to create the distribution. Arrange your files in the
+following directory structure (see Code Listing 13).</p>
+
+<h3><b>Code Listing 13- Create the Directory Structure for the
+Distribution</b></h3>
+<pre> - SampleService
+ - META-INF
+ - services.xml
+ - org
+ - apache
+ - axis2
+ - axis2userguide
+ - SampleService.class</pre>
+
+<p>Finally, deploy the service by copying the SampleService directory to the
+webapps/axis2/WEB-INF/services directory on the servlet engine. You can check
+to make sure that it's been properly deployed by checking <a
+href="http://<host>:<port>/axis2/services/listServices">http://<host>:<port>/axis2/services/listServices</a>.</p>
+<a name="deployrun"></a>
+
+<h2>Deploying and Running an Axis2 Service Created from WSDL</h2>
+
+<p>If you have a WSDL file, you can easily create and deploy a service based
+on that description. For example, to create a service based on the same WSDL
+file used in the <a href="userguide-creatingclients.html">clients section</a>
+of this document, you will follow the steps below.</p>
+
+<p><b>The short story:</b></p>
+<ol>
+ <li><a
+ href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi#std-bin">Download</a>
+ the Axis2 standard distribution, if you have not done so already.</li>
+ <li>Generate the skeleton using the WSDL2Java utility, as in: <br />
+
+ <pre>java org.apache.axis2.wsdl.WSDL2Java -uri file:///C:/apps/axis2/samples/zSample/Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s -wv 1.1 -ss -sd -ssi</pre>
+ </li>
+ <li>Open the *Skeleton.java file and add the functionality of your service
+ to the generated methods.</li>
+ <li>Build a service using Ant by typing ant jar.server</li>
+ <li>Deploy the service by copying the build/lib/*.aar file to
+ <J2EE_HOME>/webapps/axis2/WEB-INF/services</li>
+ <li>Check http://<server>:<port>/axis2/services/listServices to
+ make sure the service has been properly deployed.</li>
+</ol>
+
+<p><b>The long story:</b></p>
+
+<p>As with generating clients, you will need the <a
+href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi#std-bin">Axis2
+Standard Distribution</a>, because the <a
+href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi#war">Axis2
+WAR Distribution</a> does not include the WSDL2Java utility. Once you've got
+it downloaded and unpacked, make sure that you set the AXIS2_HOME variable to
+point to the location in which you've unpacked it.</p>
+
+<p>Now you are ready to generate the actual service. To keep things neat,
+create a new directory and change to it. The WSDL file is the same one
+referenced in <a href="userguide-creatingclients#generating.xhtml">Generating
+Clients</a> and includes four operations: NoParameters,
+TwoWayOneParameterEcho, MultipleParametersAddItem, and DoInOnly. To generate
+the service, use the WSDL2Java utility, as in Code Listing 14.</p>
+
+<h3>Code Listing 14 - Using the WSDL2Java Utility to Generate the Service</h3>
+
+<p><strong>Code Listing 14.1:</strong></p>
+<pre>java org.apache.axis2.wsdl.WSDL2Java -uri
+file:///C:/apps/axis2/samples/zSample/Axis2UserGuide.wsdl -p
+org.apache.axis2.axis2userguide -d adb -s -wv @axis2_version@ -ss -sd</pre>
+
+<p>Note: Make sure all the .jar files in the Axis2 lib directory is set to
+the CLASSPATH before you run the above code.</p>
+
+<p>This statement tells the utility you want to create a service out of the
+operations in the file <a
+href="userguide-codelisting5.html">Axis2UserGuide.wsdl</a>, and that the Java
+classes generated should be in the org.apache.axis2.axis2userguide package
+(-p). (You can view the appropriate directories created.) It also indicates
+that you want to use the Axis2 DataBinding Framework, or ADB (-d), to
+generate only synchronous or blocking code (-s), and to generate server-side
+code (-ss) as opposed to a client, including the services.xml service
+descriptor file (-sd). It also specifies version @axis2_version@ for the WSDL
+file (-wv)<strong>.</strong></p>
+
+<p><strong>Code Listing 14.2:</strong></p>
+
+<p>You can also use the following script files to achieve the same. In this
+case you do not have the set the CLASSPATH manually.</p>
+
+<p>For Linux:</p>
+<pre>$AXIS2_HOME/bin/wsdl2java.sh -uri file:///C:/apps/axis2/samples/zSample/Axis2UserGuide.wsdl
+-p org.apache.axis2.axis2userguide -o target_directory_name -d adb -s -wv @axis2_version@ -ss -sd</pre>
+
+<p>For MS Windows:</p>
+<pre>%AXIS2_HOME%\bin\wsdl2java.bat -uri file:\\\C:\apps\axis2\samples\zSample\Axis2UserGuide.wsdl
+-p org.apache.axis2.axis2userguide -o target_directory_name -d adb -s -wv @axis2_version@ -ss -sd</pre>
+
+<p>In both instances, at this point, you should see four new items in your
+chosen directory: the build.xml file, which includes instructions for Ant,
+the src directory, which includes all the generated classes and stubs, the
+resources directory, which includes a regenerated version of the WSDL, and
+the services.xml file, which ultimately controls the service's behavior.</p>
+
+<p>You can compile the service at this point, but it doesn't actually do
+anything yet. You can solve that problem by opening the
+src\org\apache\axis2\axis2userguide\Axis2UserGuideServiceSkeleton.java file
+and either editing the code in bold -- make sure you manage parameter numbers
+-- or replacing all the code with the following in Code Listing 15.</p>
+
+<h3>Code Listing 15 - Compiling the Service</h3>
+
+<p><pre>/**
+ * Axis2UserGuideServiceSkeleton.java
+ *
+ * This file was auto-generated from WSDL
+ * by the Apache Axis2 version: SNAPSHOT Oct 15, 2006 (11:23:18
+GMT+00:00)
+ */
+package org.apache.axis2.axis2userguide;
+/**
+ * Axis2UserGuideServiceSkeleton java skeleton for the axisService
+ */
+public class Axis2UserGuideServiceSkeleton {
+
+
+ /**
+ * Auto generated method signature
+
+ * @param param7
+
+ */
+ public org.apache.axis2.axis2userguide.NoParametersResponse
+NoParameters
+ (org.apache.axis2.axis2userguide.NoParametersRequest param7)
+
+ {
+ <b>System.out.println(param7);
+
+ NoParametersResponse res =
+ new NoParametersResponse();
+
+ return res;</b>
+ }
+
+
+ /**
+ * Auto generated method signature
+
+ * @param param9
+
+ */
+ public
+org.apache.axis2.axis2userguide.TwoWayOneParameterEchoResponse
+TwoWayOneParameterEcho
+ (
+ org.apache.axis2.axis2userguide.TwoWayOneParameterEchoRequest
+param9
+ )
+
+ {
+ <b>System.out.println(param9.getEchoString());
+
+ TwoWayOneParameterEchoResponse res =
+ new TwoWayOneParameterEchoResponse();
+
+ res.setEchoString(param9.getEchoString());
+
+ return res;</b>
+ }
+
+
+ /**
+ * Auto generated method signature
+
+ * @param param11
+
+ */
+ public void DoInOnly
+ (
+ org.apache.axis2.axis2userguide.DoInOnlyRequest param11
+ )
+
+ {
+ <b>System.out.println(param11.getMessageString());</b>
+ }
+
+
+ /**
+ * Auto generated method signature
+
+ * @param param12
+
+ */
+ public
+org.apache.axis2.axis2userguide.MultipleParametersAddItemResponse
+MultipleParametersAddItem
+ (
+
+org.apache.axis2.axis2userguide.MultipleParametersAddItemRequest
+param12
+ )
+
+ {
+ <b>System.out.println(param12.getPrice());
+ System.out.println(param12.getItemId());
+ System.out.println(param12.getDescription());
+ System.out.println(param12.getItemName());
+
+ MultipleParametersAddItemResponse res =
+ new MultipleParametersAddItemResponse();
+
+ res.setSuccessfulAdd(true);
+ res.setItemId(param12.getItemId());
+
+ return res;</b>
+ }
+
+}</pre>
+</p>
+
+<p>As with generating clients, all these classes, such as
+MultipleParametersAddItemRequest and TwoWayOneParameterEchoResponse, are
+generated by the utility, and can be found in the same directory as the
+skeleton file. They include methods such as setSuccessfulAdd(), which sets
+the value of the content of an element in the response, and getItemName(),
+which retrieves the content of elements in the request.</p>
+
+<p>Save the file and compile it by typing: ant jar.server</p>
+
+<p>If all goes well, you should see the BUILD SUCCESSFUL message in your
+window, and the Axis2UserGuideService.aar file in the newly created build/lib
+directory.</p>
+
+<p><img alt="The BUILD SUCCESSFUL message in your window"
+src="images/fig05.jpg" /></p>
+
+<p>Now you need to deploy the service to the server. To do that, copy the
+Axis2UserGuideService.aar file to the WEB-INF/services directory of the
+application server. (You also have the option to use the administration
+tools. See the <a href="webadminguide.html">Web Administrator's Guide</a> for
+more information.)</p>
+
+<p>To verify that the service has been properly deployed, check the list of
+services at <a
+href="http://<host>:<port>/axis2/services/listServices">http://<host>:<port>/axis2/services/listServices</a>.</p>
+
+<p><img alt="Checking the list of services" src="images/fig06.jpg" /></p>
+
+<p>Now you should be able to access the service using any of the clients
+built in the <a href="userguide-creatingclients.html#generating">Generating
+Clients</a> document.</p>
+
+<p><strong>See Next Section</strong>- <a
+href="userguide-samples.html">Samples</a></p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/userguide-codelisting5.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/userguide-codelisting5.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/userguide-codelisting5.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/userguide-codelisting5.html Fri May 25 01:09:03 2007
@@ -0,0 +1,200 @@
+<?xml version="1.0" encoding=""?>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta http-equiv="content-type" content="" />
+ <title>Code Listing 4: Generating clients from the WSDL file</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all" />
+</head>
+
+<body>
+<h1>Code Listing 5 - Generating Clients from the WSDL File</h1>
+<pre><?xml version="1.0" encoding="UTF-8"?>
+<wsdl:definitions
+ xmlns:apachesoap="http://xml.apache.org/xml-soap"
+ xmlns:impl="http://apache.org/axis2/Axis2UserGuide"
+ xmlns:intf="http://apache.org/axis2/Axis2UserGuide"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ targetNamespace="http://apache.org/axis2/Axis2UserGuide">
+
+ <wsdl:types>
+ <schema
+ elementFormDefault="qualified"
+ targetNamespace="http://apache.org/axis2/Axis2UserGuide"
+ xmlns="http://www.w3.org/2001/XMLSchema">
+
+ <!-- ELEMENTS -->
+
+ <element name="DoInOnlyRequest">
+ <complexType>
+ <sequence>
+ <element name="messageString" type="xsd:string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="TwoWayOneParameterEchoRequest">
+ <complexType>
+ <sequence>
+ <element name="echoString" type="xsd:string"/>
+ </sequence>
+ </complexType>
+ </element>
+ <element name="TwoWayOneParameterEchoResponse">
+ <complexType>
+ <sequence>
+ <element name="echoString" type="xsd:string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="NoParametersRequest">
+ <complexType/>
+ </element>
+ <element name="NoParametersResponse">
+ <complexType/>
+ </element>
+
+ <element name="MultipleParametersAddItemRequest">
+ <complexType>
+ <sequence>
+ <element name="itemId" type="xsd:int"/>
+ <element name="itemName" type="xsd:string"/>
+ <element name="price" type="xsd:float"/>
+ <element name="description" type="xsd:string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="MultipleParametersAddItemResponse">
+ <complexType>
+ <sequence>
+ <element name="itemId" type="xsd:int"/>
+ <element name="successfulAdd" type="xsd:boolean"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ </schema>
+ </wsdl:types>
+
+
+ <!-- MESSAGES -->
+
+ <wsdl:message name="DoInOnlyRequestMessage">
+ <wsdl:part name="input" element="impl:DoInOnlyRequest"/>
+ </wsdl:message>
+
+ <wsdl:message name="TwoWayOneParameterEchoRequestMessage">
+ <wsdl:part name="input" element="impl:TwoWayOneParameterEchoRequest"/>
+ </wsdl:message>
+ <wsdl:message name="TwoWayOneParameterEchoResponseMessage">
+ <wsdl:part name="output" element="impl:TwoWayOneParameterEchoResponse"/>
+ </wsdl:message>
+
+ <wsdl:message name="NoParametersRequestMessage">
+ <wsdl:part name="input" element="impl:NoParametersRequest"/>
+ </wsdl:message>
+ <wsdl:message name="NoParametersResponseMessage">
+ <wsdl:part name="output" element="impl:NoParametersResponse"/>
+ </wsdl:message>
+
+ <wsdl:message name="MultipleParametersAddItemRequestMessage">
+ <wsdl:part name="input" element="impl:MultipleParametersAddItemRequest"/>
+ </wsdl:message>
+ <wsdl:message name="MultipleParametersAddItemResponseMessage">
+ <wsdl:part name="output" element="impl:MultipleParametersAddItemResponse"/>
+ </wsdl:message>
+
+
+ <!-- Port type (operations) -->
+
+ <wsdl:portType name="Axis2UserGuidePortType">
+
+ <wsdl:operation name="DoInOnly" parameterOrder="input">
+ <wsdl:input name="DoInOnlyRequestMessage"
+ message="impl:DoInOnlyRequestMessage"/>
+ </wsdl:operation>
+
+ <wsdl:operation name="TwoWayOneParameterEcho" parameterOrder="input">
+ <wsdl:input name="TwoWayOneParameterEchoRequestMessage"
+ message="impl:TwoWayOneParameterEchoRequestMessage"/>
+ <wsdl:output name="TwoWayOneParameterEchoResponseMessage"
+ message="impl:TwoWayOneParameterEchoResponseMessage"/>
+ </wsdl:operation>
+
+ <wsdl:operation name="NoParameters" parameterOrder="input">
+ <wsdl:input name="NoParametersRequestMessage"
+ message="impl:NoParametersRequestMessage"/>
+ <wsdl:output name="NoParametersResponseMessage"
+ message="impl:NoParametersResponseMessage"/>
+ </wsdl:operation>
+
+ <wsdl:operation name="MultipleParametersAddItem" parameterOrder="input">
+ <wsdl:input name="MultipleParametersAddItemRequestMessage"
+ message="impl:MultipleParametersAddItemRequestMessage"/>
+ <wsdl:output name="MultipleParametersAddItemResponseMessage"
+ message="impl:MultipleParametersAddItemResponseMessage"/>
+ </wsdl:operation>
+
+ </wsdl:portType>
+
+
+ <!-- BINDING (bind operations) -->
+ <wsdl:binding
+ name="Axis2UserGuideSoapBinding"
+ type="impl:Axis2UserGuidePortType">
+ <wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
+
+ <wsdl:operation name="DoInOnly">
+ <wsdlsoap:operation soapAction="DoInOnly"/>
+ <wsdl:input>
+ <wsdlsoap:body use="literal"/>
+ </wsdl:input>
+ </wsdl:operation>
+
+ <wsdl:operation name="TwoWayOneParameterEcho">
+ <wsdlsoap:operation soapAction="TwoWayOneParameterEcho"/>
+ <wsdl:input>
+ <wsdlsoap:body use="literal"/>
+ </wsdl:input>
+ <wsdl:output>
+ <wsdlsoap:body use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+
+ <wsdl:operation name="NoParameters">
+ <wsdlsoap:operation soapAction="NoParameters"/>
+ <wsdl:input>
+ <wsdlsoap:body use="literal"/>
+ </wsdl:input>
+ <wsdl:output>
+ <wsdlsoap:body use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+
+ <wsdl:operation name="MultipleParametersAddItem">
+ <wsdlsoap:operation soapAction="MultipleParametersAddItem"/>
+ <wsdl:input>
+ <wsdlsoap:body use="literal"/>
+ </wsdl:input>
+ <wsdl:output>
+ <wsdlsoap:body use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+
+
+ <!-- SERVICE -->
+
+ <wsdl:service name="Axis2UserGuideService">
+ <wsdl:port binding="impl:Axis2UserGuideSoapBinding"
+ name="Axis2UserGuide">
+ <wsdlsoap:address location="http://localhost:8080/axis2/services/Axis2UserGuide"/>
+ </wsdl:port>
+ </wsdl:service>
+</wsdl:definitions></pre>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/userguide-codelisting7.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/userguide-codelisting7.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/userguide-codelisting7.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/userguide-codelisting7.html Fri May 25 01:09:03 2007
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding=""?>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta http-equiv="content-type" content="" />
+ <title>Code Listing 6: Client.java</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all" />
+</head>
+
+<body>
+<h1>Code Listing 7- Client.java</h1>
+<pre>package org.apache.axis2.axis2userguide;
+
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.DoInOnlyRequest;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.TwoWayOneParameterEchoRequest;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.NoParametersRequest;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.MultipleParametersAddItemRequest;
+
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.TwoWayOneParameterEchoResponse;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.NoParametersResponse;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.MultipleParametersAddItemResponse;
+
+public class Client{
+ public static void main(java.lang.String args[]){
+ try{
+ Axis2UserGuideServiceStub stub =
+ new Axis2UserGuideServiceStub
+ ("http://localhost:8080/axis2/services/Axis2UserGuideService");
+
+ doInOnly(stub);
+ twoWayOneParameterEcho(stub);
+ noParameters(stub);
+ multipleParameters(stub);
+
+ } catch(Exception e){
+ e.printStackTrace();
+ System.out.println("\n\n\n");
+ }
+ }
+
+ /* do in only */
+ public static void doInOnly(Axis2UserGuideServiceStub stub){
+ try{
+ DoInOnlyRequest req = new DoInOnlyRequest();
+
+ req.setMessageString("An in only request");
+
+ stub.DoInOnly(req);
+ System.out.println("done");
+ } catch(Exception e){
+ e.printStackTrace();
+ System.out.println("\n\n\n");
+ }
+ }
+
+ /* two way call/receive */
+ public static void twoWayOneParameterEcho(Axis2UserGuideServiceStub stub){
+ try{
+ TwoWayOneParameterEchoRequest req = new TwoWayOneParameterEchoRequest();
+
+ req.setEchoString("echo! ... echo!");
+
+ TwoWayOneParameterEchoResponse res =
+ stub.TwoWayOneParameterEcho(req);
+
+ System.out.println(res.getEchoString());
+ } catch(Exception e){
+ e.printStackTrace();
+ System.out.println("\n\n\n");
+ }
+ }
+
+ /* No parameters */
+ public static void noParameters(Axis2UserGuideServiceStub stub){
+ try{
+ NoParametersRequest req = new NoParametersRequest();
+
+ System.out.println(stub.NoParameters(req));
+ } catch(Exception e){
+ e.printStackTrace();
+ System.out.println("\n\n\n");
+ }
+ }
+
+ /* multiple parameters */
+ public static void multipleParameters(Axis2UserGuideServiceStub stub){
+ try{
+ MultipleParametersAddItemRequest req =
+ new MultipleParametersAddItemRequest();
+
+ req.setPrice((float)1.99);
+ req.setItemId((int)23872983);
+ req.setDescription("Must have for cooking");
+ req.setItemName("flour");
+
+ MultipleParametersAddItemResponse res =
+ stub.MultipleParametersAddItem(req);
+
+ System.out.println(res.getSuccessfulAdd());
+ System.out.println(res.getItemId());
+ } catch(Exception e){
+ e.printStackTrace();
+ System.out.println("\n\n\n");
+ }
+ }
+}</pre>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org