Read Me

This document covers the compilation and installation of the CHALICE API software.

System Requirements
-------------------
The CHALICE API is a Java application that runs as a Servlet, so the Java Runtime Environment (either Java 5 or Java 6) must be installed first. The CHALICE API also requires a servlet container, either Jetty (http://jetty.codehaus.org/) or Apache Tomcat* (http://tomcat.apache.org) are suitable. For storage of the CHALICE records, a PostgreSQL database is required.



Check out source code
---------------------
Check out the source code from trunk from the CHALICE subversion repository to develop using the latest development code:

    $ svn co https://chalice.svn.sourceforge.net/svnroot/chalice/chalice-api/



Configuration
-------------
The API can be configured via the 'webservice.properties' file. The maxmimum number of returned rows, regular expression to validate the input parameters and a list of email recipients for errors

The CHALICE API database is configured via the 'database.properties' file, where we set the driver, URL, username and password of the database.



Build the CHALICE API
---------------------
Once you checked out the code from subversion repository, change directory to the CHALICE’s root folder and execute the maven build command:

    $ mvn clean install

If the build is succesful you’ll get an output like:

    [INFO] Building war: /chalice-api/target/chalice-1.0.war

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESSFUL
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 9 seconds
    [INFO] Finished at: Mon Nov 08 17:54:27 GMT 2010
    [INFO] Final Memory: 22M/129M
    [INFO] ------------------------------------------------------------------------

Move the output .war file to the Tomcat webapps directory, where it should be deployed automatically. You can use the Tomcat manager web application to start/stop the CHALICE API software. You can also use the startup.* and shutdown.* scripts located into Tomcat’s bin folder.



Using the CHALICE API
---------------------
Queries can be made to the web service can be made as a RESTful HTTP GET request to the server running the servlet container, using parameters to specify the search parameters and return format.  In these examples, we show the web service running on localhost, port 80.

To retrieve a single entry in RDF/XML, the request is simply the identifier number of the entry
to be searched for. For example, to search for the feature number '6', a GET request should
be made to:

    http://localhost/6

To retrieve results in JSON format, the request should be:

    http://localhost/6.json

To search for a list of possible results by name, the following format should be used:

    http://localhost/name/Baschurch
    http://localhost/name/Baschurch.json

To search for results restricted to a specific date range and spatial extent, multiple parameters are required. A start date (year) and an end date (year) separated by a hyphen, followed by the coordinates of the bounding box to search within. These parameters should be separated by forward-slashes as follows:

    /[startdate]-[enddate]/[xmin]/[ymin]/[xmax]/[ymax]

For example:

    http://localhost/1060-1290/-3/53/-2/54