Incubator > Beehive
 

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>