More Web Proxy on the site http://driver.im/

Integrated Taxonomic Information System - Web Services Client

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

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

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

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 http://www.itis.gov/ITISWebService/services/ITISService?wsdl

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.

Prerequisites

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.

Install Metro

Download the metro package from Sun (https://javaee.github.io/metro/)

Change to the folder where you want to install Metro and execute the Metro installer.

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 desired location.

Set the METRO_HOME environment variable to point to the Metro folder. For example:
Windows:
set METRO_HOME=c:\metro
Linux:
export METRO_HOME=~/metro

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:
cd WebServiceClient-metro

Create the WebService Client

Run the classpath script for your system:
Windows:
    metro-classpath.cmd
Linux:
    . ./metro-classpath.sh

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

Run ant to generate the client, then build the service and test program:
    ant

Test the WebSvcClient Application

Windows:
java -cp dist\WSDL_CLient.jar;%CLASSPATH% org.usgs.itis.itis_service.WS_Test
Linux:
java -cp dist/WSDL_CLient.jar:$CLASSPATH org.usgs.itis.itis_service.WS_Test

You should see the following output:

Service Description: 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
   Common names:
      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:

Create an instance of the service. This connects the client to the service.
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 service functions.
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().

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.