edu.ucsb.nceas.metacat.client

## Class MetacatClient

- java.lang.Object
- - 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

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `MetacatClient()` Constructor to create a new instance.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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` | `getEncoding()` Returns the character encoding used used when communicating with Metacat.
    `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` | `sendParameters(java.util.Properties prop)` Send a request to Metacat.
    `java.io.InputStream` | `sendParametersInverted(java.util.Properties prop)` 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` | `setEncoding(java.lang.String encoding)` Returns the character encoding used used when communicating with Metacat.
    `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 prop)
                                             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 key", and the entry value contains the "param value". Constraint: no multi-valued parameters are supported
      Parameters:
        `args` - Properties of the parameters to be sent to Metacat, where, key = param key value = param value
      Returns:
        InputStream as returned by Metacat
      Throws:
        `java.lang.Exception` - thrown

    - #### sendParametersInverted

          public java.io.InputStream sendParametersInverted(java.util.Properties prop)
                                                     throws java.lang.Exception

      Send a request to Metacat. NOTE: 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

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

    - #### getEncoding

          public java.lang.String getEncoding()

      Description copied from interface: `Metacat`
      Returns the character encoding used used when communicating with Metacat.
      Specified by:
        `getEncoding` in interface `Metacat`
      Returns:
        character encoding name

    - #### setEncoding

          public void setEncoding(java.lang.String encoding)

      Description copied from interface: `Metacat`
      Returns the character encoding used used when communicating with Metacat.
      Specified by:
        `setEncoding` in interface `Metacat`
      Parameters:
        `encoding` - The encoding (i.e. "UTF-8")

Copyright © 2023 Regents of the University of California. All Rights Reserved.