Author: steveh Date: Fri Nov 5 15:40:49 2004 New Revision: 56708 Modified: incubator/beehive/site/build/site/index.html incubator/beehive/site/build/site/wsm/sample_AddressBook.html incubator/beehive/site/build/site/wsm/tutorial_wsm.html incubator/beehive/site/src/documentation/content/xdocs/wsm/sample_AddressBook.xml incubator/beehive/site/src/documentation/content/xdocs/wsm/tutorial_wsm.xml Log: Latest content for the WS tutorial.
Modified: incubator/beehive/site/build/site/index.html ============================================================================== --- incubator/beehive/site/build/site/index.html (original) +++ incubator/beehive/site/build/site/index.html Fri Nov 5 15:40:49 2004 @@ -264,20 +264,20 @@ <a href="#Get+Involved">Get Involved</a> </li> </ul> - <!-- - Beehive - Welcome<should link to the HTML page created from Welcome.doc> - License<should link to http://www.apache.org/licenses/LICENSE-2.0> - - Documentation - FAQ<should link to the HTML page created from FAQ.doc> - Controls Overview<should link to Kyle's control Overview> - Controls Programming<should link to Kyle's Controls programming pdf> - Web Services (JSR 181)<should link to http://jcp.org/en/jsr/detail?id=181> - - Contributing - Mailing Lists<should link to HTML Page created from MailingLists.doc> - Contributers<should link to HTML Page created from Contributers.doc> + <!-- + Beehive + Welcome<should link to the HTML page created from Welcome.doc> + License<should link to http://www.apache.org/licenses/LICENSE-2.0> + + Documentation + FAQ<should link to the HTML page created from FAQ.doc> + Controls Overview<should link to Kyle's control Overview> + Controls Programming<should link to Kyle's Controls programming pdf> + Web Services (JSR 181)<should link to http://jcp.org/en/jsr/detail?id=181> + + Contributing + Mailing Lists<should link to HTML Page created from MailingLists.doc> + Contributers<should link to HTML Page created from Contributers.doc> --> Modified: incubator/beehive/site/build/site/wsm/sample_AddressBook.html ============================================================================== --- incubator/beehive/site/build/site/wsm/sample_AddressBook.html (original) +++ incubator/beehive/site/build/site/wsm/sample_AddressBook.html Fri Nov 5 15:40:49 2004 @@ -299,7 +299,7 @@ <li>junit.jar (v3.8.1 or later)</li> -<li>derby.jar (for EmployeeWS only)</li> +<li>derby_46005.jar (for EmployeeWS only)</li> </ul> </div> @@ -329,8 +329,8 @@ <p>Download junit.jar from <a href="http://prdownloads.sourceforge.net/junit/junit3.8.1.zip?download";>http://prdownloads.sourceforge.net/junit/junit3.8.1.zip?download</a> </p> <p> Copy <span class="codefrag">junit.jar</span> to <span class="codefrag">ANT_HOME/lib</span>.</p> -<p> Download derby.jar from <a href="http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP";>http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP</a>.</p> -<p> Copy <span class="codefrag">derby.jar</span> to <span class="codefrag">BEEHIVE_HOME/samples/EmployeeWS/WEB-INF/lib</span>.</p> +<p> Download derby_46005.jar from <a href="http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP";>http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP</a>.</p> +<p> Copy <span class="codefrag">derby_46005.jar</span> to <span class="codefrag">BEEHIVE_HOME/samples/EmployeeWS/WEB-INF/lib</span>.</p> <a name="N10094"></a><a name="Setting+up+the+Server"></a> <h4>Setting up the Server</h4> <div style="margin-left: 0 ; border: 2px"> Modified: incubator/beehive/site/build/site/wsm/tutorial_wsm.html ============================================================================== --- incubator/beehive/site/build/site/wsm/tutorial_wsm.html (original) +++ incubator/beehive/site/build/site/wsm/tutorial_wsm.html Fri Nov 5 15:40:49 2004 @@ -263,47 +263,76 @@ <a href="#step1">Step 1: Begin the Web Service Tutorial</a> <ul class="minitoc"> <li> -<a href="#Download+and+Install+JDK5">Download and Install JDK5</a> +<a href="#To+Download+and+Install+J2SE5">To Download and Install J2SE5</a> </li> <li> -<a href="#Install+ANT+1.6.2">Install ANT 1.6.2</a> +<a href="#To+Install+ANT+1.6.2">To Install ANT 1.6.2</a> </li> <li> -<a href="#Download+and+Install+Tomcat+5">Download and Install Tomcat 5</a> +<a href="#To+Download+and+Install+Tomcat+5">To Download and Install Tomcat 5</a> </li> <li> -<a href="#Download+and+Install+a+Beehive+Binary+Distribution">Download and Install a Beehive Binary Distribution</a> +<a href="#To+Download+and+Install+a+Beehive+Binary+Distribution">To Download and Install a Beehive Binary Distribution</a> </li> <li> -<a href="#Set+up+the+Development+Environment">Set up the Development Environment</a> +<a href="#To+Set+up+the+Development+Environment">To Set up the Development Environment</a> </li> <li> -<a href="#Set+Up+Drop+In+Deployment">Set Up Drop In Deployment</a> +<a href="#Add+a+Manager+Role+to+Tomcat">Add a Manager Role to Tomcat</a> +</li> +<li> +<a href="#To+Start+the+Tomcat+Server">To Start the Tomcat Server</a> </li> </ul> </li> <li> -<a href="#step_2">Step 2: Create a New Web Service</a> +<a href="#step_2">Step 2: Install the Web Service Template</a> <ul class="minitoc"> <li> <a href="#Introduction">Introduction</a> </li> <li> -<a href="#To+Create+a+JWS+File">To Create a JWS File</a> +<a href="#Make+a+Project+Folder">Make a Project Folder</a> +</li> +<li> +<a href="#To+Copy+the+Web+Services+Application+Template">To Copy the Web Services Application Template</a> +</li> +<li> +<a href="#Examine+the+Blank.jws+Web+Service">Examine the Blank.jws Web Service</a> +</li> +<li> +<a href="#Copy+Runtime+JARs%2C+Compile%2C+and+Deploy+the+Web+Service">Copy Runtime JARs, Compile, and Deploy the Web Service</a> </li> <li> -<a href="#Test+the+Web+Service%3A+URL+Invocation+of+the+web+service">Test the Web Service: URL Invocation of the web service</a> +<a href="#To+Run+the+Web+Service+Provided+in+the+Template">To Run the Web Service Provided in the Template</a> </li> </ul> </li> <li> -<a href="#step_3">Step 3: Add a Parameter to the hello Method</a> +<a href="#step_3">Step 3: Add a Parameterized Method to the Web Service</a> <ul class="minitoc"> <li> <a href="#Edit+the+JWS+File">Edit the JWS File</a> </li> <li> -<a href="#Test+the+Web+Service">Test the Web Service</a> +<a href="#Compile+and+Redeploy+the+Web+Service">Compile and Redeploy the Web Service</a> +</li> +<li> +<a href="#Test+the+Parameterized+Method">Test the Parameterized Method</a> +</li> +</ul> +</li> +<li> +<a href="#Step+4%3A+Add+a+Non-Web+Invokable+Method">Step 4: Add a Non-Web Invokable Method</a> +<ul class="minitoc"> +<li> +<a href="#Compile+and+Redeploy+the+Web+Service-N101D9">Compile and Redeploy the Web Service</a> +</li> +<li> +<a href="#To+Test+the+Non-Web+Invokable+Method">To Test the Non-Web Invokable Method</a> +</li> +<li> +<a href="#Step+5%3A+Change+the+SOAP+Style">Step 5: Change the SOAP Style</a> </li> </ul> </li> @@ -331,393 +360,341 @@ <a name="N1002A"></a><a name="step1"></a> <h3>Step 1: Begin the Web Service Tutorial</h3> <div style="margin-left: 0 ; border: 2px"> -<a name="N10030"></a><a name="Download+and+Install+JDK5"></a> -<h4>Download and Install JDK5</h4> +<a name="N10030"></a><a name="To+Download+and+Install+J2SE5"></a> +<h4>To Download and Install J2SE5</h4> <div style="margin-left: 0 ; border: 2px"> -<p>If you do not have JDK5 installed on your machine, visit <a target="_blank" href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</a> and download and install the latest version.</p> +<p>If you do not have J2SE5 installed, visit <a target="_blank" href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</a>. + </p> +<p>Download and install the latest version of J2SE5.</p> </div> -<a name="N1003E"></a><a name="Install+ANT+1.6.2"></a> -<h4>Install ANT 1.6.2</h4> +<a name="N10041"></a><a name="To+Install+ANT+1.6.2"></a> +<h4>To Install ANT 1.6.2</h4> <div style="margin-left: 0 ; border: 2px"> -<p>If you do not have Ant 1.6.2 installed on your machine, visit <a target="_blank" href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip</a> - -</p> -<p>After download is complete, unzip the file <span class="codefrag">apache-ant-1.6.2-bin.zip</span> into your C: drive.</p> -<p>After the file has unzipped, confirm that the following directory structure exists: <span class="codefrag">C:/apache-ant-1.6.2</span>.</p> +<p>If you do not have Ant 1.6.2 installed, visit <a target="_blank" href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip</a>. + </p> +<p>Download the ZIP file and unzip it on your machine.</p> </div> -<a name="N10058"></a><a name="Download+and+Install+Tomcat+5"></a> -<h4>Download and Install Tomcat 5</h4> +<a name="N10052"></a><a name="To+Download+and+Install+Tomcat+5"></a> +<h4>To Download and Install Tomcat 5</h4> <div style="margin-left: 0 ; border: 2px"> -<p>If you do not have Tomcat 5 installed on your machine, visit <a target="_blank" href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip</a> and download the ZIP file.</p> -<p>Unzip jakarta-tomcat-5.0.25.zip into the C: drive.</p> -<p>After the unzip is complete, confirm that the following directory exists: <span class="codefrag">C:/jakarta-tomcat-5.0.25</span>.</p> -<p></p> +<p>If you do not have Tomcat 5 installed, visit <a target="_blank" href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip</a> + +</p> +<p>Download the ZIP file and unzip it on your machine.</p> </div> -<a name="N10071"></a><a name="Download+and+Install+a+Beehive+Binary+Distribution"></a> -<h4>Download and Install a Beehive Binary Distribution</h4> +<a name="N10063"></a><a name="To+Download+and+Install+a+Beehive+Binary+Distribution"></a> +<h4>To Download and Install a Beehive Binary Distribution</h4> <div style="margin-left: 0 ; border: 2px"> <p>Visit [todo: distribution download link] and download the latest binary distribution of Beehive.</p> -<p> Create a directory called <span class="codefrag">beehive-0.4</span> on your C: drive. This directory will store the Beehive distribution JARs and all of your Beehive projects.</p> -<p>Unzip the distribution JAR into <span class="codefrag">C:/beehive-0.4</span> - -</p> +<p>Unzip the distribution file on your machine</p> </div> -<a name="N10087"></a><a name="Set+up+the+Development+Environment"></a> -<h4>Set up the Development Environment</h4> +<a name="N10070"></a><a name="To+Set+up+the+Development+Environment"></a> +<h4>To Set up the Development Environment</h4> <div style="margin-left: 0 ; border: 2px"> +<p>Open the directory where you installed the Beehive distribution. Open the file <span class="codefrag">beehiveUser.cmd</span> in a text editor. Edit <span class="codefrag">beehiveUser.cmd</span> to fit your local environment. The following environmental variables must be set to the appropriate paths on your machine: <span class="codefrag">BEEHIVE_HOME</span>, <span class="codefrag">JAVA_HOME</span>, <span class="codefrag">ANT_HOME</span>, and <span class="codefrag">CATALINA_HOME</span>. The following example shows how to edit <span class="codefrag">beehiveUser.cmd</span> for a typical environment.</p> +<pre class="code">REM the root of Beehive distribution +set BEEHIVE_HOME=C:\beehive-alpha + +REM location of a JDK +set JAVA_HOME=C:\jdk1.5.0 + +REM location of Ant +set ANT_HOME=C:\apache-ant-1.6.2 + +REM location of Tomcat +set CATALINA_HOME=C:\jakarta-tomcat-5.0.25</pre> +<p>When you finished editing <span class="codefrag">beehiveUser.cmd</span>, save and close the file.</p> <p>Open a command shell.</p> -<p>At the command prompt, enter: <span class="codefrag">set JAVA_HOME=C:/jdk1.5.0</span> - -</p> -<p> Note: if you have JDK5 installed in a different directory, set JAVA_HOME to that location.</p> -<p>At the command prompt, enter: <span class="codefrag">set CATALINA_HOME=C:/jakarta-tomcat-5.0.25</span> - -</p> -<p>At the command prompt, enter: <span class="codefrag">set ANT_HOME=C:/apache-ant-1.6.2</span> - -</p> -<p>At the command prompt, enter: <span class="codefrag">set PATH=%PATH%;C:/apache-ant-1.6.2/bin;C:/jdk1.5.0/bin</span> +<p>cd to the directory where <span class="codefrag">beehiveUser.cmd</span> resides (= the top level directory of the Beehive distribution). Throughout this tutorial, this directory will be refered to as BEEHIVE_HOME.</p> +<p>At the command prompt, enter: <span class="codefrag">beehiveUser.cmd</span> </p> <p>Leave the command shell open to use throughout the tutorial</p> </div> -<a name="N100AF"></a><a name="Set+Up+Drop+In+Deployment"></a> -<h4>Set Up Drop In Deployment</h4> +<a name="N100AC"></a><a name="Add+a+Manager+Role+to+Tomcat"></a> +<h4>Add a Manager Role to Tomcat</h4> <div style="margin-left: 0 ; border: 2px"> -<p>Copy the folder <span class="codefrag">[todo]/AnnotatedAxis</span> into the directory <span class="codefrag">C:/jakarta-tomcat-5.0.25/webapps</span>.</p> -<p>Confirm that the following directory structure exists: <span class="codefrag">C:/jakarta-tomcat-5.0.25/webapps/AnnotatedAxis</span> - -</p> -<p>At the command prompt, enter: <span class="codefrag">C:/jakarta-tomcat-5.0.25/bin/startup.bat</span> - -</p> -<p>Visit <a target="_blank" href="http://localhost:8080/AnnotatedAxis/index.html";>http://localhost:8080/AnnotatedAxis/index.html</a> to confirm AnnotatedAxis is installed on Tomcat. If you do not see an information page on AnnotatedAxis, then something is wrong. Ensure that the AnnotatedAxis directory has been copied to C:/jakarta-tomcat-5.0.25/webapps, restart Tomcat, and try again.</p> -<p>At the command prompt, enter: <span class="codefrag">C:/jakarta-tomcat-5.0.25/bin/shutdown.bat</span> - -</p> +<p>Adding the manager role to Tomcat server allows you to run deploy related targets in the Ant file <span class="codefrag">runTomcat.xml</span>. This file is provided as a convenience for managing the Tomcat server.</p> +<pre class="code"><?xml version='1.0' encoding='utf-8'?> +<tomcat-users> + <role rolename="tomcat"/> + <role rolename="role1"/> + <role rolename="manager"/> + <user username="tomcat" password="tomcat" roles="tomcat"/> + <user username="role1" password="tomcat" roles="role1"/> + <user username="both" password="tomcat" roles="tomcat,role1"/> + <user username="manager" password="manager" roles="manager"/> +</tomcat-users> + </pre> +</div> +<a name="N100BE"></a><a name="To+Start+the+Tomcat+Server"></a> +<h4>To Start the Tomcat Server</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>At the command prompt, enter:</p> +<pre class="code">%CATALINA_HOME%\bin\startup.bat</pre> </div> </div> -<a name="N100D9"></a><a name="step_2"></a> -<h3>Step 2: Create a New Web Service</h3> +<a name="N100CE"></a><a name="step_2"></a> +<h3>Step 2: Install the Web Service Template</h3> <div style="margin-left: 0 ; border: 2px"> -<a name="N100DF"></a><a name="Introduction"></a> +<a name="N100D4"></a><a name="Introduction"></a> <h4>Introduction</h4> <div style="margin-left: 0 ; border: 2px"> <p>[todo]</p> -<p> -</p> -<p> -</p> </div> -<a name="N100EF"></a><a name="To+Create+a+JWS+File"></a> -<h4>To Create a JWS File</h4> +<a name="N100DE"></a><a name="Make+a+Project+Folder"></a> +<h4>Make a Project Folder</h4> <div style="margin-left: 0 ; border: 2px"> -<p>In the directory <span class="codefrag">C:/jakarta-tomcat-5.0.25/webapps/AnnotatedAxis</span>, create a folder named <span class="codefrag">ws_tutorial</span>.</p> -<p>In the directory <span class="codefrag">C:/jakarta-tomcat-5.0.25/webapps/AnnotatedAxis/ws_tutorial</span>, create a file named <span class="codefrag">HelloWorld.jws</span>.</p> -<p>Edit HelloWorld.jws so it looks like the following:</p> -<pre class="code"> -import javax.jws.WebService; +<p>On your C: drive, create a directory called <span class="codefrag">beehive_projects</span>.</p> +<p>In the <span class="codefrag">beehive_projects</span> directory, create a directory called ws_tutorial.</p> +<p>Before proceeding, confirm that the following directory structure exists:</p> +<pre class="code">C: + beehive_projects + ws_tutorial</pre> +</div> +<a name="N100F9"></a><a name="To+Copy+the+Web+Services+Application+Template"></a> +<h4>To Copy the Web Services Application Template</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>[todo: what is the wsm template? What is in there?]</p> +<p>Copy the <em>contents</em> of the folder</p> +<pre class="code">BEEHIVE_HOME/samples/wsm-blank</pre> +<p>into</p> +<pre class="code">C:/beehive_projects/ws_tutorial</pre> +<p>It important that you copy the <em>contents</em> of <span class="codefrag">wsm-blank</span>; do not copy the folder <span class="codefrag">wsm-blank</span> itself.</p> +<p>Before proceeding, confirm that the following directory structure exists:</p> +<pre class="code">C: + beehive_projects + ws_tutorial + WEB-INF + happyaxis.jsp + index.html</pre> +</div> +<a name="N1012A"></a><a name="Examine+the+Blank.jws+Web+Service"></a> +<h4>Examine the Blank.jws Web Service</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>Lets examine some web service code. In a text editor of your choice, open the file <span class="codefrag">C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</span>. The file extension 'JWS' stands for Java Web Service. Beehive web services do not require the JWS extension, but it is recommended that you use JWS, especially when working in conjunction Beehive Controls and Page Flows.</p> +<pre class="code">package template; +... import javax.jws.WebMethod; +import javax.jws.WebService; @WebService -public class HelloWorld +public class Blank { - @WebMethod - public String hello() - { - return "Hello, World!"; + public String sayHelloWorld() + { + return "Hello world!"; } -} - </pre> +}</pre> +<p>The web service looks like a familiar Java class, although these two elements may be new to you:</p> +<pre class="code"> + @WebService + @WebMethod +</pre> +<p> +<span class="codefrag">@WebService</span> and <span class="codefrag">@WebMethod</span> are "metadata annotations", a.k.a. "annotations". Annotations allow you to set properties on Java classes and methods. They can be used to generate compile-time artifacts such as configuration files or Java classes (this is how many Beehive Control annotations work) or to determine some runtime behavior (this is how Beehive Web Service annotations work). <span class="codefrag">@WebService</span> annotates (or "decorates") the class Blank: this tells the runtime that Blank is a web service that listens for SOAP messages and responds in kind. <span class="codefrag">@WebMethod</span> annotates the method sayHelloWorld(): this tells the runtime that the method can be invoked over the web.</p> </div> -<a name="N10110"></a><a name="Test+the+Web+Service%3A+URL+Invocation+of+the+web+service"></a> -<h4>Test the Web Service: URL Invocation of the web service</h4> +<a name="N10152"></a><a name="Copy+Runtime+JARs%2C+Compile%2C+and+Deploy+the+Web+Service"></a> +<h4>Copy Runtime JARs, Compile, and Deploy the Web Service</h4> <div style="margin-left: 0 ; border: 2px"> -<p>In this step you will test the web service by generating a WSDL for the web service....[todo: explain what a WSDL is]</p> -<p>At the command prompt, enter: <span class="codefrag">C:/jakarta-tomcat-5.0.25/bin/startup.bat</span> - -</p> -<p>Open a browser, and enter the following URL in the browser's address bar: <a target="_blank" href="http://localhost:8080/AnnotatedAxis/ws_tutorial/HelloWorld.jws?wsdl";>http://localhost:8080/AnnotatedAxis/ws_tutorial/HelloWorld.jws?wsdl</a> - -</p> -<p>The URL above will show the web service WSDL file.</p> -<p>Enter the following URL in the browser address bar: <a target="_blank" href="http://localhost:8080/AnnotatedAxis/HelloWorld.jws?method=sayHello";>http://localhost:8080/AnnotatedAxis/HelloWorld.jws?method=sayHello</a> - -</p> +<p>In this step you will copy the runtime jars to your web service, copile the web service, and deploy it to Tomcat, all in one step.</p> +<p>Run the following Ant command:</p> +<pre class="code">ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml -Dwebapp.dir=C:\beehive_projects\ws_tutorial -Dcontext.path=ws_tutorial deploy.wsm.webapp.runtime build.webapp deploy</pre> +</div> +<a name="N10164"></a><a name="To+Run+the+Web+Service+Provided+in+the+Template"></a> +<h4>To Run the Web Service Provided in the Template</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>Visit the index.jsp page: <a target="_blank" href="http://localhost:8080/ws_tutorial/index.jsp";>http://localhost:8080/ws_tutorial/index.jsp</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()" to see a SOAP response from the web service's sayHelloWorld() method.</p> </div> </div> -<a name="N10132"></a><a name="step_3"></a> -<h3>Step 3: Add a Parameter to the hello Method</h3> +<a name="N1017C"></a><a name="step_3"></a> +<h3>Step 3: Add a Parameterized Method to the Web Service</h3> <div style="margin-left: 0 ; border: 2px"> -<a name="N1013B"></a><a name="Edit+the+JWS+File"></a> +<a name="N10182"></a><a name="Edit+the+JWS+File"></a> <h4>Edit the JWS File</h4> <div style="margin-left: 0 ; border: 2px"> <p></p> -<p></p> -<pre class="code"> -import javax.jws.WebService; +<p>Edit the file <span class="codefrag">C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</span> so it appears as follows.</p> +<pre class="code">package template; +... import javax.jws.WebMethod; +import javax.jws.WebService; import javax.jws.WebParam; @WebService -public class HelloWorld +public class Blank { - @WebMethod - public String hello() - { - return "Hello, World!"; + public String sayHelloWorld() + { + return "Hello world!"; } - + @WebMethod public String sayHello( @WebParam(name="greetee") String greetee ) { - if( greetee.equals("") ) - { greetee = "World"; } + if( greetee.equals("") ) + { greetee = "World"; } - return "Hello, " + greetee + "!"; + return "Hello, " + greetee + "!"; } -} - </pre> +}</pre> +<p>The <span class="codefrag">@WebParam</span> you just added lets you pass a String parameter to the method over the web. The <span class="codefrag">name="greetee"</span> attribute is optional. If you do not explicitly specify a <span class="codefrag">name</span> attribute, the parameter will take the default name <span class="codefrag">str0</span> [<--- todo: verify].</p> </div> -<a name="N1014B"></a><a name="Test+the+Web+Service"></a> -<h4>Test the Web Service</h4> +<a name="N101A5"></a><a name="Compile+and+Redeploy+the+Web+Service"></a> +<h4>Compile and Redeploy the Web Service</h4> <div style="margin-left: 0 ; border: 2px"> -<p> - -<a target="_blank" href="http://localhost:8080/AnnotatedAxis/HelloWorld.jws?method=sayHello";>http://localhost:8080/AnnotatedAxis/HelloWorld.jws?method=sayHello</a> - -</p> +<p>At the command prompt, enter the following Ant command:</p> +<pre class="code">ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml -Dwebapp.dir=C:\beehive_projects\ws_tutorial -Dcontext.path=ws_tutorial build.webapp redeploy</pre> +<p>This Ant command compiles the app, undeploys it, and then deploys it. Calling <span class="codefrag">ant ... redeploy</span> is equivalent to calling <span class="codefrag">ant ... undeploy deploy</span>.</p> +</div> +<a name="N101BD"></a><a name="Test+the+Parameterized+Method"></a> +<h4>Test the Parameterized Method</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>Enter the following URL in the address bar of your browser. </p> +<p>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon</p> +<p>The following SOAP response appears in the browser:</p> +<pre class="code"><soapenv:Envelope> + <soapenv:Body> + <sayHelloResponse> + <ns1:result>Hello, Moon!</ns1:result> + </sayHelloResponse> + </soapenv:Body> +</soapenv:Envelope> +</pre> </div> </div> - <!--<section id="step_4"> - <title>Step 4: Submitting Data</title> - <section> - <title>To Create a Submission Form</title> - <p>Edit the file <code>C:/beehive-0.4/trunk/installed/jakarta-tomcat-5.0.25/webapps/pageflow_tutorial/page2.jsp</code> so it appears as follows.</p> - <source><![CDATA[ -<%@ page language="java" contentType="text/html;charset=UTF-8"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0"; prefix="netui-data"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0"; prefix="netui-template"%> -<netui:html> - <head> - <title>page2.jsp</title> - <netui:base/> - </head> - <netui:body> - <p> - Welcome to page2.jsp! - </p> - <p> - <netui:form action="processData"> - <p>Name:<netui:textBox dataSource="actionForm.name"/> - <p>Age:<netui:textBox dataSource="actionForm.age"/> - <p><netui:button type="submit">Submit</netui:button> - </netui:form> - </p> - </netui:body> -</netui:html> - ]]></source> - </section> - <section> - <title>To Edit the Controller File to Handle the Submitted Data</title> - <p>Open the file <code>C:/beehive-0.4/trunk/installed/jakarta-tomcat-5.0.25/webapps/pageflow_tutorial/Controller.jpf</code> - </p> - <p>Edit Controller.jpf so it appears as follows.</p> - <source><![CDATA[ -import org.apache.beehive.netui.pageflow.Forward; -import org.apache.beehive.netui.pageflow.PageFlowController; -import org.apache.beehive.netui.pageflow.annotations.Jpf; -import org.apache.beehive.netui.pageflow.FormData; - [EMAIL PROTECTED] -public class Controller extends PageFlowController + +<a name="N101D3"></a><a name="Step+4%3A+Add+a+Non-Web+Invokable+Method"></a> +<h3>Step 4: Add a Non-Web Invokable Method</h3> +<div style="margin-left: 0 ; border: 2px"> +<p>Edit the file <span class="codefrag">C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</span> so it appears as follows.</p> +<pre class="code">package template; +... +import javax.jws.WebMethod; +import javax.jws.WebService; +import javax.jws.WebParam; + [EMAIL PROTECTED] +public class Blank { - @Jpf.Action( - forwards={ - @Jpf.Forward(name="success", path="index.jsp") - } - ) - public Forward begin() - { - return new Forward("success"); + @WebMethod + public String sayHelloWorld() + { + return "Hello world!"; } - @Jpf.Action( - forwards={ - @Jpf.Forward(name="success", path="page2.jsp") - } - ) - public Forward toPage2() + @WebMethod + public String sayHello( @WebParam(name="greetee") String greetee ) { - return new Forward("success"); + + if( greetee.equals("") ) + { greetee = "World"; } + + return "Hello, " + greetee + "!"; + } - @Jpf.Action( - forwards = { - @Jpf.Forward(name = "success", path = "showData.jsp") - } - ) - public Forward processData(ProcessDataForm form) + public String sayNothingOverTheWeb() { - System.out.println("Name: " + form.name); - System.out.println("Age: " + form.age); - return new Forward("success"); + return "Not for for Web consumption!"; + } +} +</pre> +<p>Note that the method added, sayNothingOverTheWeb(), does not have the annotation @WebMethod, indicating that it cannot be invoked by SOAP messages over the web.</p> +<a name="N101E7"></a><a name="Compile+and+Redeploy+the+Web+Service-N101D9"></a> +<h4>Compile and Redeploy the Web Service</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>At the command prompt, enter the following Ant command:</p> +<pre class="code">ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml -Dwebapp.dir=C:\beehive_projects\ws_tutorial -Dcontext.path=ws_tutorial build.webapp redeploy</pre> +<p>This Ant command compiles the app, undeploys it, and then deploys it. Calling <span class="codefrag">ant ... redeploy</span> is equivalent to calling <span class="codefrag">ant ... undeploy deploy</span>.</p> +</div> +<a name="N101FF"></a><a name="To+Test+the+Non-Web+Invokable+Method"></a> +<h4>To Test the Non-Web Invokable Method</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>Enter the following URL in the address bar of your browser. </p> +<p>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayNothingOverTheWeb</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> +<pre class="code"><soapenv:Envelope> + <soapenv:Body> + <soapenv:Fault> + <faultcode>ns1:Client</faultcode> + <faultstring>No such operation 'sayNothingOverTheWeb'</faultstring> + <detail> + <ns2:hostname>[your machine name]</ns2:hostname> + </detail> + </soapenv:Fault> + </soapenv:Body> +</soapenv:Envelope> </pre> +</div> +<a name="N10214"></a><a name="Step+5%3A+Change+the+SOAP+Style"></a> +<h4>Step 5: Change the SOAP Style</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>The default SOAP style for JSR-181 web services is DOC-literal. In this step you will change the style to RPC-encoded.</p> +<p>Edit the file <span class="codefrag">C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</span> so it appears as follows.</p> +<pre class="code">package template; +... +import javax.jws.WebMethod; +import javax.jws.WebService; +import javax.jws.WebParam; +import javax.jws.soap.SOAPBinding; + [EMAIL PROTECTED] [EMAIL PROTECTED](style = SOAPBinding.Style.RPC, use = SOAPBinding.Use.ENCODED) +public class Blank +{ + @WebMethod + public String sayHelloWorld() + { + return "Hello world!"; } - public static class ProcessDataForm extends FormData + @WebMethod + public String sayHello( @WebParam(name="greetee") String greetee ) { - private int age; - private String name; + + if( greetee.equals("") ) + { greetee = "World"; } + + return "Hello, " + greetee + "!"; + + } - public void setName(String name) - { - this.name = name; - } - - public String getName() - { - return this.name; - } - - public void setAge(int age) - { - this.age = age; - } - - public int getAge() - { - return this.age; - } + public String sayNothingOverTheWeb() + { + return "Not for for Web consumption!"; } -} - ]]></source> - </section> - <section> - <title>Compile the Page Flow</title> - <p>Open a command shell.</p> - <p>At the command prompt, enter: <code>set JAVA_HOME=C:\jdk1.5.0</code> - </p> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk</code> - </p> - <p>At the command prompt, enter: <code>beehiveEnv.cmd</code> - </p> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk\test\ant</code> - </p> - <p>At the command prompt, enter: <code>ant -f buildWebapp.xml build.webapp -Dwebapp.dir=C:\beehive-0.4\trunk\installed\jakarta-tomcat-5.0.25\webapps\pageflow_tutorial</code> - </p> - </section> - <section> - <title>To Start the Tomcat Server</title> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk\installed\jakarta-tomcat-5.0.25\bin</code> - </p> - <p>At the command prompt, enter: <code>startup.bat</code> - </p> - <p>Leave this command shell open, so that you can stop and restart Tomcat when necessary.</p> - </section> - <section> - <title>To Test the Page Flow Web Application</title> - <p>Open a web browser and enter the following in the address bar: <code>http://localhost:8080/pageflow_tutorial</code> - </p> - <p>You will be directed to the index.jsp page.</p> - <p>Click the link.</p> - <p>You will be directed to page2.jsp.</p> - </section> - <section> - <title>Shutdown Tomcat Server</title> - <p>At the command prompt, enter: <code>shutdown.bat</code> - </p> - </section> - </section> - <section id="step_5"> - <title>Step 5: Processing and Displaying Data</title> - <section> - <title>To Process the Submitted Data</title> - <p>Edit the processData method in the Controller.jpf file so it appears as follows. Code to add appears in red.</p> - <source><![CDATA[ [EMAIL PROTECTED]( - forwards = { - @Jpf.Forward( name = "success", path = "showData.jsp" ) - } -) -public Forward processData( ProcessDataForm form ) -{ - System.out.println("Name: " + form.name); - System.out.println("Age: " + form.age); - getRequest().setAttribute("data", form); - return new Forward("success"); -} - ]]></source> - </section> - <section> - <title>To Create a JSP Page to Display Submitted Data</title> - <p>Create a file named displayData.jsp in the directory [TOMCAT_HOME]/directory/pageflow_tutorial. Edit showData.jsp so it appears as follows.</p> - <source><![CDATA[ -<%@ page language="java" contentType="text/html;charset=UTF-8"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0"; prefix="netui-data"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0"; prefix="netui-template"%> -<netui:html> - <head> - <title>showData.jsp</title> - <netui:base/> - </head> - <netui:body> - <p>Name:<netui:span value="${requestScope.data.name}"/> - <p>Age:<netui:span value="${requestScope.data.age}"/> - </netui:body> -</netui:html> - ]]></source> - </section> - <section> - <title>Compile the Page Flow</title> - <p>Open a command shell.</p> - <p>At the command prompt, enter: <code>set JAVA_HOME=C:\jdk1.5.0</code> - </p> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk</code> - </p> - <p>At the command prompt, enter: <code>beehiveEnv.cmd</code> - </p> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk\test\ant</code> - </p> - <p>At the command prompt, enter: <code>ant -f buildWebapp.xml build.webapp -Dwebapp.dir=C:\beehive-0.4\trunk\installed\jakarta-tomcat-5.0.25\webapps\pageflow_tutorial</code> - </p> - </section> - <section> - <title>To Start the Tomcat Server</title> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk\installed\jakarta-tomcat-5.0.25\bin</code> - </p> - <p>At the command prompt, enter: <code>startup.bat</code> - </p> - <p>Leave this command shell open, so that you can stop and restart Tomcat when necessary.</p> - </section> - <section> - <title>To Test the Page Flow Web Application</title> - <p>Open a web browser and enter the following in the address bar: <code>http://localhost:8080/pageflow_tutorial</code> - </p> - <p>You will be directed to the index.jsp page.</p> - <p>Click the link.</p> - <p>You will be directed to page2.jsp.</p> - </section> - <section> - <title>Shutdown Tomcat Server</title> - <p>At the command prompt, enter: <code>shutdown.bat</code> - </p> - </section> - </section> - <section id="summary"> - <title>Summary: Page Flow Tutorial</title> - <p>This tutorial introduced you to the basics of building web applications with Beehive Page Flows.</p> - <p>Concepts and Tasks Introduced in This Tutorial</p> - <p>[todo: more detailed summary]</p> - </section> - --> +}</pre> +<a name="N10228"></a><a name="Compile+and+Redeploy+the+Web+Service-N10217"></a> +<h5>Compile and Redeploy the Web Service</h5> +<div style="margin-left: 0 ; border: 2px"> +<p>At the command prompt, enter the following Ant command:</p> +<pre class="code">ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml -Dwebapp.dir=C:\beehive_projects\ws_tutorial -Dcontext.path=ws_tutorial build.webapp redeploy</pre> +</div> +<a name="N10237"></a><a name="To+Test+the+Non-Web+Invokable+Method-N10225"></a> +<h5>To Test the Non-Web Invokable Method</h5> +<div style="margin-left: 0 ; border: 2px"> +<p>Enter the following URL in the address bar of your browser. </p> +<p>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHelloWorld</p> +<p>The following SOAP response appears in the browser. Compare the RPC style below with the DOC style above.</p> +<pre class="code"><soapenv:Envelope> + <soapenv:Body> + <sayHelloResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> + <ns1:result xsi:type="xsd:string">Hello, Moon!</ns1:result> + </sayHelloResponse> + </soapenv:Body> +</soapenv:Envelope></pre> +</div> +</div> +</div> <div class="attribution"></div> </div> Modified: incubator/beehive/site/src/documentation/content/xdocs/wsm/sample_AddressBook.xml ============================================================================== --- incubator/beehive/site/src/documentation/content/xdocs/wsm/sample_AddressBook.xml (original) +++ incubator/beehive/site/src/documentation/content/xdocs/wsm/sample_AddressBook.xml Fri Nov 5 15:40:49 2004 @@ -21,7 +21,7 @@ <li>J2SE 5</li> <li>Ant 1.6.2</li> <li>junit.jar (v3.8.1 or later)</li> - <li>derby.jar (for EmployeeWS only)</li> + <li>derby_46005.jar (for EmployeeWS only)</li> </ul> </section> <section> @@ -47,8 +47,8 @@ </section> <p>Download junit.jar from <link href="http://prdownloads.sourceforge.net/junit/junit3.8.1.zip?download";>http://prdownloads.sourceforge.net/junit/junit3.8.1.zip?download</link> </p> <p> Copy <code>junit.jar</code> to <code>ANT_HOME/lib</code>.</p> - <p> Download derby.jar from <link href="http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP";>http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP</link>.</p> - <p> Copy <code>derby.jar</code> to <code>BEEHIVE_HOME/samples/EmployeeWS/WEB-INF/lib</code>.</p> + <p> Download derby_46005.jar from <link href="http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP";>http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP</link>.</p> + <p> Copy <code>derby_46005.jar</code> to <code>BEEHIVE_HOME/samples/EmployeeWS/WEB-INF/lib</code>.</p> <section> <title>Setting up the Server</title> <p> Modified: incubator/beehive/site/src/documentation/content/xdocs/wsm/tutorial_wsm.xml ============================================================================== --- incubator/beehive/site/src/documentation/content/xdocs/wsm/tutorial_wsm.xml (original) +++ incubator/beehive/site/src/documentation/content/xdocs/wsm/tutorial_wsm.xml Fri Nov 5 15:40:49 2004 @@ -21,361 +21,311 @@ <section id="step1"> <title>Step 1: Begin the Web Service Tutorial</title> <section> - <title>Download and Install JDK5</title> - <p>If you do not have JDK5 installed on your machine, visit <fork href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</fork> and download and install the latest version.</p> + <title>To Download and Install J2SE5</title> + <p>If you do not have J2SE5 installed, visit <fork href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</fork>. + </p> + <p>Download and install the latest version of J2SE5.</p> </section> <section> - <title>Install ANT 1.6.2</title> - <p>If you do not have Ant 1.6.2 installed on your machine, visit <fork href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip</fork> + <title>To Install ANT 1.6.2</title> + <p>If you do not have Ant 1.6.2 installed, visit <fork href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip</fork>. </p> - <p>After download is complete, unzip the file <code>apache-ant-1.6.2-bin.zip</code> into your C: drive.</p> - <p>After the file has unzipped, confirm that the following directory structure exists: <code>C:/apache-ant-1.6.2</code>.</p> + <p>Download the ZIP file and unzip it on your machine.</p> </section> <section> - <title>Download and Install Tomcat 5</title> - <p>If you do not have Tomcat 5 installed on your machine, visit <fork href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip</fork> and download the ZIP file.</p> - <p>Unzip jakarta-tomcat-5.0.25.zip into the C: drive.</p> - <p>After the unzip is complete, confirm that the following directory exists: <code>C:/jakarta-tomcat-5.0.25</code>.</p> - <p/> + <title>To Download and Install Tomcat 5</title> + <p>If you do not have Tomcat 5 installed, visit <fork href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip</fork> + </p> + <p>Download the ZIP file and unzip it on your machine.</p> </section> <section> - <title>Download and Install a Beehive Binary Distribution</title> + <title>To Download and Install a Beehive Binary Distribution</title> <p>Visit [todo: distribution download link] and download the latest binary distribution of Beehive.</p> - <p> Create a directory called <code>beehive-0.4</code> on your C: drive. This directory will store the Beehive distribution JARs and all of your Beehive projects.</p> - <p>Unzip the distribution JAR into <code>C:/beehive-0.4</code> - </p> + <p>Unzip the distribution file on your machine</p> </section> <section> - <title>Set up the Development Environment</title> + <title>To Set up the Development Environment</title> + <p>Open the directory where you installed the Beehive distribution. Open the file <code>beehiveUser.cmd</code> in a text editor. Edit <code>beehiveUser.cmd</code> to fit your local environment. The following environmental variables must be set to the appropriate paths on your machine: <code>BEEHIVE_HOME</code>, <code>JAVA_HOME</code>, <code>ANT_HOME</code>, and <code>CATALINA_HOME</code>. The following example shows how to edit <code>beehiveUser.cmd</code> for a typical environment.</p> + <source>REM the root of Beehive distribution +set BEEHIVE_HOME=C:\beehive-alpha + +REM location of a JDK +set JAVA_HOME=C:\jdk1.5.0 + +REM location of Ant +set ANT_HOME=C:\apache-ant-1.6.2 + +REM location of Tomcat +set CATALINA_HOME=C:\jakarta-tomcat-5.0.25</source> + <p>When you finished editing <code>beehiveUser.cmd</code>, save and close the file.</p> <p>Open a command shell.</p> - <p>At the command prompt, enter: <code>set JAVA_HOME=C:/jdk1.5.0</code> - </p> - <p> Note: if you have JDK5 installed in a different directory, set JAVA_HOME to that location.</p> - <p>At the command prompt, enter: <code>set CATALINA_HOME=C:/jakarta-tomcat-5.0.25</code> - </p> - <p>At the command prompt, enter: <code>set ANT_HOME=C:/apache-ant-1.6.2</code> - </p> - <p>At the command prompt, enter: <code>set PATH=%PATH%;C:/apache-ant-1.6.2/bin;C:/jdk1.5.0/bin</code> + <p>cd to the directory where <code>beehiveUser.cmd</code> resides (= the top level directory of the Beehive distribution). Throughout this tutorial, this directory will be refered to as BEEHIVE_HOME.</p> + <p>At the command prompt, enter: <code>beehiveUser.cmd</code> </p> <p>Leave the command shell open to use throughout the tutorial</p> </section> <section> - <title>Set Up Drop In Deployment</title> - <p>Copy the folder <code>[todo]/AnnotatedAxis</code> into the directory <code>C:/jakarta-tomcat-5.0.25/webapps</code>.</p> - <p>Confirm that the following directory structure exists: <code>C:/jakarta-tomcat-5.0.25/webapps/AnnotatedAxis</code> - </p> - <p>At the command prompt, enter: <code>C:/jakarta-tomcat-5.0.25/bin/startup.bat</code> - </p> - <p>Visit <fork href="http://localhost:8080/AnnotatedAxis/index.html";>http://localhost:8080/AnnotatedAxis/index.html</fork> to confirm AnnotatedAxis is installed on Tomcat. If you do not see an information page on AnnotatedAxis, then something is wrong. Ensure that the AnnotatedAxis directory has been copied to C:/jakarta-tomcat-5.0.25/webapps, restart Tomcat, and try again.</p> - <p>At the command prompt, enter: <code>C:/jakarta-tomcat-5.0.25/bin/shutdown.bat</code> - </p> + <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> + <source><![CDATA[<?xml version='1.0' encoding='utf-8'?> +<tomcat-users> + <role rolename="tomcat"/> + <role rolename="role1"/> + <role rolename="manager"/> + <user username="tomcat" password="tomcat" roles="tomcat"/> + <user username="role1" password="tomcat" roles="role1"/> + <user username="both" password="tomcat" roles="tomcat,role1"/> + <user username="manager" password="manager" roles="manager"/> +</tomcat-users> + ]]></source> + </section> + <section> + <title>To Start the Tomcat Server</title> + <p>At the command prompt, enter:</p> + <source>%CATALINA_HOME%\bin\startup.bat</source> </section> </section> <section id="step_2"> - <title>Step 2: Create a New Web Service</title> + <title>Step 2: Install the Web Service Template</title> <section> <title>Introduction</title> <p>[todo]</p> - <p> </p> - <p> </p> </section> <section> - <title>To Create a JWS File</title> - <p>In the directory <code>C:/jakarta-tomcat-5.0.25/webapps/AnnotatedAxis</code>, create a folder named <code>ws_tutorial</code>.</p> - <p>In the directory <code>C:/jakarta-tomcat-5.0.25/webapps/AnnotatedAxis/ws_tutorial</code>, create a file named <code>HelloWorld.jws</code>.</p> - <p>Edit HelloWorld.jws so it looks like the following:</p> - <source><![CDATA[ -import javax.jws.WebService; + <title>Make a Project Folder</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>[todo: what is the wsm template? What is in there?]</p> + <p>Copy the <em>contents</em> of the folder</p> + <source>BEEHIVE_HOME/samples/wsm-blank</source> + <p>into</p> + <source>C:/beehive_projects/ws_tutorial</source> + <p>It 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>Before proceeding, confirm that the following directory structure exists:</p> + <source>C: + beehive_projects + ws_tutorial + WEB-INF + happyaxis.jsp + index.html</source> + </section> + <section> + <title>Examine the Blank.jws Web Service</title> + <p>Lets examine some web service code. In a text editor of your choice, open the file <code>C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</code>. The file extension 'JWS' stands for Java Web Service. Beehive web services do not require the JWS extension, but it is recommended that you use JWS, especially when working in conjunction Beehive Controls and Page Flows.</p> + <source><![CDATA[package template; +... import javax.jws.WebMethod; +import javax.jws.WebService; @WebService -public class HelloWorld +public class Blank { - @WebMethod - public String hello() - { - return "Hello, World!"; + public String sayHelloWorld() + { + return "Hello world!"; } -} - ]]></source> +}]]></source> +<p>The web service looks like a familiar Java class, although these two elements may be new to you:</p> +<source> + @WebService + @WebMethod +</source> +<p><code>@WebService</code> and <code>@WebMethod</code> are "metadata annotations", a.k.a. "annotations". Annotations allow you to set properties on Java classes and methods. They can be used to generate compile-time artifacts such as configuration files or Java classes (this is how many Beehive Control annotations work) or to determine some runtime behavior (this is how Beehive Web Service annotations work). <code>@WebService</code> annotates (or "decorates") the class Blank: this tells the runtime that Blank is a web service that listens for SOAP messages and responds in kind. <code>@WebMethod</code> annotates the method sayHelloWorld(): this tells the runtime that the method can be invoked over the web.</p> </section> <section> - <title>Test the Web Service: URL Invocation of the web service</title> - <p>In this step you will test the web service by generating a WSDL for the web service....[todo: explain what a WSDL is]</p> - <p>At the command prompt, enter: <code>C:/jakarta-tomcat-5.0.25/bin/startup.bat</code> - </p> - <p>Open a browser, and enter the following URL in the browser's address bar: <fork href="http://localhost:8080/AnnotatedAxis/ws_tutorial/HelloWorld.jws?wsdl";>http://localhost:8080/AnnotatedAxis/ws_tutorial/HelloWorld.jws?wsdl</fork> - </p> - <p>The URL above will show the web service WSDL file.</p> - <p>Enter the following URL in the browser address bar: <fork href="http://localhost:8080/AnnotatedAxis/HelloWorld.jws?method=sayHello";>http://localhost:8080/AnnotatedAxis/HelloWorld.jws?method=sayHello</fork> - </p> + <title>Copy Runtime JARs, Compile, and Deploy the Web Service</title> + <p>In this step you will copy the runtime jars to your web service, copile the web service, and deploy it to Tomcat, all in one step.</p> + <p>Run the following Ant command:</p> + <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml -Dwebapp.dir=C:\beehive_projects\ws_tutorial -Dcontext.path=ws_tutorial deploy.wsm.webapp.runtime build.webapp deploy</source> + </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.jsp";>http://localhost:8080/ws_tutorial/index.jsp</fork>.</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()" to see a SOAP response from the web service's sayHelloWorld() method.</p> </section> </section> <section id="step_3"> - <title>Step 3: Add a Parameter to the <code>hello</code> Method</title> + <title>Step 3: Add a Parameterized Method to the Web Service</title> <section> <title>Edit the JWS File</title> <p/> - <p/> - <source><![CDATA[ -import javax.jws.WebService; + <p>Edit the file <code>C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</code> so it appears as follows.</p> + <source><![CDATA[package template; +... import javax.jws.WebMethod; +import javax.jws.WebService; import javax.jws.WebParam; @WebService -public class HelloWorld +public class Blank { - @WebMethod - public String hello() - { - return "Hello, World!"; + public String sayHelloWorld() + { + return "Hello world!"; } - + @WebMethod public String sayHello( @WebParam(name="greetee") String greetee ) { - if( greetee.equals("") ) - { greetee = "World"; } + if( greetee.equals("") ) + { greetee = "World"; } - return "Hello, " + greetee + "!"; + return "Hello, " + greetee + "!"; } -} - ]]></source> +}]]></source> +<p>The <code>@WebParam</code> you just added lets you pass a String parameter to the method over the web. The <code>name="greetee"</code> attribute is optional. If you do not explicitly specify a <code>name</code> attribute, the parameter will take the default name <code>str0</code> [<--- todo: verify].</p> </section> <section> - <title>Test the Web Service</title> - <p> - <fork href="http://localhost:8080/AnnotatedAxis/HelloWorld.jws?method=sayHello";>http://localhost:8080/AnnotatedAxis/HelloWorld.jws?method=sayHello</fork> - </p> + <title>Compile and Redeploy the Web Service</title> + <p>At the command prompt, enter the following Ant command:</p> + <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml -Dwebapp.dir=C:\beehive_projects\ws_tutorial -Dcontext.path=ws_tutorial build.webapp redeploy</source> + <p>This Ant command compiles the app, undeploys it, and then deploys it. Calling <code>ant ... redeploy</code> is equivalent to calling <code>ant ... undeploy deploy</code>.</p> + </section> + <section> + <title>Test the Parameterized Method</title> + <p>Enter the following URL in the address bar of your browser. </p> + <p>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon</p> + <p>The following SOAP response appears in the browser:</p> + <source><![CDATA[<soapenv:Envelope> + <soapenv:Body> + <sayHelloResponse> + <ns1:result>Hello, Moon!</ns1:result> + </sayHelloResponse> + </soapenv:Body> +</soapenv:Envelope> +]]></source> </section> </section> - <!--<section id="step_4"> - <title>Step 4: Submitting Data</title> - <section> - <title>To Create a Submission Form</title> - <p>Edit the file <code>C:/beehive-0.4/trunk/installed/jakarta-tomcat-5.0.25/webapps/pageflow_tutorial/page2.jsp</code> so it appears as follows.</p> - <source><![CDATA[ -<%@ page language="java" contentType="text/html;charset=UTF-8"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0"; prefix="netui-data"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0"; prefix="netui-template"%> -<netui:html> - <head> - <title>page2.jsp</title> - <netui:base/> - </head> - <netui:body> - <p> - Welcome to page2.jsp! - </p> - <p> - <netui:form action="processData"> - <p>Name:<netui:textBox dataSource="actionForm.name"/> - <p>Age:<netui:textBox dataSource="actionForm.age"/> - <p><netui:button type="submit">Submit</netui:button> - </netui:form> - </p> - </netui:body> -</netui:html> - ]]></source> - </section> - <section> - <title>To Edit the Controller File to Handle the Submitted Data</title> - <p>Open the file <code>C:/beehive-0.4/trunk/installed/jakarta-tomcat-5.0.25/webapps/pageflow_tutorial/Controller.jpf</code> - </p> - <p>Edit Controller.jpf so it appears as follows.</p> - <source><![CDATA[ -import org.apache.beehive.netui.pageflow.Forward; -import org.apache.beehive.netui.pageflow.PageFlowController; -import org.apache.beehive.netui.pageflow.annotations.Jpf; -import org.apache.beehive.netui.pageflow.FormData; - [EMAIL PROTECTED] -public class Controller extends PageFlowController + <section> + <title>Step 4: Add a Non-Web Invokable Method</title> + <p>Edit the file <code>C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</code> so it appears as follows.</p> + <source><![CDATA[package template; +... +import javax.jws.WebMethod; +import javax.jws.WebService; +import javax.jws.WebParam; + [EMAIL PROTECTED] +public class Blank { - @Jpf.Action( - forwards={ - @Jpf.Forward(name="success", path="index.jsp") - } - ) - public Forward begin() - { - return new Forward("success"); + @WebMethod + public String sayHelloWorld() + { + return "Hello world!"; } - @Jpf.Action( - forwards={ - @Jpf.Forward(name="success", path="page2.jsp") - } - ) - public Forward toPage2() + @WebMethod + public String sayHello( @WebParam(name="greetee") String greetee ) { - return new Forward("success"); + + if( greetee.equals("") ) + { greetee = "World"; } + + return "Hello, " + greetee + "!"; + } - @Jpf.Action( - forwards = { - @Jpf.Forward(name = "success", path = "showData.jsp") - } - ) - public Forward processData(ProcessDataForm form) + public String sayNothingOverTheWeb() { - System.out.println("Name: " + form.name); - System.out.println("Age: " + form.age); - return new Forward("success"); + return "Not for for Web consumption!"; + } +} +]]></source> + <p>Note that the method added, sayNothingOverTheWeb(), does not have the annotation @WebMethod, indicating that it cannot be invoked by SOAP messages over the web.</p> + <section> + <title>Compile and Redeploy the Web Service</title> + <p>At the command prompt, enter the following Ant command:</p> + <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml -Dwebapp.dir=C:\beehive_projects\ws_tutorial -Dcontext.path=ws_tutorial build.webapp redeploy</source> + <p>This Ant command compiles the app, undeploys it, and then deploys it. Calling <code>ant ... redeploy</code> is equivalent to calling <code>ant ... undeploy deploy</code>.</p> + </section> + <section> + <title>To Test the Non-Web Invokable Method</title> + <p>Enter the following URL in the address bar of your browser. </p> + <p>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayNothingOverTheWeb</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> + <soapenv:Fault> + <faultcode>ns1:Client</faultcode> + <faultstring>No such operation 'sayNothingOverTheWeb'</faultstring> + <detail> + <ns2:hostname>[your machine name]</ns2:hostname> + </detail> + </soapenv:Fault> + </soapenv:Body> +</soapenv:Envelope> ]]></source> + </section> + <section> + <title>Step 5: Change the SOAP Style</title> + <p>The default SOAP style for JSR-181 web services is DOC-literal. In this step you will change the style to RPC-encoded.</p> + <p>Edit the file <code>C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</code> so it appears as follows.</p> + <source><![CDATA[package template; +... +import javax.jws.WebMethod; +import javax.jws.WebService; +import javax.jws.WebParam; +import javax.jws.soap.SOAPBinding; + [EMAIL PROTECTED] [EMAIL PROTECTED](style = SOAPBinding.Style.RPC, use = SOAPBinding.Use.ENCODED) +public class Blank +{ + @WebMethod + public String sayHelloWorld() + { + return "Hello world!"; } - public static class ProcessDataForm extends FormData + @WebMethod + public String sayHello( @WebParam(name="greetee") String greetee ) { - private int age; - private String name; + + if( greetee.equals("") ) + { greetee = "World"; } + + return "Hello, " + greetee + "!"; + + } - public void setName(String name) - { - this.name = name; - } - - public String getName() - { - return this.name; - } - - public void setAge(int age) - { - this.age = age; - } - - public int getAge() - { - return this.age; - } + public String sayNothingOverTheWeb() + { + return "Not for for Web consumption!"; } -} - ]]></source> - </section> - <section> - <title>Compile the Page Flow</title> - <p>Open a command shell.</p> - <p>At the command prompt, enter: <code>set JAVA_HOME=C:\jdk1.5.0</code> - </p> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk</code> - </p> - <p>At the command prompt, enter: <code>beehiveEnv.cmd</code> - </p> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk\test\ant</code> - </p> - <p>At the command prompt, enter: <code>ant -f buildWebapp.xml build.webapp -Dwebapp.dir=C:\beehive-0.4\trunk\installed\jakarta-tomcat-5.0.25\webapps\pageflow_tutorial</code> - </p> - </section> - <section> - <title>To Start the Tomcat Server</title> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk\installed\jakarta-tomcat-5.0.25\bin</code> - </p> - <p>At the command prompt, enter: <code>startup.bat</code> - </p> - <p>Leave this command shell open, so that you can stop and restart Tomcat when necessary.</p> - </section> - <section> - <title>To Test the Page Flow Web Application</title> - <p>Open a web browser and enter the following in the address bar: <code>http://localhost:8080/pageflow_tutorial</code> - </p> - <p>You will be directed to the index.jsp page.</p> - <p>Click the link.</p> - <p>You will be directed to page2.jsp.</p> - </section> - <section> - <title>Shutdown Tomcat Server</title> - <p>At the command prompt, enter: <code>shutdown.bat</code> - </p> - </section> - </section> - <section id="step_5"> - <title>Step 5: Processing and Displaying Data</title> - <section> - <title>To Process the Submitted Data</title> - <p>Edit the processData method in the Controller.jpf file so it appears as follows. Code to add appears in red.</p> - <source><![CDATA[ [EMAIL PROTECTED]( - forwards = { - @Jpf.Forward( name = "success", path = "showData.jsp" ) - } -) -public Forward processData( ProcessDataForm form ) -{ - System.out.println("Name: " + form.name); - System.out.println("Age: " + form.age); - getRequest().setAttribute("data", form); - return new Forward("success"); -} - ]]></source> - </section> - <section> - <title>To Create a JSP Page to Display Submitted Data</title> - <p>Create a file named displayData.jsp in the directory [TOMCAT_HOME]/directory/pageflow_tutorial. Edit showData.jsp so it appears as follows.</p> - <source><![CDATA[ -<%@ page language="java" contentType="text/html;charset=UTF-8"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0"; prefix="netui-data"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> -<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0"; prefix="netui-template"%> -<netui:html> - <head> - <title>showData.jsp</title> - <netui:base/> - </head> - <netui:body> - <p>Name:<netui:span value="${requestScope.data.name}"/> - <p>Age:<netui:span value="${requestScope.data.age}"/> - </netui:body> -</netui:html> - ]]></source> - </section> - <section> - <title>Compile the Page Flow</title> - <p>Open a command shell.</p> - <p>At the command prompt, enter: <code>set JAVA_HOME=C:\jdk1.5.0</code> - </p> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk</code> - </p> - <p>At the command prompt, enter: <code>beehiveEnv.cmd</code> - </p> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk\test\ant</code> - </p> - <p>At the command prompt, enter: <code>ant -f buildWebapp.xml build.webapp -Dwebapp.dir=C:\beehive-0.4\trunk\installed\jakarta-tomcat-5.0.25\webapps\pageflow_tutorial</code> - </p> - </section> - <section> - <title>To Start the Tomcat Server</title> - <p>At the command prompt, enter: <code>cd C:\beehive-0.4\trunk\installed\jakarta-tomcat-5.0.25\bin</code> - </p> - <p>At the command prompt, enter: <code>startup.bat</code> - </p> - <p>Leave this command shell open, so that you can stop and restart Tomcat when necessary.</p> - </section> - <section> - <title>To Test the Page Flow Web Application</title> - <p>Open a web browser and enter the following in the address bar: <code>http://localhost:8080/pageflow_tutorial</code> - </p> - <p>You will be directed to the index.jsp page.</p> - <p>Click the link.</p> - <p>You will be directed to page2.jsp.</p> - </section> - <section> - <title>Shutdown Tomcat Server</title> - <p>At the command prompt, enter: <code>shutdown.bat</code> - </p> - </section> - </section> - <section id="summary"> - <title>Summary: Page Flow Tutorial</title> - <p>This tutorial introduced you to the basics of building web applications with Beehive Page Flows.</p> - <p>Concepts and Tasks Introduced in This Tutorial</p> - <p>[todo: more detailed summary]</p> - </section> - --> +}]]></source> + <section> + <title>Compile and Redeploy the Web Service</title> + <p>At the command prompt, enter the following Ant command:</p> + <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml -Dwebapp.dir=C:\beehive_projects\ws_tutorial -Dcontext.path=ws_tutorial build.webapp redeploy</source> + </section> + <section> + <title>To Test the Non-Web Invokable Method</title> + <p>Enter the following URL in the address bar of your browser. </p> + <p>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHelloWorld</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> + <sayHelloResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/";> + <ns1:result xsi:type="xsd:string">Hello, Moon!</ns1:result> + </sayHelloResponse> + </soapenv:Body> +</soapenv:Envelope>]]></source> + </section> + + </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/>
