ch.systemsx.cisd.openbis.dss.client.api.v1
Interface IDssComponent

All Known Implementing Classes:
DssComponent

public interface IDssComponent

A component that manages a connection to openBIS and 1 or more data store servers.

The component is a kind of state machine. In the initial state, only login is allowed. After login, other operations may be called. Thus clients should follow the following usage pattern:

  1. login
  2. ...do stuff...
  3. logout

The IDssComponent itself is designed to be used in a single thread, though it may return objects that can be used in multiple threads. Documentation for the return values clarifies their level of thread safety.


Method Summary
 void checkSession()
          Checks whether the session is alive.
 boolean deleteSessionWorkspaceFile(java.lang.String path)
          Delete a file or directory in the session workspace.
 java.util.Map<java.lang.String,java.lang.String> extractMetadata(NewDataSetDTO newDataset, java.io.File dataSetFile)
          Tries to extract the data set property key-values (metadata) from the data.
 IDataSetDss getDataSet(java.lang.String code)
          Get a proxy to the data set designated by the given data set code.
 java.io.InputStream getFileFromSessionWorkspace(java.lang.String filePath)
          Downloads a file from the session workspace.
 void getFileFromSessionWorkspace(java.lang.String filePath, java.io.File localFile)
          Downloads a file from the session workspace.
 java.lang.String getSessionToken()
          Returns the session token.
 void logout()
          Logs the current user out.
 IDataSetDss putDataSet(NewDataSetDTO newDataset, java.io.File dataSetFile)
          Upload a new data set to the DSS.
 void putFileToSessionWorkspace(java.lang.String directory, java.io.File file)
          Uploads a file to the session workspace.
 void putFileToSessionWorkspace(java.lang.String filePath, java.io.InputStream inputStream)
          Uploads a file to the session workspace.
 java.util.List<ValidationError> validateDataSet(NewDataSetDTO newDataset, java.io.File dataSetFile)
          Validate a data set.
 

Method Detail

checkSession

void checkSession()
                  throws InvalidSessionException
Checks whether the session is alive.

Throws:
InvalidSessionException - If the session is not alive.

getSessionToken

java.lang.String getSessionToken()
                                 throws java.lang.IllegalStateException
Returns the session token.

Returns:
The session token for an authenticated user.
Throws:
java.lang.IllegalStateException - Thrown if the user has not yet been authenticated.

getDataSet

IDataSetDss getDataSet(java.lang.String code)
                       throws java.lang.IllegalStateException,
                              EnvironmentFailureException
Get a proxy to the data set designated by the given data set code.

Throws:
java.lang.IllegalStateException - Thrown if the user has not yet been authenticated.
EnvironmentFailureException - Thrown in cases where it is not possible to connect to the server.

putDataSet

IDataSetDss putDataSet(NewDataSetDTO newDataset,
                       java.io.File dataSetFile)
                       throws java.lang.IllegalStateException,
                              EnvironmentFailureException,
                              ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked
Upload a new data set to the DSS.

Parameters:
newDataset - The new data set that should be registered
dataSetFile - A file or folder containing the data
Returns:
A proxy to the newly added data set
Throws:
java.lang.IllegalStateException - Thrown if the user has not yet been authenticated.
EnvironmentFailureException - Thrown in cases where it is not possible to connect to the server.
ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked - If the file transfer fails.

putFileToSessionWorkspace

void putFileToSessionWorkspace(java.lang.String filePath,
                               java.io.InputStream inputStream)
                               throws ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked
Uploads a file to the session workspace.

Parameters:
filePath - The path (directory and name) of the file to upload.
inputStream - The content of the file to upload.
Throws:
ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked - If the file transfer fails.

putFileToSessionWorkspace

void putFileToSessionWorkspace(java.lang.String directory,
                               java.io.File file)
                               throws ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked
Uploads a file to the session workspace.

Parameters:
directory - The directory in the session workspace where the file should be uploaded.
file - The file to upload.
Throws:
ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked - If the file cannot be written.

getFileFromSessionWorkspace

java.io.InputStream getFileFromSessionWorkspace(java.lang.String filePath)
                                                throws ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked
Downloads a file from the session workspace.

Parameters:
filePath - The path (directory and name) of the file to download.
Returns:
outputStream The content of the file to download.
Throws:
ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked - If the file does not exist, is a directory or cannot be opened.

getFileFromSessionWorkspace

void getFileFromSessionWorkspace(java.lang.String filePath,
                                 java.io.File localFile)
                                 throws ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked
Downloads a file from the session workspace.

Parameters:
filePath - The path (directory and name) of the file to download.
localFile - The local file to write the file from the session workspace to.
Throws:
ch.systemsx.cisd.base.exceptions.IOExceptionUnchecked - If the file does not exist.

deleteSessionWorkspaceFile

boolean deleteSessionWorkspaceFile(java.lang.String path)
Delete a file or directory in the session workspace.

Returns:
true if the path doesn't exist anymore.

validateDataSet

java.util.List<ValidationError> validateDataSet(NewDataSetDTO newDataset,
                                                java.io.File dataSetFile)
                                                throws java.lang.IllegalStateException,
                                                       EnvironmentFailureException
Validate a data set.

Parameters:
newDataset - The new data set that should be registered
dataSetFile - A file or folder containing the data
Returns:
A list of validation errors. The list is empty if there were no validation errors.
Throws:
java.lang.IllegalStateException - Thrown if the user has not yet been authenticated.
EnvironmentFailureException - Thrown in cases where it is not possible to connect to the server.

extractMetadata

java.util.Map<java.lang.String,java.lang.String> extractMetadata(NewDataSetDTO newDataset,
                                                                 java.io.File dataSetFile)
                                                                 throws java.lang.IllegalStateException,
                                                                        EnvironmentFailureException
Tries to extract the data set property key-values (metadata) from the data. The extracted metadata can be used by clients to minimize the input needed when uploading data sets.

Parameters:
newDataset - The new data set that should be registered
dataSetFile - A file or folder containing the data
Returns:
A map of extracted property-key values
Throws:
java.lang.IllegalStateException - Thrown if the user has not yet been authenticated.
EnvironmentFailureException - Thrown in cases where it is not possible to connect to the server.

logout

void logout()
Logs the current user out.