Installation

This instructions are aimed to those who want to have its local instance of the PSICQUIC web service based on SOLR.

Requirements

Obtaining the Reference Implementation source code

There are two ways to obtain the source code:

  • Download the psicquic-solr-ws-1.4.0.zip

  • Using a git client, clone the code

    git clone https://github.com/PSICQUIC/psicquic-solr-ws.git

Creating a solr working directory

This solr working directory will contain solr-home, the MITAB index and solr war file. The content of solr working directory does not need to be there, it will be created automatically by the indexing script. If a solr-home, MITAB index or solr.war file already exists in the working directory, only the MITAB index will be overwritten by the MITAB indexing script.

Building the index

The Reference Implementation uses SOLR (based on LUCENE) to index the data. This index can be generated in many ways but for your convenience, a class to create it from a PSIMITAB file (versions 2.5, 2.6, 2.7 and 2.8 are supported) is included as part of the web service. The PSIMITAB formats are described in MITAB25Format, MITAB26Format, MITAB27Format, MITAB28Format and we recommend data providers to read the Data Distribution Best Practices as well as the PSICQUIC FAQ before starting to generate a PSIMITAB dataset.

Creating an index

When the indexing job starts, it creates a file target/mitabIndexJob_currentTimeMillis which contains the job ID of the indexing process. This job ID will be necessary if you want to restart the indexing process from where it failed in case of a badly formatted MITAB line for instance.

  • You can run this bash script :

    cd psicquic-solr-ws
bash indexMitab.sh /path/to/mitab-file /path/to/solr-workingdir

    where

    • /path/to/mitab-file is the path to the MITAB file to index. This argument is mandatory.
    • /path/to/solr-workingdir is the path to the solr working directory. If this argument is not provided, the script will consider the current working directory as the solr working directory.

  • The indexing can be executed using the Maven command (used by the bash script) :

    cd psicquic-solr-ws
mvn clean install -PcreateIndex -DmitabFile=/path/to/mitab-file -Dsolr.workdir=/path/to/solr-workingdir -Dmaven.test.skip

    where

    • /path/to/solr-workingdir is the path to the solr working directory. If this argument is not provided, the script will consider the current working directory as the solr working directory.
    • /path/to/mitab-file is the path to the MITAB file to index. This argument is mandatory.

Restarting the indexing process where it failed (in case it failed)

It can happen that the indexing process fails (bad formatted MITAB line for instance, solr server down, etc.). In this case you may want to restart the indexing process from where it failed (after fixing the badly formatted line for instance). Look at the job ID in the file target/mitabIndexJob_currentTimeMillis and then you have two ways of restarting the indexing:

  • You can run this bash script :

    cd psicquic-solr-ws
bash restartIndexMitab.sh /path/to/mitab-file job-ID /path/to/solr-workingdir

    where

    • /path/to/mitab-file is the path to the MITAB file to index. This argument is mandatory.
    • job-ID is the job ID in the file target/mitabIndexJob_currentTimeMillis generated by the indexing script that failed. This argument is mandatory
    • /path/to/solr-workingdir is the path to the solr working directory. If this argument is not provided, the script will consider the current working directory as the solr working directory.

  • The script can be executed using the Maven command (used by the bash script) :

    cd psicquic-solr-ws
mvn install -PrestartIndex -DmitabFile=/path/to/mitab-file -Dsolr.workdir=/path/to/solr-workingdir -Dindexing.id=job-ID -Dmaven.test.skip

    where

    • /path/to/mitab-file is the path to the MITAB file to index. This argument is mandatory.
    • job-ID is the job ID in the file target/mitabIndexJob_currentTimeMillis generated by the indexing script that failed. This argument is mandatory
    • /path/to/solr-workingdir is the path to the solr working directory. If this argument is not provided, the script will consider the current working directory as the solr working directory.

Starting solr and the PSICQUIC service locally, using Jetty

The solr server will start with the PSICQUIC service using the same jetty server.

  • You can run this bash script :

    cd psicquic-solr-ws
bash startPsicquicServerAndSolr.sh /path/to/solr-workingdir

    where

    • /path/to/solr-workingdir is the path to the solr working directory (same as for indexing MITAB). If this argument is not provided, the script will consider the current working directory as the solr working directory.

  • The PSICQUIC service and solr can be started using the Maven command (used by the bash script):

    cd psicquic-solr-ws
mvn clean install -Pstart-jetty-solr jetty:run -Dmaven.test.skip -Dsolr.workdir=/path/to/solr-workingdir

    where

    • /path/to/solr-workingdir is the path to the solr working directory. If this argument is not provided, the script will consider the current working directory as the solr working directory.

From PSICQUIC Spec 1.1 it is possible to define and expose properties about the service. You can set which properties your service is going to show by passing the psicquic.properties variable. Properties are defined using key=value pairs, comma-separated and all the expression is quoted.

mvn clean install -Pstart-jetty-solr -Dmaven.test.skip -D psicquic.properties="owner=John Smith, contactinfo=My Address"

If you decide to use maven command, other parameters can be configured :

  • -Djetty.port=9090
  • -Dsolr.host=127.0.0.1 to set up the virtual host for the solr admin interface (by default private only)
  • -Dpsicquic.properties=properties-file-name
  • -Dpsicquic.filter=filter-query (define some filters for your service)
  • -Dservice.name=name (the name of the service such as intact, mint, ... which will be used to create the war file). If no service name is provided, the default name is 'default'
  • -Dlog.file.name=filename (define a log file where you want to log all the queries that have been sent to your service)

Here is a sample query listing a limited number of available interactions in your local service:

http://localhost:9090/psicquic/webservices/current/search/query/*?firstResult=0&maxResults=10

results matching ""

    No results matching ""