Latest revision as of 17:23, 3 October 2011

The View Manager service defines, publishes, and maintains selective views over the content of collections exposed by the Content Manager service. It is a key component of the gCube subsystem that deals with the organisation of content and related data.

We overview here the motivations, architecture and interfaces of the service, as well as its client library.

Motivations

The main purpose of the Content Manager service is to offer read and write access to the content of document collections maintained both within and outside the system. In doing so, it also publishes information about the collections and it maintains this information over time. Often, however, similar 'collection management services' are required for groups of documents, or document parts, which share common properties within a single collection. For example, the system needs information about all the metadata of a certain type and in a certain language which occur across the documents of a single collection. Similarly, the system may need information about all the documents in the collection which have been updated over the last month.

Clients of the Content Manager service may use gDoc predicates to extract such information from the collection at any time. However, a dedicated service is required to publish and maintain these collection views over time and for an arbitrary number of clients.

The View Manager service serves precisely this purpose within the system. It does so in a general fashion, creating, publishing, and maintaining any content view that can be captured by a gDoc predicate. It can also delegate to specialised plugins the maintenance of content views of particular significance and persistence within the system. Metadata and annotation views, for example, are maintained by specialised plugins of the View Manager service.

What the View Manager does not do, however, is to expose the content of the views it maintains. Access remains based instead on the Content Manager service alone, without the costs of mediated access over the wide-area network. In this sense, we say that the View Manager maintains passive views. The expectation here is that access transparencies normally associated with 'active views' may be regained at the client-side, in association with view-specific access libraries that complement corresponding service plugins. Naturally, the gCube Document Library offers such transparencies for the service plugins dedicated to the management of metadata and annotation views.

Architecture

The interface of the View Manager is distributed across two port-types:

• the View port-type serves as the interface of WS-Resources that model and publish the properties that define a content view. Some properties are defined when the view is created and do not change over time (static properties). Others requires explicit maintenance (dynamic properties). We discuss in detail the interface and Resource Properties of View resources below.

• the Factory port-type serves as the interface of a single WS-Resource that publishes information about the plugins hosted by service instance and allows the creation of View resources from definitions provided by clients, as well as their destruction. We discuss in detail the interface and Resource Properties of the Factory resource below.

View resources may be extended by delegates provided by service plugins. Delegates are first invoked by the Factory when clients mention the name of the corresponding plugin in their requests to create content views. Their task is to validate the definitions provided by clients and to maintain the dynamic properties of the view thereafter.

At the time of writing, the View Manager embeds three plugins:

• default plugin: manages arbitrary views, i.e. views that may not be more specifically managed through specialised plugins.
• metadata plugin: specialises in views over the metadata elements of the GCube Document Model.
• annotation plugin: specialises in views over the annotation elements of the GCube Document Model.

Interfaces

In this Section, we discuss in more detail the operations of the service port-types and the Resource Properties of the corresponding WS-Resources. For clarity, we show and comment the signatures of operations in terms of the underlying Java implementation, which mirror the WSDL definitions. We point directly to the WSDL for the definition of auxiliary data structures for input and outputs (e.g. values of Resource Properties).

note: the service offers a client-side library that operates at a higher level of abstraction than its public interface. The operations discussed below are of interest to clients that choose to bypass those facilities, typically because they cannot afford a static dependency to them.

Factory

The Factory resource exposes a single operation for clients that wish to create View resources. The operation is not intended for generic use, in that clients are expected to target a specific plugin to which the Factory ought to delegate the creation of a View resources. A default plugin is called upon when another one is not specifically targeted. The operation, its inputs, and its outputs are formally defined in the WSDL of the port-type:

• public ViewReference create(VMSCreateParams params) throws GCUBEFault

the operation creates a View resource and returns a references to it, which includes its endpoint as well as a model of its properties (at least those which were computed at creation time). Requests are paremetrised by:

• the name of the plugin to which the service ought to dispatch the request, the target plugin. If this is omitted, the request is implicitly addressed to the default plugin.
• a model of view that includes all the view properties to be set on the resource, from the identifier of the view to the predicate that defines it, to any other property that may be required by the target plugin.

The Factory resource exposes the following Resource Properties (in addition to standard system properties):

• Plugin: (multi-valued) a set of properties that describe a service plugin hosted by the service instance, including:

• name: the name of the plugin;
• description: a free-form description of the plugin;
• property: (multi-valued) an additional, arbitrary property of the plugin, as standardly defined for service plugins.

Views

View resources do not expose operations other than the standard operations for resource management defined by the GCUBEProvider (lifetime, Resource Property inspection, Resource Property change).

On the other hand, View resources publish the following Resource Properties (in addition to standard system properties):

• View: a set of view properties, including:

• id: the identifier of the view;
• collectionID: the identifier of the content collection bound to the view.
• type: a qualified name that types the view.
• description: a free-form description of the view;
• predicate: the predicate that identifies the elements of the view;
• cardinality: an estimate of the number of elements of the view;
• lastUpdate an estimate of the time in which the view was last updated;
• property: an additional, arbitrary property of the view (multi-valued):

• name: the qualified name of the property;
• description: a free-form description of the property;
• value: the string value of the property.

• Plugin: the name of the plugin bound to the resource.

Client Library

The Client Library offers linguistic abstractions over the interface of the View Manager service. In this role, it acts both as a client library and as a service-side library. In particular, it is a dependency of the service as well as a dependency of service clients.

