axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hemap...@apache.org
Subject svn commit: r454336 [1/3] - in /webservices/axis2/branches/java/1_1/xdocs: dii.html modules.html reference.html userguide.html xmlbased-server.html
Date Mon, 09 Oct 2006 10:52:30 GMT
Author: hemapani
Date: Mon Oct  9 03:52:29 2006
New Revision: 454336

URL: http://svn.apache.org/viewvc?view=rev&rev=454336
Log:
updated user guide for 1.1 - Srinath & Jaliya

Added:
    webservices/axis2/branches/java/1_1/xdocs/dii.html
    webservices/axis2/branches/java/1_1/xdocs/modules.html
    webservices/axis2/branches/java/1_1/xdocs/reference.html
    webservices/axis2/branches/java/1_1/xdocs/xmlbased-server.html
Modified:
    webservices/axis2/branches/java/1_1/xdocs/userguide.html

Added: webservices/axis2/branches/java/1_1/xdocs/dii.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/dii.html?view=auto&rev=454336
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/dii.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/dii.html Mon Oct  9 03:52:29 2006
@@ -0,0 +1,305 @@
+<h1><a name="Web_Service_Clients_Using_Axis2">Writing Web Service Clients Using
Axis2's Primary APIs</a></h1>
+
+
+<p>This section presents complex yet powerful <strong>XML based client API</strong>
which is intended for advanced users.However if you are a new user we recommend using code
generation given in the <a href="userguide.html">user guide</a>.
+</p>
+
+<p>Web services can be used to provide a wide-range of functionality to user
+from simple, less time consuming  operations such as "getStockQuote"  to time
+consuming business services. When we utilize (invoke using client
+applications) these Web services we cannot use simple generic invocation
+paradigms that suite all the timing complexities involved in the service
+operations. For example, if we use a single transport channel (such as HTTP)
+to invoke a Web service with an IN-OUT operation that takes a long time to
+complete, then most often we may end up with "connection time outs". On the
+other hand, if there are simultaneous service invocations that  we need to
+perform from a single client application, then the use of a "blocking" client
+API will degrade the performance of the client application. Similarly there
+are various other consequences such as One-Way transports that come in to
+play when we need them. Let's try to analyze some common service invocation
+paradigms.</p>
+
+<p>Many Web service engines provide users with a Blocking and Non-Blocking
+client APIs.</p>
+<ul>
+  <li><p style="margin-bottom: 0in"><b>Blocking API</b> -Once the
service
+    invocation is called, the client application hangs and only gets control
+    back when the operation completes, after which the client receives a
+    response or a fault. This is the simplest way of invoking Web services
+    and it also suites many business situations.</p>
+  </li>
+  <li><p><b>Non-Blocking API </b>- This is a callback or polling
based API,
+    hence once a service invocation is called, the client application
+    immediately gets the control back and the response is retrieved using the
+    callback object provided. This approach provides the flexibility to the
+    client application to invoke several Web services simultaneously without
+    blocking the operation already invoked.</p>
+  </li>
+</ul>
+
+<p>Both these mechanisms work in the API level. Let's name the  asynchronous
+behavior that we can get using the Non-Blocking API as <b>API Level
+Asynchrony.</b></p>
+
+<p>Both these mechanisms use single transport connections to send the request
+and to receive the response. They severely lag the capability of using two
+transport connections for the request and the response (either One-Way or
+Two-Way). So both these mechanisms fail to address the problem of long
+running transactions (the transport connection may time-out before the
+operation completes). A possible solution would be to use two separate
+transport connections for request and response. The asynchronous behavior
+that we gain using this solution can be called <b>Transport Level
+Asynchrony</b>.</p>
+
+<p>By <strong>combining API Level Asynchrony &amp; Transport Level
+Asynchrony</strong> we can obtain four different invocation patterns for Web
+services as shown in the following table.</p>
+<a name="table1"></a>
+
+<table width="100%" border="1" cellpadding="0" cellspacing="0">
+  <tbody>
+    <tr>
+      <td width="33%" height="19"><p><strong>API
+        (Blocking/Non-Blocking)</strong></p>
+      </td>
+      <td width="33%"><p><strong> Dual Transports (Yes/No)</strong></p>
+      </td>
+      <td width="33%"><p><strong>Description</strong></p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Blocking</p>
+      </td>
+      <td width="33%"><p>No</p>
+      </td>
+      <td width="33%"><p>The simplest and more familiar invocation pattern</p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Non-Blocking</p>
+      </td>
+      <td width="33%"><p>No</p>
+      </td>
+      <td width="33%"><p>Using callbacks or polling</p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Blocking</p>
+      </td>
+      <td width="33%"><p>Yes</p>
+      </td>
+      <td width="33%"><p>This is useful when the service operation is IN-OUT
+        in nature but the transport used is One-Way (e.g. SMTP)</p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Non-Blocking</p>
+      </td>
+      <td width="33%"><p>Yes</p>
+      </td>
+      <td width="33%"><p>This is can be used to gain the maximum asynchronous
+        behavior. Non blocking in the API level and also in the transport
+        level</p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<p>FoAxis2 provides the user with all these possibilities to invoke Web
+services.</p>
+
+<p>Following section present cleints that use different posibilites presented above
to invoke a Web Service using <code>ServiceClient</code>s.  All samples mentioned
in this guide are located at the
+<b><font color="#000000">"samples\userguide\src"</font></b> directory
of the
+binary distribution.</p>
+
+<p>This section presents four types of clients.</p>
+
+<ol>
+	<li>Request-Response, Blocking Client</li>
+	<li>One Way Client</li>
+	<li>Request-Response, Non-Blocking that uses one transport connection</li>
+	<li>Request-Response, Non-Blocking that uses one transport connections</li>
+</ol>
+
+<h4><a name="EchoBlockingClient">Request-Response, Blocking Client</a></h4>
+
+<p>Axis2 provides the user with several invocation patterns for Web services,
+ranging from pure blocking single channel invocations to non-blocking dual
+channel invocations. Let's first see how we can write a client to invoke
+"echo" operation of "MyService" using the simplest blocking invocation. The
+client code you need to write is as follows.</p>
+<source><pre>  try {
+            OMElement payload = ClientUtil.getEchoOMElement();
+            <span style="color: rgb(36, 193, 19);">            
+            Options options = new Options();
+            options.setTo(targetEPR); // this sets the location of MyService service
+            
+            ServiceClient serviceClient = new ServiceClient();
+            serviceClient.setOptions(options);
+
+            OMElement result = serviceClient.sendReceive(payload);
+            </span>
+            System.out.println(result);
+
+        } catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+        } 
+}</pre>
+</source>
+<p>1. The lines highlighted in green lines show the set of operations that
+you need to perform in order to invoke a Web service.</p>
+
+<p>2. The rest is used to create the OMElement that needs to be sent and
+display the response OMElement.</p>
+
+<p>To test this client, use the provided ant build file that can be found in
+the "<strong>Axis2_HOME/samples/userguide</strong>" directory. Run the
+"testEchoBlockingClient" target. If you can see the response OMElement
+printed in your command line,  then you have successfully tested the client.
+</p>
+
+<h4><a name="PingClient">One Way Client</a></h4>
+
+<p>In the Web service "MyService" we had an IN-ONLY operation with the name
+"ping" (see <a href="userguide2.html#Web_Services_Using_Axis2">Web Services
+Using Axis2</a>). Let's write a client to invoke this operation. The client
+code is as follows:</p>
+<pre> try {
+       OMElement payload = ClientUtil.getPingOMElement();
+       Options options = new Options();
+       options.setTo(targetEPR);
+       ServiceClient serviceClient = new ServiceClient();
+       serviceClient.setOptions(options);
+       serviceClient.fireAndForget(payload);
+        /**
+         * We have to block this thread untill we send the request , the problem
+         * is if we go out of the main thread , then request wont send ,so
+         * you have to wait some time :)
+         */
+       Thread.sleep(500);
+     } 
+catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+     }</pre>
+
+<p>Since we are accessing an IN-ONLY operation we can directly use the
+"fireAndForget()" in ServiceClient to invoke this operation. This will not
+block the invocation and will return the control immediately back to the
+client. You can test this client by running the target "testPingClient" of
+the ant build file at "<strong>Axis2Home/samples/userguide</strong>".</p>
+
+<p>We have now invoked the two operations in our service. Are we done? No!
+There's a lot more to explore. Let's see some other ways to invoke the same
+operations.</p>
+
+<h4><a name="EchoNonBlockingClient">Request-Response, Non-Blocking that uses
one transport connection</a></h4>
+
+<p>In the EchoBlockingClient once the "serviceClient.sendReceive(payload);"
+is called, the client is blocked till the operation is complete. This
+behavior is not desirable when there are many Web service invocations to be
+done in a single client application or within a GUI. A solution would be to
+use a Non-Blocking API to invoke Web services. Axis2 provides a callback
+based non-blocking API for users.</p>
+
+<p>A sample client for this can be found under
+"<strong>Axis2_HOME/samples/userguide/src/userguide/clients</strong>" with
+the name EchoNonBlockingClient. If we consider the changes that users may
+have to do with respect to the "EchoBlockingClient" that we have already
+seen, it will be as follows:</p>
+<pre style="margin-bottom: 0.2in">serviceClient.sendReceiveNonblocking(payload, callback);</pre>
+
+<p>The invocation accepts a callback object as a parameter. Axis2 client API
+provides an abstract Callback with the following methods:</p>
+<pre>public abstract void onComplete(AsyncResult result);
+public abstract void onError(Exception e);
+public boolean isComplete() {}</pre>
+
+<p>The user is expected to implement the "onComplete " and "onError " methods
+of their extended call back class. The Axis2 engine calls the onComplete
+method once the Web service response is received by the Axis2 Client API
+(ServiceClient). This will eliminate the blocking nature of the Web service
+invocation and provide users with the flexibility to use Non Blocking API for
+Web service Clients.</p>
+
+<p>To run the sample client ( EchoNonBlockingClient) you can simply use the
+"testEchoNonBlockingClient" target of the ant file found at the
+"<strong>Axis2_HOME/samples</strong>" directory.</p>
+
+<h4><a name="EchoNonBlockingDualClient">Request-Response, Non-Blocking that uses
one transport connections</a></h4>
+
+<p>The solution provided by the Non-Blocking API has one limitation when it
+comes to Web service invocations which take a long time to complete. The
+limitation is due to the use of single transport connections to invoke the
+Web service and to retrieve the response. In other words, client API provides
+a non blocking invocation mechanism for users, but the request and the
+response come in a single transport (Two-Way transport) connection (like
+HTTP). Long running Web service invocations or Web service invocations using
+One-Way transports (like SMTP) cannot be utilized by simply using a non
+blocking invocation. </p>
+
+<p>The trivial solution is to use separate transport connections (either
+One-Way or Two-Way) for the request and response. The next problem that needs
+to be solved is the correlation (correlating the request and the response).
+<a href="http://www.w3.org/2002/ws/addr/" target="_blank">WS-Addressing</a>
+provides a neat solution to this using &lt;wsa:MessageID&gt; and
+&lt;wsa:RelatesTo&gt; headers. Axis2 provides support for addressing  based
+correlation mechanism and a complying Client API to invoke Web services with
+two transport connections. (Core of Axis2 does not depend on WS-Addressing,
+but contains a set of parameters like in addressing that can be populated in
+any means. WS-Addressing is one of the uses that may populate them. Even the
+transports can populate these. Hence Axis2 has the flexibility to use
+different versions of addressing)</p>
+
+<p>Users can select between Blocking or Non-Blocking APIs for the Web service
+clients with two transport connections. By simply using a boolean flag, the
+same API can be used to invoke Web services (IN-OUT operations) using two
+separate transport connections. Let's see how it's done using an example.
+Following code fragment shows how to invoke the same "echo" operation using
+Non-Blocking API with two transport connections<strong>. The ultimate
+asynchrony!!</strong></p>
+<pre>  try {
+            OMElement payload = ClientUtil.getEchoOMElement();
+
+            Options options = new Options();
+            options.setTo(targetEPR);
+            options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
+            options.setUseSeparateListener(true);
+            options.setAction("urn:echo");  // this is the action mapping we put within the
service.xml
+
+            //Callback to handle the response
+            Callback callback = new Callback() {
+                public void onComplete(AsyncResult result) {
+                    System.out.println(result.getResponseEnvelope());
+                }
+
+                public void onError(Exception e) {
+                    e.printStackTrace();
+                }
+            };
+            //Non-Blocking Invocation            
+            sender = new ServiceClient();            
+            sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
+            sender.setOptions(options);            
+            sender.sendReceiveNonBlocking(payload, callback);            
+            //Wait till the callback receives the response.            
+            while (!callback.isComplete()) {                
+             Thread.sleep(1000);            
+            }            
+            //Need to close the Client Side Listener.        
+            } catch (AxisFault axisFault) {            
+              axisFault.printStackTrace();
+            } catch (Exception ex) {
+              ex.printStackTrace();
+            } finally {
+            try {
+                sender.finalizeInvoke();
+            } catch (AxisFault axisFault) {
+                //have to ignore this
+            }
+        }</pre>
+
+<p><font color="#0000ff"><font color="#000000">The boolean flag (value
true)
+in the "<b>options.setUseSeparateListener(...)</b>" method informs the Axis2
+engine to use separate transport connections for request and response.
+Finally "<b>service.finalizeInvoke()</b>" informs the Axis2 engine to stop
+the client side listener started to retrieve the response.</font></font></p>

