edu.ucsb.nceas.metacat.client.rest

## Interface MetacatRest

- All Known Implementing Classes:
    MetacatRestClient

      public interface MetacatRest

  This interface provides methods for initializing and logging in to a Metacat REST API, and then querying, reading, transforming, inserting, updating and deleting documents from that server.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DELETE` HTTP Verb DELETE
    `static java.lang.String` | `FUNCTION_KEYWORD` Function keyword
    `static java.lang.String` | `FUNCTION_NAME_GETALLDOCS` Function name for getalldocids function
    `static java.lang.String` | `FUNCTION_NAME_GETNEXTOBJ` Function name for getnextobject function
    `static java.lang.String` | `FUNCTION_NAME_GETNEXTREV` Function name for getnextrevision function
    `static java.lang.String` | `FUNCTION_NAME_INSERT` Function name for insert function
    `static java.lang.String` | `FUNCTION_NAME_ISREGISTERED` Function name for isregistered function
    `static java.lang.String` | `FUNCTION_NAME_LOGIN` Function name for login function
    `static java.lang.String` | `FUNCTION_NAME_LOGOUT` Function name for logout function
    `static java.lang.String` | `FUNCTION_NAME_UPDATE` Function name for update function
    `static java.lang.String` | `GET` HTTP Verb GET
    `static java.lang.String` | `POST` HTTP Verb POST
    `static java.lang.String` | `PUT` HTTP Verb PUT
    `static java.lang.String` | `RESOURCE_IDENTIFIER` API IDENTIFIER Resource which controls object unique identifier operations
    `static java.lang.String` | `RESOURCE_OBJECTS` API OBJECTS Resource which handles with document operations
    `static java.lang.String` | `RESOURCE_SESSION` API SESSION Resource which handles with user session operations

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `addLSID(java.lang.String identifierId)` Adds identifierId (Metacat Server does not support it!)
    `java.io.Reader` | `authenticatedGetObject(java.lang.String docid, java.lang.String outputFile)` Read XML document from server session, accessed by docid, and returned as a Reader.
    `java.io.Reader` | `authenticatedQuery(java.io.Reader xmlQuery)`
    `java.lang.String` | `create(java.lang.String docid, java.io.Reader xmlDocument)` Create an XML document into the repository, making it available for searching using the query() methods.
    `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 outputFile)` 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 metacat-compatible query document, and return the 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 into the repository, making it available for searching using the query() methods.

- - ### Field Detail

    - #### GET

          static final java.lang.String GET

      HTTP Verb GET
      See Also:
        Constant Field Values

    - #### POST

          static final java.lang.String POST

      HTTP Verb POST
      See Also:
        Constant Field Values

    - #### PUT

          static final java.lang.String PUT

      HTTP Verb PUT
      See Also:
        Constant Field Values

    - #### DELETE

          static final java.lang.String DELETE

      HTTP Verb DELETE
      See Also:
        Constant Field Values

    - #### RESOURCE_OBJECTS

          static final java.lang.String RESOURCE_OBJECTS

      API OBJECTS Resource which handles with document operations
      See Also:
        Constant Field Values

    - #### RESOURCE_SESSION

          static final java.lang.String RESOURCE_SESSION

      API SESSION Resource which handles with user session operations
      See Also:
        Constant Field Values

    - #### RESOURCE_IDENTIFIER

          static final java.lang.String RESOURCE_IDENTIFIER

      API IDENTIFIER Resource which controls object unique identifier operations
      See Also:
        Constant Field Values

    - #### FUNCTION_KEYWORD

          static final java.lang.String FUNCTION_KEYWORD

      Function keyword
      See Also:
        Constant Field Values

    - #### FUNCTION_NAME_LOGIN

          static final java.lang.String FUNCTION_NAME_LOGIN

      Function name for login function
      See Also:
        Constant Field Values

    - #### FUNCTION_NAME_LOGOUT

          static final java.lang.String FUNCTION_NAME_LOGOUT

      Function name for logout function
      See Also:
        Constant Field Values

    - #### FUNCTION_NAME_ISREGISTERED

          static final java.lang.String FUNCTION_NAME_ISREGISTERED

      Function name for isregistered function
      See Also:
        Constant Field Values

    - #### FUNCTION_NAME_GETALLDOCS

          static final java.lang.String FUNCTION_NAME_GETALLDOCS

      Function name for getalldocids function
      See Also:
        Constant Field Values

    - #### FUNCTION_NAME_GETNEXTREV

          static final java.lang.String FUNCTION_NAME_GETNEXTREV

      Function name for getnextrevision function
      See Also:
        Constant Field Values

    - #### FUNCTION_NAME_GETNEXTOBJ

          static final java.lang.String FUNCTION_NAME_GETNEXTOBJ

      Function name for getnextobject function
      See Also:
        Constant Field Values

    - #### FUNCTION_NAME_INSERT

          static final java.lang.String FUNCTION_NAME_INSERT

      Function name for insert function
      See Also:
        Constant Field Values

    - #### FUNCTION_NAME_UPDATE

          static final java.lang.String FUNCTION_NAME_UPDATE

      Function name for update function
      See Also:
        Constant Field Values

  - ### 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 through REST API
      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`

    - #### getObject

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

      Read a public XML document , accessed by docid, and returned as a Reader.
      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

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

      Read XML document from server session, accessed by docid, and returned as a Reader.
      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

          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`

    - #### authenticatedQuery

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

      Throws:
        `MetacatInaccessibleException`
        `java.io.IOException`

    - #### create

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

      Create 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
      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)
                           throws InsufficientKarmaException,
                                  MetacatException,
                                  java.io.IOException,
                                  MetacatInaccessibleException

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

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

    - #### setContextRootUrl

          void setContextRootUrl(java.lang.String contextRootUrl)

      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

    - #### getNextObject

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

    - #### getNextRevision

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

    - #### getAllDocids

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

    - #### isRegistered

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

    - #### addLSID

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

      Adds identifierId (Metacat Server does not support it!)
      Parameters:
        `identifierId` - String the given docid you want to use.
      Throws:
        `MetacatException` - when an error occurs

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