edu.ucsb.nceas.metacat.client.rest

## Class MetacatRestClient

- java.lang.Object
- - edu.ucsb.nceas.metacat.client.rest.MetacatRestClient

- All Implemented Interfaces:
    MetacatRest

      public class MetacatRestClient
      extends java.lang.Object
      implements MetacatRest

- - ### Field Summary

    - ### Fields inherited from interface edu.ucsb.nceas.metacat.client.rest.MetacatRest

      `DELETE, FUNCTION_KEYWORD, FUNCTION_NAME_GETALLDOCS, FUNCTION_NAME_GETNEXTOBJ, FUNCTION_NAME_GETNEXTREV, FUNCTION_NAME_INSERT, FUNCTION_NAME_ISREGISTERED, FUNCTION_NAME_LOGIN, FUNCTION_NAME_LOGOUT, FUNCTION_NAME_UPDATE, GET, POST, PUT, RESOURCE_IDENTIFIER, RESOURCE_OBJECTS, RESOURCE_SESSION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MetacatRestClient(java.lang.String contextRootUrl)` Constructor to create a new instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `addLSID(java.lang.String identifierId)` Adds identifierId
    `java.io.Reader` | `authenticatedGetObject(java.lang.String docid, java.lang.String outFile)` Read XML document from server session, accessed by docid, and returned as a Reader.
    `java.io.Reader` | `authenticatedQuery(java.io.Reader xmlQuery)` Query (as an authenticated user) the metacat document store with the given Ecogrid-compatible query document and return the Ecogrid result set as a Reader.
    `java.lang.String` | `create(java.lang.String docid, java.io.Reader xmlDocument)` Create an XML document in the repository.
    `java.lang.String` | `deleteObject(java.lang.String docid)` Delete an XML document in the repository.
    `java.util.Vector<java.lang.String>` | `getAllDocids(java.lang.String scope)` return a list of all docids that match a given scope.
    `java.lang.String` | `getNextObject(java.lang.String scope)` Return the highest document id for a given scope.
    `int` | `getNextRevision(java.lang.String identifierId)` The method will return the latest revision in metacat server for a given document id.
    `java.io.Reader` | `getObject(java.lang.String docid, java.lang.String outFile)` Read a public XML document , accessed by docid, and returned as a Reader.
    `java.lang.String` | `getSessionId()` Get the session identifier for this session.
    `boolean` | `isRegistered(java.lang.String identifierId)` 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 through REST API.
    `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 Ecogrid-compatible query document and return the Ecogrid result set as a Reader.
    `void` | `setContextRootUrl(java.lang.String contextRootUrl)` 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)` Update an XML document in the repository, replacing an existing document.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### MetacatRestClient

          public MetacatRestClient(java.lang.String contextRootUrl)

      Constructor to create a new instance.

  - ### 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 through REST API. 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 `MetacatRest`
      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 `MetacatRest`
      Returns:
        the response string from metacat in XML format
      Throws:
        `MetacatInaccessibleException` - when the metacat server can not be reached or does not respond
        `MetacatException`

    - #### getObject

          public java.io.Reader getObject(java.lang.String docid,
                                          java.lang.String outFile)
                                   throws InsufficientKarmaException,
                                          MetacatInaccessibleException,
                                          DocumentNotFoundException,
                                          MetacatException

      Read a public XML document , accessed by docid, and returned as a Reader.
      Specified by:
        `getObject` in interface `MetacatRest`
      Parameters:
        `docid` - the identifier of the document to be read
        `outputFile` - name of the file to be written to local (optional)
      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`

    - #### authenticatedGetObject

          public java.io.Reader authenticatedGetObject(java.lang.String docid,
                                                       java.lang.String outFile)
                                                throws InsufficientKarmaException,
                                                       MetacatInaccessibleException,
                                                       DocumentNotFoundException,
                                                       MetacatException

      Read XML document from server session, accessed by docid, and returned as a Reader.
      Specified by:
        `authenticatedGetObject` in interface `MetacatRest`
      Parameters:
        `docid` - the identifier of the document to be read
        `outputFile` - name of the file to be written to local (optional)
      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`

    - #### query

          public java.io.Reader query(java.io.Reader xmlQuery)
                               throws MetacatInaccessibleException,
                                      java.io.IOException

      Query the metacat document store with the given Ecogrid-compatible query document and return the Ecogrid result set as a Reader.
      Specified by:
        `query` in interface `MetacatRest`
      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`

    - #### authenticatedQuery

          public java.io.Reader authenticatedQuery(java.io.Reader xmlQuery)
                                            throws MetacatInaccessibleException,
                                                   java.io.IOException

      Query (as an authenticated user) the metacat document store with the given Ecogrid-compatible query document and return the Ecogrid result set as a Reader.
      Specified by:
        `authenticatedQuery` in interface `MetacatRest`
      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`

    - #### create

          public java.lang.String create(java.lang.String docid,
                                         java.io.Reader xmlDocument)
                                  throws InsufficientKarmaException,
                                         MetacatException,
                                         java.io.IOException,
                                         MetacatInaccessibleException

      Create an XML document in the repository.
      Specified by:
        `create` in interface `MetacatRest`
      Parameters:
        `docid` - the docid to insert the document
        `xmlDocument` - a Reader for accessing the XML document to be inserted
        `isInsert` - whether the operation is update or insert
      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)
                                  throws InsufficientKarmaException,
                                         MetacatException,
                                         java.io.IOException,
                                         MetacatInaccessibleException

      Update an XML document in the repository, replacing an existing document.
      Specified by:
        `update` in interface `MetacatRest`
      Parameters:
        `docid` - the docid to insert the document
        `xmlDocument` - a Reader for accessing the XML document to be inserted
        `isInsert` - whether the operation is update or insert
      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

    - #### deleteObject

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

      Delete an XML document in the repository.
      Specified by:
        `deleteObject` in interface `MetacatRest`
      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

    - #### getNextObject

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

    - #### getNextRevision

          public int getNextRevision(java.lang.String identifierId)
                              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:
        `getNextRevision` in interface `MetacatRest`
      Parameters:
        `identifierId` - String the given docid you want to use. the docid it self can have or haven't revision number
      Throws:
        `MetacatException`

    - #### getAllDocids

          public java.util.Vector<java.lang.String> 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 `MetacatRest`
      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 identifierId)
                               throws MetacatException

      return true of the given docid is registered, false if not
      Specified by:
        `isRegistered` in interface `MetacatRest`
      Parameters:
        `scope` - String the scope to use to limit the docid query
      Throws:
        `MetacatException` - when an error occurs

    - #### addLSID

          public java.lang.String addLSID(java.lang.String identifierId)
                                   throws MetacatException

      Adds identifierId
      Specified by:
        `addLSID` in interface `MetacatRest`
      Parameters:
        `identifierId` - String the given docid you want to use.
      Throws:
        `MetacatException` - when an error occurs

    - #### setContextRootUrl

          public void setContextRootUrl(java.lang.String contextRootUrl)

      Description copied from interface: `MetacatRest`
      When the MetacatFactory creates an instance it needs to set the MetacatUrl to which connections should be made.
      Specified by:
        `setContextRootUrl` in interface `MetacatRest`

    - #### getSessionId

          public java.lang.String getSessionId()

      Description copied from interface: `MetacatRest`
      Get the session identifier for this session.
      Specified by:
        `getSessionId` in interface `MetacatRest`

    - #### setSessionId

          public void setSessionId(java.lang.String sessionId)

      Description copied from interface: `MetacatRest`
      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 `MetacatRest`

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