ShanoirTk

Description

Shanoir (SHAring NeurOImaging Resources) comes with a set of tools and libraries which offer to access Shanoir off the web interface.

It is possible to develop your own tools in order to access and exploit Shanoir's functionalities. Note that the tools below are programs used to access Shanoir's Web Services. They are developed in Java and you will therefore need a Java Runtime Environment installed on your client machine to use them.

You can get ShanoirTk from Download section (Note that the last code is available from the svn and git repository). The archive is structured as follow:

  • a lib directory which contains jar files.
  • a bin directory which contains command lines for prompts :
    • .bat files for Windows
    • .sh files for Linux / Mac

List of available Tools

Download Web Service

Finder Web Services

These tools are used to access key entities handled by Shanoir according to various search criteria:

Another tool lists all the references used within Shanoir. For instance, this is helpful to know which value is accepted as input of a search criteria of one of the Finder Web Service above.

Import Web Service

Web Services to import processed datasets into a Shanoir instance outside the web interface.

FIXME Create and fill the importProcessedDataset page

Property File

For information, the tools connect to the web services of a Shanoir server and thus need information about the server access as well as security element in order to establish the connection:

  • host : address of the Shanoir server
  • port : connexion port
  • username : username that you would use through the web interface
  • password : the associated passord
  • truststore : path to the truststore. The truststore is supposed to handle the ssl certificate from the server you intend to connect to. So you have to get the certificate used on the Shanoir server you're trynig to reach (which is the cert file). See next paragraph to know how to add a certificate to your truststore.

For convenience, you can define all these properties in a file that must be placed in your USER_HOME. This way you won't get to fill these fields each time you run Shanoir tool. Concretely, the file $USER_HOME/.shanoir/server.properties must be created with such a following content:

user=john
password=doe
host=shanoir.johndoe.com
port=8443
truststore=C:/Documents and Settings/grenard/.shanoir/client.truststore

FIXME Set the password as a parameter in ./shanoir/server.properties

How to add a new certificate in your truststore

Shanoir Web Services require a ssl-secured connection. To establish this connection, you must get the certificate of the shanoir server you intend to connect to. Then using Keytool you will be able to add the certificate to your truststore using the following command:

keytool -import -alias name_of_cert -file path_to_the_certificate -keystore path_to_the_truststore

A trustore will be created by keytool at the given path Example /home/me/.shanoir/client.trustore

:!: When asked for a password, the password must correspond to the ShanoirTK password. For now, the password is hardcoded so you MUST set your password as “client” :!:

Development

The ShanoirTk project is Maven “super-project” composed of nested module projects. Each nested module project (except ShanoirTkCLI) contains a client tool which is associated to a dedicated Shanoir webservice. For convenience, all these tools inherits ShanoirTkCLI which gathers common command line features. In order to create a new client tool, you have to nest a new maven module project under the ShanoirTk root and take inspiration from the existing tool.

Warning : the jar file shanoirws-${version}.jar is mandatory in any project that accesses to the Shanoir webservices.

Compilation

If your Shanoir is deployed in a dcm4chee-JBoss

To activate the webservices, Jboss has to be started with specific libs.

Those libs aren't available in dcm4chee-JBoss, so find them in a basic Jboss distribution.

Copy/Paste following libs from jboss-4.2.3.GA/client to jboss-4.2.3.GA/lib/endorsed

jaxb-api.jar
jboss-jaxrpc.jar
jboss-jaxws.jar
jboss-saaj.jar

Then when starting Jboss, you have to specify where to find those libs.

For example :

$JBOSS_HOME/bin/run.sh  -Djava.endorsed.dirs=$JBOSS_HOME/lib/endorsed

Develop your own tool

To develop your own tools, 3 steps are needed:

If you think your development may be useful for the community and wish to share it, you can contact us that we add it in Shanoir Tool Kit.

Create a zip file to distribute the ShanoirTk tools

This will allow to distribute within one single archive all the tools to access Shanoir's webservices. To do so, execute the pom.xml (the one in ShanoirTk root) with package assembly:assembly as parameter. This will create 2 zip files in the target directory:

  • shanoirtool-version-bin.zip : binary files

shanoirtool-version-src.zip : sources files


Personal Tools