Web Service Client Development
|The ITIS Web Services
provide the ability to search and retrieve data from ITIS by providing
access to the data behind the ITIS web
| About Web Services
Web services are a way to provide access to data and processes exposed
via the internet. A web service provider will make these available
through their site using predefined protocols; the most common of these
are SOAP and REST.
Why do we need web services? They allow users to work with information
in the way they want to, which may not be a way we have anticipated.
For example, at the ITIS web site (http://www.itis.gov), site users can
only access data in very formatted ways. If they want other views of
the data, they need to download data files and create their own
database from these files, or screen scrape the returned HTML pages.
Currently there is no other way for the user to obtain custom data.
To provide this functionality without a web service, we'd need to allow
users to access the ITIS database directly, or provide a custom
reporting solution on the ITIS site. Direct access is unacceptable for
many reasons, and even with a custom reporting solution (which would be
costly and difficult to implement), we couldn't anticipate every user's
A web service will provide the appearance of direct database access,
while protecting the data from malicious users. The web service
provides a fixed application programming interface (API) that users can
work with to access data in whatever way they need. APIs can also be
designed to provide data processing functionality, like converting text
between languages, processing numeric data, etc.
Web services are created by writing the APIs and then publishing them
through a web server using a Web Services Toolkit. ITIS web services
were created with the Axis2 toolkit, which is an open source web
service toolkit provided by Apache.org (http://ws.apache.org/axis2/).
It supports both the SOAP and REST protocols.
SOAP is the Simple Object Access Protocol, which is an industry
standard for message packaging. Axis2 takes care of packaging and
unpackaging the SOAP messages for you so you only have to focus on
build and deploying your web service.
REST stands for REpresentational State Transfer. In a REST web service,
each call to the web service returns a piece of information, including
a link to the next transformation or state of the information. For
example, a bowling league service might return league names. With each
name, a link could be returned for the league record, or a list of
league members. Normally, REST access is provided using the HTTP
Once we have the ITIS web service implemented, how do users know what
services it provides? This is done with a document called a Web Service
Description Language (WSDL, pronounced wizz-dul) document.
The WSDL is an XML file containing a list of the services provided and
the interface required for each service. You can use the WSDL to create
a web service or a web service client. Axis2 automatically generates a
WSDL file for your web service if necessary.
You can see the WSDL we'll be using for ITIS at
| Creating A Web Service Client
Clients for a web service are simply code that accesses the service
through the web interface. You could write all the code manually based
on the WSDL file, or even write the code by interpreting or
transforming the returned XML from the web service. However, the web
service packages supply tools to create most of the code you need to
access the web service. While this tool differs from package to
pacvkage, the functionality is similar. Note: Due to a know bug in the
Apache Axis2 generation utility (wsdl2java) which prevents it from
creating compilable code from the ITIS WSDL, we'll be using the Sun
Metro package to create our code.
In order to use these instructions, you will need a Sun Java
Development Kit (JDK, not JRE, Version 1.6 or higher), Apache Ant (V
1.7 or higher), and the Sun Metro package (V 1.2 or higher).
JDK installations are available at (http://java.sun.com/javase/downloads/index.jsp).
Ant installation packages are available at (http://ant.apache.org/bindownload.cgi).
Because Ant and the Java JDK are usually part of a Java development
environment, their installation won't be covered here. The instructions
below assume the javac, java, and ant commands are available from the
command line and working correctly.
JAVA_HOME and ANT_HOME should be set to point to
the Java and Ant installation folders.
Download the metro package from Sun (https://metro.dev.java.net/1.2/)
Change to the folder where you want to install Metro. Execute the Metro
java -jar metro-1_2.jar
Note: The installer
only creates a Metro folder containing the Metro tools and samples. You
can run the installer from any location, then move this folder to your
Set the METRO_HOME environment variable to point to the Metro folder.
Install the Web Service Sample Client
Download the client from the ITIS download site.
Create and/or change to your development folder.
Unzip the sample client zip file.
Change to the client folder:
Create the WebService
Run the classpath script for your system:
You will need a copy of the ITIS Service WSDL file to proceed. One has
been provided as part of this package. To make sure you have the most current
version, you should retrieve it from the ITIS web
Run ant to generate the client, then build the service and test
| Test the WebSvcClient Application
java -cp dist\WSDL_CLient.jar;%CLASSPATH%
java -cp dist/WSDL_CLient.jar:$CLASSPATH
You should see the following output:
This is the ITIS Web Service, providing access to
the data behind www.itis.gov.
The database contains 483,305 scientific names (380,578 of them
valid/accepted) and 109,142 common names.
Full Record Data for TSN 180543
Scientific name: Ursus arctos
TSN: 180543 has Vernacular: Brown
Bear in Language: English
TSN: 180543 has Vernacular: Grizzly
Bear in Language: English
TSN: 180543 has Vernacular: Oso
pardo in Language: Spanish
Taxonomic Rank: Species which is Rank ID: 220
Kingdom: Animalia which is Kingdom ID: 5
The Parent TSN is: 180541
Note: The Full
Record Data can take a number of seconds to return (this
is one of the most time intensive methods in the service).
|Client Code Analysis
The sample client is in the file
src/org/usgs/itis/itis_service/WS_Test.java. The client accesses the
ITIS web service and uses the getDescription(), getFullRecord(),
and searchByCommonName() methods of the service.
As commented in the code, there are four steps to acquiring data from
the web service:
The client simply puts these steps in a main method and uses system.out
to display the returned values. You can, of course, use any type of
Java application to display the returned data, including desktop client
code, server code, JSP code on a web page, etc.
Create an instance of the service. This connects the client to the
Get the port endpoint from the service. There are several endpoints
available, the client uses the Soap1.2 Endpoint. This is most common
and should work for most applications.
Get the data from the port endpoint. This is where you call the web
Use the data. The Metro generated code returns an object containing
the data you requested. To get the actual data values from the object,
you must use getValue().