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 callclose()
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.
-
-
-
Method Detail
-
close
public void close()
Closes all open connections and release all resources.- Specified by:
close
in interfacejava.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 operationoperationId
- the operation to performauthInfo
- the authentication to provideattributes
- 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 operationoperationId
- the operation to performauthInfo
- the authentication to provideattributes
- the attributes to provide to the operationinput
- 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 operationoperationId
- the operation to performauthInfo
- the authentication to provideattributes
- the attributes to provide to the operationinput
- 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 operationoperationId
- the operation to performauthInfo
- the authentication to provideattributes
- the attributes to provide to the operationserviceInfo
- 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 operationoperationId
- the operation to performauthInfo
- the authentication to provideattributes
- the attributes to provide to the operationinput
- the input to the operation as a JsonElementserviceInfo
- 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 operationoperationId
- the operation to performauthInfo
- the authentication to provideattributes
- the attributes to provide to the operationinput
- the input to the operation as an InDoipMessageserviceInfo
- 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 requestinput
- 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 requestinput
- the input to the operation as an InDoipMessageserviceInfo
- 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 createauthInfo
- the authentication to provideserviceInfo
- 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 updateauthInfo
- 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 updateauthInfo
- the authentication to provideserviceInfo
- 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 retrieveauthInfo
- 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 retrieveauthInfo
- the authentication to provideserviceInfo
- 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 retrieveincludeElementData
- if true, include data for all elementsauthInfo
- 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 retrieveincludeElementData
- if true, include data for all elementsauthInfo
- the authentication to provideserviceInfo
- 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 deleteauthInfo
- 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 deleteauthInfo
- the authentication to provideserviceInfo
- 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 objectauthInfo
- 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 objectauthInfo
- the authentication to provideserviceInfo
- 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 queryparams
- the query parametersauthInfo
- 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 queryparams
- the query parametersauthInfo
- the authentication to provideserviceInfo
- 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 queryparams
- the query parametersauthInfo
- 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 queryparams
- the query parametersauthInfo
- the authentication to provideserviceInfo
- 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 provideserviceInfo
- 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 objectelementId
- the id of the elementauthInfo
- 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 objectelementId
- the id of the elementauthInfo
- the authentication to provideserviceInfo
- 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 objectelementId
- the id of the elementstart
- 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 provideserviceInfo
- 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
-
-