org.icatproject.icat.client

Class Session

java.lang.Object

org.icatproject.icat.client.Session

public class Session
extends Object

A RESTful ICAT session.

The exportMetaData and ImportMetaData call make use of a special format to represent ICAT data efficiently. The file may contain line starting with a # sign. The first non-comment line contains the version number of the file format with major and minor parts. Each entity type is preceded by a blank line line followed by a one line entity descriptor and then a line for each entity of that type.

For example:

 #  Version of file format
 1.0
 
 Facility ( name:0, daysUntilRelease:1, createId:2, createTime:3)
 "Test port facility", 90, "Zorro", 1920-05-16T16:58:26.12Z
 
 InvestigationType (facility(name:0), name:1)
 "Test port facility", "atype"
 "Test port facility", "btype"
 
 Investigation(facility(name:0), name:1, visitId:2, type(facility(name:0), name:3), title:4)
 "Test port facility", "expt1", "one", "atype", "a title"
 

The entity descriptor starts with the name of the entity type followed by a comma separated list attribute of field names held inside parentheses. It is not necessary to include those which you don't wish to set as any that are not present and are allowed to be null will be set to null when importing. So we see that this file will create a Facility with fields: name, daysUntilRelease, createId and createTime. Following the field name is a colon and an integer showing the offset to the data field in each of the next set of rows. So a facility will be created with a name of "Test port facility" and with 90 daysUntilRelease. All strings must be enclosed in double quotes; to represent a a double quote within the string then it must be escaped with a back slash: \". The following escape sequences are available:

• \t : tab
• \r : carriage return
• \f : form feed
• \b : bell
• \n : new line
• \" : "
• \' : ' (Not really needed)
• \\ : \

True, false and null literals are not case sensitive. The last two fields of the facility are createId and createTime. If you specify that you want all attributes and you are a "root user" then the values of createId and createTime will be respected otherwise the current time is used and the id is that of the user doing the import. Timestamp literals follow ISO 8601 and support fractional seconds and time zones. If the time zone is omitted it is interpreted as local time.

Now consider the InvestigationType for which we need to specify the facility to which it belongs and its name. The facility cannot be described by its id because we don't know what it is. So instead we list in parentheses the field names that define it. So name:0 is the name of the facility and name:1 is the name of the InvestigationType.

The next line shows the convenience of this syntax. The investigation has a facility (identified by its name:0) and the name:1 of the investigation and the visitId but it also has a type which is identified a facility (identified by its name:0) and by the name:3 of the type. Finally it has a title:4 field. Note that name:0 is used twice as in this case the investigation belongs to the same facility as its type. This works fine as long as we deal with entity types which have key fields. This is shown in the next snippet from an import file:

 DataCollection(?:0)
 "a"
 "b"
 "c"
 
 DataCollectionDatafile(datafile(dataset(investigation(facility(name:0), name:1, visitId:2), name:3), name:4), dataCollection(?:5))
 "Test port facility", "expt1", "one", "ds1", "df1",  "a"
 "Test port facility", "expt1", "one", "ds1", "df2",  "b"
 
 Job(application(facility(name:0), name:1, version:2), inputDataCollection(?:3), outputDataCollection(?:4))
 "Test port facility", "aprog", "1.2.3", "a", "b"
 

Here we have the DataCollection which we imagine to be identified by the anonymous variable "?". This section of the file will create three DataCollection entries which we shall remember for the duration of the import process as "a", "b" and "c".

DataCollectionDatafiles are then associated with DataCollections "a" and "b" and a job is created with one DataCollection as input and one as output.

When performing export the same format is used however some values will be repeated - for example the facility name will appear many times in most rows.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Session.Attributes Control the attributes to be imported or exported
static class	Session.DuplicateAction Control the action when a duplicate entry is encountered on import

Method Summary

