Elda

An implementation of the Linked Data API

This document is a quick-start for the Epimorphics Ltd implementation, Elda, of the Linked Data API. The Elda runnable-demo jar can be downloaded from its Googlecode downloads page; pick the latest unless you have good reason not to.

A separate document describes Elda's extensions and an introduction to using Elda's code directly rather than bundled as servlets/restlets.

If you want to explore the Elda codebase and have Mercurial installed, you can download the Elda repository:

hg clone https://elda.googlecode.com/hg/ elda  

In the rest of this document, "the Elda jar" means the downloaded standalone demonstration jar.

What is the LDA?

The Linked Data API provides a configurable way to access RDF data using simple RESTful URLs that are translated into queries to a SPARQL endpoint. The API developer (probably you) writes an API spec (in RDF) which specifies how to translate URLs into queries. Elda comes with some pre-built examples which allow you to experiment with the style of query and get started with building your own specs.

Prerequisites

Elda is written in Java (using the Jena RDF toolkit), so you will need Java installed on your system.

The default demonstration setup for Elda uses the data.gov.uk data accessible from the SPARQL endpoint http://services.data.gov.uk/education/sparql. To run the demonstration, you will need to have open web access.

Feedback

Elda aims to provide a complete implementation of the Linked Data API. Problems with Elda should be reported to the linked data API discussion group (note: you will need a google account to use this group).

Current issues can be seen on the Elda issues list .

Getting started

The Elda code is shipped as a single self-unpacking jar, elda-VERSION.jar. You can start it from the command line:

java -jar elda-VERSION.jar
or, if your system permits, by double-clicking on it in your preferred file browser.

In either case, Elda unzips itself from that jar into a new directory, Elda_VERSION, from which it starts itself as a Jetty server running on port 8080.

You should now be able to browse to LDA URIs:

http://localhost:8080/elda/api/education/schools.json

http://localhost:8080/elda/api/education/schools.xml

http://localhost:8080/elda/api/education/schools.html

http://localhost:8080/elda/api/education/schools.xml?label=Hope+Primary+School

http://localhost:8080/elda/api/education/schools.xml?max-schoolCapacity=100
and see presentations of selected schools' data. The html rendering (which is provided by an XSLT transform of the xml rendering) has many interesting features.

Once Elda has unzipped itself, you can run it from the Elda directory it creates:

(in Elda_VERSION)

java -jar start.jar
(Or by double-clicking, etc).

If you can't use port 8080

You may already be using port 8080 for some local service. In that case, you can start Elda from the command line (no double-click) with

java -jar elda.jar -Djetty.port=NNNN
or, if you're starting from the unzipped Elda directory,
java -Djetty.port=NNNN -jar start.jar
where NNNN is the port of your choice. (Yes, the -D comes after elda.jar, but before start.jar.)

To change the port number without having to supply a -Djetty.port command line option every time, in the Elda directory edit the configuration file etc/jetty.xml and change the line:

<Set name="port"><SystemProperty name="jetty.port" default="8080"/></Set>
to:
<Set name="port"><SystemProperty name="jetty.port" default="NNNN"/></Set>
where NNNN is the port number of your choice.

Using other LDA specifications

From the command line

To use different LDA specifications, use the system property elda.spec. Like the port number, it can be set as part of launching the elda jar or when launching the jetty start jar:

java -jar elda.jar -Delda.spec=SPECS
or (in the Elda directory):
java -Delda.spec=SPECS -jar start.jar
where SPECS is one or more LDA specification files separated by commas.

If you use elda.spec, then Elda ignores the default specification (the education LDA) wired into it.

html formatters

The default formatter supplied by Elda is a very simple HTML formatter showing the properties and their values of the selected items. Elda also ships with a renderer that uses XSLT (and Javascript at the client end) to produce pages with additional controls and a richer appearance. To use this as your html renderer, add:

	
; api:formatter 
  [a api:XsltFormatter
  ; api:name 'html'
  ; api:stylesheet 'xsltsheets/ashtml.xsl'
  ; api:mimeType 'text/html'
] 

to your API root in your configuration file and arrange that the webapps/elda directory contents are served as static files.

By editing web.xml

