Class 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 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
      • 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
      • 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