Modifier and Type	Method and Description
long	cloneEntity(String name, long id, Map<String,String> keys) Clone an entity and return the id of the clone
List<Long>	create(String entities) Deprecated. Replace by write(String)
void	delete(String entities) Delete ICAT entities specified by a Json String.
InputStream	exportMetaData(Session.Attributes attributes) Export all metadata from ICAT.
InputStream	exportMetaData(String query, Session.Attributes attributes) Export metadata from ICAT as specified in the query
String	get(String query, long id) Carry out an ICAT get.
String	getId() Return the sessionId
double	getRemainingMinutes() Return the time remaining in the session in minutes
String	getUserName() Return the user name corresponding to the session.
void	importMetaData(Path path, Session.DuplicateAction duplicateAction, Session.Attributes attributes) Import metadata into ICAT for a file specified by a Path
String	list(String path)
void	logout() Logout of the session after which the session cannot be re-used
void	luceneClear() Clear the lucene populating list
void	luceneCommit() Force a commit of the lucene database
List<String>	luceneGetPopulating() Return a list of class names for which population is going on
void	lucenePopulate(String entityName, long minid) Clear and repopulate lucene documents for the specified entityName.
void	refresh() Refresh the session by resetting the time remaining
String	search(String query) Carry out an ICAT search.
String	searchDatafiles(String user, String text, Date lower, Date upper, List<ParameterForLucene> parameters, int maxResults) Return a set of data files satisfying the constraints
String	searchDatasets(String user, String text, Date lower, Date upper, List<ParameterForLucene> parameters, int maxResults) Return a set of datasets satisfying the constraints
String	searchInvestigations(String user, String text, Date lower, Date upper, List<ParameterForLucene> parameters, List<String> samples, String userFullName, int maxResults) Return a set of investigations satisfying the constraints
void	waitMillis(long ms) Wait for the specified number of milliseconds and return.
List<Long>	write(String entities) Write (create or update) ICAT entities from a Json String.

Methods inherited from class java.lang.Object

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

Method Detail

write

public List<Long> write(String entities)
                 throws IcatException

Write (create or update) ICAT entities from a Json String.

Parameters:

entities - Json representation of ICAT entities and their related entities. If there is only one, the outer "[" "]" may be omitted.

Returns:

the ids of the top level entities created

Throws:

IcatException - For various ICAT errors

create

@Deprecated
public List<Long> create(String entities)
                              throws IcatException

Deprecated. Replace by write(String)

Create ICAT entities from a Json String.

Parameters:

entities - Json representation of ICAT entities and their related entities. If there is only one, the outer "[" "]" may be omitted.

Returns:

the ids of the top level entities created

Throws:

IcatException - For various ICAT errors

delete

public void delete(String entities)
            throws IcatException

Delete ICAT entities specified by a Json String.

Parameters:

entities - Json representation of ICAT entities. If there is only one the outer "[" "]" may be omitted.

Throws:

IcatException - For various ICAT errors

exportMetaData

public InputStream exportMetaData(Session.Attributes attributes)
                           throws IcatException

Export all metadata from ICAT.

Parameters:

attributes - which attributes to export. If you don't plan to importMetaData as a "root user" there is no point in using Session.Attributes.ALL and Session.Attributes.USER is to be preferred.

Returns:

an OutputStream. The structure of the OutputStream is described at Session

Throws:

IcatException - For various ICAT errors

exportMetaData

public InputStream exportMetaData(String query,
                                  Session.Attributes attributes)
                           throws IcatException

Export metadata from ICAT as specified in the query

Parameters:

query - a normal ICAT query which may have an INCLUDE clause. This is used to define the metadata to export.

attributes - which attributes to export. If you don't plan to importMetaData as a "root user" there is no point in using Session.Attributes.ALL and Session.Attributes.USER is to be preferred.

Returns:

an OutputStream. The structure of the OutputStream is described at Session

Throws:

IcatException - For various ICAT errors

getRemainingMinutes

public double getRemainingMinutes()
                           throws IcatException

Return the time remaining in the session in minutes

Returns:

the time remaining

Throws:

IcatException - For various ICAT errors

getId

public String getId()

Return the sessionId

Returns:

the sessionId

getUserName

public String getUserName()
                   throws IcatException

Return the user name corresponding to the session.

Returns:

the user name

Throws:

IcatException - For various ICAT errors

importMetaData

public void importMetaData(Path path,
                           Session.DuplicateAction duplicateAction,
                           Session.Attributes attributes)
                    throws IcatException

Import metadata into ICAT for a file specified by a Path

Parameters:

path - the path of the import file. The structure of the import file is described at Session

duplicateAction - what to do when a duplicate is encountered

attributes - which attributes to import. Only a "root user" can specify Session.Attributes.ALL to respect those fields specified in the import file which are not settable by normal users: createId, createTime, modId and modTime. This is to allow an ICAT to be accurately exported and imported.

Throws:

IcatException - For various ICAT errors

logout

public void logout()
            throws IcatException

Logout of the session after which the session cannot be re-used

Throws:

IcatException - For various ICAT errors

refresh

public void refresh()
             throws IcatException

Refresh the session by resetting the time remaining

Throws:

IcatException - For various ICAT errors

search

public String search(String query)
              throws IcatException

Carry out an ICAT search. The data are returned as a Json string Note that this call is experimental and should not be relied upon to continue in its present form.

Parameters:

