Package net.dona.doip.client

## Class DoipClient

- java.lang.Object
- - net.dona.doip.client.DoipClient

- All Implemented Interfaces:
    `java.lang.AutoCloseable`

      public class DoipClient
      extends java.lang.Object
      implements java.lang.AutoCloseable

  A DOIP client for performing operations on objects. The client can be used to perform arbitrary operations on object, and also provides specific methods for the basic DOIP operations. In general handle resolution will be used to find the service information for accessing the object: the target id is resolved, handle values of type DOIPService are references to service ids which are resolved, handle values of type DOIPServiceInfo have service connection information. It is also possible to explicitly supply the service through which the operation is to be performed. The user should call `close()` to release all resources.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DoipClient()` | Constructs a new DoipClient.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Closes all open connections and release all resources.
    `DigitalObject` | `create​(DigitalObject dobj, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Creates a digital object at a service.
    `void` | `delete​(java.lang.String targetId, AuthenticationInfo authInfo)` | Deletes a digital object.
    `void` | `delete​(java.lang.String targetId, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Deletes a digital object from a specified service.
    `static DoipException` | `doipExceptionFromDoipResponse​(DoipClientResponse resp)` |
    `DigitalObject` | `hello​(java.lang.String targetId, AuthenticationInfo authInfo)` | Performs the "hello" operation.
    `DigitalObject` | `hello​(java.lang.String targetId, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Performs the "hello" operation at a specified service.
    `java.util.List<java.lang.String>` | `listOperations​(java.lang.String targetId, AuthenticationInfo authInfo)` | Lists operations available for a digital object.
    `java.util.List<java.lang.String>` | `listOperations​(java.lang.String targetId, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Lists operations available for a digital object at a specified service.
    `DoipClientResponse` | `performOperation​(java.lang.String targetId, java.lang.String operationId, AuthenticationInfo authInfo, com.google.gson.JsonObject attributes)` | Performs an operation, looking up the target's service information by handle resolution.
    `DoipClientResponse` | `performOperation​(java.lang.String targetId, java.lang.String operationId, AuthenticationInfo authInfo, com.google.gson.JsonObject attributes, com.google.gson.JsonElement input)` | Performs an operation, looking up the target's service information by handle resolution.
    `DoipClientResponse` | `performOperation​(java.lang.String targetId, java.lang.String operationId, AuthenticationInfo authInfo, com.google.gson.JsonObject attributes, com.google.gson.JsonElement input, ServiceInfo serviceInfo)` | Performs an operation at a specified service.
    `DoipClientResponse` | `performOperation​(java.lang.String targetId, java.lang.String operationId, AuthenticationInfo authInfo, com.google.gson.JsonObject attributes, ServiceInfo serviceInfo)` | Performs an operation at a specified service.
    `DoipClientResponse` | `performOperation​(java.lang.String targetId, java.lang.String operationId, AuthenticationInfo authInfo, com.google.gson.JsonObject attributes, InDoipMessage input)` | Performs an operation, looking up the target's service information by handle resolution.
    `DoipClientResponse` | `performOperation​(java.lang.String targetId, java.lang.String operationId, AuthenticationInfo authInfo, com.google.gson.JsonObject attributes, InDoipMessage input, ServiceInfo serviceInfo)` | Performs an operation at a specified service.
    `DoipClientResponse` | `performOperation​(DoipRequestHeaders headers, InDoipMessage input)` | Performs an operation, looking up the target's service information by handle resolution.
    `DoipClientResponse` | `performOperation​(DoipRequestHeaders headers, InDoipMessage input, ServiceInfo serviceInfo)` | Performs an operation at a specified service.
    `DigitalObject` | `retrieve​(java.lang.String targetId, boolean includeElementData, AuthenticationInfo authInfo)` | Retrieves a digital object, possibly including all element data.
    `DigitalObject` | `retrieve​(java.lang.String targetId, boolean includeElementData, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Retrieves a digital object from a specified service, possibly including all element data.
    `DigitalObject` | `retrieve​(java.lang.String targetId, AuthenticationInfo authInfo)` | Retrieves a digital object.
    `DigitalObject` | `retrieve​(java.lang.String targetId, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Retrieves a digital object from a specified service.
    `java.io.InputStream` | `retrieveElement​(java.lang.String targetId, java.lang.String elementId, AuthenticationInfo authInfo)` | Retrieves an element from a digital object.
    `java.io.InputStream` | `retrieveElement​(java.lang.String targetId, java.lang.String elementId, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Retrieves an element from a digital object at a specified service.
    `java.io.InputStream` | `retrievePartialElement​(java.lang.String targetId, java.lang.String elementId, java.lang.Long start, java.lang.Long end, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Retrieves a byte range of an element from a digital object at a specified service.
    `SearchResults<DigitalObject>` | `search​(java.lang.String targetId, java.lang.String query, QueryParams params, AuthenticationInfo authInfo)` | Search for digital objects, returning the full results as digital objects.
    `SearchResults<DigitalObject>` | `search​(java.lang.String targetId, java.lang.String query, QueryParams params, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Search for digital objects, returning the full results as digital objects.
    `SearchResults<java.lang.String>` | `searchIds​(java.lang.String targetId, java.lang.String query, QueryParams params, AuthenticationInfo authInfo)` | Search for digital objects, returning the ids of the results.
    `SearchResults<java.lang.String>` | `searchIds​(java.lang.String targetId, java.lang.String query, QueryParams params, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Search for digital objects, returning the ids of the results.
    `DigitalObject` | `update​(DigitalObject dobj, AuthenticationInfo authInfo)` | Updates a digital object.
    `DigitalObject` | `update​(DigitalObject dobj, AuthenticationInfo authInfo, ServiceInfo serviceInfo)` | Updates a digital object at a specified service.

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

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

- - ### Constructor Detail

    - #### DoipClient

          public DoipClient()

      Constructs a new DoipClient.

  - ### Method Detail

    - #### close

          public void close()

      Closes all open connections and release all resources.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`

    - #### performOperation

          public DoipClientResponse performOperation​(java.lang.String targetId,
                                                     java.lang.String operationId,
                                                     AuthenticationInfo authInfo,
                                                     com.google.gson.JsonObject attributes)
                                              throws DoipException

      Performs an operation, looking up the target's service information by handle resolution. No input (beyond attributes) is provided to the operation.
      Parameters:
        `targetId` - the object on which to perform the operation
        `operationId` - the operation to perform
        `authInfo` - the authentication to provide
        `attributes` - the attributes to provide to the operation
      Returns:
        the response
      Throws:
        `DoipException`

    - #### performOperation

          public DoipClientResponse performOperation​(java.lang.String targetId,
                                                     java.lang.String operationId,
                                                     AuthenticationInfo authInfo,
                                                     com.google.gson.JsonObject attributes,
                                                     com.google.gson.JsonElement input)
                                              throws DoipException

      Performs an operation, looking up the target's service information by handle resolution.
      Parameters:
        `targetId` - the object on which to perform the operation
        `operationId` - the operation to perform
        `authInfo` - the authentication to provide
        `attributes` - the attributes to provide to the operation
        `input` - the input to the operation as a JsonElement
      Returns:
        the response
      Throws:
        `DoipException`

    - #### performOperation

          public DoipClientResponse performOperation​(java.lang.String targetId,
                                                     java.lang.String operationId,
                                                     AuthenticationInfo authInfo,
                                                     com.google.gson.JsonObject attributes,
                                                     InDoipMessage input)
                                              throws DoipException

      Performs an operation, looking up the target's service information by handle resolution.
      Parameters:
        `targetId` - the object on which to perform the operation
        `operationId` - the operation to perform
        `authInfo` - the authentication to provide
        `attributes` - the attributes to provide to the operation
        `input` - the input to the operation as an InDoipMessage
      Returns:
        the response
      Throws:
        `DoipException`

    - #### performOperation

          public DoipClientResponse performOperation​(java.lang.String targetId,
                                                     java.lang.String operationId,
                                                     AuthenticationInfo authInfo,
                                                     com.google.gson.JsonObject attributes,
                                                     ServiceInfo serviceInfo)
                                              throws DoipException

      Performs an operation at a specified service. No input (beyond attributes) is provided to the operation.
      Parameters:
        `targetId` - the object on which to perform the operation
        `operationId` - the operation to perform
        `authInfo` - the authentication to provide
        `attributes` - the attributes to provide to the operation
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the response
      Throws:
        `DoipException`

    - #### performOperation

          public DoipClientResponse performOperation​(java.lang.String targetId,
                                                     java.lang.String operationId,
                                                     AuthenticationInfo authInfo,
                                                     com.google.gson.JsonObject attributes,
                                                     com.google.gson.JsonElement input,
                                                     ServiceInfo serviceInfo)
                                              throws DoipException

      Performs an operation at a specified service.
      Parameters:
        `targetId` - the object on which to perform the operation
        `operationId` - the operation to perform
        `authInfo` - the authentication to provide
        `attributes` - the attributes to provide to the operation
        `input` - the input to the operation as a JsonElement
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the response
      Throws:
        `DoipException`

    - #### performOperation

          public DoipClientResponse performOperation​(java.lang.String targetId,
                                                     java.lang.String operationId,
                                                     AuthenticationInfo authInfo,
                                                     com.google.gson.JsonObject attributes,
                                                     InDoipMessage input,
                                                     ServiceInfo serviceInfo)
                                              throws DoipException

      Performs an operation at a specified service.
      Parameters:
        `targetId` - the object on which to perform the operation
        `operationId` - the operation to perform
        `authInfo` - the authentication to provide
        `attributes` - the attributes to provide to the operation
        `input` - the input to the operation as an InDoipMessage
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the response
      Throws:
        `DoipException`

    - #### performOperation

          public DoipClientResponse performOperation​(DoipRequestHeaders headers,
                                                     InDoipMessage input)
                                              throws DoipException

      Performs an operation, looking up the target's service information by handle resolution.
      Parameters:
        `headers` - the content of the initial segment of the request
        `input` - the input to the operation as an InDoipMessage
      Returns:
        the response
      Throws:
        `DoipException`

    - #### performOperation

          public DoipClientResponse performOperation​(DoipRequestHeaders headers,
                                                     InDoipMessage input,
                                                     ServiceInfo serviceInfo)
                                              throws DoipException

      Performs an operation at a specified service.
      Parameters:
        `headers` - the content of the initial segment of the request
        `input` - the input to the operation as an InDoipMessage
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the response
      Throws:
        `DoipException`

    - #### create

          public DigitalObject create​(DigitalObject dobj,
                                      AuthenticationInfo authInfo,
                                      ServiceInfo serviceInfo)
                               throws DoipException

      Creates a digital object at a service.
      Parameters:
        `dobj` - the digital object to create
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the created digital object
      Throws:
        `DoipException`

    - #### update

          public DigitalObject update​(DigitalObject dobj,
                                      AuthenticationInfo authInfo)
                               throws DoipException

      Updates a digital object.
      Parameters:
        `dobj` - the digital object to update
        `authInfo` - the authentication to provide
      Returns:
        the updated digital object
      Throws:
        `DoipException`

    - #### update

          public DigitalObject update​(DigitalObject dobj,
                                      AuthenticationInfo authInfo,
                                      ServiceInfo serviceInfo)
                               throws DoipException

      Updates a digital object at a specified service.
      Parameters:
        `dobj` - the digital object to update
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the updated digital object
      Throws:
        `DoipException`

    - #### retrieve

          public DigitalObject retrieve​(java.lang.String targetId,
                                        AuthenticationInfo authInfo)
                                 throws DoipException

      Retrieves a digital object.
      Parameters:
        `targetId` - the id of the object to retrieve
        `authInfo` - the authentication to provide
      Returns:
        the digital object
      Throws:
        `DoipException`

    - #### retrieve

          public DigitalObject retrieve​(java.lang.String targetId,
                                        AuthenticationInfo authInfo,
                                        ServiceInfo serviceInfo)
                                 throws DoipException

      Retrieves a digital object from a specified service.
      Parameters:
        `targetId` - the id of the object to retrieve
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the digital object
      Throws:
        `DoipException`

    - #### retrieve

          public DigitalObject retrieve​(java.lang.String targetId,
                                        boolean includeElementData,
                                        AuthenticationInfo authInfo)
                                 throws DoipException

      Retrieves a digital object, possibly including all element data.
      Parameters:
        `targetId` - the id of the object to retrieve
        `includeElementData` - if true, include data for all elements
        `authInfo` - the authentication to provide
      Returns:
        the digital object
      Throws:
        `DoipException`

    - #### retrieve

          public DigitalObject retrieve​(java.lang.String targetId,
                                        boolean includeElementData,
                                        AuthenticationInfo authInfo,
                                        ServiceInfo serviceInfo)
                                 throws DoipException

      Retrieves a digital object from a specified service, possibly including all element data.
      Parameters:
        `targetId` - the id of the object to retrieve
        `includeElementData` - if true, include data for all elements
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the digital object
      Throws:
        `DoipException`

    - #### delete

          public void delete​(java.lang.String targetId,
                             AuthenticationInfo authInfo)
                      throws DoipException

      Deletes a digital object.
      Parameters:
        `targetId` - the id of the object to delete
        `authInfo` - the authentication to provide
      Throws:
        `DoipException`

    - #### delete

          public void delete​(java.lang.String targetId,
                             AuthenticationInfo authInfo,
                             ServiceInfo serviceInfo)
                      throws DoipException

      Deletes a digital object from a specified service.
      Parameters:
        `targetId` - the id of the object to delete
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Throws:
        `DoipException`

    - #### listOperations

          public java.util.List<java.lang.String> listOperations​(java.lang.String targetId,
                                                                 AuthenticationInfo authInfo)
                                                          throws DoipException

      Lists operations available for a digital object.
      Parameters:
        `targetId` - the id of the digital object
        `authInfo` - the authentication to provide
      Returns:
        the list of available operation ids
      Throws:
        `DoipException`

    - #### listOperations

          public java.util.List<java.lang.String> listOperations​(java.lang.String targetId,
                                                                 AuthenticationInfo authInfo,
                                                                 ServiceInfo serviceInfo)
                                                          throws DoipException

      Lists operations available for a digital object at a specified service.
      Parameters:
        `targetId` - the id of the digital object
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the list of available operation ids
      Throws:
        `DoipException`

    - #### doipExceptionFromDoipResponse

          public static DoipException doipExceptionFromDoipResponse​(DoipClientResponse resp)

    - #### searchIds

          public SearchResults<java.lang.String> searchIds​(java.lang.String targetId,
                                                           java.lang.String query,
                                                           QueryParams params,
                                                           AuthenticationInfo authInfo)
                                                    throws DoipException

      Search for digital objects, returning the ids of the results.
      Parameters:
        `targetId` - the id of the operation target (generally a DOIP service id)
        `query` - the query
        `params` - the query parameters
        `authInfo` - the authentication to provide
      Returns:
        the search results as ids
      Throws:
        `DoipException`

    - #### searchIds

          public SearchResults<java.lang.String> searchIds​(java.lang.String targetId,
                                                           java.lang.String query,
                                                           QueryParams params,
                                                           AuthenticationInfo authInfo,
                                                           ServiceInfo serviceInfo)
                                                    throws DoipException

      Search for digital objects, returning the ids of the results.
      Parameters:
        `targetId` - the id of the operation target (generally a DOIP service id)
        `query` - the query
        `params` - the query parameters
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the search results as ids
      Throws:
        `DoipException`

    - #### search

          public SearchResults<DigitalObject> search​(java.lang.String targetId,
                                                     java.lang.String query,
                                                     QueryParams params,
                                                     AuthenticationInfo authInfo)
                                              throws DoipException

      Search for digital objects, returning the full results as digital objects.
      Parameters:
        `targetId` - the id of the operation target (generally a DOIP service id)
        `query` - the query
        `params` - the query parameters
        `authInfo` - the authentication to provide
      Returns:
        the search results as digital objects
      Throws:
        `DoipException`

    - #### search

          public SearchResults<DigitalObject> search​(java.lang.String targetId,
                                                     java.lang.String query,
                                                     QueryParams params,
                                                     AuthenticationInfo authInfo,
                                                     ServiceInfo serviceInfo)
                                              throws DoipException

      Search for digital objects, returning the full results as digital objects.
      Parameters:
        `targetId` - the id of the operation target (generally a DOIP service id)
        `query` - the query
        `params` - the query parameters
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the search results as digital objects
      Throws:
        `DoipException`

    - #### hello

          public DigitalObject hello​(java.lang.String targetId,
                                     AuthenticationInfo authInfo)
                              throws DoipException

      Performs the "hello" operation.
      Parameters:
        `targetId` - the id of the operation target (generally a DOIP service id)
        `authInfo` - the authentication to provide
      Returns:
        the result of the hello operation as a service info digital object
      Throws:
        `DoipException`

    - #### hello

          public DigitalObject hello​(java.lang.String targetId,
                                     AuthenticationInfo authInfo,
                                     ServiceInfo serviceInfo)
                              throws DoipException

      Performs the "hello" operation at a specified service.
      Parameters:
        `targetId` - the id of the operation target (generally a DOIP service id)
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        the result of the hello operation as a service info digital object
      Throws:
        `DoipException`

    - #### retrieveElement

          public java.io.InputStream retrieveElement​(java.lang.String targetId,
                                                     java.lang.String elementId,
                                                     AuthenticationInfo authInfo)
                                              throws DoipException

      Retrieves an element from a digital object.
      Parameters:
        `targetId` - the id of the digital object
        `elementId` - the id of the element
        `authInfo` - the authentication to provide
      Returns:
        an input stream with the bytes of the element
      Throws:
        `DoipException`

    - #### retrieveElement

          public java.io.InputStream retrieveElement​(java.lang.String targetId,
                                                     java.lang.String elementId,
                                                     AuthenticationInfo authInfo,
                                                     ServiceInfo serviceInfo)
                                              throws DoipException

      Retrieves an element from a digital object at a specified service.
      Parameters:
        `targetId` - the id of the digital object
        `elementId` - the id of the element
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        an input stream with the bytes of the element
      Throws:
        `DoipException`

    - #### retrievePartialElement

          public java.io.InputStream retrievePartialElement​(java.lang.String targetId,
                                                            java.lang.String elementId,
                                                            java.lang.Long start,
                                                            java.lang.Long end,
                                                            AuthenticationInfo authInfo,
                                                            ServiceInfo serviceInfo)
                                                     throws DoipException

      Retrieves a byte range of an element from a digital object at a specified service. Either start or end may be null. If neither are null, all bytes from start to end, inclusive, with the first byte of the element being numbered 0, are returned. If both are null, the entire element is returned. If only end is null, all bytes from start to the end of the element are returned. If only start is null, end indicates how many bytes to return from the end of the element. For example, if start is null and end is 500, the last 500 bytes of the element are returned.
      Parameters:
        `targetId` - the id of the digital object
        `elementId` - the id of the element
        `start` - the start byte of the desired range, or null (indicates that the number of bytes given by end should be retrieved from the end of the element)
        `end` - the end byte of the desired range, or null (indicates the range should extend to the end of the element)
        `authInfo` - the authentication to provide
        `serviceInfo` - the service at which to perform the operation
      Returns:
        an input stream with the bytes of the element from start to end inclusive
      Throws:
        `DoipException`