Project

General

Profile

LCF Server

Contains implementations of the LCF protocol using the LCF schema

generated classes as the java model.

It includes three different server implementations:

  • org.restlet

  • basic servlet

  • jax-rs (not fully implemented)

Build requirements:

  • JDK 8

  • Maven

To build

  mvn package

Output

  • lcfserver-frontend-restlet-cli Standalone server (org.restlet framework. To run: java -jar -lcfserver.jar. For alternate start-up options: java -jar lcfserver.jar --help

  • lcfserver-frontend-restlet-war Webapp to deploy on J2EE compliant server (org.restlet framework)

  • lcfserver-frontend-servlet-war Webapp to deploy on J2EE compliant server. When deployed, edit /WEB-INF/web.xml and change the publicURL parameter to reflect the hostname and port of the J2EE compliant server

  • lcfserver-frontend-jaxrs-war Jaxrs framework - not fully implemented

Configuration and Customisation

Part of the design of this framework was to work as closely to the classes generated by JAXB

from the LCF schema as possible, so that updates to the scheme could be accommodated by the framework

with minimal effort (ideally just regenerating the schema and recompiling the java).

There are two key packages for walking and modifying entities

###com.ceridwen.lcf.server.core.referencing

Parent and child entities are referenced by "href" entries which are a URL to the REST service where the entity can be retrieved.

These will be of the form

  http[s]://{server}[:{port}]/{path}/lcf/1.0/{entity}/{id}

As the protocol, server, port and path will vary according to where the service is deployed, these are not easy to handle internally.

The referencing classes allow these to be modified on incoming messages to any internal representation (dereferenced), and allow the internal

representation to be converted back (referenced).

A class implementing the ReferenceEditor interface determines the conversion rules. Classes in the modifier subpackage determine how this is

applied to the various LCF schema generated classes.

BasicReferenceEditor implements the following dereferencing\referencing rules:

  • dereference:

    http[s]://{server}[:{port}]/{path}/lcf/1.0/{entity}/{id} -> {id}

  • reference:

    {id -> http[s]://{server}[:{port}]/{path}/lcf/1.0/{entity}/{id}
    

com.ceridwen.lcf.server.core.integrity

This controls handling parent\child relations - updating href's and if necessary deleting orphaned children on deletion of the parent

This can be overlaid on any datasource by applying the ReferentialIntegrityFilter, but it is likely an LMS will handle parent\child anyway

RelationshipFactory contains the definitions of the different parent\child relations in the LCF schema classes. It is also used for constructing\validating

urls of the form

  http[s]:/{server}[:{port}/{path}/lcf/1.0/{parent}/id/{child}

Implementing a new data source

You need to create new classes implementing the following interfaces:

###EntitySourceInterface<E>

for each LCF entity type you will need to implement EntitySourceInterface<E> (e.g. EntitySourceInterface<Patron>).

This should return the populated entity from the LMS, allow creation\modification of entities in the LMS, etc.

EntitySourcesInterface

This has a single function which should return an instance of the class implementing EntitySourceInterface for the given entity type

Configuration

This returns the ReferenceEditor and an instance of the above EntitySourcesInterface class.

You should put the name of the new Configuration class in the file

 META-INF/services/com.ceridwen.lcf.server.core.config.Configuration

Default configuration

By default, the server loads class com.ceridwen.lcf.impl.hashmap.HashMapSourceConfiguration

This returns the BasicReferenceEditor, and loads a HashMap based datasource which a number of filters. Some of these

can be used by a custom datasource but are designed for the reference memory datasource:

  • DefaultDataLoaderFilter() loads a default set of data

  • PersistentFilter(file) adds snapshotting and loading the memory data to an xml file

  • ServerGeneratedIdFilter(class) the default behaviour for creating a new entity that a client supplied id is used if supplied, otherwise one is generated. This filter will always generate a server id for the designated entity type

  • ClientGeneratedIdFilter(class) - the default behaviour for creating a new entity that a client supplied id is used if supplied, otherwise one is generated. This filter will return an error if no client supplied id is present

  • ReferentialIntegrityFilter - used the routines in the com.ceridwen.lcf.model.integrity to ensure parent\child relations

  • LoanFilter - generates specific lcf-loan-response messages for loans

  • PatronCountFieldsFilter - automatically calculate the (readonly) loan\reservation... fields in a patron record

  • ReadOnlyFilter(class) - Forces the designated type to be readonly by rejecting create\update requests