query - a normal ICAT query with optional INCLUDE and LIMIT clauses.

Returns:

the Json holding the results

Throws:

IcatException - For various ICAT errors

get

public String get(String query,
                  long id)
           throws IcatException

Carry out an ICAT get. The data are returned as a Json string Note that this call is experimental and should not be relied upon to continue in its present form.

Parameters:

query - a normal ICAT get query with an optional INCLUDE clause.

id - the id of the entity to be returned

Returns:

the Json holding the result

Throws:

IcatException - For various ICAT errors

searchInvestigations

public String searchInvestigations(String user,
                                   String text,
                                   Date lower,
                                   Date upper,
                                   List<ParameterForLucene> parameters,
                                   List<String> samples,
                                   String userFullName,
                                   int maxResults)
                            throws IcatException

Return a set of investigations satisfying the constraints

Parameters:

user - If not null must exactly match the name of a user related via the investigation user to the investigation.

text - If not null a text search (with ANDs ORs etc) for any text in the investigation fields. This is understood by the lucene parser but avoid trying to use fields.

lower - If not null investigation end date must be greater than or equal to this.

upper - If not null investigation start date must be less than or equal to this.

parameters - If not null all the parameters must match.

samples - If not null all the specified samples, using a text search (with ANDs ORs etc) must be related to the investigation. This is understood by the lucene parser but avoid trying to use fields.

userFullName - If not null a text search is made against the full name of a user related via the investigation user to the investigation. This is understood by the lucene parser but avoid trying to use fields.

maxResults - The maximum number of results to return.

Returns:

the Json holding the result.

Throws:

IcatException - For various ICAT errors.

searchDatasets

public String searchDatasets(String user,
                             String text,
                             Date lower,
                             Date upper,
                             List<ParameterForLucene> parameters,
                             int maxResults)
                      throws IcatException

Return a set of datasets satisfying the constraints

Parameters:

user - If not null must exactly match the name of a user related via the investigation user and the investigation to the data set.

text - If not null a text search (with ANDs ORs etc) for any text in the data set fields. This is understood by the lucene parser but avoid trying to use fields.

lower - If not null data set end date must be greater than or equal to this.

upper - If not null data set start date must be less than or equal to this.

parameters - If not null all the parameters must match.

maxResults - The maximum number of results to return.

Returns:

the Json holding the result.

Throws:

IcatException - For various ICAT errors.

luceneClear

public void luceneClear()
                 throws IcatException

Clear the lucene populating list

Throws:

IcatException - For various ICAT errors.

luceneCommit

public void luceneCommit()
                  throws IcatException

Force a commit of the lucene database

Throws:

IcatException - For various ICAT errors.

lucenePopulate

public void lucenePopulate(String entityName,
                           long minid)
                    throws IcatException

Clear and repopulate lucene documents for the specified entityName.

Parameters:

entityName - the name of the entity

Throws:

IcatException - For various ICAT errors.

luceneGetPopulating

public List<String> luceneGetPopulating()
                                 throws IcatException

Return a list of class names for which population is going on

Returns:

list of class names

Throws:

IcatException - For various ICAT errors.

searchDatafiles

public String searchDatafiles(String user,
                              String text,
                              Date lower,
                              Date upper,
                              List<ParameterForLucene> parameters,
                              int maxResults)
                       throws IcatException

Return a set of data files satisfying the constraints

Parameters:

user - If not null must exactly match the name of a user related via the investigation user and the investigation to the data set.

text - If not null a text search (with ANDs ORs etc) for any text in the data file fields. This is understood by the lucene parser but avoid trying to use fields.

lower - If not null data file date must be greater than or equal to this.

upper - If not null data file date must be less than or equal to thilist of class namess.

parameters - If not null all the parameters must match.

maxResults - The maximum number of results to return.

Returns:

the Json holding the result.

Throws:

IcatException - For various ICAT errors.

cloneEntity

public long cloneEntity(String name,
                        long id,
                        Map<String,String> keys)
                 throws IcatException

Clone an entity and return the id of the clone

Parameters:

name - the name of the type of entity

id - the id value of the entity to be cloned

keys - a map of field names and values to be different in the clone

Returns:

the id of the clone

Throws:

IcatException - For various ICAT errors.

waitMillis

public void waitMillis(long ms)
                throws IcatException

Wait for the specified number of milliseconds and return. This is only used in testing

Parameters:

ms - number of milliseconds to wait

Throws:

IcatException - For various ICAT errors.

list

public String list(String path)
            throws IcatException

Parameters:

path - input path to find contents of

Returns:

json describing the contents

Throws:

IcatException