Added: webservices/axis2/branches/java/1_1/xdocs/modules.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/modules.html?view=auto&rev=454336
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/modules.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/modules.html Mon Oct  9 03:52:29 2006
@@ -0,0 +1,308 @@
+<h2><a name="Modules"></a>Writing your Own Axis2 Module</h2>
+
+<p>Axis2 provides extended support for modules (See <a
+href="Axis2ArchitectureGuide.html" target="_blank">Architecture Guide</a> for
+more details about modules in Axis2). Let's create a custom module and deploy
+it to MyService which we created earlier.</p>
+
+<p>Following steps show the actions that need to be performed to deploy a
+custom module for a given Web service:</p>
+<ol>
+  <li><p style="margin-bottom: 0in">Create the Module Implementation</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Create the Handlers</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Create the module.xml</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Modify the "axis2.xml" (if you need
+    custom phases)</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Modify the "services.xml" to engage
+    modules at the deployment time.</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Package in a ".mar" (Module Archive)</p>
+  </li>
+  <li><p>Deploy the module in Axis2</p>
+  </li>
+</ol>
+
+<h3><a name="MyService_with_a_Logging_Module">MyService with a Logging
+Module</a></h3>
+
+<p>Let's write a simple logging module for our sample located at
+<b>"samples\userguide\src"</b> directory of the binary distribution. This
+module contains one handler that just logs the message that is passed through
+it. Axis2 uses ".mar" (Module Archive) to deploy modules in Axis2. Following
+diagram shows the file structure inside which needs to be there in the ".mar"
+archive. Let's create all these and see how it works.</p>
+
+<p><img src="images/userguide/ModuleView.jpg" name="Graphic5" align="bottom"
+border="0"></p>
+
+<h4><a name="Step1_:_LoggingModule_Class">Step1 : LoggingModule Class</a></h4>
+
+<p>LoggingModule is the implementation class of the Axis2 module. Axis2
+modules should implement the "<a
+href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/modules/Module.java?rev=396785&amp;view=log">org.apache.axis2.modules.Module</a>"
+interface with the following methods.</p>
+<pre>public void init(ConfigurationContext configContext, AxisModule module) throws
AxisFault;//Initialize the module
+public void shutdown(AxisConfiguration axisSystem) throws AxisFault;//End of module processing
+public void engageNotify(AxisDescription axisDescription) throws AxisFault;</pre>
+
+<p>These methods can be used to control the module initialization and the
+termination. With the input parameter AxisConfiguration, the user is provided
+with the complete configuration hierarchy. This can be used to fine-tune the
+module behavior by the module writers. For the simple logging service we can
+keep these methods blank in our implementation class.</p>
+
+<h4><a name="Step2_:_LogHandler">Step2 : LogHandler</a></h4>
+
+<p>A module in Axis2 can contain, one or more handlers that perform various
+SOAP header processing at different phases. (See<a
+href="Axis2ArchitectureGuide.html#incomingsoap" target="_blank"> Architecture
+Guide</a> for more information on phases). To write a handler one should
+implement <a
+href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/engine/Handler.java?rev=357187&amp;view=log">org.apache.axis2.engine.Handler</a>.
+But for convenience, <a
+href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/handlers/AbstractHandler.java?rev=396788&amp;view=log">org.apache.axis2.handlers.AbstractHandler</a>
+provides an abstract implementation of the Handler interface.</p>
+
+<p>For the logging module we will write a handler with the following methods.
+"public void invoke(MessageContext ctx);" is the method that is called by
+Axis2 engine when the control is passed to the handler. "public void
+revoke(MessageContext ctx);" is called when the handlers are revoked by the
+Axis2 engine.</p>
+<pre>public class LogHandler extends AbstractHandler implements Handler {
+    private Log log = LogFactory.getLog(getClass());
+    private QName name;
+
+    public QName getName() {
+        return name;
+    }
+
+    public void invoke(MessageContext msgContext) throws AxisFault {
+        log.info(msgContext.getEnvelope().toString());
+    }
+
+    public void setName(QName name) {
+        this.name = name;
+    }
+}</pre>
+
+<h4><a name="Step3_:_module_xml">Step3 : module.xml</a></h4>
+
+<p>"module.xml" contains the deployment configurations for a particular
+module. It contains details such as Implementation class of the module (in
+this example it is the "LoggingModule" class and various handlers that will
+run in different phases). "module.xml" for the logging module will be as
+follows:</p>
+<pre>&lt;module name="logging" class="userguide.loggingmodule.LoggingModule "&gt;
+   &lt;inflow&gt;
+        &lt;handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+        &lt;order phase="loggingPhase" /&gt;
+        &lt;/handler&gt;
+   &lt;/inflow&gt;
+
+   &lt;outflow&gt;
+        &lt;handler name="OutFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+        &lt;order phase="loggingPhase"/&gt;
+        &lt;/handler&gt;
+   &lt;/outflow&gt;
+
+   &lt;Outfaultflow&gt;
+        &lt;handler name="FaultOutFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+        &lt;order phase="loggingPhase"/&gt;
+        &lt;/handler&gt;
+   &lt;/Outfaultflow&gt;
+
+   &lt;INfaultflow&gt;
+        &lt;handler name="FaultInFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+        &lt;order phase="loggingPhase"/&gt;
+        &lt;/handler&gt;
+   &lt;/INfaultflow&gt;
+&lt;/module&gt;</pre>
+
+<p>As you can see there are four flows defined in this "module.xml"</p>
+<ol>
+  <li>inflow - Represents the handler chain that will run when a message is
+    coming in. </li>
+  <li><p style="margin-bottom: 0in">outflow - Represents the handler chain
+    that will run when the message is going out. </p>
+  </li>
+  <li><p style="margin-bottom: 0in">Outfaultflow - Represents the handler
+    chain that will run when there is a fault and the fault is going out</p>
+  </li>
+  <li><p>INfaultflow - Represents the handler chain that will run when there
+    is a fault and the fault is coming in </p>
+  </li>
+</ol>
+
+<p>Following set of tags describe the name of the handler, handler class and
+the phase in which this handler is going to run. "InFlowLogHandler" is the
+name given for the particular instance of this handler class. The value of
+class attribute is the actual implementation class for this handler. Since we
+are writing logging handler, we can reuse the same handler in all these
+phases. However this may not be the same for all the modules. "&lt;order
+phase="loggingPhase" /&gt;" describes the phase in which this handler
+runs.</p>
+<pre>&lt;handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+&lt;order phase="loggingPhase" /&gt;
+&lt;/handler&gt;</pre>
+
+<p>To learn more about Phase rules, check out the article <a
+href="http://www.developer.com/java/web/article.php/3529321"
+target="_blank">Axis2 Execution Framework</a></p>
+
+<h4><a name="Step_4:_Modify_the_&#34;axis2_xml&#34;">Step 4: Modify the
+"axis2.xml"</a></h4>
+
+<p>In this handler, the phase "loggingPhase", is defined by the module
+writer. It is not a pre-defined handler phase, hence the module writer should
+introduce it to the "axis2.xml" (NOT the services.xml) so that the Axis2
+engine knows where to place the handler in different "flows" ( inFlow,
+outFlow, etc.). Following xml lines show the respective changes made to the
+"axis2.xml" in order to deploy this logging module in the Axis2 engine. This
+is an extract of the phase section of "axis2.xml".</p>
+<pre>&lt;!-- ================================================= --&gt;
+&lt;!-- Phases --&gt;
+&lt;!-- ================================================= --&gt;
+
+&lt;phaseOrder type="inflow"&gt;
+        &lt;!--  System pre defined phases       --&gt;
+        &lt;phase name="TransportIn"/&gt;
+        &lt;phase name="PreDispatch"/&gt;
+        &lt;phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase"&gt;
+            &lt;handler name="AddressingBasedDispatcher"
+                     class="org.apache.axis2.engine.AddressingBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name="RequestURIBasedDispatcher"
+                     class="org.apache.axis2.engine.RequestURIBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name="SOAPActionBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPActionBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name="SOAPMessageBodyBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="InstanceDispatcher"
+                     class="org.apache.axis2.engine.InstanceDispatcher"&gt;
+                &lt;order phase="PostDispatch"/&gt;
+            &lt;/handler&gt;
+        &lt;/phase&gt;
+        &lt;!--  System pre defined phases       --&gt;
+        &lt;!--   After Postdispatch phase module author or service author can add any
phase he wants      --&gt;
+        &lt;phase name="OperationInPhase"/&gt;
+        &lt;phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type="outflow"&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name="OperationOutPhase"/&gt;
+        &lt;phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/&gt;
+        &lt;!--system predefined phases--&gt;
+        &lt;!--these phases will run irrespective of the service--&gt;
+        &lt;phase name="PolicyDetermination"/&gt;
+        &lt;phase name="MessageOut"/&gt;
+    &lt;/phaseOrder/&gt;
+    &lt;phaseOrder type="INfaultflow"&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name="OperationInFaultPhase"/&gt;
+        &lt;phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type="Outfaultflow"&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name="OperationOutFaultPhase"/&gt;
+        &lt;phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/&gt;
+        &lt;phase name="PolicyDetermination"/&gt;
+        &lt;phase name="MessageOut"/&gt;
+    &lt;/phaseOrder&gt;
+    </pre>
+
+<p>The text in green, the custom phase "loggingPhase" is placed in all the
+flows, hence that phase will be called in all the message flows in the
+engine. Since our module is associated with this phase, the LogHandler inside
+the module will now be executed in this phase.</p>
+
+<h4><a name="Step5_:_Modify_the_&#34;services_xml&#34;">Step5 : Modify
the
+"services.xml"</a></h4>
+
+<p>Up to this point we have created the required classes and configuration
+descriptions for the logging module and by changing the "axis2.xml" we have
+created the required phases for the logging module.</p>
+
+<p>Next step is to "<b>engage</b>" (use) this module in one of our services.
+For this, let's use the same Web service that we have used throughout the
+user's guide- MyService. However, since we need to modify the "services.xml"
+of MyService in order to engage this module, we use a separate Web service,
+but with the similar operations.</p>
+
+<p>The code for this service can be found in the
+"<strong>Axis2_HOME/samples/userguide/src/userguide/example2</strong>"
+directory. The simple changes that we have done to "services.xml' are shown
+in green in the following lines of xml.</p>
+<pre>&lt;service name="<span style="color: rgb(36, 193, 19);">MyServiceWithModule</span>"&gt;
+    &lt;description&gt;
+    This is a sample Web service with a logging module engaged.
+    &lt;/description&gt;
+    <span style="color: rgb(36, 193, 19);">&lt;module ref="logging"/&gt;</span>
+    &lt;parameter name="ServiceClass" locked="xsd:false"&gt;userguide.example2.MyService&lt;/parameter&gt;
+    &lt;operation name="echo"&gt;
+    &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+    &lt;/operation&gt;
+    &lt;operation name="ping"&gt;
+    &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+    &lt;/operation&gt;
+&lt;/service&gt;</pre>
+
+<p>In this example we have changed the service name (the implementation class
+is very similar to what we have used earlier although it is in a different
+package). In addition we have added the line <b>"&lt;module
+ref="logging"/&gt;"</b> to "services.xml". This informs the Axis2 engine that
+the module "logging" should be engaged for this service. The handler inside
+the module will be executed in their respective phases as described by the
+"module.xml".</p>
+
+<p><b><a name="Step6_:_Packaging">Step6 : Packaging</a></b></p>
+
+<p>Before deploying the module we need to create the ".mar" file for this
+module. This can be done, using the "jar" command and then renaming the
+created jar file. Or you can find the "logging.mar" that is already created
+for you in the "<strong>Axis2_HOME/samples/userguide</strong>" directory.</p>
+
+<h4><a name="Step7_:_Deploy_the_Module_in_Axis2">Step7 : Deploy the Module in
+Axis2</a></h4>
+
+<p>Deploying a module in Axis2 require the user to create a directory with
+the name "modules" in the "webapps/axis2/WEB-INF" directory of their servlet
+container and then copying the ".mar" file to that directory. So let's first
+create the "modules" directory and drop the "logging.mar" in to this
+directory.</p>
+
+<p>Although the required changes to the "services.xml" is very little, we
+have created a separate service archive (MyServiceWithModule.aar) for users
+to deploy and see.</p>
+
+<p>Deploy this service using the same steps that you used to <a
+href="#Step4_:Deploy_the_Web_Service">deploy "MyService"</a> and copy the
+"logging.mar" file to the "modules" directory.</p>
+
+<p>Then run using the "TestWebServiceWithModuleClient.bat" or
+"TestWebServiceWithModuleClient.sh" in the
+"<strong>Axis2Home/samples/userguide/src/userguide/clients/bin</strong>"
+directory.</p>
+
+<p>Note: To see logs, the user needs to modify the "log4j.properties" to log
+INFO. The property file is located in
+"<strong>webapps/axis2/WEB-INF/classes</strong>" of your servlet container.
+Change the line "log4j.rootCategory= ERROR, LOGFILE" to
+"log4j.rootCategory=INFO, ERROR, LOGFILE".</p>
+
+<p><font size="4"><b>Note (on samples):</b></font> All samples
mentioned in
+the user's guide are located at <b>"samples\userguide\src"</b> directory of
+the binary distribution.</p>