The library includes:

• the stubs of the service automatically generated from the WSDL definition of its port-types;
• the high-level calls, a set of abstractions over the service stubs;

High-level calls are Java objects that model interactions with the View Manager service. encapsulating stub-based interactions behind local object-oriented interfaces that offer transparencies over the remote interfaces of the service port-types. In particular, the local interfaces are based on language features that are not found in the service stubs, including high-level models of inputs and outputs, method overloading, and parametric types.

Behind these abstractions, the call objects engage in optimised and best-effort interactions with the WS-Resources of the service. In particular, they can hide from clients the complexity of resource discovery while keeping visible the remote nature of the interactions and the possibility of their failure.

High-level calls are defined in the package <code>org.gcube.contentmanagement.viewmanager.stubs.calls and rely on models defined in the package org.gcube.contentmanagement.contentmanager.stubs.model. From the client perspective, the components of interests are:

• ViewCall: represents calls to the Factory port-type of the service, hence offer high-level APIs to create and destroy views.
• View: represents a view managed by the service as a WS-Resource.
• Constants: a set of constants for client use.

A ViewCall is created with reference to a target plugin of the View Manager and a scope:

//some scope
GCUBEScope scope = ...
 
//some plugin
String plugin = ... 
ViewCall call = new ViewCall(pluginName,scope);

In a secure infrastructure, the call may also be configured with a security manager:

//some scope
GCUBEScope scope = .....
 
//some plugin
String plugin = ...
 
//some security manager = ....
GCUBESecurityManager manager = ....
 
ViewCall call = new ViewCall(plugin,scope,manager);

In both cases, the plugin can be omitted. In this case, the ViewCall targets the default plugin for arbitrary views.

The call may then be issued, i.e. used to create or destroy views. To create a view, clients first define it as an View object and the pass the object to the create method. In the following example, the client creates a generic view over a given collection, a view defined by an arbitrary predicate and managed by the default service plugin:

GCUBEScope scope = ...
 
ViewCall call = new ViewCall(scope);
 
View view =new View(); 
view.setCollectionID("...");v.setDescription("..."); 
QName type = ...
view.setType(type); 
TreePredicate predicate = ..
v.setPredicate(predicate); 
view = call.create(view);

Here the client indicates the target collection, a description of the view, a free-form type label as a QName and, most importantly, the defining predicate over the documents of the collection. Arbitrary ViewPropertys could be part of the definition (see addProperty method), as could an identifier of the view if the client wanted to provide one and thus take responsibility for its uniqueness (see setId()). Alternatively, the service will generate a unique identifier for the view, as well as compute its dynamic properties (cardinality and time of last update) upon successful creation of a corresponding WS-Resource. These properties are made available to the client after the invocation of the create() method, which returns a model of the view that complements the original definition passed as a parameter with the properties set by the service (hence the re-assignment above).

In the interaction triggered by create, the ViewCall will attempt to discover Factory WS-Resources that host the target plugin. It will then try to interact with each resource in turn, until one responds successfully or else indicates that continuing will be to no avail (by returning a GCUBEUnretrievableFault).

Clients who know and wish to target a specific Factory resource, can disable the best-effort strategy by configuring the call with a reference to its endpoint:

//a reference to the endpoint of a View WS-Resource
EndpointReferenceType epr = ...
 
call.setEndpointReferenceType(epr);

Clients may destroy a view that exists as a WS-Resource of the service if they have e reference to its endpoint. This could be discovered, of course, or else stored from the creation of the view, using the getEndpointReference method of the View object returned from an invocation of the create method, e.g.:

ViewCall createCall = ...
 
View view = ...
view =  createCall.create(view);
 
EndpointReference epr = view.getEndpointReference(); 
...
 
ViewCall destroyCall = ...
 
destroyCall.destroy(epr);

Creating and destroying metadata and annotation views follows similar patterns, deviating only in these respects:

• the target plugin named at ViewCall-creation time, which is Constants.METADATA_PLUGIN_NAME for metadata views and Constants.ANNOTATION_PLUGIN_NAME for annotation views.
• the type of the view, which is set by the plugin.
• the view predicate, which is synthesised by the plugin based on the value of plugin-specific properties, which are named after three distinguished properties of document elements defined in |gCube Document Model: language, schema name, and schema uri. Clients may refer to them using the corresponding constants defined in the org.gcube.contentmanagement.gcubemodellibrary.constants.Labels package of the gCube Model Library (LANGUAGE, SCHEMA_NAME, andSCHEMA_URI.

As an example of metadata view creation, consider the following:

import static org.gcube.contentmanagement.viewmanager.stubs.calls.Constants.*;
import static org.gcube.contentmanagement.gcubemodellibrary.constants.Labels.*;
 
...
 
View metadataView = new View)();
 
metadataView.setCollectionID("...");
metadataView.setDescription("...");
 
ViewProperty property = new ViewProperty();
property.setName(new QName(LANGUAGE));
property.setValue("...");
 
metadataView.addProperty(property);
 
property = new ViewProperty();
property.setName(new QName(SCHEMA_NAME));
property.setValue("...");
 
metadataView.addProperty(property);
 
property = new ViewProperty();
property.setName(new QName(SCHEMA_URI));
property.setValue("...");
 
metadataView.addProperty(property);
 
GCUBEScope scope = ...
 
metadataView = new ViewCall(METADATA_PLUGIN_NAME,scope).create(metadataView);