| 

Back


Java Client Development Kit (CDK) (version beta 2.0)

1. Introduction

The public interface to GenomeSpace will include several web services – the Identity Manager, the Data Manager, and the Analysis Tool Manager.  We are providing Client Development Kits to simplify access to these tools.  This specification describes the Java Client Development Kit (CDK), which is the first client development kit and the reference implementation.  Non-java clients may use the same functionality via the web services API.  The web services accessed by the CDK are described in http://www.genomespace.org/support/api/restful-access-to-dm-beta-2-0. For CDK usage examples, please refer to the JUnit tests that can be found in the version control system:
https://bitbucket.org/GenomeSpace/combined/src/e6e7ff0411ae/cdk/test/org/genomespace/client/TestGenomeSpaceClient.java
https://bitbucket.org/GenomeSpace/combined/src/e6e7ff0411ae/cdk/test/org/genomespace/client/DataManagerClientTests.java
The CDK is responsible for providing GenomeSpace clients with basic identity management, file management, and web tool launch capabilities.  The requirements for and implementation of these capabilities are described in more detail below.

2. Requirements

2.1 Identity Management

The CDK is responsible for providing GenomeSpace clients with basic identity management.  It shall provide the ability for clients to login, logout, query whether a user is logged in, and register a new user.

2.1.1 Login

The login method shall take the username and password, send those securely to the IdentityManager, receive the encrypted GenomeSpace user token from the IdentityManager, hold onto that token, and hide the token itself from the client.  If the login fails, then the exception shall be returned to the client.

2.1.2 Logout

The logout method shall clear the GenomeSpace user token.

2.1.3 Query Login Status

The CDK shall provide the client with the ability to determine whether the current user is logged into GenomeSpace.

2.1.4 Register User

The CDK shall provide the client with the ability to register a new GenomeSpace user.  This method shall take a username, password, and e-mail address, send that information securely to the IdentityManager, and return to the client whether the registration succeeded or not.  If the registration fails (for example, if the requested username is already in use), then the CDK shall return to the user an understandable error message.

2.2 File Management

The CDK shall provide the client with the ability upload files to GenomeSpace, download files from GenomeSpace, list files in GenomeSpace, and delete files in GenomeSpace.  The CDK shall only provide access to files owned by the user – files owned by other users shall not be visible to the user. 
For the first version of the CDK, all files will be placed in the user’s GenomeSpace home directory; no subdirectory operations (e.g., createDirectory, deleteDirectory, etc.).  The second version of the CDK will provide full subdirectory operations, and an updated version of this document will include specifications for those operations.

2.2.1 Upload

The CDK shall provide the ability to upload a file to GenomeSpace.  The upload method will take as input the location of the file to be uploaded, and will upload that file to the user’s GenomeSpace home directory.

2.2.2 Download

The CDK shall provide the ability to download a file from GenomeSpace.  There will be two forms of the download operation – one form will actually download the file to a temporary directory and return the location of that temporary file, the other form will return a signed, one-time usage URL that the client can use to directly download the file from Amazon S3.  The download methods shall throw an appropriate exception if the file is not found on GenomeSpace.

2.2.3 List

The CDK shall provide the ability to list the files in the user’s GenomeSpace home directory.  This method will return a representation of the files in GenomeSpace, such that the objects can be easily passed to the download or delete method.

2.2.4 Delete

The CDK shall provide the ability to delete files in the user’s GenomeSpace home directory.  This method will take the name of the file as input and delete that file in GenomeSpace.  If the file is not found on GenomeSpace, it shall throw an appropriate exception.

2.3 Analysis Tool Management

The CDK is responsible for providing GenomeSpace clients with web tool launch capabilities.  The GenomeSpace Analysis Tool Manager (ATM) maintains a repository of tools available via the web that it can launch on behalf of a user.  These tools may be web applications or client applications that run on the user’s local machine, but are launchable via an URL.

2.3.1 List Web Tools

The CDK shall provide the client with the ability to retrieve a list of the available web tools available in the ATM. 

2.3.2 Launch URL for a Web Tool

The CDK shall provide the client with the ability to retrieve an URL to launch a web tool, passing it GenomeSpace files as arguments.

3. Implementation

3.1 Description

The CDK provides a client application with the ability to perform basic identity management tasks and basic GenomeSpace file management tasks.  The identity management tasks include the ability to register a new user, login, logout, and check whether the current user is logged in.  The file management tasks allow the client to upload a file to GenomeSpace, download a file from GenomeSpace, list files uploaded to GenomeSpace, and delete a file uploaded to GenomeSpace. 
The main entry point to the CDK is the GsSession class.  The client instantiates a GsSession instance, and then calls methods on GsSession to perform identity and file management operations. 

3.2 GsSession Construction

The GsSession class provides several constructors.  Most clients will simply use the default constructor, which configures the GsSession instance to communicate with the production GenomeSpace servers running on Amazon AWS. 


  GsSession session = new GsSession(); 

