Main Page

From EUN Learning Resource Exchange Developer Guide

This guide explain how to connect a metadata repository and/or a search interface to the EUN Learning Resource Exchange.

1 Overview of the Simple Query Interface (SQI)
2 Tools
- 2.1 SQI Connection Kit

Overview of the Simple Query Interface (SQI)

The Simple Query Interface (SQI) is an Application Program Interface (API) for querying heterogeneous repositories of learning resource metadata. SQI was developed on behalf of the CEN/ISSS Workshop on Learning Technology by a group of experts from different federations of learning resources such as Celebrate, Elena, Ariadne, and Edutella. It was endorsed as an official CEN Workshop Agreement in June 2005 (CWA 15454).

SQI main characteristics are:

Simplicity and ease of implementation,
Neutrality in terms of query languages and result formats, and
Support for both a synchronous and an asynchronous query mode.

Considering two repositories sharing at least a common query language and a common metadata format, the following steps are necessary to enable one repository (referred as the source of the query) to query the other (referred as the target of the query) using SQI:

the source selects one of the query languages available at the target (e.g., XQUERY -- It is possible to skip this step when a default query language is proposed by the target),
the source selects one of the result formats available at the target (e.g., the IEEE Learning Object Metadata binding -- Here also it is possible to skip this step when a default result format is proposed by the target),
the source sends a query in the selected query language,
depending on the query mode selected, the target provides the result of the query in the selected format either as the return value of the call used to send the query (synchronous mode) or by calling one or more times a query result listener implemented by the source (asynchronous mode). The latter mode is much more robust and enables SQI to be used as the front-end interface of a federated search since it is not necessary to wait for the end of the initial query before returning the first results.

The API itself is depicted on the above class diagram. It consists of thirteen methods that can be grouped into four categories: session management, query management, synchronous query management, and asynchronous query management.

Actually, session management methods are not part of the SQI specification itself and can potentially be replaced by any other session management mechanism that would be considered more appropriate. Current methods permit to open anonymously (createAnonymousSession) or not (createSession) and to close (destroySession) a session with the target repository.

The query management methods permit the configuration of query parameters such as the query language (setQueryLanguage), the format of the results (setResultsFormat), the maximum number of results returned (setMaxQueryResults), and the duration of a query (setMaxDuration).

In a synchronous query, query results are returned as the result of a query call (synchronousQuery). Additional methods permit the choice of the number of results returned by a call (setResultsSetSize) and to know the total number of results of a query (getTotalResultsCount).

In an asynchronous query, query results are sent by the target to the source of the query by calling a listener implemented by the source (queryResultsListener). This implies that the source has to indicate the location of the listener to the target (setSourceLocation) before sending an asynchronous query (asynchronousQuery).

The fault mechanism provided by SQI is intentionally unsophisticated. It aims at simplicity rather than richness in order to offer the greatest opportunity for consumption by a variety of applications. When a failure occurs, each SQI method is able to report it by throwing a fault (SQIFault) that specifies a free-text message and a predefined error code. Error codes are part of the SQI specification.

Tools

This section presents some tools that were developed to help developers who want to connect a repository to the Learning Resource Exchange.

SQI Connection Kit

What is this tool about

Connecting a repository to the learning resource exchange (LRE) consists of:

Managing a connection with the brokerage system
Implementing FireSQITarget on top of the repository, which includes:
- Managing sessions for incoming queries,
- Dealing with incoming query parameters,
- Turning incoming queries into a query language supported by the repository,
- Querying the repository, and
- Turning query results into the requested metadata format (e.g., strict LOM)

Among these tasks, only the last three ones (i.e., "turning incoming queries into a query language supported by the repository", "querying the repository", and "turning query results into the requested metadata format") are specific to a given repository. All the others can potentially be solved the same way by all the repositories that want to connect to the (LRE). In terms of SQI methods, it means that these repositories can share the implementation of all the SQI methods but the query ones (i.e., synchronousQuery and asynchronousQuery).

The SQI Connection Kit proposes a reference implementation for all the aspects of the connection of a repository that are not specific to this repository. It allows developers to:

Focus on the implementation of the specific aspects (i.e., SQI methods synchronousQuery and asynchronousQuery) and
Easily deploy the result as a web application that can be used to manage the connection of the repository to the LRE.

Requirements in terms of environment and settings

The SQI Connection Kit assumes that the repository to connect can be queried using the Java programming language. It requires:

