edu.ucsb.nceas.metacat.client.rest

Class MetacatRestClient

java.lang.Object

edu.ucsb.nceas.metacat.client.rest.MetacatRestClient

All Implemented Interfaces:

MetacatRest

public class MetacatRestClient
extends java.lang.Object
implements MetacatRest

Field Summary

Fields inherited from interface edu.ucsb.nceas.metacat.client.rest.MetacatRest

DELETE, FUNCTION_KEYWORD, FUNCTION_NAME_GETALLDOCS, FUNCTION_NAME_GETNEXTOBJ, FUNCTION_NAME_GETNEXTREV, FUNCTION_NAME_INSERT, FUNCTION_NAME_ISREGISTERED, FUNCTION_NAME_LOGIN, FUNCTION_NAME_LOGOUT, FUNCTION_NAME_UPDATE, GET, POST, PUT, RESOURCE_IDENTIFIER, RESOURCE_OBJECTS, RESOURCE_SESSION

Constructor Summary

Constructors

Constructor and Description
MetacatRestClient(java.lang.String contextRootUrl) Constructor to create a new instance.

Method Summary

Modifier and Type	Method and Description
java.lang.String	addLSID(java.lang.String identifierId) Adds identifierId
java.io.Reader	authenticatedGetObject(java.lang.String docid, java.lang.String outFile) Read XML document from server session, accessed by docid, and returned as a Reader.
java.io.Reader	authenticatedQuery(java.io.Reader xmlQuery) Query (as an authenticated user) the metacat document store with the given Ecogrid-compatible query document and return the Ecogrid result set as a Reader.
java.lang.String	create(java.lang.String docid, java.io.Reader xmlDocument) Create an XML document in the repository.
java.lang.String	deleteObject(java.lang.String docid) Delete an XML document in the repository.
java.util.Vector<java.lang.String>	getAllDocids(java.lang.String scope) return a list of all docids that match a given scope.
java.lang.String	getNextObject(java.lang.String scope) Return the highest document id for a given scope.
int	getNextRevision(java.lang.String identifierId) The method will return the latest revision in metacat server for a given document id.
java.io.Reader	getObject(java.lang.String docid, java.lang.String outFile) Read a public XML document , accessed by docid, and returned as a Reader.
java.lang.String	getSessionId() Get the session identifier for this session.
boolean	isRegistered(java.lang.String identifierId) return true of the given docid is registered, false if not
java.lang.String	login(java.lang.String username, java.lang.String password) Method used to log in to a metacat server through REST API.
java.lang.String	logout() Method used to log out a metacat server.
java.io.Reader	query(java.io.Reader xmlQuery) Query the metacat document store with the given Ecogrid-compatible query document and return the Ecogrid result set as a Reader.
void	setContextRootUrl(java.lang.String contextRootUrl) When the MetacatFactory creates an instance it needs to set the MetacatUrl to which connections should be made.
void	setSessionId(java.lang.String sessionId) Set the session identifier for this session.
java.lang.String	update(java.lang.String docid, java.io.Reader xmlDocument) Update an XML document in the repository, replacing an existing document.

Methods inherited from class java.lang.Object

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

Constructor Detail

MetacatRestClient

public MetacatRestClient(java.lang.String contextRootUrl)

Constructor to create a new instance.

Method Detail

login

public java.lang.String login(java.lang.String username,
                              java.lang.String password)
                       throws MetacatAuthException,
                              MetacatInaccessibleException

Method used to log in to a metacat server through REST API. Implementations will need to cache a cookie value to make the session persistent. Each time a call is made to one of the other methods (e.g., read), the cookie will need to be passed back to the metacat server along with the request.

Specified by:

login in interface MetacatRest

Parameters:

username - the username of the user, like an LDAP DN

password - the password for that user for authentication

Returns:

the response string from metacat in XML format

Throws:

MetacatAuthException - when the username/password could not be authenticated

MetacatInaccessibleException

logout

public java.lang.String logout()
                        throws MetacatInaccessibleException,
                               MetacatException

Method used to log out a metacat server. The Metacat server will end the session when this call is invoked.

Specified by:

logout in interface MetacatRest

Returns:

the response string from metacat in XML format

Throws:

MetacatInaccessibleException - when the metacat server can not be reached or does not respond

MetacatException

getObject

public java.io.Reader getObject(java.lang.String docid,
                                java.lang.String outFile)
                         throws InsufficientKarmaException,
                                MetacatInaccessibleException,
                                DocumentNotFoundException,
                                MetacatException

Read a public XML document , accessed by docid, and returned as a Reader.

Specified by:

getObject in interface MetacatRest

Parameters:

docid - the identifier of the document to be read

outputFile - name of the file to be written to local (optional)

Returns:

a Reader for accessing the document

Throws:

InsufficientKarmaException - when the user has insufficent rights for the operation

MetacatInaccessibleException - when the metacat server can not be reached or does not respond

MetacatException - when the metacat server generates another error

DocumentNotFoundException

authenticatedGetObject

public java.io.Reader authenticatedGetObject(java.lang.String docid,
                                             java.lang.String outFile)
                                      throws InsufficientKarmaException,
                                             MetacatInaccessibleException,
                                             DocumentNotFoundException,
                                             MetacatException

Read XML document from server session, accessed by docid, and returned as a Reader.

Specified by:

authenticatedGetObject in interface MetacatRest

Parameters:

docid - the identifier of the document to be read

outputFile - name of the file to be written to local (optional)

Returns:

a Reader for accessing the document

Throws:

InsufficientKarmaException - when the user has insufficent rights for the operation