Added: webservices/axis2/branches/java/1_1/xdocs/reference.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/reference.html?view=auto&rev=454336
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/reference.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/reference.html Mon Oct  9 03:52:29 2006
@@ -0,0 +1,76 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <title>Axis2 Reference Guide</title>
+</head>
+
+<body lang="en-US" dir="ltr">
+<h1 align="center"><a name="_Toc96697849" id="_Toc96697849">Axis2 Reference Guide</h1>
+
+<h2 name="wsdl2code">WSDL2Code Reference</h2>
+
+<pre>
+NAME
+       WSDL2Java.sh or WSDL2Java.bat - Given a WSDL file generate java code to handle Web
Service invocation.
+       Shell script can be found from bin directory in the Axis2 distribution.
+
+
+SYNOPSIS
+       WSDL2Java.sh [OPTION]... -uri &lt;Location of WSDL&gt;
+
+DESCRIPTION
+	Given a WSDL file generate java code to handle Web Service invocation.
+
+	-o &lt;output Location&gt; : output file location
+	-a : Generate async style code only. Default is off
+	-s : Generate sync style code only. Default is off. takes precedence over -a
+	-p &lt;package name&gt; : set custom package name
+	-l &lt;language&gt; : valid languages are java and csharp. Default is java
+	-t : Generate TestCase to test the generated code
+	-ss : Generate server side code (i.e. skeletons). Default is off
+	-sd : Generate service descriptor (i.e. services.xml). Default is off. Valid with -ss
+	-d &lt;databinding&gt; : valid databinding(s) are adb, xmlbeans and jaxme. Default
is adb
+	-g Generates all the classes. valid only with the -ss (This will generate client and server
codes)
+	-pn &lt;port_name&gt; : name of port in the presence of multiple ports
+	-sn &lt;service_name&gt; : name of service in the presence of multiple services
+	-u : unpacks the databinding classes
+	-r &lt;repository_path&gt; : path of the repository against which code is generated
+EXAMPLES
+	WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl
+	WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd 
+	WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ../samples
-p org.apache.axis2.userguide
+
+</pre>
+
+<h2 name="wsdl2java">Java2WSDL Reference</h2>
+<pre>
+NAME
+       Java2WSDL.sh or Java2WSDL.bat - Given a java class generate a WSDL file for the given
java class. 
+       Can be found from bin directory in the Axis2 distribution.
+
+
+SYNOPSIS
+       Java2WSDL.sh [OPTION]... -cn &lt;fully qualified class name&gt;
+
+DESCRIPTION
+       Given a java class generate a WSDL file for the given java class. 
+
+       -o &lt;output Location&gt; : output file location
+       -cp &lt;class path uri&gt; : list of classpath entries - (urls)
+       -tn &lt;target namespace&gt; : target namespace
+       -tp &lt;target namespace prefix&gt; : target namespace prefix
+       -stn &lt;schema target namespace&gt; : target namespace for schema
+       -stp &lt;schema target namespace prefix&gt; : target namespace prefix for
schema
+       -sn &lt;service name&gt; : service name
+       -of &lt;output file name&gt; : output file name for the WSDL
+       -st &lt;binding style&gt; : style for the WSDL
+       -u &lt;binding use&gt; : use for the WSDL
+       -l &lt;soap address&gt; : address of the port for the WSDL
+       -efd &lt;qualified/unqualified&gt; : Setting for elementFormDefault (defaults
to qualified)
+       -afd &lt;qualified/unqualified&gt; : Setting for attributeFormDefault (defaults
to qualified)
+       -xc &lt;extra class&gt; : Extra class for which schematype must be generated.
 Use as : -xc class1 -xc class2 ...
+EXAMPLE
+	
+
+</html>



---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org


Mime
View raw message