org.gcube.contentmanagement.gcubedocumentlibrary.io
Interface Writer

All Known Implementing Classes:
DocumentWriter

public interface Writer

Defines facilities to change the contents of a remote collection of document descriptions, including adding new descriptions, updating existing descriptions, and deleting existing descriptions.

Author:
Fabio Simeoni (University of Strathclyde)

Method Summary
 java.lang.String add(GCubeDocument document)
          Adds a document description to the target collection and returns an identifier for it.
 java.util.concurrent.Future<?> add(java.util.Iterator<GCubeDocument> documents)
          Adds a stream of document descriptions to the target collection.
 java.util.List<AddOutcome> add(java.util.List<GCubeDocument> documents)
          Adds a list of document descriptions to the target collection and returns a list of corresponding outcomes, where each outcome is either an identifier for the description or else a processing failure.
 GCubeDocument addAndSynchronize(GCubeDocument document)
          Adds a document description to the target collection and returns a proxy for it which is synchronised with the changes applied to the description at the point of addition, including the assignment of identifiers to the description and its inner elements.
 java.lang.String collectionID()
          Returns the identifier of the target collection.
 void delete(GCubeDocument document)
          Deletes a document description from the target collection using a proxy for it.
 java.util.concurrent.Future<?> delete(java.util.Iterator<GCubeDocument> documents)
          Deletes multiple document descriptions from the target collection using a stream of proxies for them.
 java.util.Map<java.lang.String,java.lang.Throwable> delete(java.util.List<GCubeDocument> documents)
          Deletes multiple document descriptions from the target collection using a list of proxies for them.
 void update(GCubeDocument document)
          Updates a document description in the target collection with the properties of a local proxy.
 java.util.concurrent.Future<?> update(java.util.Iterator<GCubeDocument> documents)
          Updates multiple document descriptions with the properties of a stream of proxies.
 java.util.Map<java.lang.String,java.lang.Throwable> update(java.util.List<GCubeDocument> documents)
          Updates multiple document descriptions in the target collections with the properties of a list of proxies.
 GCubeDocument updateAndSynchronize(GCubeDocument document)
          Updates a document description in the target collection with the properties of a local proxy, and returns a a new proxy which is fully synchronised with the description.
 

Method Detail

add

java.lang.String add(GCubeDocument document)
                     throws java.lang.IllegalArgumentException,
                            DiscoveryException,
                            GCUBEException,
                            java.lang.Exception
Adds a document description to the target collection and returns an identifier for it.

The description must satisfy certain basic criteria, including the lack of identifiers for it and all its inner elements, the consistency between the collection bound to it and the collection bound to this Writer, and other constraints that are specific to its inner elements. We say that the description must be valid for addition.

Parameters:
document - a document description valid for addition.
Returns:
the identifier assigned to the description as a result of its successful addition to the target collection.
Throws:
java.lang.IllegalArgumentException - if the document description is not valid for addition.
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

addAndSynchronize

GCubeDocument addAndSynchronize(GCubeDocument document)
                                throws java.lang.IllegalArgumentException,
                                       DiscoveryException,
                                       GCUBEException,
                                       java.lang.Exception
Adds a document description to the target collection and returns a proxy for it which is synchronised with the changes applied to the description at the point of addition, including the assignment of identifiers to the description and its inner elements.

The description must satisfy certain basic criteria, including the lack of identifiers for it and all its inner elements, the consistency between the collection bound to it and the collection bound to this Writer, and other constraints that are specific to its inner elements. We say that the description must be valid for addition.

Parameters:
document - a document description valid for addition.
Returns:
a synchronised proxy of the description.
Throws:
java.lang.IllegalArgumentException - if the document description is not valid for addition.
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

add

java.util.List<AddOutcome> add(java.util.List<GCubeDocument> documents)
                               throws java.lang.IllegalArgumentException,
                                      DiscoveryException,
                                      GCUBEException,
                                      java.lang.Exception
Adds a list of document descriptions to the target collection and returns a list of corresponding outcomes, where each outcome is either an identifier for the description or else a processing failure.

Each description must satisfy certain basic criteria, including the lack of identifiers for it and all its inner elements, the consistency between the collection bound to it and the collection bound to this Writer, and other constraints that are specific to its inner elements. We say that the description must be valid for addition. If one of the descriptions in input is not valid for addition, the operation fails before any attempt is made to add any description to the target collection.