MetacatInaccessibleException - when the metacat server can not be reached or does not respond

MetacatException - when the metacat server generates another error

DocumentNotFoundException

query

public java.io.Reader query(java.io.Reader xmlQuery)
                     throws MetacatInaccessibleException,
                            java.io.IOException

Query the metacat document store with the given Ecogrid-compatible query document and return the Ecogrid result set as a Reader.

Specified by:

query in interface MetacatRest

Parameters:

xmlQuery - a Reader for accessing the XML version of the query

Returns:

a Reader for accessing the result set

Throws:

MetacatInaccessibleException

java.io.IOException

authenticatedQuery

public java.io.Reader authenticatedQuery(java.io.Reader xmlQuery)
                                  throws MetacatInaccessibleException,
                                         java.io.IOException

Query (as an authenticated user) the metacat document store with the given Ecogrid-compatible query document and return the Ecogrid result set as a Reader.

Specified by:

authenticatedQuery in interface MetacatRest

Parameters:

xmlQuery - a Reader for accessing the XML version of the query

Returns:

a Reader for accessing the result set

Throws:

MetacatInaccessibleException

java.io.IOException

create

public java.lang.String create(java.lang.String docid,
                               java.io.Reader xmlDocument)
                        throws InsufficientKarmaException,
                               MetacatException,
                               java.io.IOException,
                               MetacatInaccessibleException

Create an XML document in the repository.

Specified by:

create in interface MetacatRest

Parameters:

docid - the docid to insert the document

xmlDocument - a Reader for accessing the XML document to be inserted

isInsert - whether the operation is update or insert

Returns:

the metacat response message

Throws:

InsufficientKarmaException - when the user has insufficent rights for the operation

MetacatInaccessibleException - when the metacat server can not be reached or does not respond

MetacatException - when the metacat server generates another error

java.io.IOException - when there is an error reading the xml document

update

public java.lang.String update(java.lang.String docid,
                               java.io.Reader xmlDocument)
                        throws InsufficientKarmaException,
                               MetacatException,
                               java.io.IOException,
                               MetacatInaccessibleException

Update an XML document in the repository, replacing an existing document.

Specified by:

update in interface MetacatRest

Parameters:

docid - the docid to insert the document

xmlDocument - a Reader for accessing the XML document to be inserted

isInsert - whether the operation is update or insert

Returns:

the metacat response message

Throws:

InsufficientKarmaException - when the user has insufficent rights for the operation

MetacatInaccessibleException - when the metacat server can not be reached or does not respond

MetacatException - when the metacat server generates another error

java.io.IOException - when there is an error reading the xml document

deleteObject

public java.lang.String deleteObject(java.lang.String docid)
                              throws InsufficientKarmaException,
                                     MetacatException,
                                     MetacatInaccessibleException

Delete an XML document in the repository.

Specified by:

deleteObject in interface MetacatRest

Parameters:

docid - the docid to delete

Returns:

the metacat response message

Throws:

InsufficientKarmaException - when the user has insufficent rights for the operation

MetacatInaccessibleException - when the metacat server can not be reached or does not respond

MetacatException - when the metacat server generates another error

getNextObject

public java.lang.String getNextObject(java.lang.String scope)
                               throws MetacatException

Return the highest document id for a given scope. This is used by clients to make it easier to determine the next free identifier in a sequence for a given scope.

Specified by:

getNextObject in interface MetacatRest

Parameters:

scope - String the scope to use for looking up the latest id

Throws:

MetacatException - when an error occurs

getNextRevision

public int getNextRevision(java.lang.String identifierId)
                    throws MetacatException

The method will return the latest revision in metacat server for a given document id. If some error happens, this method will throw an exception.

Specified by:

getNextRevision in interface MetacatRest

Parameters:

identifierId - String the given docid you want to use. the docid it self can have or haven't revision number

Throws:

MetacatException

getAllDocids

public java.util.Vector<java.lang.String> getAllDocids(java.lang.String scope)
                                                throws MetacatException

return a list of all docids that match a given scope. if scope is null return all docids registered in the system

Specified by:

getAllDocids in interface MetacatRest

Parameters:

scope - String the scope to use to limit the docid query

Throws:

MetacatException - when an error occurs

isRegistered

public boolean isRegistered(java.lang.String identifierId)
                     throws MetacatException

return true of the given docid is registered, false if not

Specified by:

isRegistered in interface MetacatRest

Parameters:

scope - String the scope to use to limit the docid query

Throws:

MetacatException - when an error occurs

addLSID

public java.lang.String addLSID(java.lang.String identifierId)
                         throws MetacatException

Adds identifierId

Specified by:

addLSID in interface MetacatRest

Parameters:

identifierId - String the given docid you want to use.

Throws:

MetacatException - when an error occurs

setContextRootUrl

public void setContextRootUrl(java.lang.String contextRootUrl)

Description copied from interface: MetacatRest

When the MetacatFactory creates an instance it needs to set the MetacatUrl to which connections should be made.

Specified by:

setContextRootUrl in interface MetacatRest

getSessionId

public java.lang.String getSessionId()

Description copied from interface: MetacatRest

Get the session identifier for this session.

Specified by:

getSessionId in interface MetacatRest

setSessionId

public void setSessionId(java.lang.String sessionId)

Description copied from interface: MetacatRest

Set the session identifier for this session. This identifier was previously established with a call to login. To continue to use the same session, set the session id before making a call to one of the metacat access methods (e.g., read, query, insert, etc.).

Specified by:

setSessionId in interface MetacatRest