NatureServe Web Services

Code Samples

This page provides simple Java code samples for developers. The samples are meant to focus as tightly as possible on calling a web service and processing the results. As such, no attention is paid to any user interface nuances or other considerations.

Note: If you are simply looking to get some one-off data, you probably need nothing more than your browser. See the sample service calls in the service descriptions for URL's you can play with and adapt to meet your needs.

Setting up Java

The samples are written in Java and have been tested on Java version 1.5 and higher. They definitely do NOT work on 1.4 (released 2002, 'end of life' October 2008), due to Java not bundling the required components in that release. If you experience problems running the samples, this is probably due to a Java version problem. To upgrade, follow the instructions below as if you were newly installing the Java JDK.

If you do not already have the Java JDK (Java Development Kit) on your machine, install it now from the Sun Java SE Downloads page - note that you may have Java, but not the JDK. There may be many download options - choose the latest one which is marked as a JDK. Ignore anything which mentions 'Java SE' or 'Java Runtime Environment' - these do not contain the tools necessary to develop programs.

There are usually options which 'bundle' the JDK with other components - ignore these until you know your way around java. The pure JDK contains everything you will need.

Follow the installation instructions carefully and make sure to update the PATH variable. This step is marked as optional - for our purposes, it is not. It should be set to the full path to the JDK installation /bin subfolder, e.g. C:\Program Files\Java\jdk1.6.0_07\bin. It is difficult to cover all types and flavors of operating systems but, in general:

  • On Windows, go to Control Panel > System (you may have to switch to 'Classic View') >
    Advanced tab > Environment Variables > Select 'Path' from the System Variables panel >
    Edit > Add a semi-colon (;) and then the JDK /bin folder full path to the END of the declaration > OK > OK
Creating a work area

You will need somewhere to work, so create a folder as follows:

  1. Open a 'Command prompt' (Windows - usually under All Programs > Accessories) or a 'Terminal Window' (Linux/Unix/Mac).
  2. Type md nssamples and hit Enter.

This will create a folder called nssamples underneath your 'home'. This makes it very easy to find in the steps that follow.

Running the samples

To run a sample program, the steps are as follows:

  1. Download the sample (e.g. to your work folder.
  2. Open a 'Command prompt' (Windows - usually under All Programs > Accessories) or a 'Terminal Window' (Linux/Unix/Mac).
  3. Go to your working folder by typing cd nssamples and hitting Enter.
  4. Compile the sample by typing javac sample_file_name, e.g. javac, and hitting Enter.
  5. Run the sample by typing java sample_file_name_WITHOUT_extension, e.g. java sample1, and hitting Enter.

Note that this is not the day-to-day developer's way of creating and running Java programs - this is just the simplest to describe and setup. Once you have worked through the samples and decided to work in Java, see the Technical Library for some links to 'Integrated Development Environments' (IDE's), which make the job much easier.


Sample 1 - Get Data (with Java crash course)

Sample 2 - Get Data and Reformat (with XSLT crash course)