Several other constructors are provided for development purposes.  These constructors provide the ability to specify the URL for GenomeSpace servers, so that the JCDK can be used for testing development servers.  In addition, a constructor is provided that takes a GenomeSpace token as an argument, for use in testing GenomeSpace authentication.  These other constructors are not needed for development of GenomeSpace clients and consequently are not specified in this document.

3.3 Identity Operations

The GenomeSpace web services (Identity Manager, Analysis Tool Manager, etc.) require that the user be logged into GenomeSpace in order to access their services. 

3.3.1 Login

To login using the CDK, the client should create a GsSession object and then call the login method.  The login method takes the username and password as arguments, encrypts them, and sends them to the IdentityManager for authentication.  The login method returns a User object which contains the username:


  GsSession session = new GsSession();

  String username = "test";

  String password = "password";

  User user = session.login(username, password);

  System.out.println("Logged in to GenomeSpace: " + 

        session.isLoggedIn() + " as " + user.getUsername()); 

Assuming that authentication is successful, the IdentityManager then returns a cookie an authentication token in an HTTP cookie.   GsSession includes the cookie value is included in every HTTP request to the GenomeSpace web services.
The token contains the username and an expiration time stamp. If the token expires, the web services will return an HTTP authentication failure, and the CDK will throw an AuthorizationException.
The client shall hold onto the GsSession object, because that is required for any further identity and file operations, as described below.

3.3.2 isLoggedIn

The CDK provides the isLoggedIn method so that a client can determine whether their current GsSession is logged into GenomeSpace.  This method returns true if the GsSession is logged into GenomeSpace and false otherwise:


  GsSession session = new GsSession();

  String username = "test";

  String password = "password";

  User user = session.login(username, password);

  System.out.println("Logged in to GenomeSpace: " + 

        session.isLoggedIn() + " as " + user.getUsername()); 

3.3.3 Logout

To logout using the CDK, the client should call the logout method on their GsSession object:


  GsSession session = new GsSession();

  String username = "test";

  String password = "password";

  User user = session.login(username, password);

  session.logout(); 

3.3.4 Register User

The GsSession object provides the client with the ability to register a new user in GenomeSpace.  This method requires a username, password, and e-mail address:


  GsSession session = new GsSession();

  User newUser = session.registerUser(“aUsername”, 

       "aPassword", "test@noreply.org"); 

3.4 File Operations

GenomeSpace provides each user with a private base directory in S3; the users only have access to their own GenomeSpace files.  The CDK allows users to:

  • Upload files
  • Download files
  • Delete files
  • Create directory hierarchies
  • List directory contents
  • Move and rename files and directories
  • Copy files and directories

All the file system operation are defined by the interface:
 org.genomespace.client.DataManagerClient

3.4.1 Default Directory

Every user has a home or default directory assigned to them in the GenomeSpace file system. In this directory and all directories below it the user is permitted all the supported file operations.
To obtain a listing of the user’s default directory:


  DataManagerClient dmClient = gsSession.getDataManagerClient();

  GSDirectoryListing homeDirInfo = dmClient.listDefaultDirectory(); 

The GSDirectoryListing is discussed below.

3.4.2 Listing directory contents

For a given directory file path:


  String thePath = “/users/test”;

  GSDirectoryListing dirContents = dmClient.list(fileDirPath); 

GSDirectoryListing has a reference to the metadata (GSFileMetadata) of the target directory and a list of metadata objects corresponding to each child file and directory.
GSFileMetadata indicates whether a particular file system object is a file or directory, when it was last modified, the size in bytes, etc.
If you have the metadata object for the directory, the preferred way of getting a directory listing:


  GSDirectoryListing dirContents = dmClient.list(dirMetadata); 

3.4.3 Obtaining metadata for a file system object by its path

The file system metadata objects can be obtained indirectly through directory listings or at object creation time. They can also be obtained through their paths.


  String objectFilePath = “/users/test/myFileOrDirName”;

  GSFileMetadata objectMetadata = dmClient.getMetadata(objectFilePath); 

3.4.4 Creating directories

CDK allows arbitrary directory levels. To create a directory, in this case, as the child of the home directory:


  GSFileMetadata homeDirMeta = dmClient.listDefaultDirectory().getDirectory();

  String newDirName = “MyNewDirectory”;

  GSFileMetadata newDirMeta = dmClient.createDirectory(homeDirMeta,newDirName); 

3.4.5 Uploading files

We support two methods for this operation. The simplest, if you have the GenomeSpace target directory metadata and you want to upload a local file, preserving the same name remotely:


  GSFileMetadata newDirMeta = dmClient.createDirectory(homeDirMeta,newDirName);

  File theLocalFile = new File(“myFileToUpload.txt”);

  GSFileMetadata uploadedFileMeta = uploadFile(theLocalFile,newDirMeta); 

