Beehive Web Service Tutorial
Introduction
This tutorial introduces you to the basic development cycle for Beehive web services. The tutorial assumes that you are working on a Windows machine. But, with a little common sense, it is easy to execute the tutorial on a Unix machine. For example, when you are asked to run the file beehiveUser.cmd, run the file beehiveUser.sh instead.
Tutorial Goals
In this tutorial, you will learn:
- How to create a basic Beehive web service application.
- How to use (JSR 175 and 181) metadata annotations.
- How to deploy and test a web service to Tomcat
Step 1: Begin the Web Service Tutorial
To Set up the Development Environment
Complete all of the necessary and optional steps in the following topic: Beehive Installation and Setup
After completing the instructions, leave the command shell open to use throughout this tutorial.
Before proceding, confirm that you have the following variables set in your shell:
- BEEHIVE_HOME
- ANT_HOME
- JAVA_HOME
- CATALINA_HOME
Also ensure that the following elements are on your PATH:
- ANT_HOME/bin
- JAVA_HOME/bin
To Make a Project Folder Using the Web Service Application Template
On your C: drive, create a directory called beehive_projects.
Copy the folder BEEHIVE_HOME/samples/wsm-blank into C:/beehive_projects.
Rename the folder C:/beehive_projects/wsm-blank as C:/beehive_projects/ws_tutorial
Before proceeding, confirm that the following directory structure exists:
C: beehive_projects ws_tutorial WEB-INF happyaxis.jsp index.html
Edit the build.properties File
In this section you will edit the build.properties file--the file that sets the build-related properties for your web service application.
Open the file C:/beehive_projects/ws_tutorial/WEB-INF/build.properties in a text editor.
Edit the beehive.home property points to the top-level folder of your beehive installation.
Add the line service.name=tutorial (as shown below).
For example, if your beehive installation resides at C:/apache/apache-beehive-1.0, then your build.properties file would appear as follows.
beehive.home=C:/apache/apache-beehive-1.0 service.name=tutorial
To Start the Tomcat Server
At the command prompt, enter:
%CATALINA_HOME%\bin\startup.bat
Step 2: Run the Web Service Template
To Examine the Blank.jws Web Service
You are now ready to compile and run the template web service already included in the project folder--but before we run the web service, let's first look at the code.
In a text editor of your choice, open the file C:/beehive_projects/ws_tutorial/WEB-INF/src/web/Blank.jws.
The file extension .jws stands for Java Web Service. It is important to note that the file Blank.jws is a plain old JAVA source file--nothing more, nothing less. If your were to rename Blank.jws to Blank.java, this tutorial, and any subsequent development beyond this tutorial, would proceed normally. We use the 'JWS' file extension purely as a mnemonic device to help the developer remember what this file is: a Java Web Service file.
The code looks like this:
package web; ... import javax.jws.WebMethod; import javax.jws.WebService; @WebService public class Blank { @WebMethod public String sayHelloWorld(String s) { return "Hello world, " + s + "!"; } }
If you are familiar with Java code, everything probably looks familiar to you, although these two elements may be new:
@WebService @WebMethod
@WebService, @WebMethod, and @WebParam 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).
@WebService 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.
@WebMethod annotates the method sayHelloWorld(): this tells the runtime that the method can be invoked over the web.
To Compile and Deploy the Web Service
You are now ready to compile the web service and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\ws_tutorial\WEB-INF\build.xml -Dto.dir=%CATALINA_HOME%\webapps clean build deploy Copy and Paste version: ant -f C:\beehive_projects\ws_tutorial\WEB-INF\build.xml -Dto.dir=%CATALINA_HOME%\webapps clean build deploy
To Run the Web Service
Visit the index.jsp page: http://localhost:8080/tutorialWS/index.html.
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.
Click the "WSDL" link to see the web service's WSDL.
Click the "sayHelloWorld()" link to see a SOAP response from the web service's sayHelloWorld() method.
Step 3: Add a Parameterized Method to the Web Service
In this step you will add a new method to the web service: a method that accepts in 'IN' parameter.
To Edit the JWS File
Edit the file C:/beehive_projects/ws_tutorial/WEB-INF/src/web/Blank.jws so it appears as follows. Code to add appears in bold type.
package web; ... import javax.jws.WebMethod; import javax.jws.WebService; import javax.jws.WebParam; @WebService public class Blank { @WebMethod public String sayHelloWorld(String s) { return "Hello world, " + s + "!"; } @WebMethod public String sayHelloWorldInParam( @WebParam String greetee ) { if( greetee.equals("") ) { greetee = "World"; } return "Hello, " + greetee + "!"; } }
The @WebParam you just added lets you pass a String parameter to the method over the web.
To Compile and Redeploy the Web Service
To compile the web service and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\ws_tutorial\WEB-INF\build.xml -Dto.dir=%CATALINA_HOME%\webapps clean build deploy Copy and Paste version: ant -f C:\beehive_projects\ws_tutorial\WEB-INF\build.xml -Dto.dir=%CATALINA_HOME%\webapps clean build deploy
To Test the Parameterized Method
Enter the following URL in the address bar of your browser.
http://localhost:8080/tutorialWS/web/Blank.jws?method=sayHelloWorldInParam&greetee=Moon
The following SOAP response appears in the browser:
<soapenv:Envelope> <soapenv:Body> <sayHelloWorldInParamResponse> <ns1:result>Hello, Moon!</ns1:result> </sayHelloWorldInParamResponse> </soapenv:Body> </soapenv:Envelope>
Step 4: Add a Non-Web Invokable Method
To Edit the JWS File
Edit the file C:/beehive_projects/ws_tutorial/WEB-INF/src/web/Blank.jws so it appears as follows. Code to add appears in bold type.
package web; ... import javax.jws.WebMethod; import javax.jws.WebService; import javax.jws.WebParam; @WebService public class Blank { @WebMethod public String sayHelloWorld(String s) { return "Hello world, " + s + "!"; } @WebMethod public String sayHelloWorldInParam( @WebParam String greetee ) { if( greetee.equals("") ) { greetee = "World"; } return "Hello, " + greetee + "!"; } public String sayNothingOverTheWeb() { return "Not for for Web consumption!"; } }
Note that the method added, sayNothingOverTheWeb(), does not have the annotation @WebMethod, indicating that it cannot be invoked by SOAP messages over the web.
To Compile and Redeploy the Web Service
To compile the web service and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\ws_tutorial\WEB-INF\build.xml -Dto.dir=%CATALINA_HOME%\webapps clean build deploy Copy and Paste version: ant -f C:\beehive_projects\ws_tutorial\WEB-INF\build.xml -Dto.dir=%CATALINA_HOME%\webapps clean build deploy
To Test the Non-Web Invokable Method
Enter the following URL in the address bar of your browser.
http://localhost:8080/tutorialWS/web/Blank.jws?method=sayNothingOverTheWeb
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).
<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>
Step 5: Change the SOAP Style
To Edit the JWS File
The default SOAP style for JSR-181 web services is DOC-literal. In this step you will change the style to RPC-encoded.
Edit the file C:/beehive_projects/ws_tutorial/WEB-INF/src/web/Blank.jws so it appears as follows. Code to add appears in bold type.
package web; ... import javax.jws.WebMethod; import javax.jws.WebParam; import javax.jws.WebService; import javax.jws.soap.SOAPBinding; @WebService @SOAPBinding(style = SOAPBinding.Style.RPC, use = SOAPBinding.Use.ENCODED) public class Blank { @WebMethod public String sayHelloWorld(@WebParam(name="name",header=true) String s) { return "Hello world, " + s + "!"; } @WebMethod public String sayHelloWorldInParam( @WebParam String greetee ) { if( greetee.equals("") ) { greetee = "World"; } return "Hello, " + greetee + "!"; } public String sayNothingOverTheWeb() { return "Not for for Web consumption!"; } }
To Compile and Redeploy the Web Service
To compile the web service and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\ws_tutorial\WEB-INF\build.xml -Dto.dir=%CATALINA_HOME%\webapps clean build deploy Copy and Paste version: ant -f C:\beehive_projects\ws_tutorial\WEB-INF\build.xml -Dto.dir=%CATALINA_HOME%\webapps clean build deploy
To Test the SOAP-encoded Style
Enter the following URL in the address bar of your browser.
http://localhost:8080/tutorialWS/web/Blank.jws?method=sayHelloWorldInParam&greetee=Moon
The following SOAP response appears in the browser. Compare the RPC style below with the DOC style above.
<soapenv:Envelope> <soapenv:Body> <sayHelloWorldInParamResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <ns1:result xsi:type="xsd:string">Hello, Moon!</ns1:result> </sayHelloWorldInParamResponse> </soapenv:Body> </soapenv:Envelope>