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
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.
[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.