|
Code Samples and Tutorials
Connection to NatureServe Web Services using SOAP and Java
Introduction
NatureServe provides several ways to access their data using Web Services. This tutorial covers how to access the NatureServe species data using SOAP-based Web Services, the Java programming language and the Apache AXIS Web Service framework. It assumes that you have some basic knowledge of what a Web Service is and how to program in Java. If you are interested in accessing the Web Services using the REST front-end, please follow the links to the XSLT tutorial.
One reason to use the SOAP-based interface rather than the REST-based interface to the NatureServe Web Services is that SOAP-based interfaces bind better to object oriented programming languages. A SOAP-based Web Service is formally described by an XML document called a WSDL (Web Service Descriptor Language) and based on this formal description, most object oriented languages can build objects that represent the Web Service. The advantage of this is that you can then deal with a call to a Web Service as though it were a local object and not have to worry about the network communication overhead and the XML parsing - everything is represented as objects in the native programming language. Apache AXIS is an add-on framework to Java that reads WSDL's and compiles them down to Java objects. This tutorial describes how to compile the NatureServe species Web Service WSDL to a set of Java objects and then perform some basic operations using these Java objects.
Software Requirements
In order to work through this tutorial you need to have the following software downloaded and installed:
- Java 1.4 or higher
- Apache AXIS 1.3 or higher
This tutorial assumes that you are working in a Microsoft Windows environment. While this tutorial will work on *nix systems, the exact commands used to create the script to run WSDL2Java will need to be translated to your shell of choice.
Step-by-Step Walkthrough
Step 1: Convert the WSDL to Java objects
Axis provides a tool to compile WSDL's to Java objects called WSDL2Java which takes a WSDL as input and outputs a set of Java objects into a predefined package. The hardest part about using WSDL2Java is setting the class path. The best way to solve this problem is to create a batch file that will set the class path and hide the details of calling WSDL2Java. Here are the steps to create the batch file:
Open Notepad and copy and paste the following text into it:
----- Start Copy Paste Block -----
set AXIS_HOME=w:\natureservices\lib\axis-1_2_1
set CLASSPATH=%CLASSPATH%;%AXIS_HOME\lib\commons-logging-1.0.4.jar
set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\commons-discovery-0.2.jar
set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\axis-1_2_1\lib\wsdl4j-1.5.1.jar
set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\jaxrpc.jar
set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\saaj.jar
set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\axis.jar
java -class path %CLASSPATH% org.apache.axis.wsdl.WSDL2Java -p %1 -s -o %2 %3
---- End Copy Paste Block -----
Now change the location of the AXIS_HOME, the first line, so that it points to where you installed AXIS
Save this file somewhere convenient and name it WSDL2Java.bat
The batch file that has now been created takes in three different parameters:
- The Java package that this should be created in. For this example, it will always be set to org.natureserve.species.soap
- The location where the actual Java objects will be outputted to. For this example, it will always be set to w:\
- The URL that points at the WSDL that is being compiled to Java objects. For this example, and for any time you are compiling the species WSDL, it will be set to https://services.natureserve.org/idd/soap/services/Species?wsdl
The first two parameters should be modified to reflect your environment. The third parameter should be left alone for this tutorial, but if a different service is being accessed, this parameter would also be modified to point to the appropriate WSDL.
- Finally, open a command prompt and run the batch file with the appropriate parameter values. For example: "w:\WSDL2Java.bat org.natureserve.species.soap w:\ https://services.natureserve.org/idd/soap/services/Species?wsdl" This command should produce a lot of output describing what files are created.
Step 2: Test the resulting Java objects
- The goal of this section is to generate a sample program that connects to the species Web Service and retrieves the information about a given species using the species id. Here is the sample code that will be used:
----- Start Sample Code -----
/**
* A simple program that retrieves data about a given species
*/
public class TestSpecies
{
public static void main( String args[] ) throws Exception
{
Species_ServiceLocator locator =
new Species_ServiceLocator();
GlobalSpeciesRequestType request =
new GlobalSpeciesRequestType( "ELEMENT_GLOBAL.2.101805" );
GlobalSpeciesType species =
locator.getSpecies().species( request, "my-developer-token" );
System.out.println( species.getClassification().getNames().
getScientificName().getFormattedName() );
}
}
----- End Sample Code -----
- This sample code is meant to be put in the same package as you compiled the WSDL to Java objects in. This test code makes a request to the species Web Service and then prints out the formatted name of the species that was returned. The sample program can be dissected in the following way:
- Species_ServiceLocator locator = new Species_ServiceLocator(); - This creates the service locator for the species Web Service. The locator is the AXIS object that hides all of the network calls from the user. The locator object is what knows the physical location of the species Web Service.
- GlobalSpeciesRequestType request = new GlobalSpeciesRequestType( "ELEMENT_GLOBAL.2.101805" ); - This creates a request that tells the species Web Service which species you are trying to retrieve information about. In this case, the unique id of the species is passed in.
- GlobalSpeciesType species = locator.getSpecies().species( request, "my-developer-token" ); - This is the line that actually makes the Web Service call and retrieves all of the data. One thing to be careful of in this example is that you use the developer token that was issued to you by NatureServe. If you do not have a token, you can request one here. The GlobalSpeciesType object that results contains all of the species information.
- System.out.println( species.getClassification().getNames().getScientificName().getFormattedName() ); - This line uses the resulting object to retrieve the name of the species that was returned from the Web Service.
Conclusion
This tutorial shows how to use Java and AXIS to make Web Service data available to you in your Java programs. While this tutorial highlights the NatureServe species Web Service, the same technique outlined here can be used to access any Web Service that you have a WSDL for.
|
