org.icatproject.ids.client

Class IdsClient

java.lang.Object

org.icatproject.ids.client.IdsClient

public class IdsClient
extends Object

Client to communicate with IDS server

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	IdsClient.Flag Defines packaging options
class	IdsClient.ServiceStatus Returned by the getServiceStatus call
static class	IdsClient.Status Values to be returned by the getStatus() calls.

Constructor Summary

Constructors

Constructor and Description
IdsClient(URL idsUrl)

Method Summary

Methods

Modifier and Type	Method and Description
void	archive(String sessionId, DataSelection dataSelection) Archive data specified by the dataSelection.
void	delete(String sessionId, DataSelection dataSelection) Delete data specified by the dataSelection.
InputStream	getData(String sessionId, DataSelection dataSelection, IdsClient.Flag flags, String outname, long offset) Get the data specified by the dataSelection.
InputStream	getData(String preparedId, String outname, long offset) Get the data using the preparedId returned by a call to prepareData
URL	getDataUrl(String sessionId, DataSelection dataSelection, IdsClient.Flag flags, String outname) Get the URL to retrieve the data specified by the dataSelection.
URL	getDataUrl(String preparedId, String outname) Get the URL to retrieve the data specified by the preparedId returned by a call to prepareData
IdsClient.ServiceStatus	getServiceStatus(String sessionId) Return a ServiceStatus object to understand what the IDS is doing.
IdsClient.Status	getStatus(String sessionId, DataSelection dataSelection) Return the status of the data specified by the dataSelection.
boolean	isPrepared(String preparedId) Returns true if the data identified by the preparedId returned by a call to prepareData is ready.
void	ping() Check that the server is alive and is an IDS server
String	prepareData(String sessionId, DataSelection dataSelection, IdsClient.Flag flags) Prepare data for a subsequent getData call.
Long	put(String sessionId, InputStream inputStream, String name, long datasetId, long datafileFormatId, String description) Put the data in the inputStream into a data file and catalogue it.
Long	put(String sessionId, InputStream inputStream, String name, long datasetId, long datafileFormatId, String description, String doi, Date datafileCreateTime, Date datafileModTime) Put the data in the inputStream into a data file and catalogue it.
void	restore(String sessionId, DataSelection dataSelection) Restore data specified by the dataSelection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IdsClient

public IdsClient(URL idsUrl)

Parameters:

idsUrl - The URL of the ids server host. This should be of the form https://example.com:443.

Method Detail

archive

public void archive(String sessionId,
           DataSelection dataSelection)
             throws NotImplementedException,
                    BadRequestException,
                    InsufficientPrivilegesException,
                    InternalException,
                    NotFoundException

Archive data specified by the dataSelection.

Parameters:

sessionId - A valid ICAT session ID

dataSelection - A data selection object that must not be empty

Throws:

NotImplementedException

BadRequestException

InsufficientPrivilegesException

InternalException

NotFoundException

delete

public void delete(String sessionId,
          DataSelection dataSelection)
            throws NotImplementedException,
                   BadRequestException,
                   InsufficientPrivilegesException,
                   InternalException,
                   NotFoundException,
                   DataNotOnlineException

Delete data specified by the dataSelection.

Parameters:

sessionId - A valid ICAT session ID

dataSelection - A data selection object that must not be empty

Throws:

NotImplementedException

BadRequestException

InsufficientPrivilegesException

InternalException

NotFoundException

DataNotOnlineException

getData

public InputStream getData(String sessionId,
                  DataSelection dataSelection,
                  IdsClient.Flag flags,
                  String outname,
                  long offset)
                    throws NotImplementedException,
                           BadRequestException,
                           InsufficientPrivilegesException,
                           NotFoundException,
                           InternalException,
                           DataNotOnlineException

Get the data specified by the dataSelection.

Parameters:

sessionId - A valid ICAT session ID

dataSelection - A data selection object that must not be empty

flags - To select packing options

outname - The name of the file. If it is in .zip format the .zip extension will be added if not present.

offset - Skip this number of bytes in the returned stream

Returns:

an InputStream to allow the data to be read

Throws:

NotImplementedException

BadRequestException

InsufficientPrivilegesException

NotFoundException

InternalException

DataNotOnlineException

getData

public InputStream getData(String preparedId,
                  String outname,
                  long offset)
                    throws NotImplementedException,
                           BadRequestException,
                           InsufficientPrivilegesException,
                           NotFoundException,
                           InternalException,
                           DataNotOnlineException

Get the data using the preparedId returned by a call to prepareData

Parameters:

preparedId - A valid preparedId returned by a call to prepareData

outname - The name of the file. If it is in .zip format the .zip extension will be added if not present.

offset - Skip this number of bytes in the returned stream

Returns:

an InputStream to allow the data to be read

Throws:

NotImplementedException

BadRequestException

InsufficientPrivilegesException

NotFoundException

InternalException

DataNotOnlineException

getDataUrl

public URL getDataUrl(String sessionId,
             DataSelection dataSelection,
             IdsClient.Flag flags,
             String outname)

Get the URL to retrieve the data specified by the dataSelection.

Parameters:

sessionId - A valid ICAT session ID

dataSelection - A data selection object that must not be empty

flags - To select packing options

outname - The name of the file. If it is in .zip format the .zip extension will be added if not present.

Returns:

the URL to allow the data to be read

getDataUrl

