Package edu.ucsb.nceas.metacat.client

Interface Metacat

All Known Implementing Classes:

MetacatClient

public interface Metacat

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

Method Summary

Modifier and Type	Method	Description
String	delete(String docid)	Delete an XML document in the repository.
String	getAccessControl(String docid)
Vector	getAllDocids(String scope)	return a list of all docids that match a given scope.
String	getEncoding()	Returns the character encoding used used when communicating with Metacat.
String	getLastDocid(String scope)	Return the highest document id for a given scope.
String	getloggedinuserinfo()	Get the logged in user for this session.
int	getNewestDocRevision(String docId)	The method will return the latest revision in metacat server for a given document id.
String	getSessionId()	Get the session identifier for this session.
String	insert(String docid, Reader xmlDocument, Reader schema)	Insert an XML document into the repository, making it available for searching using the query() methods.
boolean	isRegistered(String docid)	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.
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.
Reader	query(Reader xmlQuery, String qformat)	Query the metacat document store with the given metacat-compatible query document and qformat, and return the result set as a Reader.
InputStream	read(String docid)	Read an XML document from the metacat server session, accessed by docid, and returned as a Reader.
InputStream	readInlineData(String inlinedataid)	Read inline data from the metacat server session, accessed by inlinedataid, and returned as a Reader.
String	setAccess(String docid, String accessBlock)
String	setAccess(String docid, String principal, String permission, String permType, String permOrder)	set the access on an XML document in the repository.
void	setEncoding(String encoding)	Returns the character encoding used used when communicating with Metacat.
void	setMetacatUrl(String metacatUrl)	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, Reader schema)	Update an XML document in the repository by providing a new version of the XML document.
String	upload(String docid, File file)	Upload a data document into the repository.
String	upload(String docid, String fileName, InputStream fileData, int size)	Upload a data document into the repository.

Method Details

login

String login(String username,
 String password)
      throws MetacatAuthException,
MetacatInaccessibleException

Method used to log in to a metacat server. 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.

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

read

InputStream read(String docid)
          throws InsufficientKarmaException,
MetacatInaccessibleException,
DocumentNotFoundException,
MetacatException

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

Parameters:

docid - the identifier of the document to be read

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

readInlineData

InputStream readInlineData(String inlinedataid)
                    throws InsufficientKarmaException,
MetacatInaccessibleException,
MetacatException

Read inline data from the metacat server session, accessed by inlinedataid, and returned as a Reader.

Parameters:

inlinedataid - the identifier of the document to be read

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

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

query

Reader query(Reader xmlQuery,
 String qformat)
      throws MetacatInaccessibleException,
IOException

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

Parameters:

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

qformat - the format of return doc. It can be xml, knb, lter and etal.

Returns:

a Reader for accessing the result set

Throws:

MetacatInaccessibleException

IOException

insert

String insert(String docid,
 Reader xmlDocument,
 Reader schema)
       throws InsufficientKarmaException,
MetacatException,
IOException,
MetacatInaccessibleException

Insert 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

schema - a Reader for accessing the DTD or XML Schema for the document

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,
 Reader schema)
       throws InsufficientKarmaException,
MetacatException,
IOException,
MetacatInaccessibleException

Update an XML document in the repository by providing a new version of the XML document. The new version is placed in the search index, and older versions are archived (accessible by read(), but not in the search index).

Parameters:

docid - the docid to update

xmlDocument - a Reader for accessing the XML text to be updated

schema - a Reader for accessing the DTD or XML Schema for the document

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

upload

String upload(String docid,
 File file)
       throws InsufficientKarmaException,
MetacatException,
IOException,
MetacatInaccessibleException

Upload a data document into the repository. Data files are stored on metacat and may be in any format (binary or text), but they are all treated as if they were binary. Data files are not searched by the query() methods because they are not loaded into the XML store because they are not XML documents. The File parameter is used to determine a name for the uploaded document.

Parameters:

docid - the identifier to be used for the document

file - the File to be uploaded

document - a InputStream containing the data to be uploaded

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

upload

String upload(String docid,
 String fileName,
 InputStream fileData,
 int size)
       throws InsufficientKarmaException,
MetacatException,
IOException,
MetacatInaccessibleException

Upload a data document into the repository. Data files are stored on metacat and may be in any format (binary or text), but they are all treated as if they were binary. Data files are not searched by the query() methods because they are not loaded into the XML store because they are not XML documents. The name for the document is set explicitly using the filename parameter.

Parameters:

docid - the identifier to be used for the document

filename - the name to be used in the MIME description of the uploaded file

document - a InputStream containing the data to be uploaded

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

delete

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

getAccessControl

String getAccessControl(String docid)
                 throws InsufficientKarmaException,
MetacatException,
MetacatInaccessibleException

Throws:

InsufficientKarmaException

MetacatException

MetacatInaccessibleException

setAccess

String setAccess(String docid,
 String principal,
 String permission,
 String permType,
 String permOrder)
          throws InsufficientKarmaException,
MetacatException,
MetacatInaccessibleException

set the access on an XML document in the repository.

Parameters:

_docid - the docid of the document for which the access should be applied.

_principal - the document's principal

_permission - the access permission to be applied to the docid {e.g. read,write,all}

_permType - the permission type to be applied to the document {e.g. allow or deny}

_permOrder - the order that the document's permissions should be processed {e.g. denyFirst or allowFirst}

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

setAccess

String setAccess(String docid,
 String accessBlock)
          throws InsufficientKarmaException,
MetacatException,
MetacatInaccessibleException

Throws:

InsufficientKarmaException

MetacatException

MetacatInaccessibleException

setMetacatUrl

void setMetacatUrl(String metacatUrl)

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

getloggedinuserinfo

String getloggedinuserinfo()
                    throws MetacatInaccessibleException

Get the logged in user for this session.

Throws:

MetacatInaccessibleException

getNewestDocRevision

int getNewestDocRevision(String docId)
                  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:

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

Throws:

MetacatException

getLastDocid

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

getAllDocids

Vector 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 docid)
              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

getEncoding

String getEncoding()

Returns the character encoding used used when communicating with Metacat.

Returns:

character encoding name

setEncoding

void setEncoding(String encoding)

Returns the character encoding used used when communicating with Metacat.

Parameters:

encoding - The encoding (i.e. "UTF-8")