Author: steveh Date: Tue Jan 18 10:10:33 2005 New Revision: 125524 URL: http://svn.apache.org/viewcvs?view=rev&rev=125524 Log: Adding user's guide for web services. Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_JWSFiles.xml (contents, props changed) Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_overview.xml
Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml?view=diff&rev=125524&p1=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml&r1=125523&p2=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml&r2=125524 ============================================================================== --- incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml (original) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml Tue Jan 18 10:10:33 2005 @@ -29,9 +29,11 @@ <tutorial_control label="Control Tutorial" href="controls/tutorial_controls.html"/> </controls> <wsm label="Web Services"> - <jsr181 label="Web Services (JSR 181)" href="webservices.html"/> + <wsm_overview label="Web Services Overview" href="wsm/wsm_overview.html"/> + <wsm_overview label="Java Web Service Files" href="wsm/wsm_JWSFiles.html"/> <supported_datatypes label="Supported Data Types" href="wsm/datatypes.html"/> <tutorial_wsm label="Web Services Tutorial" href="wsm/tutorial_wsm.html"/> + <jsr181 label="Web Services (JSR 181)" href="webservices.html"/> </wsm> <samples label="Samples"> <jpetstore label="Petstore" href="jpetstore.html"/> Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml?view=diff&rev=125524&p1=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml&r1=125523&p2=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml&r2=125524 ============================================================================== --- incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml (original) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml Tue Jan 18 10:10:33 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd";> <!--<!DOCTYPE document SYSTEM "C:\apache-forrest-0.5.1\context\resources\schema\dtd\document-v12.dtd">--> <document> <header> @@ -21,12 +21,15 @@ <title>Step 1: Begin the Web Service Tutorial</title> <section> <title>To Set up the Development Environment</title> - <p>Follow the setup directions at <fork href="../setup.html">Beehive Installation and Setup</fork></p> + <p>Follow the setup directions at <a class="fork" href="../setup.html">Beehive Installation and Setup</a></p> <p>After completing the instructions, leave the command shell open to use throughout this tutorial.</p> </section> <section> <title>Add a Manager Role to Tomcat</title> - <p>Adding the manager role to Tomcat server allows you to run deploy related targets in the Ant file <code>runTomcat.xml</code>. This file is provided as a convenience for managing the Tomcat server.</p> + <p>Adding the manager role to Tomcat server allows you to run + deploy related targets in the Ant file + <code>runTomcat.xml</code>. This file is provided as a + convenience for managing the Tomcat server.</p> <p>Edit the file <code>CATALINA_HOME/conf/tomcat-users.xml</code> so it appears as follows:</p> <source><![CDATA[<?xml version='1.0' encoding='utf-8'?> <tomcat-users> @@ -52,22 +55,12 @@ <p>[todo]</p> </section>--> <section> - <title>Make a Project Folder</title> + <title>Make a Project Folder Using the Web Service Application Template</title> <p>On your C: drive, create a directory called <code>beehive_projects</code>.</p> - <p>In the <code>beehive_projects</code> directory, create a directory called ws_tutorial.</p> - <p>Before proceeding, confirm that the following directory structure exists:</p> - <source>C: - beehive_projects - ws_tutorial</source> - </section> - <section> - <title>To Copy the Web Services Application Template</title> - <p>In this step you will copy the Web Services project template into your project folder. The project template contains a simple web service and a test JSP page.</p> - <p>Copy the contents of the folder</p> - <source>BEEHIVE_HOME/samples/wsm-blank</source> - <p>into your project folder</p> - <source>C:/beehive_projects/ws_tutorial</source> - <p>It is important that you copy the <em>contents</em> of <code>wsm-blank</code>; do not copy the folder <code>wsm-blank</code> itself.</p> + <p>Copy the folder <strong><code>BEEHIVE_HOME/samples/wsm-blank</code></strong> + into the folder <strong><code>C:/beehive_projects</code></strong>.</p> + <p>Rename the folder <code>C:/beehive_projects/</code><strong><code>wsm-blank</code></strong> + as <code>C:/beehive_projects/</code><strong><code>ws_tutorial</code></strong></p> <p>Before proceeding, confirm that the following directory structure exists:</p> <source>C: beehive_projects @@ -130,7 +123,7 @@ </section> <section> <title>To Run the Web Service Provided in the Template</title> - <p>Visit the index.jsp page: <fork href="http://localhost:8080/ws_tutorial/index.html";>http://localhost:8080/ws_tutorial/index.html</fork>.</p> + <p>Visit the index.jsp page: <a class="fork" href="http://localhost:8080/ws_tutorial/index.html";>http://localhost:8080/ws_tutorial/index.html</a>.</p> <p>Click the "Validate" link for an evaluation of the resources available to your web service. Note that you will need to download additional resources to take full advantage of Beehive web services. For example, for Axis to work properly with SOAP attachments, additional, external jars (activation.jar and mailapi.jar) are required. You will download those resources in later steps in the tutorial.</p> <p>Click the "WSDL" link to see the web service's WSDL. </p> <p>Click the "sayHelloWorld()" link to see a SOAP response from the web service's sayHelloWorld() method.</p> @@ -182,7 +175,7 @@ <section> <title>Test the Parameterized Method</title> <p>Enter the following URL in the address bar of your browser. </p> - <p><fork href="http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon";>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon</fork></p> + <p><a class="fork" href="http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon";>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon</a></p> <p>The following SOAP response appears in the browser:</p> <source><![CDATA[<soapenv:Envelope> <soapenv:Body> @@ -242,7 +235,7 @@ <section> <title>To Test the Non-Web Invokable Method</title> <p>Enter the following URL in the address bar of your browser. </p> - <p><fork href="http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayNothingOverTheWeb";>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayNothingOverTheWeb</fork></p> + <p><a class="fork" href="http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayNothingOverTheWeb";>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayNothingOverTheWeb</a></p> <p>The following SOAP response appears in the browser, indicating that the method sayNothingOverTheWeb() cannot be invoked through the web service (although it can be called by other methods within the web service).</p> <source><![CDATA[<soapenv:Envelope> <soapenv:Body> @@ -304,7 +297,7 @@ <section> <title>To Test the Parameterized Method (with SOAP-encoded style)</title> <p>Enter the following URL in the address bar of your browser. </p> - <p><fork href="http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon";>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon</fork></p> + <p><a class="fork" href="http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon";>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon</a></p> <p>The following SOAP response appears in the browser. Compare the RPC style below with the DOC style above.</p> <source><![CDATA[<soapenv:Envelope> <soapenv:Body> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_JWSFiles.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_JWSFiles.xml?view=auto&rev=125524 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_JWSFiles.xml Tue Jan 18 10:10:33 2005 @@ -0,0 +1,221 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd";> +<document> + <header> + <title>Java Web Service Files</title> + </header> + <body> + <p>This topic explains the basic techniques for exposing a Java class + as a web service using the Beehive web service metadata + annotations.</p> + <section id="annotations"> + <title>What is a Metadata Annotation?</title> + <p>A metadata annotation is a property setting on some piece of + Java code. That's where the "meta" in "metadata annotation" + comes from: metadata annotations overlay the Java code they + modify.</p> + <p>Metadata annotations can decorate either (1) Java classes or (2) + Java methods. Syntactically speaking, a class-decorating + annotation appears as follows:</p> + <source><strong>@WebService</strong> public class MyWebService { + ... }</source> + <p>A method-decorating annotation appears as follows:</p> + <source>@WebService public class MyWebService { + <strong>@WebMethod</strong> public String sayHelloWorld() { + return "Hello world!"; } }</source> + </section> + <section id="wsdl_mapping_annotations + "> + <title>WSDL Mapping Annotations</title> + <p>These annotations let you control how your Java source + implementation is exposed through the web service's WSDL file. + More generally: these annotations let you control which parts + of the WSDL are associated with which Java implementation + code.</p> + <section id="at_webservice"> + <title> + <code>@WebService</code> + </title> + <p>To specify that a Java class should be exposed as a web service, + decorate the class signature with the <code>@WebService</code> + annotation. The imported class + <code>javax.jws.WebService</code> is the backing class for the + annotation.</p> + <source><strong>import javax.jws.WebService; @WebService</strong> + public class MyWebService { ... }</source> + <p>Attributes on the annotation determine properties on the web + services WSDL. For example, the namespace advertised by the + WSDL (and used for the SOAP XML documents generated by the web + service) is specified by the <code>targetNamespace</code> + attribute.</p> + <source>import javax.jws.WebService; @WebService( + <strong>targetNamespace = + http://www.openuri.org/my/web/service/wsdl</strong> ) public + class MyWebService { ... }</source> + <p>The WSDL will contain the namespace referenced as follows:</p> + <source> <wsdl:definitions targetNamespace="targetNamespace = + <strong>http://www.openuri.org/my/web/service/wsdl</strong>"> + <wsdl:types> <schema elementFormDefault="qualified" + targetNamespace="targetNamespace = http://www.openuri.org/my/web/service/wsdl";> + <element name="sayHelloWorld"> ... </source> + <p>SOAP documents generated by the this web service will reference + the namespace as so:</p> + <source>[todo]</source> + </section> + + <section id="at_webmethod"> + <title>@WebMethod</title> + <p>The <code>@WebMethod</code> annotation decorates a method: + it means that the method should be exposed as a web service + method, i.e., a method that is invokable through SOAP + messages.</p> + <source>import javax.jws.WebService; +<strong>import javax.jws.WebMethod;</strong> + [EMAIL PROTECTED]( + targetNamespace="targetNamespace = http://www.openuri.org/my/web/service/wsdl"; +) +public class MyWebService +{ + <strong>@WebMethod</strong> + public String sayHelloWorld() + { + return "Hello world!"; + } +}</source> + <p>[todo]</p> + </section> + <section id="at_webparam"> + <title>@WebParam</title> + <p>The <code>@WebParam</code> annotation marks a parameter of a + web-exposed method (a method exposed by the + <code>@WebMethod</code> annotation).</p> + <source>import javax.jws.WebService; +import javax.jws.WebMethod; +<strong>import javax.jws.WebParam;</strong> + [EMAIL PROTECTED]( + targetNamespace="targetNamespace = http://www.openuri.org/my/web/service/wsdl"; +) +public class MyWebService +{ + @WebMethod + public String sayHelloWorld( <strong>@WebParam</strong> String greetee ) + { + return "Hello " + greetee + "!"; + } +}</source> + </section> + <section id="separating_contract_and_impl"> + <title>Separating the Public and Implementation Names of + Methods and Parameters</title> + <p>Changing the name displayed in the WSDL for methods and + parameters...</p> + <p>These features make it possible to change the underlying + Java source implementation for a pre-existing WSDL, or to + change the WSDL with only minor changes to the underlying + Java source implementation.</p> + <p>To display a different method name in the WSDL, use the + <code>@WebParam( operationName="[opName]" )</code> + attribute.</p> + <source>import javax.jws.WebService; +import javax.jws.WebMethod; +import javax.jws.WebParam; + [EMAIL PROTECTED]( + targetNamespace="targetNamespace = http://www.openuri.org/my/web/service/wsdl"; +) +public class MyWebService +{ + @WebMethod( + <strong>operationName="getGreeting"</strong> + ) + public String sayHelloWorld( @WebParam String greetee ) + { + return "Hello " + greetee + "!"; + } +}</source> + <p>The WSDL will display the operation <code>getGreeting</code> + to the client.</p> + <source> +<wsdl:portType name="MyWebService"> + <wsdl:operation name="<strong>getGreeting</strong>"> + <wsdl:input message="impl:getGreetingRequest" name="getGreetingRequest"/> + <wsdl:output message="impl:getGreetingResponse" name="getGreetingResponse"/> + </wsdl:operation> +</wsdl:portType> +</source> + <p>To display a different name for the method parameter, use + the <code>@WebParam( name="[name]" )</code> attribute.</p> + <source>import javax.jws.WebService; +import javax.jws.WebMethod; +import javax.jws.WebParam; + [EMAIL PROTECTED]( + targetNamespace="targetNamespace = http://www.openuri.org/my/web/service/wsdl"; +) +public class MyWebService +{ + @WebMethod( + operationName="getGreeting" + ) + public String sayHelloWorld( @WebParam( name="greetWho" ) String greetee ) + { + return "Hello " + greetee + "!"; + } +}</source> + <p>The relevant part of the WSDL is shown below.</p> + <source> +<element name="getGreeting"> + <complexType> + <sequence> + <element name="<strong>greetWho</strong>" type="xsd:string"/> + </sequence> + </complexType> +</element> +</source> + <p>Changing the method invoked...[todo: doable?]</p> + </section> + <section id="at_webresult"><title>@WebResult</title> + <p>[todo]</p></section> + </section> + <section id="binding_annotations"> + <title>Binding Annotations</title> + <p>These annotations let you control the network protocols and + message formats supported by your web service.</p> + <section> + <title>@SOAPBinding</title> + <p>[todo]</p> + </section> + </section> + <section id="security_annotations"> + <title>Security Annotations</title> + <p>These annotations let you request authentication and + authorization services from the web service's deployment + container.</p> + <section> + <title>@SecurityIdentity</title> + <p>[todo]</p> + </section> + <section> + <title>@SecurityRoles</title> + <p>[todo]</p> + </section> + </section> + <section id="handler_annotations"> + <title>Handler Annotations</title> + <p>These annotations let you intercept incoming and outgoing SOAP + messages for additional processing before and after the + execution of web service's business processes.</p> + <section id="at_soapmessagehandlers"> + <title>@SOAPMessageHandlers</title> + <p>[todo]</p> + </section> + </section> + </body> + <footer> + <legal>Java, J2EE, and JCP are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.<br/> + © 2004, Apache Software Foundation + </legal> + </footer> +</document> Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_overview.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_overview.xml?view=diff&rev=125524&p1=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_overview.xml&r1=125523&p2=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_overview.xml&r2=125524 ============================================================================== --- incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_overview.xml (original) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/wsm_overview.xml Tue Jan 18 10:10:33 2005 @@ -5,7 +5,49 @@ <title>Web Services Overview</title> </header> <body> - <p>todo</p> + <section> + <title>Beehive Web Services Features</title> + <p><strong>Metadata Annotations</strong></p> + <p>Beehive web services use Java metadata annotations to simply the web service development process. + Metadata annotations are easy to learn and use, and offer the developer an especially + quick way to change the web service implementation. The annotations offer + implementations of the most common web service features, such as + (1) conforming to basic SOAP and WSDL standards, (2) separating the public contract + and the private implementation, and (3) creating asynchronous communitication between the + web service and its clients. The basic idea underlying all Beehive web service developement + is that the developer writes an ordinary Java class, whose functionality is exposed + as a web service. The manner of exposure is specified by the metadata annotations + that decorate the class and its methods.</p> + <p><strong>Standards Based</strong></p> + <p>Beehive web services are based on + the <a class="fork" href="http://jcp.org/en/jsr/detail?id=181";>JSR 181</a> + web service standard. JSR 181 sets out the core annotations used to expose + Java classes as web services.</p> + <p><strong>No Expertice with APIs and Deployment Descriptors Required</strong></p> + <p>Beehive web services are implemented as ordinary Java classes decorated with + metadata annotations. The metadata annotations (1) replace the deployment descriptors + (that would ordinarily be used to configure the Java class) + and (2) encapsulate the web service APIs (that would ordinarily be used by the developer + as an implementation resource). The result is a web service implementation that is much + easier to learn and understand. Instead of keeping multiple Java clases and XML configuration + files in sync, the developer needs to edit only one file: the annotated Java class.</p> + <p><strong>Containers</strong></p> + <p>[todo]</p> + </section> + <section> + <title>Web Service Basics</title> + <p><strong>What Do Web Services Do?</strong></p> + <p>At the most basic level, web services are servlets that take requests (in the form + of XML documents) and sends back responses (in the form of XML documents). </p> + <p><strong>SOAP</strong></p> + <p></p> + <p><strong>Design Considerations</strong></p> + <p></p> + <p><strong></strong></p> + <p></p> + <p><strong></strong></p> + <p></p> + </section> </body> <footer> <legal>Java, J2EE, and JCP are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.<br/>
