Incubator > Beehive
 

EnhancedAddressBookWS Sample

The Sample

The EnhancedAddressBookWS sample uses metadata annotations, has customized annotations properties, and shows exception handling.

Apache Axis provides the automatic client-generation for the web services. Custom unit tests are provided to exercise the webservice methods. The unit tests create the database tables, insert new records, query the database, and finally drop the tables. Use the junit tests as a template for building automatic tests for your own web services

Running the Sample

Requirements for Running the Sample

To run the Sample, you need:

  • Beehive
  • Tomcat 5
  • J2SE 5
  • Ant 1.6.2
  • junit.jar (v3.8.1 or later, details below)

To Set up the Environment

Before proceeding, complete all of the necessary and optional steps in the following topic: Beehive Installation and Setup

Open a command shell and confirm that the following variables have been set:

  • ANT_HOME
  • CATALINA_HOME
  • JAVA_HOME

Also ensure that the following elements are on your PATH:

  • ANT_HOME/bin
  • JAVA_HOME/bin

To Set up the Server

To Copy the Application to a Project Folder (Optional Step)

To keep your Beehive distribution directory pristine, you should copy the application folders to another location before proceeding. The following instructions assume that you have copied the folder

<BeehiveRoot>/samples/wsm-addressbook-enhanced

into the directory C:/beehive_projects, resulting in the following directory structure.

C: 
  beehive_projects 
    wsm-addressbook-enhanced
Note
<BeehiveRoot> refers to the top-level directory of your Beehive installation. A typical value for <BeehiveRoot> would be C:/apache/apache-beehive-1.0.
Note
Strictly speaking, you do not need to copy the wsm-addressbook-enhanced directory to another location. If you wish to leave the wsm-addressbook-enhanced directory in place, in the instructions below you must replace occurrences of the path element C:\beehive_projects with this path element: <BeehiveRoot>\samples.

For example, to build the sample, run the following Ant command:

   ant -f <BeehiveRoot>\samples\wsm-addressbook-enhanced\src\WEB-INF\build.xml clean build

To delete the sample's build directory, run the clean target:

   ant -f <BeehiveRoot>\samples\wsm-addressbook-enhanced\src\WEB-INF\build.xml clean

To Start Tomcat

To start Tomcat, run the following command:

%CATALINA_HOME%\bin\startup.bat

To Download Junit the JAR File

Download the junit ZIP archive from http://prdownloads.sourceforge.net/junit/junit3.8.1.zip?download

Unzip the archive, locate junit.jar, and copy junit.jar to ANT_HOME/lib.

Edit the build.properties Files

In this section you will edit the build.properties file--the files that set the build-related properties for the web service.

Open the file C:/beehive_projects/wsm-addressbook-enhanced/WEB-INF/build.properties in a text editor.

Edit the file so that the beehive.home property points to the top-level folder of your beehive installation. For example, if you beehive installation resides at C:/apache/apache-beehive-1.0, then your build.properties files would appear as follows.

beehive.home=C:/apache/apache-beehive-1.0

To Compile the App

To compile the EnhancedAddressBookWS app, enter the following Ant command.

ant 
  -f C:\beehive_projects\wsm-addressbook-enhanced\WEB-INF\src\build.xml 
  clean 
  build 

Copy and paste version:

ant -f C:\beehive_projects\wsm-addressbook-enhanced\WEB-INF\src\build.xml clean build

The command above creates a WAR file named EnhancedAddressBookWS.war and saves it at C:\beehive_projects.

To deploy the app to Tomcat, run the following command:

copy C:\beehive_projects\EnhancedAddressBookWS.war %CATALINA_HOME%\webapps /Y

To Verify the Deployment

http://localhost:8080/EnhancedAddressBookWS/

To Run the Web Service Client

To generate and run the client, run the following build file.

ant -f C:\beehive_projects\wsm-addressbook-enhanced\WEB-INF\src\build-client.xml

Note that you do not need to run a particular target within the build files client-build.xml. Simply run the Ant command shown above and the client will be generated in WEB-INF/build/generated.

Note
When you compile this app you may see the error messages below.

[wsdl2java] - Unable to find required classes (javax.activation.DataHandler and javax.mail.internet.MimeMultipart). Attachment support is disabled.

[junit] - Unable to find required classes (javax.activation.DataHandler and javax.mail.internet.MimeMultipart). Attachment support is disabled.

You can ignore these error messages, since this sample does not rely on the classes mentioned.

The client consists of JUnit test cases that exercise the contract published in the WSDL. The final result shows the number of successfully passed JUnit tests.

The code generated in /WEB-INF/build/generated/ can be used as a template to write your own client side applications.

Note that the client-build.xml script makes certain assumptions about the Tomcat deployment context path, namely, that the app is deployed on the context path EnhancedAddressBookWS. If the context path is changed from this value, the URL in the build-client.xml file must be adjusted accordingly.