edu.ucsb.nceas.metacat.client.rest

Interface MetacatRest

All Known Implementing Classes:

MetacatRestClient

public interface MetacatRest

This interface provides methods for initializing and logging in to a Metacat REST API, and then querying, reading, transforming, inserting, updating and deleting documents from that server.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DELETE HTTP Verb DELETE
static java.lang.String	FUNCTION_KEYWORD Function keyword
static java.lang.String	FUNCTION_NAME_GETALLDOCS Function name for getalldocids function
static java.lang.String	FUNCTION_NAME_GETNEXTOBJ Function name for getnextobject function
static java.lang.String	FUNCTION_NAME_GETNEXTREV Function name for getnextrevision function
static java.lang.String	FUNCTION_NAME_INSERT Function name for insert function
static java.lang.String	FUNCTION_NAME_ISREGISTERED Function name for isregistered function
static java.lang.String	FUNCTION_NAME_LOGIN Function name for login function
static java.lang.String	FUNCTION_NAME_LOGOUT Function name for logout function
static java.lang.String	FUNCTION_NAME_UPDATE Function name for update function
static java.lang.String	GET HTTP Verb GET
static java.lang.String	POST HTTP Verb POST
static java.lang.String	PUT HTTP Verb PUT
static java.lang.String	RESOURCE_IDENTIFIER API IDENTIFIER Resource which controls object unique identifier operations
static java.lang.String	RESOURCE_OBJECTS API OBJECTS Resource which handles with document operations
static java.lang.String	RESOURCE_SESSION API SESSION Resource which handles with user session operations

Method Summary

Modifier and Type	Method and Description
java.lang.String	addLSID(java.lang.String identifierId) Adds identifierId (Metacat Server does not support it!)
java.io.Reader	authenticatedGetObject(java.lang.String docid, java.lang.String outputFile) Read XML document from server session, accessed by docid, and returned as a Reader.
java.io.Reader	authenticatedQuery(java.io.Reader xmlQuery)
java.lang.String	create(java.lang.String docid, java.io.Reader xmlDocument) Create an XML document into the repository, making it available for searching using the query() methods.
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 outputFile) 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 metacat-compatible query document, and return the 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 into the repository, making it available for searching using the query() methods.

Field Detail

GET

static final java.lang.String GET

HTTP Verb GET

See Also:

Constant Field Values

POST

static final java.lang.String POST

HTTP Verb POST

See Also:

Constant Field Values

PUT

static final java.lang.String PUT

HTTP Verb PUT

See Also:

Constant Field Values

DELETE

static final java.lang.String DELETE

HTTP Verb DELETE

See Also:

Constant Field Values

RESOURCE_OBJECTS

static final java.lang.String RESOURCE_OBJECTS

API OBJECTS Resource which handles with document operations

See Also:

Constant Field Values

RESOURCE_SESSION

static final java.lang.String RESOURCE_SESSION

API SESSION Resource which handles with user session operations

See Also:

Constant Field Values

RESOURCE_IDENTIFIER

static final java.lang.String RESOURCE_IDENTIFIER

API IDENTIFIER Resource which controls object unique identifier operations

See Also:

Constant Field Values

FUNCTION_KEYWORD

static final java.lang.String FUNCTION_KEYWORD

Function keyword

See Also:

Constant Field Values

FUNCTION_NAME_LOGIN

static final java.lang.String FUNCTION_NAME_LOGIN

Function name for login function

See Also:

Constant Field Values

FUNCTION_NAME_LOGOUT

static final java.lang.String FUNCTION_NAME_LOGOUT

Function name for logout function

See Also:

Constant Field Values

FUNCTION_NAME_ISREGISTERED

static final java.lang.String FUNCTION_NAME_ISREGISTERED

Function name for isregistered function

See Also:

Constant Field Values

FUNCTION_NAME_GETALLDOCS

static final java.lang.String FUNCTION_NAME_GETALLDOCS

Function name for getalldocids function

See Also:

Constant Field Values

FUNCTION_NAME_GETNEXTREV

static final java.lang.String FUNCTION_NAME_GETNEXTREV

Function name for getnextrevision function

See Also:

Constant Field Values

FUNCTION_NAME_GETNEXTOBJ

static final java.lang.String FUNCTION_NAME_GETNEXTOBJ

Function name for getnextobject function

See Also:

Constant Field Values

FUNCTION_NAME_INSERT

static final java.lang.String FUNCTION_NAME_INSERT

Function name for insert function

See Also:

Constant Field Values

FUNCTION_NAME_UPDATE

static final java.lang.String FUNCTION_NAME_UPDATE

Function name for update function

See Also:

Constant Field Values

Method Detail

login

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

Throws:

MetacatInaccessibleException

java.io.IOException

create

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

Create an XML document into the repository, making it available for searching using the query() methods.

Parameters:

docid - the docid to insert the document

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

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

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

Update an XML document into the repository, making it available for searching using the query() methods.

Parameters:

docid - the docid to insert the document

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

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

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

Delete an XML document in the repository.

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

setContextRootUrl

void setContextRootUrl(java.lang.String contextRootUrl)

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

Parameters:

metacatUrl - the URL for the metacat server

getSessionId

java.lang.String getSessionId()

Get the session identifier for this session.

setSessionId

void setSessionId(java.lang.String sessionId)

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.).

Parameters:

String - the sessionId from a previously established session

getNextObject

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.

Parameters:

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

Throws:

MetacatException - when an error occurs

getNextRevision

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.

Parameters:

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

Throws:

MetacatException

getAllDocids

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

Parameters:

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

Throws:

MetacatException - when an error occurs

isRegistered

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

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

Parameters:

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

Throws:

MetacatException - when an error occurs

addLSID

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

Adds identifierId (Metacat Server does not support it!)

Parameters:

identifierId - String the given docid you want to use.

Throws:

MetacatException - when an error occurs