nmukhi 2002/12/06 13:14:20 Modified: java/doc samples.html Log: New list of samples, outline for required samples files and documentation Revision Changes Path 1.2 +98 -39 xml-axis-wsif/java/doc/samples.html Index: samples.html =================================================================== RCS file: /home/cvs/xml-axis-wsif/java/doc/samples.html,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- samples.html 3 Dec 2002 19:54:56 -0000 1.1 +++ samples.html 6 Dec 2002 21:14:20 -0000 1.2 @@ -10,44 +10,103 @@ <h1> Web Services Invocation Framework:<br> Samples</h1> -<p>The WSIF distribution comes with a set of sample clients that demonstrate WSIF features. This document describes the features demonstrated by each sample, along with a guide to running them. The samples begin with invocation of a basic SOAP service and progress to more complex WSDL described services. Each sample has two clients - one that uses WSIF's DII directly, the other that uses a local proxy for the WSDL service.</p> -<p><table> -<tr bgcolor="lightgreen"><td><h3>Invoking a simple SOAP service</h3> -<br><b>Stockquote sample</b> (under <tt>samples/stockquote</tt>) -<br><b>Value of sample</b>: Demonstrates how to invoke most common kind of WSDL described service - one with a SOAP binding. Note that same client can be used for a different binding as well, its code is <em>not</em> binding specific - welcome to WSIF! -<br><b>Running the sample</b>: Deploy the SOAP service as described <a href="#deployingsoap">here</a>. Once you have verified that the service is properly deployed, you can use any of the two clients to invoke the service. -<br><em>Running DII client</em>: Run the DynamicInvoker class, specifying as command line arguments the location of the WSDL file for the stockquote sample followed by the operation you wish to invoke and the symbol for the company whose stockquote you are interested in. For example, <tt>java samples.clients.DynamicInvoker file://mywsifinstallation/samples/stockquote/Stockquote.wsdl getQuote IBM</tt> -<br><em>Running proxy client</em>: Run the StockquoteClient class, specifying on the command line the symbol for the compnay whose stockquote you are interested in. For example, <tt>java samples.clients.StockquoteClient IBM</tt> -</td></tr> -<tr bgcolor="lightgrey""><td><h3>Exploiting multiple bindings offered by a service</h3> -<br><b>StockquoteMulti sample</b> (under <tt>samples/stockquotemulti</tt>) -<br><b>Value of sample</b>: Demonstrates how to exploit multiple bindings offered by a service, choose desired binding at runtime in a transparent way. Note that client code here is much the same as first sample. This shows that if our service was originally accessible over SOAP and we needed to switch this to JMS, our client code what not undergo any change at all. If it is accessible over both protocols, we can choose the one that is more convenient at the itme of invocation. -<br><b>Running the sample</b>: Deploy the SOAP service as described <a href="#deployingsoap">here</a>. Deploy the JMS-accessible service as described <a href="#deployingjms">here</a>. Once you have verified that the service is properly deployed and available through boths protocols, you can use any of the two clients to invoke the service. -<br><em>Running DII client</em>: Run the DynamicInvoker class, specifying as command line arguments the location of the WSDL file for the stockquotemulti sample followed by the port you wish to use, the operation you wish to invoke and the symbol for the company whose stockquote you are interested in. For example, <tt>java samples.clients.DynamicInvoker file://mywsifinstallation/samples/stockquote/Stockquote.wsdl JMSPort getQuote IBM</tt> -<br><em>Running proxy client</em>: Run the StockquoteMultiClient class, specifying on the command line the name of the port you wish to use followed by the symbol for the compnay whose stockquote you are interested in. For example, <tt>java samples.clients.StockquoteClient SOAPPort IBM</tt> -</td></tr> -<tr bgcolor="lightgreen"><td><h3>Invoking a service that uses custom types</h3> -<br><b>AddressBook sample</b> (under <tt>samples/addressbook</tt>) -<br><b>Value of sample</b>: Demonstrates how to invoke service that use custom types. Here, the service is offered as an EJB, and note that the client code is predictably much the same as first two samples. -<br><b>Running the sample</b>: Deploy the EJB as described <a href="#deployingejb">here</a>. -<br><em>Running DII client</em> -<br><em>Running proxy client</em> -</td></tr> -<tr bgcolor="lightgrey"><td><h3>Customising your invocation framework for maximum flexibility</h3> -<br><b>AddressBookMulti sample</b> (under <tt>samples/addressbookmulti</tt>) -Service WSDL will have complex types and a SOAP, Java, EJB, JMS, JCA binding. Client setup will plugin a custom implementation of WSIFServiceFactory and WSIFService that uses some heuristics to pick the best binding in the getPort call. -<br><b>Value of sample</b>: Demonstrates how to exploit multiple bindings, leaving client code unchanged while plugging in customisations into the WSIF framework. -<br><b>Running the sample</b>: -<br><em>Running DII client</em> -<br><em>Running proxy client</em> -</td></tr> +<p>The WSIF distribution comes with a set of sample clients that demonstrate WSIF features. This document describes the features demonstrated by each sample, along with a guide to running them.</p> +<p>The samples are present under the samples directory of your WSIF installation. Each sample resides in its own directory. Within each sample directory, you will find the following files (here, <em>SampleName</em> is the name of the sample): +<ul> + <li><tt>SampleName.wsdl</tt>: WSDL file for sample</li> + <li><tt>README.html</tt>: README file describing the sample, what WSIF features it demonstrates, and how to run it.</li> + <li><tt>service</tt>: Subdirectory containing service implementation files, deployment files, README file describing how to deploy service. In case the sample uses a publicly available service, this directory will contain only a README file describing where the service is hosted, and pointing to further information on the service.</li> + <li><tt>client</tt>: Subdirectory containing two further subdirectories, <tt>dynamic</tt> and <tt>stub</tt>. The dynamic subdirectory contains files for a client that uses WSIF's DII (dynamic invocation interface) to invoke the sample service. The stub subdirectory contains a pregenerated set of files that allow invocation of the service through a JAX-RPC compliant service interface. Each of these subdirectories may contain README files for useful information about that particular client.</li> +</ul></p> +<p>You will find that in most cases the sample WSDLs widely differ, but the client code remains much the same. This is the whole point of WSIF - providing access to services exposed via diverse protocols through a uniform WSDL-based API. So you might have two samples, one of which invokes the EJB binding for a service and the other invoking a SOAP binding. Since the client does not contain any binding specific code, the client code for these samples might be identical.</p> +<p>Below you will find a listing of the available samples and a pointer to the README files for each of them.</p> +<p> +<table> +<tr bgcolor="lightgreen"> + <td><b>What the sample demonstrates</b></td> + <td><b>Where the sample is available</b></td> + <td><b>Information on how to setup and run this sample</b></td> +</tr> +<tr> + <td>How to invoke a simple SOAP service</td> + <td>The samples/SimpleSOAP directory under your WSIF installation</td> + <td><a href="../samples/SimpleSOAP/README.html">The Sample README</a></td> +</tr> +<tr> + <td>How to invoke a SOAP service that uses custom schema types</td> + <td>The samples/ComplexSOAP directory under your WSIF installation</td> + <td><a href="../samples/ComplexSOAP/README.html">The Sample README</a></td> +</tr> +<tr> + <td>How to invoke a local java class as a service</td> + <td>The samples/Java directory under your WSIF installation</td> + <td><a href="../samples/Java/README.html">The Sample README</a></td> +</tr> +<tr> + <td>How to invoke an EJB as a service</td> + <td>The samples/EJB directory under your WSIF installation</td> + <td><a href="../samples/EJB/README.html">The Sample README</a></td> +</tr> +<tr> + <td>How to invoke software accessible using the JCA (Java Connector Architecture) as a service</td> + <td>The samples/JCA directory under your WSIF installation</td> + <td><a href="../samples/JCA/README.html">The Sample README</a></td> +</tr> +<tr> + <td>How to invoke software accessible via the Java Message Service (JMS)</td> + <td>The samples/JMS directory under your WSIF installation</td> + <td><a href="../samples/JMS/README.html">The Sample README</a></td> +</tr> +<tr> + <td>How to choose between the available bindings of a service at runtime</td> + <td>The samples/Multi directory under your WSIF installation</td> + <td><a href="../samples/Multi/README.html">The Sample README</a></td> +</tr> +<tr> + <td>How to customise WSIF to select between bindings using your own heuristics</td> + <td>The samples/CustomFactory directory under your WSIF installation</td> + <td><a href="../samples/CustomFactory/README.html">The Sample README</a></td> +</tr> </table> -</p> -<p><a name="deployingsoap"><b>Deploying SOAP services</b>: You first need to run your favorite web server on your local machine, port 8080. In the future localhost:8080 will be a property loaded from wsif.test.propeerties. Find the deployment descriptor for your service (usually a file called DeploymentDescriptor.xml) in the sample directory and deploy the service. The way a service is deployed depends on the SOAP libraries you use. I use soap 2.2 on tomcat so I issue java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter deploy "samples\services\addressbook\DeploymentDescriptor.xml". -</p> -<p><a name="deployingejb"><b>Deploying EJB services</b>:</p> -<p><a name="deployingjava"><b>Deploying Java services</b>:</p> -<p><a name="deployingjms"><b>Deploying JMS services</b>:</p> -<p><a name="deployingjca"><b>Deploying JCA services</b>:</p> <hr width="100%"> -</body></html> \ No newline at end of file +</body></html> + +<!-- <tr bgcolor="lightgreen"><td><h3>Invoking a simple SOAP service</h3> --> +<!-- <br><b>Stockquote sample</b> (under <tt>samples/stockquote</tt>) --> +<!-- <br><b>Value of sample</b>: Demonstrates how to invoke most common kind of WSDL described service - one with a SOAP binding. Note that same client can be used for a different binding as well, its code is <em>not</em> binding specific - welcome to WSIF! --> +<!-- <br><b>Running the sample</b>: Deploy the SOAP service as described <a href="#deployingsoap">here</a>. Once you have verified that the service is properly deployed, you can use any of the two clients to invoke the service. --> +<!-- <br><em>Running DII client</em>: Run the DynamicInvoker class, specifying as command line arguments the location of the WSDL file for the stockquote sample followed by the operation you wish to invoke and the symbol for the company whose stockquote you are interested in. For example, <tt>java samples.clients.DynamicInvoker file://mywsifinstallation/samples/stockquote/Stockquote.wsdl getQuote IBM</tt> --> +<!-- <br><em>Running proxy client</em>: Run the StockquoteClient class, specifying on the command line the symbol for the compnay whose stockquote you are interested in. For example, <tt>java samples.clients.StockquoteClient IBM</tt> --> +<!-- </td></tr> --> +<!-- <tr bgcolor="lightgrey""><td><h3>Exploiting multiple bindings offered by a service</h3> --> +<!-- <br><b>StockquoteMulti sample</b> (under <tt>samples/stockquotemulti</tt>) --> +<!-- <br><b>Value of sample</b>: Demonstrates how to exploit multiple bindings offered by a service, choose desired binding at runtime in a transparent way. Note that client code here is much the same as first sample. This shows that if our service was originally accessible over SOAP and we needed to switch this to JMS, our client code what not undergo any change at all. If it is accessible over both protocols, we can choose the one that is more convenient at the itme of invocation. --> +<!-- <br><b>Running the sample</b>: Deploy the SOAP service as described <a href="#deployingsoap">here</a>. Deploy the JMS-accessible service as described <a href="#deployingjms">here</a>. Once you have verified that the service is properly deployed and available through boths protocols, you can use any of the two clients to invoke the service. --> +<!-- <br><em>Running DII client</em>: Run the DynamicInvoker class, specifying as command line arguments the location of the WSDL file for the stockquotemulti sample followed by the port you wish to use, the operation you wish to invoke and the symbol for the company whose stockquote you are interested in. For example, <tt>java samples.clients.DynamicInvoker file://mywsifinstallation/samples/stockquote/Stockquote.wsdl JMSPort getQuote IBM</tt> --> +<!-- <br><em>Running proxy client</em>: Run the StockquoteMultiClient class, specifying on the command line the name of the port you wish to use followed by the symbol for the compnay whose stockquote you are interested in. For example, <tt>java samples.clients.StockquoteClient SOAPPort IBM</tt> --> +<!-- </td></tr> --> +<!-- <tr bgcolor="lightgreen"><td><h3>Invoking a service that uses custom types</h3> --> +<!-- <br><b>AddressBook sample</b> (under <tt>samples/addressbook</tt>) --> +<!-- <br><b>Value of sample</b>: Demonstrates how to invoke service that use custom types. Here, the service is offered as an EJB, and note that the client code is predictably much the same as first two samples. --> +<!-- <br><b>Running the sample</b>: Deploy the EJB as described <a href="#deployingejb">here</a>. --> +<!-- <br><em>Running DII client</em> --> +<!-- <br><em>Running proxy client</em> --> +<!-- </td></tr> --> +<!-- <tr bgcolor="lightgrey"><td><h3>Customising your invocation framework for maximum flexibility</h3> --> +<!-- <br><b>AddressBookMulti sample</b> (under <tt>samples/addressbookmulti</tt>) --> +<!-- Service WSDL will have complex types and a SOAP, Java, EJB, JMS, JCA binding. Client setup will plugin a custom implementation of WSIFServiceFactory and WSIFService that uses some heuristics to pick the best binding in the getPort call. --> +<!-- <br><b>Value of sample</b>: Demonstrates how to exploit multiple bindings, leaving client code unchanged while plugging in customisations into the WSIF framework. --> +<!-- <br><b>Running the sample</b>: --> +<!-- <br><em>Running DII client</em> --> +<!-- <br><em>Running proxy client</em> --> +<!-- </td></tr> --> +<!-- </table> --> +<!-- </p> --> +<!-- <p><a name="deployingsoap"><b>Deploying SOAP services</b>: You first need to run your favorite web server on your local machine, port 8080. In the future localhost:8080 will be a property loaded from wsif.test.propeerties. Find the deployment descriptor for your service (usually a file called DeploymentDescriptor.xml) in the sample directory and deploy the service. The way a service is deployed depends on the SOAP libraries you use. I use soap 2.2 on tomcat so I issue java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter deploy "samples\services\addressbook\DeploymentDescriptor.xml". --> +<!-- </p> --> +<!-- <p><a name="deployingejb"><b>Deploying EJB services</b>:</p> --> +<!-- <p><a name="deployingjava"><b>Deploying Java services</b>:</p> --> +<!-- <p><a name="deployingjms"><b>Deploying JMS services</b>:</p> --> +<!-- <p><a name="deployingjca"><b>Deploying JCA services</b>:</p> --> + +
