cz.cuni.versatile.api
Interface ResourceProvider

All Superinterfaces:
PropertyRegistry

public interface ResourceProvider
extends PropertyRegistry

ResourceProvider is an abstraction of a multi-variant resource repository or a class factory. The implementations of the interface are assumed to be specialized for a particular role or an environment. For example:

In a typical configuration, we envision multiple purpose-specific ResourceProvider instances to correspond to a single general-purpose DeliveryContext within a particular application scope (e.g. a module or a component). On the other hand, resource providers are more-likely to be re-used across multiple application scopes.

Remarks: The main purpose of using the property mappings in the ResourceProvider is to allow for a kind of reverse mapping: The mappings in the DeliveryContext transform meta-data from domain-specific to application-centric data structures. The ResourceProvider may need to transform these data back as it consumes queries using the application-centric properties, while the resource repository can have the data annotated using the original raw meta-data or a third-party meta-data. Of course, in a perfect world, the resource repositories are cleansed and tagged by the application-centric annotations, but this may not be always possible in practice.

An important consequence of the above is that when registering a mapped property in the ResourceProvider, the semantics of the PropertyRegistry.registerProperty(Property, PropertyMapping) is exactly the opposite to the DeliveryContext: we are not transforming to the mapped property but instead from the property being mapped to the built-in properties of the ResourceProvider. (Naturally, there is no need to register the leaf properties in the case of the ResourceProvider as they are exactly those built-in properties specific to a particular ResourceProvider implementation and/or instance.)

Author:
Jaroslav Gergic
See Also:
PropertyRegistry.registerProperty(Property, PropertyMapping)

Method Summary
 ResultSet get(Query q)
          Get an N-best collection of resources matching the given Query.
 ResultSet get(java.lang.String resourceName, QueryTemplate qt)
          Get an N-best collection of resources matching the given resourceName and query template.
 java.lang.Object getValue(java.lang.String resourceName, QueryTemplate qt)
          Get the closest match without the attached meta-data annotations.
 
Methods inherited from interface cz.cuni.versatile.api.PropertyRegistry
getProperties, getProperty, getPropertyMapping, hasProperty, hasProperty, isMappedProperty, registerProperty, unregisterProperty
 

Method Detail

get

public ResultSet get(Query q)
              throws UnregisteredPropertyException,
                     java.util.MissingResourceException
Get an N-best collection of resources matching the given Query. The method always returns at least a collection which one entry (or fires an exception).

Parameters:
q - a Query to process
Returns:
an N-best collection of resources matching the given Query
Throws:
UnregisteredPropertyException - in case a property in the query is not known (registered) to the ResourceProvider
java.util.MissingResourceException - in case there are no resource entries matching the Query

get

public ResultSet get(java.lang.String resourceName,
                     QueryTemplate qt)
              throws UnregisteredPropertyException,
                     java.util.MissingResourceException
Get an N-best collection of resources matching the given resourceName and query template.

(Syntax sugar: Semantically equivalent to calling ResourceProvider.get(qt.newQuery(resourceName)).)

Parameters:
resourceName - a unique identifier of a resource in the scope of the ResourceProvider
(resource means a versioned entity, not a particular version/variant of that entity)
qt - a QueryTemplate specifying the meta-data constraints (preferences) and other query settings
Returns:
an N-best collection of resources matching the given Query
Throws:
UnregisteredPropertyException - in case a property in the query is not known (registered) to the ResourceProvider
java.util.MissingResourceException - in case there are no resource entries matching the Query

getValue

public java.lang.Object getValue(java.lang.String resourceName,
                                 QueryTemplate qt)
                          throws UnregisteredPropertyException,
                                 java.util.MissingResourceException
Get the closest match without the attached meta-data annotations.

(Syntax sugar: Semantically equivalent to calling ResourceProvider.get(qt.newQuery(resourceName)).getValue().)

Parameters:
resourceName - a unique identifier of a resource in the scope of the ResourceProvider
(resource means a versioned entity, not a particular version/variant of that entity)
qt - a QueryTemplate specifying the meta-data constraints (preferences) and other query settings
Returns:
the value from the first ResourceEntry of the N-best ResultSet
Throws:
UnregisteredPropertyException - in case a property in the query is not known (registered) to the ResourceProvider
java.util.MissingResourceException - in case there are no resource entries matching the Query