org.gcube.contentmanagement.gcubedocumentlibrary.io
Class DocumentWriter

java.lang.Object
  extended by org.gcube.contentmanagement.gcubedocumentlibrary.io.DocumentWriter
All Implemented Interfaces:
Writer

public class DocumentWriter
extends java.lang.Object
implements Writer

A Writer implementation.

Author:
Fabio Simeoni (University of Strathclyde)

Constructor Summary
DocumentWriter(CollectionReference reference, GCUBEScope scope)
          Creates an instance for a target collection, in a given GCUBEScope and with a given GCUBESecurityManager.
DocumentWriter(CollectionReference reference, GCUBEScope scope, GCUBESecurityManager securityManager)
          Creates an instance for a target collection, in a given GCUBEScope and with a given GCUBESecurityManager.
DocumentWriter(java.lang.String collID)
          Creates an instance for a given target collection in the current scope.
DocumentWriter(java.lang.String collID, GCUBEScope scope)
          Creates an instance for a given target collection and in a given scope.
DocumentWriter(java.lang.String collID, GCUBEScope scope, GCUBESecurityManager securityManager)
          Creates an instance for a given target collection, in a given scope, and with a given security manager.
 
Method Summary
 java.lang.String add(GCubeDocument doc)
          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 document description to the target collection and returns an identifier for it.
 java.util.List<AddOutcome> add(java.util.List<GCubeDocument> elements)
          Adds a document description to the target collection and returns an identifier for it.
 GCubeDocument addAndSynchronize(GCubeDocument doc)
          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 doc)
          Deletes a document description from the target collection using a proxy for it.
 java.util.concurrent.Future<?> delete(java.util.Iterator<GCubeDocument> documents)
          Deletes a document description from the target collection using a proxy for it.
 java.util.Map<java.lang.String,java.lang.Throwable> delete(java.util.List<GCubeDocument> elements)
          Deletes a document description from the target collection using a proxy for it.
 void update(GCubeDocument doc)
          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 a document description in the target collection with the properties of a local proxy.
 java.util.Map<java.lang.String,java.lang.Throwable> update(java.util.List<GCubeDocument> elements)
          Updates a document description in the target collection with the properties of a local proxy.
 GCubeDocument updateAndSynchronize(GCubeDocument doc)
          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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DocumentWriter

public DocumentWriter(java.lang.String collID)
               throws java.lang.IllegalStateException,
                      java.lang.Exception
Creates an instance for a given target collection in the current scope.

Parameters:
collID - the identifier of the target collection.
Throws:
java.lang.IllegalStateException - if the the current scope is not set.
java.lang.Exception - if the instance could not be created.

DocumentWriter

public DocumentWriter(java.lang.String collID,
                      GCUBEScope scope)
               throws java.lang.Exception
Creates an instance for a given target collection and in a given scope.

Parameters:
collID - the identifier of the target collection.
scope - the scope.
Throws:
java.lang.Exception - if the instance could not be created.

DocumentWriter

public DocumentWriter(java.lang.String collID,
                      GCUBEScope scope,
                      GCUBESecurityManager securityManager)
               throws java.lang.Exception
Creates an instance for a given target collection, in a given scope, and with a given security manager.

Parameters:
collID - the identifier of the target collection.
scope - the scope.
securityManager - the security manager.
Throws:
java.lang.Exception - if the instance could not be created.

DocumentWriter

public DocumentWriter(CollectionReference reference,
                      GCUBEScope scope)
               throws java.lang.Exception
Creates an instance for a target collection, in a given GCUBEScope and with a given GCUBESecurityManager.

Parameters:
reference - a CollectionReference to the collection.
scope - the scope.
Throws:
java.lang.Exception - id the instance could not be initialised.

DocumentWriter

public DocumentWriter(CollectionReference reference,
                      GCUBEScope scope,
                      GCUBESecurityManager securityManager)
               throws java.lang.Exception
Creates an instance for a target collection, in a given GCUBEScope and with a given GCUBESecurityManager.

Parameters:
reference - a CollectionReference to the collection.
scope - the scope.
securityManager - the security manager.
Throws:
java.lang.Exception - id the instance could not be initialised.
Method Detail

add

public java.lang.String add(GCubeDocument doc)
                     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.

Specified by:
add in interface Writer
Parameters:
doc - 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

public GCubeDocument addAndSynchronize(GCubeDocument doc)
                                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.

Specified by:
addAndSynchronize in interface Writer
Parameters:
doc - 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

public java.util.List<AddOutcome> add(java.util.List<GCubeDocument> elements)
                               throws 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.

Specified by:
add in interface Writer
Parameters:
elements - 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:
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.IllegalArgumentException - if the document description is not valid for addition.
java.lang.Exception - if the operation cannot be completed due to local errors.

add

public java.util.concurrent.Future<?> add(java.util.Iterator<GCubeDocument> documents)
                                   throws 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.

Specified by:
add in interface Writer
Parameters:
documents - 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:
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.IllegalArgumentException - if the document description is not valid for addition.
java.lang.Exception - if the operation cannot be completed due to local errors.

update

public void update(GCubeDocument doc)
            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.

Specified by:
update in interface Writer
Parameters:
doc - 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

public GCubeDocument updateAndSynchronize(GCubeDocument doc)
                                   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.

Specified by:
updateAndSynchronize in interface Writer
Parameters:
doc - 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

public java.util.Map<java.lang.String,java.lang.Throwable> update(java.util.List<GCubeDocument> elements)
                                                           throws 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.

Specified by:
update in interface Writer
Parameters:
elements - a proxy which is valid for update.
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.IllegalArgumentException - if the proxy is not valid for update.
java.lang.Exception - if the operation cannot be completed due to local errors.

update

public java.util.concurrent.Future<?> update(java.util.Iterator<GCubeDocument> documents)
                                      throws 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.

Specified by:
update in interface Writer
Parameters:
documents - a proxy which is valid for update.
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.IllegalArgumentException - if the proxy is not valid for update.
java.lang.Exception - if the operation cannot be completed due to local errors.

delete

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

Specified by:
delete in interface Writer
Parameters:
doc - 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

public java.util.Map<java.lang.String,java.lang.Throwable> delete(java.util.List<GCubeDocument> elements)
                                                           throws DiscoveryException,
                                                                  GCUBEException,
                                                                  java.lang.Exception
Deletes a document description from the target collection using a proxy for it.

Specified by:
delete in interface Writer
Parameters:
elements - a proxy of the description to be deleted from the target collection.
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.IllegalArgumentException - if the input is not a proxy (i.e. has no identifier).
java.lang.Exception - if the operation cannot be completed due to local errors.

delete

public java.util.concurrent.Future<?> delete(java.util.Iterator<GCubeDocument> documents)
                                      throws DiscoveryException,
                                             GCUBEException,
                                             java.lang.Exception
Deletes a document description from the target collection using a proxy for it.

Specified by:
delete in interface Writer
Parameters:
documents - a proxy of the description to be deleted from the target collection.
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.IllegalArgumentException - if the input is not a proxy (i.e. has no identifier).
java.lang.Exception - if the operation cannot be completed due to local errors.

collectionID

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

Specified by:
collectionID in interface Writer
Returns:
the identifier.