To change the specification used without having to use a -Delda.spec command line option every time, edit the Elda webapps/elda/WEB-INF/web.xml. Find the servlet configuration

<servlet>
  <servlet-name>loader-init</servlet-name>
  <servlet-class>com.epimorphics.lda.routing.Loader</servlet-class>
  <init-param>
    <param-name>com.epimorphics.api.initialSpecFile</param-name>
    <param-value>specs/education.ttl</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
Replace specs/education.ttl with the name of the LDA specification files you wish to load, separated by commas.

Querying a local file

If the remote SPARQL endpoint is slow, not yet fully configured, or plain unimplemented, you might want to set up a local endpoint using a tool like Fuseki. But it's also possible for Elda to query a local RDF file.

Edit your spec file, which will look something like the education spec suplied with Elda:

spec:api
  a api:API ;
  rdfs:label "Edubase API"@en;
  api:maxPageSize "50";
  api:defaultPageSize "10" ;
  api:sparqlEndpoint <http://services.data.gov.uk/education/sparql> ;
  api:endpoint 
   spec:schools
   , spec:schoolsPrimary
   , spec:schoolsSecondary
   , spec:schoolsPrimaryDistrict
   , spec:schoolsSecondaryDistrict 
 .
Replace the services URI with local:content-name, where content-name is the name of the RDF source you wish to query. When Elda issues queries to a local: endpoint, it loads (and remembers) the contents and queries those directly.

Usually the content-name is a file name. It is resolved against the webapps context path (ie the directory from which it serves files). If there is no such file, then the content-name is treated as a URL and its contents fetched. If that fails, then the content is searched for along the webapps classpath. In all of these cases, the fetched content is loaded into memory as an RDF model and all queries to the endpoint are answered by this model.

(The name-lookup functionality is supplied by the underlying Jena FileManager class; for more details, see the Jena documentation currently at openjena.org.)

Using a local TDB datasource

As an alternative to setting up a local SPARQL endpoint, or using a local: file, you can instead use a local Jena TDB database. To do so you will need to modify the web.xml webapp configuration file and supply an additional init-param for the loader-init servlet. You can do this in two ways:

<init-param>
  <param-name>com.epimorphics.api.TDB-base-directory</param-name>
  <param-value>tdb-directory</param-value>
</init-param>

Replace tdb-directory with the path to your chosen TDB directory. Note that the path is relative to the webapps directory – your best choice is to use an absolute path.

Warning. If the directory does not contain any TDB files, TDB will create a new empty dataset in it. This is usually not what you want, since all queries will return no answers, so Elda will report an error during setup.

The alternative form:

<init-param>
  <param-name>com.epimorphics.api.dataStoreDirectory</param-name>
  <param-value>datastore-directory</param-value>
</init-param>

specifies datastore-directory as a directory containing a TDB directory named tdb. The same warnings as above apply. (This form exists because Elda can do limited LARQ indexing and in that case the datastore directory will have a larq subdirectory for the LARQ indexes.)

Having specified a TDB directory, you can now edit your spec's sparqlEndpoint declaration, which in the education example looks like:

spec:api
  a api:API ;
  rdfs:label "Edubase API"@en;
  api:maxPageSize "50";
  api:defaultPageSize "10" ;
  api:sparqlEndpoint <http://services.data.gov.uk/education/sparql> ;
  api:endpoint 
   spec:schools
   , spec:schoolsPrimary
   , spec:schoolsSecondary
   , spec:schoolsPrimaryDistrict
   , spec:schoolsSecondaryDistrict
 .
Replace the services URI with tdb:model-name, where model-name is the name of your endpoint model inside the TDB store.

Using Elda as a webapp

The Elda shipped jar is just a delivery mechanism for getting started with LDA functionality. Elda itself is just a webapp which the jar bundles with Jetty.

To use Elda in your own webapps, you can copy the constructed Elda webapp from the unzipped Elda-VERSION/webapps/elda directory and edit its web.xml as you require. The necessary jars are all in webapps/elda/WEB-INF/lib.

If you have downloaded the Elda repository, then you can rebuild the Elda working jars (json-rdf-VERSION.jar and lda-VERSION.jar) and webapp using Maven; see the advanced documentation.

The demo jar is given the name elda-standalone-VERSION.jar by the "mvn install" process.