If you want to assign a different name to the uploaded remote file:


  GSFileMetadata newDirMeta = dmClient.createDirectory(homeDirMeta,newDirName);

  File localFile = new File(“myFileToUpload.txt”);

  String remoteFileName = “theNewName.txt”;

  GSFileMetadata uploadedFileMeta = uploadFile(localFile,newDirMeta.getPath(),remoteFileName); 

3.4.6 Downloading files

To download a file, need to get the metadata object of the source remote file:


  GSDirectoryListing dirListing = dmClient.listDefaultDirectory();

  GSFileMetadata fileToDownload = dirListing.getContents().get(0);

  File targetFile = new File(“theLocalTargetFile.txt”);

  dmClient.downloadFile(fileToDownload, targetFile,true); 

The boolean argument overwriteIfExists will come in to play if the target file exists. An exception will be raised if flag is false and the target file already exists in the local file system.

3.4.7 Obtaining a File Download URL

If you need to get the contents of a file, but you need to do it through a URL, the following method will issue a one-time, limited shelf life URL for the file of interest:


  GSDirectoryListing dirListing = dmClient.listDefaultDirectory();

  GSFileMetadata fileToDownload = dirListing.getContents().get(0);

  java.net.URL downloadUrl = dmClient.getDownloadUrl(fileToDownload); 

same can be done if you only have the file path:


  String filePath = “/users/test/myFile.txt”;

  java.net.URL downloadUrl = dmClient.getDownloadUrl(filePath); 

3.4.8 Deleting files and directories

If the user owns the file or directory (i.e., the file or directory is under her home directory):


  GSDirectoryListing dirListing = dmClient.listDefaultDirectory();

  GSFileMetadata fileToDelete = dirListing.getContents().get(0);

  dmClient.delete(fileToDelete); 

The procedure is the same for files and directories. Only empty directories can be deleted.

3.4.9 Copying files and directories

Files and directories can be copied within the GenomeSpace file system without having to download them.


  GSDirectoryListing dirList = dmClient.listDefaultDirectory();

  GSFileMetadata fileToCopy = dirListing.getContents().get(0);

  GSFileMetadata newParent Dir=dmClient.createDirectory(dirList.getDirectory(),”destDir”);

  GSFileMetadata filedCopy = dmClient.copy(fileToCopy,newParentDir,”theNewFileName.txt”); 

In the case of the directories, the procedure is the same. The Data Manager will recursively copy the directory to the source directory under the target parent directory with the newly assigned file name.
A null for new file name will keep the original file object name.

3.4.10 Moving files and directories

Same as the copy, but the source objects will be removed. As before, directory moves are recursive.


  GSDirectoryListing dirList = dmClient.listDefaultDirectory();

  GSFileMetadata fileToMove = dirListing.getContents().get(0);

  GSFileMetadata newParent Dir=dmClient.createDirectory(dirList.getDirectory(),”destDir”);

  GSFileMetadata movedFile = dmClient.move(fileToMove,newParentDir,”theNewFileName.txt”); 

3.5 Analysis Tool Operations

The GenomeSpace CDK provides clients the ability to:

  • List all web tools
  • Get an URL to launch a web tool

Later versions of the CDK will add additional functionality.  The interface to the ATM in the CDK is still in flux and may change.
The client must be logged into the CDK in order to use the Analysis Tool operations.

3.5.1 List Web Tools

The client can retrieve a list of web tools using the AnalysisToolManagerClient, which can be obtained from the GsSession object.  The getWebTools method returns a list of WebToolDescriptors.


  AnalysisToolManagerClient client = gsSession.getAnalysisToolManagerClient();

  assertNotNull("user should not be null", user);

  List<WebToolDescriptor> webTools = client.getWebTools();

  for (WebToolDescriptor tool : webTools) {

  System.out.println("tool name: " + tool.getToolName());

      for (ToolParameter param : tool.getParams()) {

          System.out.println("param name: " + param.getParameterName());

         }

  } 

The CDK shall provide the client with the ability to retrieve a list of the available web tools available in the ATM. 

3.5.2 Launch URL for a WebTool

The CDK shall provide the client with the ability to retrieve an URL to launch a web tool, passing it GenomeSpace files as arguments.  Once the client has retrieved a list of webtools, the client can select the webtool of interest and obtain a launch URL for that webtool using the getWebToolLaunchUrl method.


  for (WebToolDescriptor desc : webTools) {

    if ("GenePattern-ConvertLineEndings".equals(desc.getToolName())) {

      List<ToolParameter> params = desc.getParams();

      FileParameterWrapper wrapper = null;

      List<FileParameterWrapper> wrappers = new ArrayList<FileParameterWrapper

      for (ToolParameter param : params) {

        if (param instanceof DataSourceParameter && 

                 "input.filename".equals(param.getParameterName())) {

          DataSourceParameter dsParam = (DataSourceParameter) param;

          wrapper = new FileParameterWrapper(dsParam, metadata);

          wrappers.add(wrapper);

          }

        }

        client.getWebToolLaunchUrl(desc, wrappers);

     }

  }