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

    All Methods Instance Methods Abstract 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)`
    `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()` Get the logged in user for this session.
    `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, making it available for searching using the query() methods.
    `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.
    `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` | `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.lang.String` | `setAccess(java.lang.String docid, java.lang.String accessBlock)`
    `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 by providing a new version of the XML document.
    `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.

- - ### Method Detail

    - #### login

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

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

          java.io.InputStream read(java.lang.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

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

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

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

          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, 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
        `java.io.IOException` - when there is an error reading the xml document

    - #### update

          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 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
        `java.io.IOException` - when there is an error reading the xml document

    - #### upload

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

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

          java.lang.String delete(java.lang.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

          java.lang.String getAccessControl(java.lang.String docid)
                                     throws InsufficientKarmaException,
                                            MetacatException,
                                            MetacatInaccessibleException

      Throws:
        `InsufficientKarmaException`
        `MetacatException`
        `MetacatInaccessibleException`

    - #### setAccess

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

          java.lang.String setAccess(java.lang.String docid,
                                     java.lang.String accessBlock)
                              throws InsufficientKarmaException,
                                     MetacatException,
                                     MetacatInaccessibleException

      Throws:
        `InsufficientKarmaException`
        `MetacatException`
        `MetacatInaccessibleException`

    - #### setMetacatUrl

          void setMetacatUrl(java.lang.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

          java.lang.String getSessionId()

      Get the session identifier for this session.

    - #### setSessionId

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

    - #### getloggedinuserinfo

          java.lang.String getloggedinuserinfo()
                                        throws MetacatInaccessibleException

      Get the logged in user for this session.
      Throws:
        `MetacatInaccessibleException`

    - #### getNewestDocRevision

          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.
      Parameters:
        `docId` - String the given docid you want to use. the docid it self can have or haven't revision number
      Throws:
        `MetacatException`

    - #### getLastDocid

          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.
      Parameters:
        `scope` - String the scope to use for looking up the latest id
      Throws:
        `MetacatException` - when an error occurs

    - #### getAllDocids

          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
      Parameters:
        `scope` - String the scope to use to limit the docid query
      Throws:
        `MetacatException` - when an error occurs

    - #### isRegistered

          boolean isRegistered(java.lang.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

          java.lang.String getEncoding()

      Returns the character encoding used used when communicating with Metacat.
      Returns:
        character encoding name

    - #### setEncoding

          void setEncoding(java.lang.String encoding)

      Returns the character encoding used used when communicating with Metacat.
      Parameters:
        `encoding` - The encoding (i.e. "UTF-8")

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