Note that this operation uses result set mechanisms to interact with the remote collection and thus can be invoked only inside a container.

Parameters:
documents - a list of document descriptions valid for addition.
Returns:
a list of AddOutcomes, in the same order as the descriptions in input.
Throws:
java.lang.IllegalArgumentException - if at least one of the document descriptions in input is not valid for addition.
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

add

java.util.concurrent.Future<?> add(java.util.Iterator<GCubeDocument> documents)
                                   throws DiscoveryException,
                                          GCUBEException,
                                          java.lang.Exception
Adds a stream of document descriptions to the target collection. The operation is non-blocking, in that clients regain control as the descriptions are being added to the target collection.

Each description must satisfy certain basic criteria, including the lack of identifiers for it and all its inner elements, the consistency between the collection bound to it and the collection bound to this Writer, and other constraints that are specific to its inner elements. We say that the description must be valid for addition. Descriptions in the stream that are not valid for addition are discarded and no attempt is made to add them to the target collection (the exclusion is logged).

Due to the possibility of pre-processing failures and its non-blocking nature, the operation cannot guarantee the fidelity of outcome reports. For this reason, the operation returns only a Future that clients can poll to know when all the descriptions in input have been submitted for addition. Clients that work with large or remote streams, and are interested in processing outcomes, are responsible for grouping the elements of the streams in 'chunks' of acceptable size and use add(List) with each chunk. The facilities of the DSL for streams can be conveniently used for this purpose (cf. Streams.group(Iterator),Streams#group(RemoteIterator)).

Note that this operation uses result set mechanisms to interact with remote services and thus can be invoked only inside a container.

Parameters:
documents - an Iterator over a stream of document descriptions valid for addition.
Returns:
a Future for the completion of the operation.
Throws:
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

update

void update(GCubeDocument document)
            throws java.lang.IllegalArgumentException,
                   DiscoveryException,
                   GCUBEException,
                   java.lang.Exception
Updates a document description in the target collection with the properties of a local proxy.

The proxy must satisfy certain basic criteria, including the consistency between the collection bound to it and the collection bound to this Writer, the existence of tracked changes on it (cf. GCubeDocument#trackChanges()), and other constraints that are specific to its inner elements. We say that the proxy must be valid for update.

Note that, upon successful completion of the operation, the proxy in input may not be synchronised with the updated document description.Use #updateAndSynchronize(GCubedocument) to obtain a synchronised proxy of the updated document description.

Parameters:
document - a proxy which is valid for update.
Throws:
java.lang.IllegalArgumentException - if the proxy is not valid for update.
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

updateAndSynchronize

GCubeDocument updateAndSynchronize(GCubeDocument document)
                                   throws java.lang.IllegalArgumentException,
                                          DiscoveryException,
                                          GCUBEException,
                                          java.lang.Exception
Updates a document description in the target collection with the properties of a local proxy, and returns a a new proxy which is fully synchronised with the description.

The proxy must satisfy certain basic criteria, including the consistency between the collection bound to it and the collection bound to this Writer, the existence of tracked changes on it (cf. GCubeDocument#trackChanges()), and other constraints that are specific to its inner elements. We say that the proxy must be valid for update.

Parameters:
document - a proxy which is valid for update.
Throws:
java.lang.IllegalArgumentException - if the proxy is not valid for update.
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

update

java.util.Map<java.lang.String,java.lang.Throwable> update(java.util.List<GCubeDocument> documents)
                                                           throws DiscoveryException,
                                                                  GCUBEException,
                                                                  java.lang.Exception
Updates multiple document descriptions in the target collections with the properties of a list of proxies. It returns a list of processing failures indexed by description identifiers.

Each proxy must satisfy certain basic criteria, including the consistency between the collection bound to it and the collection bound to this Writer, the existence of tracked changes on it (cf. GCubeDocument#trackChanges()), and other constraints that are specific to its inner elements. We say that the proxy must be valid for update. If one of the proxies in input is not valid for addition, the operation fails before any attempt is made to update any description in the target collection.

Note that this operation uses result set mechanisms to interact with the remote collection and thus can be invoked only inside a container.

Parameters:
documents - a list of proxies valid for update.
Returns:
a map of processing failures indexed by the identifiers of the corresponding descriptions.
Throws:
java.lang.IllegalArgumentException - if at least one of the proxies in input is not valid for update.
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

update

java.util.concurrent.Future<?> update(java.util.Iterator<GCubeDocument> documents)
                                      throws DiscoveryException,
                                             GCUBEException,
                                             java.lang.Exception
Updates multiple document descriptions with the properties of a stream of proxies. The operation is non-blocking, in that clients regain control as the descriptions are being updated in the target collection.

Each proxy must satisfy certain basic criteria, including the consistency between the collection bound to it and the collection bound to this Writer, the existence of tracked changes on it (cf. GCubeDocument#trackChanges()), and other constraints that are specific to its inner elements. We say that the proxy must be valid for update. Proxies in the stream that are not valid for update are discarded and no attempt is made to update the corresponding descriptions. (the exclusion is logged).

Due to the possibility of pre-processing failures and its non-blocking nature, the operation cannot guarantee the fidelity of outcome reports. For this reason, the operation returns only a Future that clients can poll to know when all the proxies in input have been submitted for update. Clients that work with large or remote streams and are interested in processing outcomes, are responsible for grouping the elements of the stream in 'chunks' of acceptable size and use update(List) with each chunk. The facilities of the DSL for streams can be conveniently used for this purpose (cf. Streams.group(Iterator),Streams#group(RemoteIterator)).

Note that this operation uses result set mechanisms to interact with remote services and thus can be invoked only inside a container.

Parameters:
documents - an Iterator over proxies that are valid for update.
Returns:
a Future for the completion of the operation.
Throws:
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

delete

void delete(GCubeDocument document)
            throws java.lang.IllegalArgumentException,
                   DiscoveryException,
                   GCUBEException,
                   java.lang.Exception
Deletes a document description from the target collection using a proxy for it.

Parameters:
document - a proxy of the description to be deleted from the target collection.
Throws:
java.lang.IllegalArgumentException - if the input is not a proxy (i.e. has no identifier).
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

delete

java.util.Map<java.lang.String,java.lang.Throwable> delete(java.util.List<GCubeDocument> documents)
                                                           throws DiscoveryException,
                                                                  GCUBEException,
                                                                  java.lang.Exception
Deletes multiple document descriptions from the target collection using a list of proxies for them. It returns a list of processing failures indexed by description identifiers.

If the list contains a description which is not a proxy, the operation fails before any attempt is made to delete any document description in the target collection.

Note that this operation uses result set mechanisms to interact with remote services and thus can be invoked only inside a container.

Parameters:
documents - a list of proxies of the descriptions to be deleted from the target collection.
Returns:
a list of processing failures, indexed by the identifier of the corresponding descriptions.
Throws:
java.lang.IllegalArgumentException - if the input list contains at least one description which is not a proxy.
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

delete

java.util.concurrent.Future<?> delete(java.util.Iterator<GCubeDocument> documents)
                                      throws DiscoveryException,
                                             GCUBEException,
                                             java.lang.Exception
Deletes multiple document descriptions from the target collection using a stream of proxies for them. The operation is non-blocking, in that clients regain control as the descriptions are being deleted from the target collection.

Descriptions in the stream that are not proxies are discarded (the exclusion is logged). Due to the possibility of pre-processing failures and its non-blocking nature, the operation cannot guarantee the fidelity of outcome reports. For this reason, the operation returns only a Future that clients can poll to know when all the proxies in input have been submitted for deletion. Clients that work with large or remote stream, and are interested in processing outcomes, are responsible for grouping the elements of the stream in 'chunks' of acceptable size and use update(List) with each chunk. The facilities of the DSL for streams can be conveniently used for this purpose (cf. Streams.group(Iterator),Streams#group(RemoteIterator)).

Note that this operation uses result set mechanisms to interact with remote services and thus can be invoked only inside a container.

Parameters:
documents - an Iterator over the proxies of the descriptions to be deleted from the target collection.
Returns:
a Future for the completion of the operation.
Throws:
DiscoveryException - if the operation cannot be completed due to collection discovery errors.
GCUBEException - if the operation cannot be completed due to other remote errors.
java.lang.Exception - if the operation cannot be completed due to local errors.

collectionID

java.lang.String collectionID()
Returns the identifier of the target collection.

Returns:
the identifier.