edu.ucsb.nceas.metacat.client
Class MetacatClient

java.lang.Object
  extended byedu.ucsb.nceas.metacat.client.MetacatClient
All Implemented Interfaces:
Metacat

public class MetacatClient
extends java.lang.Object
implements 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.


Constructor Summary
protected MetacatClient()
          Constructor to create a new instance.
 
Method Summary
 java.lang.String delete(java.lang.String docid)
          Delete an XML document in the repository.
 int getNewestDocRevision(java.lang.String docId)
          The method will return the lasted revision in metacat server for a given document id.
 java.lang.String getSessionId()
          Get the session identifier for this session.
 java.lang.String insert(java.lang.String docid, java.io.Reader xmlDocument, java.io.Reader schema)
          Insert an XML document into the repository.
 java.lang.String login(java.lang.String username, java.lang.String password)
          Method used to log in to a metacat server.
 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.
 java.io.Reader read(java.lang.String docid)
          Read an XML document from the metacat server session, accessed by docid, and returned as a Reader.
 java.io.Reader readInlineData(java.lang.String inlinedataid)
          Read inline data from the metacat server session, accessed by inlinedataid and returned as a Reader.
 java.lang.String setAccess(java.lang.String _docid, java.lang.String _principal, java.lang.String _permission, java.lang.String _permType, java.lang.String _permOrder)
          set the access on an XML document in the repository.
 void setMetacatUrl(java.lang.String metacatUrl)
          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, java.io.Reader schema)
          Update an XML document in the repository.
 java.lang.String upload(java.lang.String docid, java.io.File file)
          Upload a data document into the repository.
 java.lang.String upload(java.lang.String docid, java.lang.String filename, java.io.InputStream fileData, int size)
          Upload a data document into the repository.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MetacatClient

protected MetacatClient()
Constructor to create a new instance. Protected because instances should only be created by the factory MetacatFactory.

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

public java.io.Reader read(java.lang.String docid)
                    throws InsufficientKarmaException,
                           MetacatInaccessibleException,
                           MetacatException
Read an XML document from the metacat server session, accessed by docid, and returned as a Reader.

Specified by:
read in interface Metacat
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

readInlineData

public java.io.Reader readInlineData(java.lang.String inlinedataid)
                              throws InsufficientKarmaException,
                                     MetacatInaccessibleException,
                                     MetacatException
Read inline data from the metacat server session, accessed by inlinedataid and returned as a Reader.

Specified by:
readInlineData in interface Metacat
Parameters:
inlinedataid - the identifier of the data 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

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

Specified by:
query in interface Metacat
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

insert

public java.lang.String insert(java.lang.String docid,
                               java.io.Reader xmlDocument,
                               java.io.Reader schema)
                        throws InsufficientKarmaException,
                               MetacatException,
                               java.io.IOException,
                               MetacatInaccessibleException
Insert an XML document into the repository.

Specified by:
insert in interface Metacat
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
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,
                               java.io.Reader schema)
                        throws InsufficientKarmaException,
                               MetacatException,
                               java.io.IOException,
                               MetacatInaccessibleException
Update an XML document in the repository.

Specified by:
update in interface Metacat
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
java.io.IOException - when there is an error reading the xml document

upload

public java.lang.String upload(java.lang.String docid,
                               java.io.File file)
                        throws InsufficientKarmaException,
                               MetacatException,
                               java.io.IOException,
                               MetacatInaccessibleException
Upload a data document into the repository.

Specified by:
upload in interface Metacat
Parameters:
docid - the docid to insert 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
java.io.IOException - when there is an error reading the xml document

upload

public java.lang.String upload(java.lang.String docid,
                               java.lang.String filename,
                               java.io.InputStream fileData,
                               int size)
                        throws InsufficientKarmaException,
                               MetacatException,
                               java.io.IOException,
                               MetacatInaccessibleException
Upload a data document into the repository.

Specified by:
upload in interface Metacat
Parameters:
docid - the docid to insert the document
filename - the name of the document
fileData - InputStream of the document that has to be inserted
size - size of the data being sent. If more data is found in the InputStream, an error would be reported.
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

delete

public java.lang.String delete(java.lang.String docid)
                        throws InsufficientKarmaException,
                               MetacatException,
                               MetacatInaccessibleException
Delete an XML document in the repository.

Specified by:
delete in interface Metacat
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

setAccess

public java.lang.String setAccess(java.lang.String _docid,
                                  java.lang.String _principal,
                                  java.lang.String _permission,
                                  java.lang.String _permType,
                                  java.lang.String _permOrder)
                           throws InsufficientKarmaException,
                                  MetacatException,
                                  MetacatInaccessibleException
set the access on an XML document in the repository.

Specified by:
setAccess in interface Metacat
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

setMetacatUrl

public void setMetacatUrl(java.lang.String metacatUrl)
When the MetacatFactory creates an instance it needs to set the MetacatUrl to which connections should be made.

Specified by:
setMetacatUrl in interface Metacat
Parameters:
metacatUrl - the URL for the metacat server

getSessionId

public java.lang.String getSessionId()
Get the session identifier for this session. This is only valid if the login methods has been called successfully for this Metacat object beforehand.

Specified by:
getSessionId in interface Metacat

setSessionId

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

Specified by:
setSessionId in interface Metacat

getNewestDocRevision

public int getNewestDocRevision(java.lang.String docId)
                         throws MetacatException
The method will return the lasted revision in metacat server for a given document id. If some error happent, this method will throw a exception.

Specified by:
getNewestDocRevision in interface Metacat
Parameters:
docId - String the given docid you want to use. the docid it self can have or haven't revision number
Throws:
MetacatException


Copyright © 2000 National Center for Ecological Analysis and Synthesis. All Rights Reserved.