Writer
Date: 2013-06-18

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `AddOutcome`s, 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD