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.
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 accessible from the SPARQL endpoint
To run the demonstration, you will need to have open
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 .
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.jaror, 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=100and 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=NNNNor, if you're starting from the unzipped Elda directory,
java -Djetty.port=NNNN -jar start.jarwhere 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
-Djetty.port command line option
every time, in the Elda directory edit the
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
java -jar elda.jar -Delda.spec=SPECSor (in the Elda directory):
java -Delda.spec=SPECS -jar start.jarwhere 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.
; 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
-Delda.spec command line option every time, edit the
webapps/elda/WEB-INF/web.xml. Find the
<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
database. To do so you will need to modify the
webapp configuration file and supply an additional init-param
loader-init servlet. You can do this in
<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
The demo jar is given the name elda-standalone-VERSION.jar by the "mvn install" process.