COSMOSQueryInterfaceInitialDesign

Design Requirements

Remoteable The Query service must be accessible to remote consumers on both java and non-java platforms.

Introspectable The Query service's capabilities must be discoverable at runtime. Mechanisms must be provide to introspect the service in local and remote environments. The Query service must allow consumers to determine the types of queries that may be specified for the service implementation, the return formats of the service supports, and the valid combinations of query and return formats. Additionally, the Query service must provide a mechanism for determining the scope of the data being queried (for example, the set of machines for which a particular query service exposes log data for).

Decoupled from Implementation The Query service API must not specify any particular underyling data store type or query language. The API must be flexible enough to allow adoptors to easily integrate existing data stores, but must be suitable to encourage de-facto standards and/or standard implementations to emerge.

Optimizable The Query service API must not over-specific to the point of precluding optimizations.

High Level Structure

The Query service is implemented as a QueryComponent type, which acts as a root node in a DataCollection Assembly. QueryComponent implementations must implement a QueryService interface, which is converted into a WSDM capability on the QueryComponent at runtime. The QueryComponent also supports the MetadataExchange capability, allowing a QueryComponent instance to provide both a WSDL and SML description of itself.

The QueryService interface by itself is very generic. It is envisioned that additional 'de-facto' standard interfaces (eg a LogDataService) will emerge and either layer on top of sit adjacent to the QueryService interface.

QueryComponents may interact with Transforms and Filters to modify the collections to be returned by specific queries. In order to control the path through a series of transformations and/or filters, all sub-trees wired into a QueryComponent must terminate with a special type of component (a QueryResponse component) that allows the framework to determine the types of query dialect/response pairs are supported by component.

Query Capability The Query capability is implemented using the following interface:

@ManagedResourceCapability(namespace="http://cosmos.eclipse.org/capabilities/query")
public interface IDataQueryService extends IWireSource, IWireTerminal {


	@ManagedOperation(namespace=NAMESPACE_URI)
	String[] getSupportedDialects();
	
	@ManagedOperation(namespace=NAMESPACE_URI)
	String[] getSupportedResponses();
	
	@ManagedOperation(namespace=NAMESPACE_URI)
	boolean supportedQuery(String dialect, String response);	
	
	@ManagedOperation(namespace=NAMESPACE_URI)
	IDataQueryResult query(String dialect, String response, String queryString) throws Exception;
	
	@ManagedOperation(namespace=NAMESPACE_URI)
	IDataQueryResult pageQuery(String dialect, String response, String queryString, int max, int start) throws Exception;

}

This interface is annotated to expose itself as a WSDM manageability capability with a URI of http://cosmos.eclipse.org/capabilities/query. The getSupportedDialects and getSupportedResponses methods provide an initial introspection capability, where the supportedQuery method allows the consumer to determine support for a particular combination of dialect and response types.

The query method supports a generic query with no restrictions on the return value.

The pageQuery method supports page-oriented query semantics, useful for large data sets.

The IDataQueryResult is a simple wrapper object that may contain either a single object or a single collection.

Query Component Types

The QueryComponent type may only exist as the direct child of an outbound DataCollection Assembly. The QueryComponent may support a default (preferred) response type, but may also be wired to Transformers or Filters to convert or remove results for the query response collection. For any component chains wired to a Query, those chains MUST be terminated with a QueryResponse Component.

<?xml version="1.0" encoding="UTF-8"?>
<!--
 *  Test configuration for outbound pipeline
 -->
<context xmlns="http://www.eclipse.org/xmlns/cosmos/1.0"
	xmlns:cosmos="http://www.eclipse.org/xmlns/cosmos/1.0"
	xmlns:test="http://cosmos.eclipse.org/tests/runtime/1.0"
	cosmos:name="TestQuery" cosmos:direction="out">
	<query cosmos:factory="TestQueryFactory" cosmos:optimizable="true">
		<test:binding/>
		<transform cosmos:factory="TestTransformFactory" cosmos:optimizable="false">
			<test:binding/>
			<response cosmos:factory="TestResponseFactory" cosmos:optimizable="true">
				<test:binding/>
			</response>
		</transform>
	</query>    
</context>

Query Response Type

The QueryResponse component type acts as a collection point for objects that are dispatched through a DataCollection wire. For inbound assemblies, all objects dispatched through a DataCollection wire are either ignored or persisted - there is no requirement to return objects from the wire. For outbound assemblies, the whole reason for being is to return objects from the DataCollection wire - hence the requirement for a collector component. For cases where the desired return type requires a wire to be active, the ResponseObject performs the role of populating the collection object in a IDataQueryResult instance provided by the root QueryComponent.