Package 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

Modifier and Type	Method	Description
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.