public URL getDataUrl(String preparedId,
             String outname)

Get the URL to retrieve the data specified by the preparedId returned by a call to prepareData

Parameters:

preparedId - A valid preparedId returned by a call to prepareData

outname - The name of the file. If it is in .zip format the .zip extension will be added if not present.

Returns:

the URL to allow the data to be read

getServiceStatus

public IdsClient.ServiceStatus getServiceStatus(String sessionId)
                                         throws InternalException,
                                                InsufficientPrivilegesException

Return a ServiceStatus object to understand what the IDS is doing. To use this call, the user represented by the sessionId must be in the set of rootUserNames defined in the IDS configuration.

Parameters:

sessionId - A valid ICAT session ID of a user in the IDS rootUserNames set.

Returns:

a ServiceStatus object

Throws:

InternalException

InsufficientPrivilegesException

getStatus

public IdsClient.Status getStatus(String sessionId,
                         DataSelection dataSelection)
                           throws BadRequestException,
                                  NotFoundException,
                                  InsufficientPrivilegesException,
                                  InternalException,
                                  NotImplementedException

Return the status of the data specified by the dataSelection.

Parameters:

sessionId - A valid ICAT session ID

dataSelection - A data selection object that must not be empty

Returns:

the status

Throws:

NotImplementedException

BadRequestException

InsufficientPrivilegesException

NotFoundException

InternalException

isPrepared

public boolean isPrepared(String preparedId)
                   throws BadRequestException,
                          NotFoundException,
                          InternalException,
                          NotImplementedException

Returns true if the data identified by the preparedId returned by a call to prepareData is ready.

Parameters:

preparedId - the id returned by a call to prepareData

Returns:

true if ready otherwise false.

Throws:

BadRequestException

NotFoundException

InternalException

NotImplementedException

ping

public void ping()
          throws InternalException,
                 NotFoundException

Check that the server is alive and is an IDS server

Throws:

InternalException

NotFoundException - If the server gives an unexpected response

prepareData

public String prepareData(String sessionId,
                 DataSelection dataSelection,
                 IdsClient.Flag flags)
                   throws NotImplementedException,
                          BadRequestException,
                          InsufficientPrivilegesException,
                          NotFoundException,
                          InternalException

Prepare data for a subsequent getData call.

Parameters:

sessionId - A valid ICAT session ID

dataSelection - A data selection object that must not be empty

flags - To select packing options

Returns:

a prepareId to be used in calls to getData and getStatus

Throws:

NotImplementedException

BadRequestException

InsufficientPrivilegesException

NotFoundException

InternalException

put

public Long put(String sessionId,
       InputStream inputStream,
       String name,
       long datasetId,
       long datafileFormatId,
       String description)
         throws BadRequestException,
                NotFoundException,
                InternalException,
                InsufficientPrivilegesException,
                NotImplementedException,
                DataNotOnlineException,
                InsufficientStorageException

Put the data in the inputStream into a data file and catalogue it. The client generates a checksum which is compared to that produced by the server to detect any transmission errors.

Parameters:

sessionId - A valid ICAT session ID

inputStream - the input stream providing the data to store

name - the name to associate with the data file

datasetId - the id of the ICAT "Dataset" which should own the data file

datafileFormatId - the id of the ICAT "DatafileForat" to be associated with the data file

description - Free text to associate with the data file (may be null)

Returns:

the ICAT id of the "Datafile" object created

Throws:

BadRequestException

NotFoundException

InternalException

InsufficientPrivilegesException

NotImplementedException

DataNotOnlineException

InsufficientStorageException

put

public Long put(String sessionId,
       InputStream inputStream,
       String name,
       long datasetId,
       long datafileFormatId,
       String description,
       String doi,
       Date datafileCreateTime,
       Date datafileModTime)
         throws BadRequestException,
                NotFoundException,
                InternalException,
                InsufficientPrivilegesException,
                NotImplementedException,
                DataNotOnlineException,
                InsufficientStorageException

Put the data in the inputStream into a data file and catalogue it. The client generates a checksum which is compared to that produced by the server to detect any transmission errors.

Parameters:

sessionId - A valid ICAT session ID

inputStream - the input stream providing the data to store

name - the name to associate with the data file

datasetId - the id of the ICAT "Dataset" which should own the data file

datafileFormatId - the id of the ICAT "DatafileForat" to be associated with the data file

description - Free text to associate with the data file. (may be null)

doi - The Digital Object Identifier to associate with the data file. (may be null)

datafileCreateTime - the time to record as the creation time of the datafile. If null the current time as known to the IDS server will be stored.

datafileModTime - the time to record as the modification time of the datafile. If null the value of the datafileCreateTime or the current time as known to the IDS server if that value is also null will be stored.

Returns:

the ICAT id of the "Datafile" object created.

Throws:

BadRequestException

NotFoundException

InternalException

InsufficientPrivilegesException

NotImplementedException

DataNotOnlineException

InsufficientStorageException

restore

public void restore(String sessionId,
           DataSelection dataSelection)
             throws NotImplementedException,
                    BadRequestException,
                    InsufficientPrivilegesException,
                    InternalException,
                    NotFoundException

Restore data specified by the dataSelection.

Parameters:

sessionId - A valid ICAT session ID

dataSelection - A data selection object that must not be empty

Throws:

NotImplementedException

BadRequestException

InsufficientPrivilegesException

InternalException

NotFoundException