CollectionView
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.views
Interface CollectionView<E extends GCubeElement,P extends Property>

Type Parameters:
  `E` - the type of `GCubeElement`s characterised by the view.
  `P` - the type of the properties of the `GCubeElement`s characterised by the view.

All Known Implementing Classes:
  AnnotationView, BaseCollectionView, GenericView, MetadataView, SimpleView

    public interface CollectionView<E extends GCubeElement,P extends Property>

A local proxy of a remote view defined over the document descriptions of a remote collection.

Collection views are document-oriented abstractions over the generic `View` proxies of the View Manager (VM) service.
Most properties of `View` proxies carry over directly to collection views, including:

- the collection identifier (cf. `collectionId()`);
- the view identifier (cf. `id()`);
- the descriptive name of the view, e.g `"myview"` (cf. `name()`);
- the free-form description of the view, e.g. `"all document descriptions such that..."` (cf. `description()`);
- the broad type of the view, e.g. a `QName` like `{http://...}mytype` (cf. `type()`);
- the time of last update of the view (cf. `lastUpdate()`)
- the cardinality of the view (cf. `cardinality()`);
- the generic properties of the view (cf. `properties()`).

Most importantly, the tree `Predicate`s used in `View` proxies to characterise the document descriptions in the view become `Projection`s over `GCubeElement`s, whether entire document descriptions (i.e. `GCubeDocument`s) or specific inner elements of such descriptions (e.g. `GCubeMetadata`s).

Collection views can be used for:

- view creation: collection views can be published with the VM as remote views for the target collection (cf. `#publish(boolean)`);
- view discovery: collection views can act as simple queries to discover similar remote views of the same type (cf. `findSimilar()`). In this case, the following view properties are all transformed into equality constraints for the query:
  - the view identifier;
  - the collection identifier;
  - the view type;
  - the generic properties of the view.
  This supports combinations of three common use cases for view discovery: `view-by-id`, `views-for-collection`, and `views-with-properties`. For cross-collection discovery, see `Views.find(String, GCUBEScope)`, `Views.find(String, GCUBEScope, GCUBESecurityManager)`.
- view-based access: collection views can provide `ViewReader`s for retrieving document descriptions in the remote views (cf. `reader()`);

The possibility of using a collection view for creation, discovery, and access depends on the state as a proxy of a remote view (cf. `isBound()`). In particular:

- if the view is bound to a remote view, then it may be used only for access.
- if the view is unbound, then it may be used for creation and discovery.

Typically, collection views are created unbound and used for publication or discovery, depending on the general goals of the client. Both operations introduce bindings. A published view become bound and all the views returned from discovery operations are naturally bound. These can then be used for view-based access. In less common cases, clients may start with a VM proxy and inject it directly into a view, which is thus bound. Implementations of this interface are responsible for enforcing state-based constraints.

Author:
  Fabio Simeoni (University of Strathclyde)

Method Summary
`long` | `cardinality()` Returns the cardinality of the view.
`java.lang.String` | `collectionId()` Returns the identifier of target collection of the view.
`void` | `delete()` Delete the view and un-publish it.
`java.lang.String` | `description()` Returns the description of the view.
`java.util.List<? extends CollectionView<E,P>>` | `findSimilar()` Returns proxies for all the views that share the same properties as the view associated with this proxy.
`java.lang.String` | `id()` Returns the identifier of the view.
`View` | `inner()` Returns the inner view.
`boolean` | `isBound()` Returns `true` if this proxy is bound.
`java.util.Calendar` | `lastUpdate()` Returns the time in which the view was last updated.
`java.lang.String` | `name()` Returns the name of the view.
`Projection<E,P>` | `projection()` Returns the `Projection` that defines the view.
`java.util.Map<javax.xml.namespace.QName,ViewProperty>` | `properties()` Returns the generic properties of the view.
`void` | `publish()` Publishes this proxy as a remote view.
`void` | `publishAndBroadcast()` Publishes this proxy as a remote view and broadcasts the publication.
`ViewReader` | `reader()` Returns a `Reader` for retrieving the elements of the view.
`GCUBEScope` | `scope()` Returns the scope of the view.
`GCUBESecurityManager` | `securityManager()` Returns the `SecurityManager` to use view discovery and view-based access.
`javax.xml.namespace.QName` | `type()` Returns the type of the view.

