Main Page

From EUN Learning Resource Exchange Developer Guide

Jump to: navigation, search

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


Contents

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.

Image:Sqi.gif


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.

LRE SQI Target (SOAP Web Service)

It is possible to query the Learning Resource Exchange (LRE) collections using a SOAP implementation of SQI. This section explains how to query the LRE using this target.

Getting Access to the Service

The SQI service is deployed behind a firewall. If you want to access it, please contact the European Schoolnet staff to be authorized to reach it.

WSDL

The LRE SQI Target is implemented using the Common SQI WSDL Binding (CSWB) available on sourceforge (http://sourceforge.net/projects/sqi-wsdl/).

Currently, the LRE SQI Target can only be queried in synchronous mode. It implements two of the CSWB WSDLs:

Querying

Querying the LRE SQI Service is relatively straightforward. It is a 2-step process:

  1. Opening a session
  2. Sending a query

Opening a Session

Simply call the createAnonymousSession service. Don't forget to store the session identifier string returned by this call as you will need it to query the target service.

Managing Queries

Supported Services

  • setQueryLanguage: The method requires 2 parameters: A sessionId obtained when the session was created and an identifier of the query language. Currently, the target only supports one query language "lre" that is used as the target default query language. Therefore, it is not necessary to call this method since the only value allowed is set by default. LRE QL, the query language itself, is described in a section below.
  • setResultsFormat: The method requires 2 parameters: A sessionId obtained when the session was created and an identifier of the results format requested. Similarly to the setQueryLanguage service, the target only supports one results format "lre" that is used as the target default results format. Therefore, it is not necessary to call this method since the only value allowed is set by default. The result format itself is described in a section below.
  • setMaxQueryResults: The method supports 2 parameters: A sessionId and a positive integer representing the maximum number of results to be returned by a query. By default, no maximum is set and queries return all the results available in the LRE.
  • setResultsSetSize: The method supports 2 parameters: A sessionId and a positive integer representing the size of the results set returned by a call to the synchronousQuery service. By default no limit is set which means that the number of results returned by a call will corresponds to the total number of query results returned by the query.
  • synchronousQuery: The method requires 3 parameters: A sessionId, a query statement(in LRE QL), and an integer representing the start result (and ranging from 1 to the total number of results).
  • getTotalResultsCount: The method requires 2 parameters: A sessionId and a query statement (in LRE QL). It returns an integer corresponding to the total number of results returned by the query statement.

NOTE that the asynchronous query services and setMaxDuration are not supported at the moment.

Putting Things Together

Suppose that you want to query for learning resources in German. In the LRE Query Language, this can be expressed as follows: lre.loLanguage = de (see below for a complete description of the query language). This kind of generic query can potentially return a lot of results and, before submitting it, you might want to check how many results it will return. This can be done using the getTotalResultsCount service.

  • getTotalResultsCount( "mySessionId", "lre.loLanguage=de")

This query returns more than 30,000 results. In order to actually get these results, you must call the synchronousQuery service as follows:

  • synchronousQuery( "mySessionId", "lre.loLanguage=de, 1)

30,000 results is probably more than what you need and you may wish to limit them to, for example, the first 1000 results. This can be achieved using the setMaxQueryResults service.

  • setMaxQueryResults( "mySessionId", 1000 )

After this call, calling

  • synchronousQuery( "mySessionId", "lre.loLanguage=de, 1)

will return 1000 records instead of more than 30,000.

This being said, 1000 records is something that you might regard as too big to be returned in one service call. So, to further develop our example, also you are interested in the top 1000 resources in German, you might want to be able to collect them by group of 100. This requires the setResultsSetSize service.

  • setResultsSetSize( "mySessionId", 100 )

Then, you can call the service synchronousQuery as follows to get the first 100 results.

  • synchronousQuery( "mySessionId", "lre.loLanguage=de, 1)

Then call the synchronousQuery service again just changing its third parameters to get the following 100 results.

  • synchronousQuery( "mySessionId", "lre.loLanguage=de, 101)

LRE Query Language

Keywords

In LRE QL, a simple keyword can be used as a query. For example, the query:

  • water

Returns all the metadata records containing the term "water" either in their (lom.general.)title, (lom.general.)description, or (lom.general.)keyword.

If the term to be searched contains one of the following characters:

  • blank " "
  • ^
  • .
  • tabulation " "
  • \
  • "
  • (
  • )
  • =
  • <
  • >
  • /

It has to be put between double quotes as in the following example:

  • "E=MC2"

Boolean operators

Keyword clauses (and the LRE Context Set clauses that will be introduced in the next section) can be combined using the following binary Boolean operators:

  1. "and" : coffee and tea (returns metadata records that contain both terms: "coffee" and "tea")
  2. "or" : coffee and tea (returns metadata records that contain either the term "coffee" or the term "tea" or both)
  3. "and not" : coffee and not tea (returns metadata records that contain the term "coffee" but does not contain the term "tea")

LRE Context Set

lre.descriptor

The LRE thesaurus is a multilingual thesaurus used to index the LRE learning resources. Each entry (or descriptor) of the thesaurus is identified by a numeric code (for example 144 corresponds to biology) and can be queried as follows:

  • lre.descriptor = 144

Note that this query:

  1. returns not only the metadata records of the resources indexed with the descriptor term "biology" but also the metadata records indexed with a narrower term of "biology" (e.g., anatomy, botany, microbiology).
  2. does not return the metadata records that contain the word biology but have not been indexed with the descriptor 144.

As a consequence, in order to get all the biology-related metadata records it is necessary to combine the descriptor clause with a search for the term biology:

  • biology and lre.descriptor = 144

An alphabetic list of the thesaurus descriptors (in English) and their numeric values is available here.

lre.minAge

The index minAge allows for querying the minimum age part of element Educational.Typical Age Range of LOM.

For example:

  • lre.minAge < 6
  • lre.minAge <= 6
  • lre.minAge = 6
  • lre.minAge >= 6
  • lre.minAge > 6

lre.maxAge

Similarly, the index maxAge allows for querying the maximum age part of element Educational.Typical Age Range of LOM.

For example:

  • lre.maxAge < 16
  • lre.maxAge <= 16
  • lre.maxAge = 16
  • lre.maxAge >= 16
  • lre.maxAge > 16

lre.ageRange

The index ageRange allows for searching element Educational.Typical Age Range of LOM.

For example:

  • lre.ageRange = "12-16"

Returns resources suitable for pupils between 12 and 16 years old.

  • lre.ageRange = "12-*"

Returns resources suitable for pupils who are 12 years old or older while

  • lre.ageRange = "*-8"

Returns resources for pupils up to the age of 8.

Note that ageRange queries are interpreted in a loose way. As a consequence, queries such as:

  • lre.ageRange = "12-16"

are equivalent to:

  • lre.minAge <= 16 and lre.maxAge >= 12

lre.lrt

The "lrt" index allows for selecting a given "Learning Resource Type" as defined in the LRE Application Profile (LRE-AP). According to this application profile, there are 2 categories of learning objects:

  1. Complex learning resources such as: application, assessment, broadcast, case study, course, demonstration, drill and practice, educational game, enquiry-oriented activity, experiment, exploration, glossary, guide, lesson plan, open activity, presentation, project, reference, role play, simulation, tool, weblog, web page, wiki, other web resource, and other.
  2. Simple learning assets such as: audio, data, image, model, text, and video.

Learning object of a given learing resource type (for example, images) can be searched as follows:

  • lre.lrt = image

lre.isAsset

It is possible to limit a search to learning assets without enumerating all the asset learning resource types (lre.lrt = audio or lre.lrt = data or lre.lrt = image or lre.lrt = model or lre.lrt = text or lre.lrt = video) by using the index "isAsset" as follows:

  • lre.isAsset

This notation is a shortcut for (and is equivalent to):

  • lre.isAsset = true

lre.isResource

Similarly, it is possible to limit a search to learning resources using the index "isResource" as follows:

  • lre.isResource

This is equivalent to:

  • lre.isResource = true

lre.status

The "status" index allows for filtering resources with a given status (as defined by element lom.general.status). For example, the query:

  • lre.status = draft

Will select draft resources.

lre.cc

The "cc" index allows for searching for resources with a Creative Commons license.

It can be used in conjunction with the following 5 values:

  • true: lre.cc = true. This can be shorten lre.cc and returns all the resources licensed under a CC license.
  • sa (Share-Alike): lre.cc = sa
  • nc (Non Commercial): lre.cc = nc
  • nd (Non Derivative): lre.cc = nd
  • by (Attribution): lre.cc = by

For example, the query:

  • lre.cc = sa and lre.cc = nc

Will return metadata records describing resources licensed under a Non-Commercial, Share-Alike Creative Commons license.

lre.loLanguage

The "loLanguage" index allows for selecting the language of a learning resources. For example, the query:

  • lre.loLanguage = fr

Returns resources in French.

Note that "loLanguage" selects the language of the learning resources, not the language of the metadata. As a consequence, the query lre.loLanguage = fr can return descriptions in multiple languages of resources in French.

For selecting the metadata language use lre.mtdLanguage.

lre.mtdLanguage

The mtdLanguage index allows for selecting the language of the metadata records. For example, the query:

  • lre.mtdLanguage = en

Returns resource descriptions in English.

Note that "mtdLanguage" selects the language of the metadata, not the language of the learning resources. As a consequence, the query lre.mtdLanguage = en returns English descriptions of resources that can be in other languages.

For selecting the language of the resource use lre.loLanguage.

lre.set

The "set" index allows for limiting a query to the collection of a given metadata provider. For example, the query:

  • lre.set = cahi

Will return all the LOM records contributed by Cambridge-Hitachi.

The sets currently supported are:

  • apertus (Hungary)
  • ariadne (Ariadne Foundation)
  • bmbwk (Austria)
  • cahi (Cambridge-Hitachi, UK)
  • cfl (Sweden)
  • estonia (Estonia)
  • eun (European Schoolnet)
  • fwu (Germany)
  • educatio (Hungary)
  • indire (Italy)
  • kul (Katholiek Universiteit Leuven, Belgium)
  • mec (Spain)
  • msu (Sweden)
  • ncte (Ireland)
  • promothean (http://www.prometheanworld.com/)
  • scholaris (Poland)
  • skolavefurinn (Iceland)
  • tlf (Lithuania)
  • ul (Slovenia)
  • xtec (Catalonia)

LRE Result Format

Query results are encoded using an XML binding: strictLreResults-1.0.xsd (http://fire.eun.org/xsd/strictLreResults-1.0.xsd).

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