Java JDK 1.5 and JWSDP 2.0 (downladable from http://java.sun.com/downloads/)
Ant (see http://ant.apache.org/). Note that a version of Ant comes with JWSDP.
Apache Tomcat 5.5 -- or another J2EE web application server (downloadable from http://tomcat.apache.org/)

The Connection Kit itself can be obtained at http://fire.eun.org/ConnectionKit.zip.

JDK 1.5

Install JDK 1.5. Don't forget to add it to your path and to set the JAVA_HOME environment variable.

Java Web Service Developer Pack (JWSDP 2.0)

Install JWSDP 2.0. You don't need to bundle it to a web application server. Don't forget to set the JWSDP_HOME environment variable.

Tomcat 5.5

On a Unix box:

Unzip Tomcat 5.5
Set the CATALINA_HOME environment variable
Edit the file ${CATALINA_HOME}/conf/tomcat-users.xml
- Add the following roles:
  - <role rolename="manager"/>
  - <role rolename="admin"/>
  - <role rolename="lre"/>
- And add users to them
  - <user username="lre" password="lrePassword" roles="lre"/>
  - <user username="admin" password="adminPassword" roles="admin,manager"/>
Add the JWSDP libraries to tomcat classpath:
- Edit the file ${CATALINA_HOME}/bin/setclasspath.sh and add the following lines at the end of the file just before the line _RUNJAVAC="$JAVA_HOME"/bin/javac:

 echo "Load JWSDP jar files from >${CATALINA_HOME}<"
 if [ -r ${CATALINA_HOME}/bin/addjwsdp.sh ]; then
 echo "Loading JWSDP jar files"
 . ${CATALINA_HOME}/bin/addjwsdp.sh
 fi

- Save the following lines into a file named ${CATALINA_HOME}/bin/addjwsdp.sh

 #!/bin/sh
 set -a
 # JWSDP_HOME=/opt/jwsdp-2.0
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jwsdp-shared/lib/mail.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jwsdp-shared/lib/activation.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jwsdp-shared/lib/resolver.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jwsdp-shared/lib/jaas.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jwsdp-shared/lib/relaxngDatatype.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jwsdp-shared/lib/jta-spec1_0_1.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jwsdp-shared/lib/xsdlib.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jwsdp-shared/lib/xmlsec.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jwsdp-shared/bin/commons-launcher.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxws/lib/jaxws-tools.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxws/lib/jaxws-api.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxws/lib/jaxws-rt.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxws/lib/jsr181-api.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxws/lib/jsr250-api.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/fastinfoset/lib/FastInfoset.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/sjsxp/lib/jsr173_api.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/sjsxp/lib/sjsxp.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxp/lib/jaxp-api.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxrpc/lib/jaxrpc-impl.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxrpc/lib/jaxrpc-api.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxrpc/lib/jaxrpc-spi.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/saaj/lib/saaj-api.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/saaj/lib/saaj-impl.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/xmldsig/lib/xmldsig.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxr/lib/jaxr-api.jar
 CLASSPATH=${CLASSPATH}:${JWSDP_HOME}/jaxr/lib/jaxr-impl.jar

Make it executable: chmod +x ${CATALINA_HOME}/bin/addjwsdp.sh
Start tomcat

On a Windows box:

Unzip Tomcat 5.5
Set the CATALINA_HOME environment variable
Edit the file %CATALINA_HOME%\conf\tomcat-users.xml
- Add the following roles:
  - <role rolename="manager"/>
  - <role rolename="admin"/>
  - <role rolename="lre"/>
- And add users to them
  - <user username="lre" password="lrePassword" roles="lre"/>
  - <user username="admin" password="adminPassword" roles="admin,manager"/>
Add the JWSDP libraries to tomcat classpath:
- Edit the file %CATALINA_HOME%\bin\setclasspath.bat
- After the lines:

 rem Set standard CLASSPATH
 rem Note that there are no quotes as we do not want to introduce random
 rem quotes into the CLASSPATH
 set CLASSPATH=%JAVA_HOME%\lib\tools.jar

- Add the lines:

 rem JWSDP libraries
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jwsdp-shared\lib\mail.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jwsdp-shared/lib/activation.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jwsdp-shared/lib/resolver.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jwsdp-shared/lib/jaas.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jwsdp-shared/lib/relaxngDatatype.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jwsdp-shared/lib/jta-spec1_0_1.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jwsdp-shared/lib/xsdlib.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jwsdp-shared/lib/xmlsec.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jwsdp-shared/bin/commons-launcher.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxws/lib/jaxws-tools.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxws/lib/jaxws-api.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxws/lib/jaxws-rt.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxws/lib/jsr181-api.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxws/lib/jsr250-api.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\fastinfoset/lib/FastInfoset.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\sjsxp/lib/jsr173_api.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\sjsxp/lib/sjsxp.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxp/lib/jaxp-api.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxrpc/lib/jaxrpc-impl.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxrpc/lib/jaxrpc-api.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxrpc/lib/jaxrpc-spi.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\saaj/lib/saaj-api.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\saaj/lib/saaj-impl.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\xmldsig/lib/xmldsig.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxr/lib/jaxr-api.jar
 set CLASSPATH=%CLASSPATH%;%JWSDP_HOME%\jaxr/lib/jaxr-impl.jar

Start tomcat

Ant

Ant comes with JWSDP. Make sure to add the following directory to your path:

Unix: ${JWSDP_HOME}/apache-ant/bin
Windows: %JWSDP_HOME%\apache-ant\bin

Getting started

Checking the environment

Unzip ConnectionKit.zip.
In a console, cd to the directory jdbcConnectionKit.
Run ant clean

Retrieved from "http://wiki.eun.org/lre-dev-guide/index.php/Main_Page"