Method Detail

### inner

    View inner()

  Returns the inner view.

  Returns:
    the inner view.

### collectionId

    java.lang.String collectionId()

  Returns the identifier of target collection of the view.

  Returns:
    the identifier.

### id

    java.lang.String id()

  Returns the identifier of the view.

  Returns:
    the identifier.

### type

    javax.xml.namespace.QName type()

  Returns the type of the view.

  Returns:
    the type.

### name

    java.lang.String name()

  Returns the name of the view.

  Returns:
    the name.

### description

    java.lang.String description()

  Returns the description of the view.

  Returns:
    the description.

### lastUpdate

    java.util.Calendar lastUpdate()

  Returns the time in which the view was last updated.

  Returns:
    the last update time.

### cardinality

    long cardinality()

  Returns the cardinality of the view.

  Returns:
    the cardinality.

### projection

    Projection<E,P> projection()

  Returns the `Projection` that defines the view.

  Returns:
    the projection.

### properties

    java.util.Map<javax.xml.namespace.QName,ViewProperty> properties()

  Returns the generic properties of the view.

  Returns:
    the properties.

### scope

    GCUBEScope scope()

  Returns the scope of the view.

  Returns:
    the scope.

### securityManager

    GCUBESecurityManager securityManager()

  Returns the `SecurityManager` to use view discovery and view-based access.

  Returns:
    the manager.

### isBound

    boolean isBound()

  Returns `true` if this proxy is bound.

  Returns:
    `true` if this proxy is bound.

### reader

    ViewReader reader()
                      throws java.lang.IllegalStateException,
                             java.lang.Exception

  Returns a `Reader` for retrieving the elements of the view.

  Returns:
    the `Reader`.
  Throws:
    `java.lang.IllegalStateException` - if the view is unbound.
    `java.lang.Exception` - if the `Reader` could not be instantiated.

### publish

    void publish()
                 throws java.lang.IllegalStateException,
                        GCUBEException,
                        java.lang.Exception

  Publishes this proxy as a remote view.

  Throws:
    `java.lang.IllegalStateException` - if the view is bound.
    `GCUBEException` - if the operation fails due to remote errors.
    `java.lang.Exception` - if the operation fails due to local errors.

### publishAndBroadcast

    void publishAndBroadcast()
                             throws java.lang.IllegalStateException,
                                    GCUBEException,
                                    java.lang.Exception

  Publishes this proxy as a remote view and broadcasts the publication.

  Throws:
    `java.lang.IllegalStateException` - if the view is bound.
    `GCUBEException` - if the operation fails due to remote errors.
    `java.lang.Exception` - if the operation fails due to local errors.

### delete

    void delete()
                throws java.lang.IllegalStateException,
                       GCUBEException,
                       java.lang.Exception

  Delete the view and un-publish it.

  Throws:
    `java.lang.IllegalStateException` - if the view is unbound.
    `GCUBEException` - if the operation fails due to remote errors.
    `java.lang.Exception` - if the operation fails due to local errors.

### findSimilar

    java.util.List<? extends CollectionView<E,P>> findSimilar()
                                                                                                    throws DiscoveryException,
                                                                                                           GCUBEException,
                                                                                                           java.lang.Exception

  Returns proxies for all the views that share the same properties as the view associated with this proxy.

  Throws:
    `DiscoveryException` - if the operation could not be completed due to service discovery errors.
    `GCUBEException` - if the operation could not be completed due to other forms of remote errors.
    `java.lang.Exception` - if the operation could not be completed due to local errors.

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