Package 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	Description
static final String	DELETE	HTTP Verb DELETE
static final String	FUNCTION_KEYWORD	Function keyword
static final String	FUNCTION_NAME_GETALLDOCS	Function name for getalldocids function
static final String	FUNCTION_NAME_GETNEXTOBJ	Function name for getnextobject function
static final String	FUNCTION_NAME_GETNEXTREV	Function name for getnextrevision function
static final String	FUNCTION_NAME_INSERT	Function name for insert function
static final String	FUNCTION_NAME_ISREGISTERED	Function name for isregistered function
static final String	FUNCTION_NAME_LOGIN	Function name for login function
static final String	FUNCTION_NAME_LOGOUT	Function name for logout function
static final String	FUNCTION_NAME_UPDATE	Function name for update function
static final String	GET	HTTP Verb GET
static final String	POST	HTTP Verb POST
static final String	PUT	HTTP Verb PUT
static final String	RESOURCE_IDENTIFIER	API IDENTIFIER Resource which controls object unique identifier operations
static final String	RESOURCE_OBJECTS	API OBJECTS Resource which handles with document operations
static final String	RESOURCE_SESSION	API SESSION Resource which handles with user session operations

Method Summary

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

Field Details

GET

static final String GET

HTTP Verb GET

See Also:

• Constant Field Values

POST

static final String POST

HTTP Verb POST

See Also:

• Constant Field Values

PUT

static final String PUT

HTTP Verb PUT

See Also:

• Constant Field Values

DELETE

static final String DELETE

HTTP Verb DELETE

See Also:

• Constant Field Values

RESOURCE_OBJECTS

static final String RESOURCE_OBJECTS

API OBJECTS Resource which handles with document operations

See Also:

• Constant Field Values

RESOURCE_SESSION

static final String RESOURCE_SESSION

API SESSION Resource which handles with user session operations

See Also:

• Constant Field Values

RESOURCE_IDENTIFIER

static final String RESOURCE_IDENTIFIER

API IDENTIFIER Resource which controls object unique identifier operations

See Also:

• Constant Field Values

FUNCTION_KEYWORD

static final String FUNCTION_KEYWORD

Function keyword

See Also:

• Constant Field Values

FUNCTION_NAME_LOGIN

static final String FUNCTION_NAME_LOGIN

Function name for login function

See Also:

• Constant Field Values

FUNCTION_NAME_LOGOUT

static final String FUNCTION_NAME_LOGOUT

Function name for logout function

See Also:

• Constant Field Values

FUNCTION_NAME_ISREGISTERED

static final String FUNCTION_NAME_ISREGISTERED

Function name for isregistered function

See Also:

• Constant Field Values

FUNCTION_NAME_GETALLDOCS

static final String FUNCTION_NAME_GETALLDOCS

Function name for getalldocids function

See Also:

• Constant Field Values

FUNCTION_NAME_GETNEXTREV

static final String FUNCTION_NAME_GETNEXTREV

Function name for getnextrevision function

See Also:

• Constant Field Values

FUNCTION_NAME_GETNEXTOBJ

static final String FUNCTION_NAME_GETNEXTOBJ

Function name for getnextobject function

See Also:

• Constant Field Values

FUNCTION_NAME_INSERT

static final String FUNCTION_NAME_INSERT

Function name for insert function

See Also:

• Constant Field Values

FUNCTION_NAME_UPDATE

static final String FUNCTION_NAME_UPDATE

Function name for update function

See Also:

• Constant Field Values

Method Details

login

String login(String username,
 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

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

Reader getObject(String docid,
 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

Reader authenticatedGetObject(String docid,
 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

Reader query(Reader xmlQuery)
      throws MetacatInaccessibleException,
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

IOException

authenticatedQuery

Reader authenticatedQuery(Reader xmlQuery)
                   throws MetacatInaccessibleException,
IOException

Throws:

MetacatInaccessibleException

IOException

create

String create(String docid,
 Reader xmlDocument)
       throws InsufficientKarmaException,
MetacatException,
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

IOException - when there is an error reading the xml document

update

String update(String docid,
 Reader xmlDocument)
       throws InsufficientKarmaException,
MetacatException,
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

IOException - when there is an error reading the xml document

deleteObject

String deleteObject(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(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

String getSessionId()

Get the session identifier for this session.

setSessionId

void setSessionId(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

String getNextObject(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(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

Vector<String> getAllDocids(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(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

String addLSID(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