Shanoir Tool Kit

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 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

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 Sahnoir server
  • port : conncection 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. 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

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

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.

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.

ShanoirWs (2009)

ShanoirWs is a library that allows you to access to the Shanoir webservices.

Générer le projet à partir des sources

In this part is explained how to build a jar file.

Pre-requisite : maven, ant

  1. Firstly, you need to get the WSDL files from the Shanoir server. To do so, you can download the sources of Shanoir and then execute the Ant task “ant build-server-java”. This will create the wanted files in the directory ${INRIANEUROTK_SOURCES}/resources/WEB-INF/wsdl.
  2. Then you must define where are located the WSDL files in the “pom.xml” file. To do so, just modify the “wsdlSrcDir” property at the end of the pom.xml file.
  3. At last, execute the command line “mvn clean compile license:format license:check package” at the root of the ShanoirWs project. This will create a jar file into the “target” directory. To install it on your local maven repository, execute the command line “mvn install”.

ShanoirTk (2009)

ShanoirTk is a toolbox of several tools and libraries to access to the Shanoir webservices.
The libraries are written in Java and can be easily integrated into existing projects.
Warning : the jar file shanoirws-${version}.jar is mandatory in any project that accesses to the Shanoir webservices.

Installation

You need to get the binary distribution or the sources. To do so, go to the download page.

How to use the binary distribution

The binary distribution comes with two folders : lib and bin.
bin: contains a linux and a windows version of all tools of ShanoirTk
lib: you can find pre-compiled jar files version of all tools of ShanoirTk and you can integrate them in your own project.

How to use the sources distribution

  1. Firstly, you need to get ShanoirWs and install it on your local maven repository.
  2. Then you can modify the source code in respect of the license agreement.
  3. Then you can compile all the tools and create an archive by running the command line: “mvn clean compile license:format license:check package assembly:assembly” at the root of the project. This will create two zip files in the “target” directory and create jar files of all tools in their “target” directory.

Warning: If you have the following error, then you need to uncheck “Resolve workspace artefacts” in maven build configuration:

Reason: Failed to create assembly: Error adding file 'org.shanoir:shanoir-ws:jar:0.2' to archive: C:\workspace\ShanoirWs\target\classes isn't a file.

Extend the access API of Shanoir features

Overview of the API architecture

Shanoir is a Web application. It provides webservices which are all listed in the ShanoirWs project. This project gathers within client libraries the access point to the web services and can be used within any other java projects. The projects located of ShanoirTk are client implementation illustrating how to use ShanoirWs.

API Overview

API Overview

Générer des WSDL dans Shanoir

Webservices are created in the package org.shanoir.webservices. To automatically generate the associated WSDL, you just need to call the build-server-java Ant task described in the build.xml file of the Shanoir project. Pay attention : each webservice requires a wsgen Ant task in the build-server-java task. Sample for DownloadService :

<wsgen genwsdl="true" keep="true" verbose="true" destdir="${wsdl.dir}" sei="org.shanoir.webservices.impl.Downloader">
  <classpath>
    <pathelement path="${lib.dir}/ejb-api.jar" />
    <pathelement path="${lib.dir}/jboss-seam.jar" />
    <path location="${jar.dir}" />
  </classpath>
</wsgen>

If you get such error message :

[wsgen] D:\workspaces\ShaNoir\Shanoir\exploded-archives\Shanoir.jar\org\inria\neurotk\core\model\dataset\mr\MrDataset.class: warning: Cannot find annotation method 'name()' in type 'javax.persistence.Table': class file for javax.persistence.Table not found
    [wsgen] D:\workspaces\ShaNoir\Shanoir\exploded-archives\Shanoir.jar\org\inria\neurotk\core\model\dataset\mr\MrDataset.class: warning: Cannot find annotation method 'name()' in type 'javax.persistence.PrimaryKeyJoinColumn': class file for javax.persistence.PrimaryKeyJoinColumn not found
    [wsgen] D:\workspaces\ShaNoir\Shanoir\exploded-archives\Shanoir.jar\org\inria\neurotk\core\model\dataset\mr\MrDataset.class: warning: Cannot find annotation method 'fetch()' in type 'javax.persistence.ManyToOne': class file for javax.persistence.ManyToOne not found
    [wsgen] Problem encountered during annotation processing; 
    [wsgen] see stacktrace below for more information.
    [wsgen] com.sun.tools.ws.processor.modeler.ModelerException: [failed to localize] modeler.nestedGeneratorError(java.lang.NullPointerException)

You probably forgot to add a library, in the above case ejb3-persistence.jar is missing :

<pathelement path="${lib.dir}/ejb3-persistence.jar" />

Extend the ShanoirWs project

This project contains 3 packages :

  • org.shanoir.ws.custom : Webservice Access Classes with which we can specify on-the-run the address of the Shanoir Server.
  • org.shanoir.ws.generated : Generated Classes by the maven wsimport task
  • org.shanoir.ws.util : Utile Classes for the ShanoirWs project

In order to automatically generate theclasses and install the resulting jars ShanoirWs-version.jar in the local Maven repository, You just need to run the pom.xml file with clean install as parameter. Warning: the content of the jaxws-maven-plugin, located in the pom.xml, must be synchronized all the wsdl files from the org.shanoir.webservices package of the Shanoir project.

Ajouter un projet dans ShanoirTk

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.

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

Outils personnels