edu.ucsb.nceas.metacat.client
Class MetacatClient

java.lang.Object
  extended by edu.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.
 java.lang.String getAccessControl(java.lang.String docid)
          get the access control info for a given document id.
 java.util.Vector getAllDocids(java.lang.String scope)
          return a list of all docids that match a given scope.
 java.lang.String getLastDocid(java.lang.String scope)
          Return the highest document id for a given scope.
 java.lang.String getloggedinuserinfo()
          Method used to log in to a metacat server.
static MetacatClient getMetacatClient(javax.servlet.http.HttpServletRequest request)
          JSP API: This is a convenience method to reduce the amount of code in a Metacat Client JSP.
 int getNewestDocRevision(java.lang.String docId)
          The method will return the latest 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 isAuthorized(java.lang.String resourceLsid, java.lang.String permission, java.lang.String sessionId)
          Method used to log in to a metacat server.
 boolean isRegistered(java.lang.String docid)
          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.
 java.lang.String logout()
          Method used to log out a metacat server.
static void main(java.lang.String[] args)
           
 java.io.Reader query(java.io.Reader xmlQuery)
          Query the metacat document store with the given metacat-compatible query document and default qformat xml, and return the result set as a Reader.
 java.io.Reader query(java.io.Reader xmlQuery, java.lang.String qformat)
          Query the metacat document store with the given metacat-compatible query document and qformat, and return the result set as a Reader.
 java.io.InputStream read(java.lang.String docid)
          Read an XML document from the metacat server session, accessed by docid, and returned as a Reader.
 java.io.InputStream readInlineData(java.lang.String inlinedataid)
          Read inline data from the metacat server session, accessed by inlinedataid and returned as a Reader.
 java.io.InputStream sendData(java.util.Properties args, java.util.Properties filename, java.io.InputStream fileData, int size)
          Send a request to Metacat
 java.io.InputStream sendParameters(java.util.Properties args)
          Send a request to Metacat.
 java.lang.String setAccess(java.lang.String docid, java.lang.String accessBlock)
          Set access for a given doc id.
 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.
 java.lang.String validateSession(java.lang.String sessionId)
          Method used to log in to a metacat server.
 
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

main

public static void main(java.lang.String[] args)

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

getloggedinuserinfo

public java.lang.String getloggedinuserinfo()
                                     throws 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:
getloggedinuserinfo 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

validateSession

public java.lang.String validateSession(java.lang.String sessionId)
                                 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

isAuthorized

public java.lang.String isAuthorized(java.lang.String resourceLsid,
                                     java.lang.String permission,
                                     java.lang.String sessionId)
                              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

read

public java.io.InputStream read(java.lang.String docid)
                         throws InsufficientKarmaException,
                                MetacatInaccessibleException,
                                MetacatException,
                                DocumentNotFoundException
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
DocumentNotFoundException

readInlineData

public java.io.InputStream 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 default qformat xml, 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

query

public java.io.Reader query(java.io.Reader xmlQuery,
                            java.lang.String qformat)
                     throws MetacatInaccessibleException,
                            java.io.IOException
Query the metacat document store with the given metacat-compatible query document and qformat, 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
qformat - the format of return doc. It can be xml, knb, lter and etal.
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. 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.

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

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

getAccessControl

public java.lang.String getAccessControl(java.lang.String docid)
                                  throws InsufficientKarmaException,
                                         MetacatException,
                                         MetacatInaccessibleException
get the access control info for a given document id.

Specified by:
getAccessControl in interface Metacat
Parameters:
_docid - the docid of the document for which the access should be applied.
Returns:
the metacat access xml
Throws:
InsufficientKarmaException
MetacatException
MetacatInaccessibleException

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

setAccess

public java.lang.String setAccess(java.lang.String docid,
                                  java.lang.String accessBlock)
                           throws InsufficientKarmaException,
                                  MetacatException,
                                  MetacatInaccessibleException
Set access for a given doc id. The access is represented in an access block of xml. All existing access will be replaced with the access provided in the access block.

Specified by:
setAccess in interface Metacat
Parameters:
docid - the doc id for the doc we want to update
accessBlock - the xml access block. This is the same structure as that returned by the getdocumentinfo action in metacat.
Returns:
a string holding the response xml
Throws:
InsufficientKarmaException
MetacatException
MetacatInaccessibleException

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
Parameters:
String - the sessionId from a previously established session

getNewestDocRevision

public int getNewestDocRevision(java.lang.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.

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

getLastDocid

public java.lang.String getLastDocid(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:
getLastDocid in interface Metacat
Parameters:
scope - String the scope to use for looking up the latest id
Throws:
MetacatException - when an error occurs

getAllDocids

public java.util.Vector 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 Metacat
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 docid)
                     throws MetacatException
return true of the given docid is registered, false if not

Specified by:
isRegistered in interface Metacat
Parameters:
scope - String the scope to use to limit the docid query
Throws:
MetacatException - when an error occurs

sendParameters

public java.io.InputStream sendParameters(java.util.Properties args)
                                   throws java.lang.Exception
Send a request to Metacat. An alternative to the sentData method. Allows for sending multiple parameters with the same name, different names, or any combo. Send properties where the entry key contains the "param value", and the entry value contains the "param name". Constraint: param values must be unique.

Parameters:
args - Properties of the parameters to be sent to Metacat, where, key = param value value = param name
Returns:
InputStream as returned by Metacat
Throws:
java.lang.Exception - thrown

sendData

public java.io.InputStream sendData(java.util.Properties args,
                                    java.util.Properties filename,
                                    java.io.InputStream fileData,
                                    int size)
                             throws java.lang.Exception
Send a request to Metacat

Parameters:
args - the properties to be sent to Metacat
filename - the properties to be sent to Metacat in case of upload, otherwise null
fileData - the inputStream for the file data to be sent to Metacat in case of upload, otherwise null
size - the size of the data being sent to Metacat in case of upload, otherwise 0
Returns:
InputStream as returned by Metacat
Throws:
java.lang.Exception

getMetacatClient

public static MetacatClient getMetacatClient(javax.servlet.http.HttpServletRequest request)
                                      throws MetacatInaccessibleException
JSP API: This is a convenience method to reduce the amount of code in a Metacat Client JSP. It handles creating/reusing an instance of a MetacatClient.

Parameters:
request - Since this is intended to be used by a JSP, it is passed the available "request" variable (the HttpServletRequest).
Returns:
MetacatClient instance.
Throws:
MetacatInaccessibleException - Received by MetacatFactory.


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