Page Tree:

Child pages
  • Collocation Service Contract Description - v0.8-pre-alpha

This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Service Description

The Resource Oriented Architecture (Web Services) interface provides ways for web-based clients to perform collocation queries.


  • Codebase: ${REPOSITORY_ROOT}/sandbox/christensen/trunk/

Note that references to schemas, below, are relative to ${REPOSITORY_ROOT}.


RESTful service methods for invoking the Collocation Service via HTTP.


Base URLs

It is assumed in this documentation that no centrally-run instances of the Bamboo Services Platform will be running after the project ends on 31 March 2013. Therefore, base URLs are assumed to be on a developer's machine, localhost. The base URL with a port number assumes that the BSP is running unsecured; the URL without a port number assumes that security is enforced and Apache Web Server is intercepting and redirecting service calls. Please see the page Identity and Access Management - Authentication and Authorization for context, as well as links to installation and configuration instructions for secured instances of BSP.

Note that ONLY services at v0.9 or greater will run properly in a secured instance of the BSP.

Currently available base URLs:



HTTP Headers and Output Formats

The service supports the following values in the HTTP Accept header:

  • application/xml

Output will be serialized accordingly.

Sample xml Collocation Service Output

Calling Method and Arguments

Perform collocation table query.

GET /collocation/$service/$identifier?q=$query


Adheres to the CollocationServiceResponse schema - ${REPOSITORY_ROOT}/sandbox/christensen/trunk/collocation-service/resource/src/main/resources/CollocationServiceResponse.xsd

Error Responses

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to Philologic Service requests:

Error (Status Code)


Returned When


Bad Request

Request is missing required parameters


Not Found

The requested document does not exist and/or the requested analysis returned no results


Internal Server

A service error occurred



Collocation service API.

Calling methods and arguments

Perform collocation query.
  * Perform collocation query.
  * @param  service name
  * @param  identifier that is specific to service
  * @param  query to perform
  * @throws IllegalArgumentException if invalid argument.
  * @throws IllegalStateException if no collection available.
  * @throws CollocationException if request cannot be completed
  * @return Collocation results
  public abstract Collocation getCollocation(String service, String identifier, String query) throws CollocationException;
  • No labels