JeromeDL: The Semantic Digital Library - Installation


HyperCuP Lightweight Implementation in JeromeDL - User Guide

Sławomir Grzonkowski & Ewelina Kruk

1. Introduction

HyperCuP Lightweight Implementation is an open source library that provides a communication backend for developing distributed applications with a very efficient broadcast algorithm.

The aim of this manual is to provide general information about configuring HyperCuP within JeromeDL. Moreover, the manual shows how to configure a single JeromeDL installation to make it able to co-operate with other instances.

2. HyperCuP Configuration

2.1 Using Properties File (recommended)

The easiest and recommended way to configure the HyperCuP is to prepare a properties file: JeromeDL/WEB-INF/hypercup.properties. An example properties file looks like the following: 
services.amount = 2
services.name.1 = elp
services.name.2 = dfoaf
service.elp.localquery = org.jeromedl.service.elp.LocalQueryImpl
service.elp.url = http://another.library.net/services/HyperCuPService  	
service.elp.integrationchampion = http://another.library.net/services/HyperCuPService
service.dfoaf.localquery = org.foafrealm.hypercup.LocalQueryImpl
service.dfoaf.url = http://another.library.net/services/HyperCuP4DFOAF
service.dfoaf.integrationchampion = http://another.library.net/services/HyperCuP4DFOAF
From an administrator's perspective, only four lines are important, which are responsible for setting up the addresses. The administrator should adjust them to the library needs:
  • service.elp.url=http://another.library.net/services/HyperCuPService - This entry contains a proper address of the ELP service (distributed searching protocol in JeromeDL) . Usually, it is required to change the ‘another.library.net’ to a correct library address. Each library has a unique address.
  • service.elp.integrationchampion=http://library.deri.org/services/HyperCuPService - This line informs the system about the other library elp service address which the system will connect after pressing the start button. The administrator must replace the ‘library.deri.org’ part with a correct service’s address. The address can be same for many libraries who participate in the federated network.
  • service.dfoaf.url=http://another.library.net/services/HyperCuP4DFOAF - The line’s meaning is similar to the service.elp.url; it contains a proper address of the dfoaf service. Usually, it is required to change the ‘library.deri.ie’ to a correct library address. The address is individual for various libraries.
  • service.dfoaf.integrationchampion=http://another.library.net/services/HyperCuP4DFOAF - The line meaning is similar to the service.elp.integrationchampion; it informs the system about the other dfoaf service address provided by other library which the system will connect after pressing the start button. The administrator must replace the ‘library.deri.org’ part with a correct service’s address. The address can be same for many libraries who participate in the federated network. When the properties file is completed, the administrator must click on the start button (See Figure 1) in the HyperCuP panel.
    Figure 1: Starting connections

2.2 Using WWW Panel

It is possible to configure HyperCuP using the web panel. HyperCuP’s panel is depicted in the figure 2. See table 1 for an explanation of the fields.
Figure 2: HyperCuP's control panel


number
on the Fig. 2

name

description

1

version id

for information only. in order to connect different libraries into one network, all libraries must have the same hypercup version.


2

keep-alive interval

a control value which enables to check states of the connected libraries. the default value is 20000 milliseconds; it means that library checks availability of other connected libraries every 20 seconds. if an accident occur or a connection is unsuccessful, the automatic repair of the connection is performed.

3

restore predefined

connections

it allows an administrator to start a set of predefined connections. the properties can be viewed by clicking on a highlighted link (4). figure 5 in section 4 shows an example window which appears after clicking on the link. the button start executes the prepared configuration file.


4

properties link

the location of the properties file. click on it to preview.

5

start a new service

this area allows creating new services. working with JeromeDL, an administrator probably will never use this feature. however, a sample configuration parameters are described below:

  • dfoaf
    1. enter service address: http://library.deri.ie/jeromedl/services/hypercup4dfoaf
    2. enter service alias: dfoaf
    3. localquery implementation: org.foafrealm.hypercup.localqueryimpl
  • elp
    1. enter service address: http://library.deri.ie/jeromedl/services/hypercupservice
    2. enter service alias: dfoaf
    3. localquery implementation: org.jeromedl.service.elp.localqueryimpl
The service addresses differ depending on the real installation address. After filling in the forms, the button initialize (10) must be pressed; if everything went correctly a new service will appear in the available services (9) area.

6

address

enter the address of the library you are going to connect

7

join

press it when you configure the service and are going to join.

8

peers

the list of the peers who are connected to a given service

9

available services

this area shows a detailed overview of all configured services. the meaning of all used fields is explained below:

    • alias – the service’s name,

    • address – the service’s address,

    • query status – if the localquery is registered correctly, the status is ‘ok’.


Configured libraries are able to co-operate with each other. If two librarians decide to connect their libraries, one of them must join to the other. In order to perform this task, an administrator must fill in the form (6) with the other library’s service address and press the join (7) button.

JeromeDL uses two services: dfoaf and elp; they require separate configuration.

The HyperCuP protocol [2] connects libraries using specific algorithms as a result libraries have connections which are known as virtual; they are needed for maintenance reasons; such connections are listed in the ‘The peers for this service’ area (8). It is strongly recommended to use a properties file in order to configure libraries!

3. Configuration Test

In order to check if the provided addresses are correct, the administrator should try to enter the parameters given in the service.elp.url and service.elp.integrationchampion to a web browser. For instance, entering http://library.deri.ie/services/HyperCuPService or http://library.deri.org/services/HyperCuPService should result in a web page (see Fig. 3).
Figure 3: Correct elp service configuration
So as to check the dfoaf service, we proceed similarly. Entering service.dfoaf.url or service.dfoaf.integrationchampion parameters in a web-browser should results in showing a screen Figure 4.
Figure 4: Correct dfoaf service configuration
Additionally, the successful configuration process is noticeable form the HyperCuP administration panel. Clicking on the link 4 (See figure 1) results in showing the current configuration; a sample configuration has been shown in figure 5. Only connections which are configured by means of the properties are shown on this page. Moreover, the connections have different status.

The status is explained below.
  • Not initialized – the service still needs some steps to complete the configuration process,
  • Initialized but not connected – the service is connected. However, it is not connected to any other service,
  • Initialized and connected and – informs that the service is both configured and connected with other service or services,
  • Unknown – some unexpected problems arose.
Figure 5: Predefined connections preview