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 he...@apache.org on 2006/10/09 12:43:08 UTC
svn commit: r454334 [1/3] - in
/webservices/axis2/branches/java/1_1/xdocs/1_1: dii.html modules.html
reference.html src/ src/Axis2SampleDocLitServiceCode.html userguide.html
xmlbased-server.html
Author: hemapani
Date: Mon Oct 9 03:43:07 2006
New Revision: 454334
URL: http://svn.apache.org/viewvc?view=rev&rev=454334
Log:
updated user guide for 1.1 relese
Added:
webservices/axis2/branches/java/1_1/xdocs/1_1/dii.html
webservices/axis2/branches/java/1_1/xdocs/1_1/modules.html
webservices/axis2/branches/java/1_1/xdocs/1_1/reference.html
webservices/axis2/branches/java/1_1/xdocs/1_1/src/
webservices/axis2/branches/java/1_1/xdocs/1_1/src/Axis2SampleDocLitServiceCode.html
webservices/axis2/branches/java/1_1/xdocs/1_1/xmlbased-server.html
Modified:
webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html
Added: webservices/axis2/branches/java/1_1/xdocs/1_1/dii.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/dii.html?view=auto&rev=454334
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/dii.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/dii.html Mon Oct 9 03:43:07 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 & 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 <wsa:MessageID> and
+<wsa:RelatesTo> 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/1_1/modules.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/modules.html?view=auto&rev=454334
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/modules.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/modules.html Mon Oct 9 03:43:07 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&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&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&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><module name="logging" class="userguide.loggingmodule.LoggingModule ">
+ <inflow>
+ <handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase" />
+ </handler>
+ </inflow>
+
+ <outflow>
+ <handler name="OutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </outflow>
+
+ <Outfaultflow>
+ <handler name="FaultOutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </Outfaultflow>
+
+ <INfaultflow>
+ <handler name="FaultInFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </INfaultflow>
+</module></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. "<order
+phase="loggingPhase" />" describes the phase in which this handler
+runs.</p>
+<pre><handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+<order phase="loggingPhase" />
+</handler></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_"axis2_xml"">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><!-- ================================================= -->
+<!-- Phases -->
+<!-- ================================================= -->
+
+<phaseOrder type="inflow">
+ <!-- System pre defined phases -->
+ <phase name="TransportIn"/>
+ <phase name="PreDispatch"/>
+ <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">
+ <handler name="AddressingBasedDispatcher"
+ class="org.apache.axis2.engine.AddressingBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="RequestURIBasedDispatcher"
+ class="org.apache.axis2.engine.RequestURIBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPActionBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPActionBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPMessageBodyBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+ <handler name="InstanceDispatcher"
+ class="org.apache.axis2.engine.InstanceDispatcher">
+ <order phase="PostDispatch"/>
+ </handler>
+ </phase>
+ <!-- System pre defined phases -->
+ <!-- After Postdispatch phase module author or service author can add any phase he wants -->
+ <phase name="OperationInPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ </phaseOrder>
+ <phaseOrder type="outflow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ <!--system predefined phases-->
+ <!--these phases will run irrespective of the service-->
+ <phase name="PolicyDetermination"/>
+ <phase name="MessageOut"/>
+ </phaseOrder/>
+ <phaseOrder type="INfaultflow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationInFaultPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ </phaseOrder>
+ <phaseOrder type="Outfaultflow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutFaultPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ <phase name="PolicyDetermination"/>
+ <phase name="MessageOut"/>
+ </phaseOrder>
+ </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_"services_xml"">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><service name="<span style="color: rgb(36, 193, 19);">MyServiceWithModule</span>">
+ <description>
+ This is a sample Web service with a logging module engaged.
+ </description>
+ <span style="color: rgb(36, 193, 19);"><module ref="logging"/></span>
+ <parameter name="ServiceClass" locked="xsd:false">userguide.example2.MyService</parameter>
+ <operation name="echo">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ <operation name="ping">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+</service></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>"<module
+ref="logging"/>"</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/1_1/reference.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/reference.html?view=auto&rev=454334
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/reference.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/reference.html Mon Oct 9 03:43:07 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 <Location of WSDL>
+
+DESCRIPTION
+ Given a WSDL file generate java code to handle Web Service invocation.
+
+ -o <output Location> : 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 <package name> : set custom package name
+ -l <language> : 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 <databinding> : 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 <port_name> : name of port in the presence of multiple ports
+ -sn <service_name> : name of service in the presence of multiple services
+ -u : unpacks the databinding classes
+ -r <repository_path> : 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 <fully qualified class name>
+
+DESCRIPTION
+ Given a java class generate a WSDL file for the given java class.
+
+ -o <output Location> : output file location
+ -cp <class path uri> : list of classpath entries - (urls)
+ -tn <target namespace> : target namespace
+ -tp <target namespace prefix> : target namespace prefix
+ -stn <schema target namespace> : target namespace for schema
+ -stp <schema target namespace prefix> : target namespace prefix for schema
+ -sn <service name> : service name
+ -of <output file name> : output file name for the WSDL
+ -st <binding style> : style for the WSDL
+ -u <binding use> : use for the WSDL
+ -l <soap address> : address of the port for the WSDL
+ -efd <qualified/unqualified> : Setting for elementFormDefault (defaults to qualified)
+ -afd <qualified/unqualified> : Setting for attributeFormDefault (defaults to qualified)
+ -xc <extra class> : Extra class for which schematype must be generated. Use as : -xc class1 -xc class2 ...
+EXAMPLE
+
+
+</html>
Added: webservices/axis2/branches/java/1_1/xdocs/1_1/src/Axis2SampleDocLitServiceCode.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/src/Axis2SampleDocLitServiceCode.html?view=auto&rev=454334
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/src/Axis2SampleDocLitServiceCode.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/src/Axis2SampleDocLitServiceCode.html Mon Oct 9 03:43:07 2006
@@ -0,0 +1,154 @@
+<h1>Code Listing For Axis2SampleDocLitService Service</h1>
+
+<h2>Server</h2>
+
+<h3>echoString</h3>
+
+<p>Locate the following code segment in "Axis2SampleDocLitServiceSkeleton.java" and add the business logic as shown below.</p>
+<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>
+
+<p>Once the business logic is added, the source code appears as below:</p>
+<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.
+ EchoStringReturnDocument retDoc = EchoStringReturnDocument.Factory.newInstance();
+ //send the string back.
+ retDoc.setEchoStringReturn(param4.getEchoStringParam());
+ return retDoc;
+ }
+</pre>
+
+<h3>echoStringArray</h3>
+<p>The code segment for echoStringArray is shown below:</p>
+<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.
+ EchoStringArrayReturnDocument retDoc = EchoStringArrayReturnDocument.Factory.newInstance();
+ //Get the String array from the input parameters.
+ String[] inParams = param0.getEchoStringArrayParam().getStringArray();
+ ArrayOfstringLiteral retParams = 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]);
+ }
+ //return the output document.
+ retDoc.setEchoStringArrayReturn(retParams);
+ return retDoc;
+}
+</pre>
+
+<h3>echoStruct</h3>
+<p>The code segment for echoStruct is shown below:</p>
+<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.
+ EchoStructReturnDocument retDoc = EchoStructReturnDocument.Factory.newInstance();
+
+ //Get the SOAPStrcut from the incoming parameters
+ SOAPStruct inStruct = param2.getEchoStructParam();
+
+ //Struct for the sending back
+ SOAPStruct outStruct = 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>
+
+
+
+<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>
+<pre>
+ //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
+ Axis2SampleDocLitPortTypeStub stub= new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+ //Create the request document to be sent.
+ EchoStringParamDocument reqDoc= EchoStringParamDocument.Factory.newInstance();
+ reqDoc.setEchoStringParam("Axis2 Echo");
+ //invokes the Web service.
+ EchoStringReturnDocument resDoc=stub.echoString(reqDoc);
+ System.out.println(resDoc.getEchoStringReturn());
+
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+</pre>
+
+<p>Similarly the following code fragments show client side code for echoStringArray operation and echoStruct operation respectively.</p>
+
+<h3>Client for echoStringArray Operation</h3>
+<pre>
+ //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
+ Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+
+ //Create the request document to be sent.
+ EchoStringArrayParamDocument reqDoc = EchoStringArrayParamDocument.Factory.newInstance();
+ ArrayOfstringLiteral paramArray = ArrayOfstringLiteral.Factory.newInstance();
+
+ paramArray.addString("Axis2");
+ paramArray.addString("Echo");
+
+ reqDoc.setEchoStringArrayParam(paramArray);
+ 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 (Exception e) {
+ e.printStackTrace();
+ }
+</pre>
+
+<h3>Client for echoStruct Operation</h3>
+<pre>
+ //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
+ Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+ //Create the request Document
+ EchoStructParamDocument reqDoc = EchoStructParamDocument.Factory.newInstance();
+
+ //Create the complex type
+ SOAPStruct reqStruct = SOAPStruct.Factory.newInstance();
+
+ reqStruct.setVarFloat(100.50F);
+ reqStruct.setVarInt(10);
+ reqStruct.setVarString("High");
+
+ reqDoc.setEchoStructParam(reqStruct);
+
+ //Service invocation
+ EchoStructReturnDocument resDoc = stub.echoStruct(reqDoc);
+ 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());
+
+</pre>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org