Elda

An implementation of the Linked Data API

Additional Elda features

Configuration variables

Elda reserves LDA variable names that begin "_" for configuration purposes.

Variables used by the stylesheet

The built-in Elda stylesheet generates HTML pages that require http access to images, CSS stylesheets, and Javascript served by the Elda server. Because the webapp root isn't fixed, the stylesheet reads location information from LDA variables that are set as part of creating an Elda webapp.

Variables used by the Elda code

wildcard '*' in view property chains

A property chain appearing in a view specification may contain the special element '*', meaning "any property". In the generated query it is replaced by a fresh variable. There can be any number of *-elements, anywhere within the chain.

api:base

An LDA configuration may specify an api:base property. This should, if possible, be used to specify where the Elda webapp is served from. If specified, all Elda's constructed URIs (such as those for different views or formats of the displayed page) will use that base URI with the path and query parameters supplied in the request. This means that a server at location A can generate URIs as though it were at location B (from which it may have been redirected).

SPARQL 1.1 features

Some generated queries -- those that have view defined by property chains and are applied to many selected items -- are rather large (exceeding a megabyte). These queries are repetitions of the view property accesses specialised by the selected item. If the SPARQL server supports nested selects (part of, but not limited to, SPARQL 1.1), then these repetitions can be replaced by a single application of the view wrapped round a nested select that fetches the items.

Elda automatically uses nested selects if the data source is a local: or tdb: model, or it the sparqEndpoint value of the API is a resource with an extras:supportsNestedSelects value of true, "true", or "yes". (We anticipate that later versions of Elda will dynamically check the server to see if nested selects work.)

configuration rendering

Elda provides the api:base-relative URI path /api-config. Browsing this URI delivers a rendering of the various APIs that the Elda instance provides. Each API description shows the different endpoints, with their variable bindings and named views, and the dictionary of shortnames appropriate to this endpoint. By default the descriptions are hidden (for compactness) and are revealed by clicking on the section titles.

The api:base-relative URI path /meta/some/uri/template provides the same configuration description as /api-config, but the API and endpoint for some/uri/template are already opened.

Formatting extensions

If the object of an api:stylesheet directive starts with the prefix "xsl:", then the stylesheet is loaded from Elda's stylesheet directory, wherever that is. (By default it is webapp/xsltsheets, but this will become configurable.)

If a formatter has the property http://www.epimorphics.com/vocabularies/lda#className, then the (String) object of that property must be the name of a Java class that implements the RendererFactory interface. When rendering is required, an instance of that class is invoked to deliver a Renderer, and that Renderer is used to render the result set.

statistics

The api:base-relative URI path /control/show-stats displays statistics about the queries that this Elda instance has handled, including:

(Elda maintains two internal caches, one mapping the computed selection query to the list of items it generates, the other mapping (list of item, view) pairs to generated result sets. These are independant of any caches provided by eg an Apache server wrapping Elda.)

All of these results show the total time, the mean time over all requests, and the maximum and minimum times over all requests.

All of these results show the total size (in [kilo-]bytes), and the mean, maximum, and minimum over all requests.

The display also breaks down rendering sizes and times by the rendering format (ie JSON/XML/HTML ...).

Cache

Elda caches the results of queries so that they may be re-served quickly. When the cache gets "too full", it is reset. "Too full" by default is measured by the number of triples in the cache.

Using Elda directly

You don't need to go through a servlet (or restlet) framework to exploit Elda. You can call the components yourself and supply whatever glue you like.

Creating an APISpec

The constructor

APISpec(Resource config, ModelLoader forVocab)
delivers a new APISpec object configured from the given Resource. You may have chosen a Resource with a known URI in a config model, or found one with rdf:type api:API, depending on your usecase. The ModelLoader is only used if the config has api:vocabulary elements, in which case it loads the models for its API vocabulary.

Given an APISpec, the method getEndpoints() delivers a list of APIEndpoint objects corresponding (in no defined order) with the endpoint descriptions in the config model.

Running an endpoint

You can then invoke

APIEndpointUtil.call( control, match, requestUri, formatSuffix, queryParams )
where

The call returns a three-element object which contains the ResultSet of the query execution (the result model and selected items), the name of the result formatter that has been selected by the endpoint, and the variable Bindings.

Rendering results

Once you have chosen a renderer R to use for the result set, the invocation

R.render( t, rc, results )
where t is a Times object, delivers a String which is the rendering of results according to the RenderContext rc, which you can construct from the VarValues embedded in the call context, the context path, and an AsURL object to convert URI fragments into full URIs.

The method call R.getMediaType() returns the media type for the renderer's result.

Building Elda

Prerequisites: Java (underlying platform), Mercurial (to fetch the sources), Maven (build management). Maven will download remaining necessary jars for Jena, Jersey, etc.

Download the Elda sources:

hg clone https://elda.googlecode.com/hg/ elda  
places the Elda sources in ./elda (which is created if necessary).

Running

mvn clean install
will now build the Elda jars and put them into your local Maven repository, along with all the jars that they depend on. You can then either use Maven to build your own application with those jars as dependencies, or extract them and embed them in your own libraries.

Look in the (automatically created) file /lda/src/main/java/com/epimorphics/lda/Version.java to see which version of Elda is being built. If you want to use a non-SNAPSHOT version, use

hg update -r REVISION
before running maven, where REVISION is your choice of the revision tags you get from running:
hg tags
and selecting a tag that looks like lda-top-1.X.Y; that is the shape of tag generated by the Elda release process.