Direct queries are query expression that are submitted as the value of the parameter q in a REST URL. By default, the query expression must be specified as a URL-encoded CohQL expression (the predicate part of CohQL). See Filtering Entries in a Result Set in Developing Applications with Oracle Coherence. The syntax of a direct query is as follows:

GET http://host:port/cacheName?q=query

For example, to query the person cache for person objects where age is less than 18:

GET http://host:port/person?q=age%3C18

Direct queries are disabled by default. To enabled direct queries, edit the coherence-rest-config.xml file and add a <direct-query> element for each resource to be queried and set the enabled attribute to true. For example:

<resource>
   <cache-name>persons</cache-name>
   <key-class>java.lang.Integer</key-class>
   <value-class>example.Person</value-class>
   <direct-query enabled="true"/>
</resource>

A 403 (Forbidden) response code is returned if a query is performed on a resource that does not have direct queries enabled.

Named queries are query expression that are configured for a resource in the coherence-rest-config.xml file. By default, the query expression must be specified as a CohQL expression (the predicate part of CohQL). Since this expression is configured in an XML file, any special characters (such as < and >) must be escaped using the corresponding entity. See Filtering Entries in a Result Set in Developing Applications with Oracle Coherence. In addition, named queries can include context values as required. The syntax of a named query is as follows:

GET http://host:port/cacheName/namedQuery?param1=value1,param2=value2...

To specify named queries, add any number of <query> elements, within a <resource> element, that each contain a query expression and name binding. See query. For example:

<resource>
   <cache-name>persons</cache-name>
   <key-class>java.lang.Integer</key-class>
   <value-class>example.Person</value-class>
   <query>
      <name>minors</name>
      <expression>age &lt; 18</expression>
   </query>
   <query>
      <name>first-name</name>
      <expression>name is :name</expression>
   </query>
</resource>

To use a named query, enter the name of the query within the REST URL. The following example uses the minors named query that is defined in the above example.

GET http://host:port/persons/minors

Parameters provide flexibility by allowing context values to be replaced in the query expression. The following example uses the :name parameter that is defined in the first-name query expression above to only query entries whose name property is Mark.

http://host:port/persons/first-name?name=Mark

Parameter names must be prefixed by a colon character (:paramName). Parameter bindings do not have access to type information, so it's possible to get a false where a true is expected on the comparison operators. To avoid such behavior, specify type hints as part of a query parameter (:paramName;int). Table 30-1 lists the supported type hints.

Named queries can also be used in conjunction with aggregation and entry processing. See Performing Aggregations with REST and Performing Entry Processing with REST, respectively. For example:

http://host:port/persons/first-name?name=Mark/long-max(age)

http://host:port/persons/first-name?name=Mark/increment(age,1)

The sort matrix parameter is an optional parameter used within a REST URL that provides the ability to order the returned results of a query. The sort parameter is available for both direct queries and named queries. The value of the sort parameters is a comma-separated list of properties to sort on, each of which can have an optional :asc (default) or :desc qualifier that determines the order of the sort. For example, to sort a list of people by last name with family members sorted from the oldest to the youngest, the sort parameter is defined as follows:

GET http://host:port/persons/minors;sort=lastName,age:desc

The following example uses the sort parameter as part of a direct query.

GET http://host:port/persons;sort=lastName,age:desc?q=age%3C18

Queries against large caches can potentially return large result sets that may cause out-of-memory errors. You should always use keys when querying large caches even though the use of keys in queries is optional. If keys are omitted, then the query may return all cache entries.

There are two ways to limit the number of results that are returned to a client: the start and count matrix parameters and the max-results attribute. Both ways are supported for direct and named queries.

The start and count parameters are optional integer arguments that determine the subset of the results to return. The following example uses the parameters as part of a named query and returns the first 10 entries sorted by name.

http://host:port/persons/minors;start=0;count=10;order=name:asc

The following example uses the parameters as part of a direct query.

GET http://host:port/persons;start=0;count=10?q=age%3C18

The max-results attribute is used within the coherence-rest-config.xml file and explicitly limits how many results are returned to the client. Note that this attribute does not limit the number of entries that are returned from a cache. The following example sets the max-results attribute:

<resource max-results="50">
   <cache-name>persons</cache-name>
   <key-class>java.lang.Integer</key-class>
   <value-class>example.Person</value-class>
   <direct-query enabled="true" max-results="25">
   <query max-results="25">
      <name>minors</name>
      <expression>age &lt; 18</expression>
   </query>
</resource>

The max-results value for a direct or named query overrides the resource's max-results value if both are specified. If a query includes a count parameter and a max-results element is also specified, the lesser value is used.

It is possible to retrieve just keys of entries stored in cache. Key operations do not support paging and sorting, therefore those query parameters, if submitted, are ignored. The following key retrieval operations are supported:

GET http://host:port/cacheName/keys

Returns the keys of all entries in the cache.

GET http://host:port/cacheName/keys?q=query

Returns the keys of all entries satisfying the direct query criteria.

GET http://host:port/cacheName/namedQuery/keys

Returns the keys of all entries that satisfy the named query criteria.

This section includes the following topics:

• Implementing Custom Query Engines
  
• Enabling Custom Query Engines
  

The following examples demonstrate how to perform aggregations using REST. If the aggregation succeeds, a 200 (OK) status code returns with the aggregation result as an entity.

• Aggregates all entries in the cache.

  GET http://host:port/cacheName/aggregator(args, ...)
  

• Aggregates query results. The query must be specified as a URL-encoded CohQL expression (the predicate part of CohQL).

  GET http://host:port/cacheName/aggregator(args, ...)?q=query
  
  GET http://host:port/cacheName/namedQuery/aggregator(args, ...)?param1=value1
  

• Aggregates specified entries.

  GET http://host:port/cacheName/(key1, key2, ...)/aggregator(args, ...)
  

Coherence REST provides a simple strategy for aggregator creation (out of aggregator related URL segments). Out-of-box, Coherence REST can resolve any registered (either built-in or user registered) aggregator with a constructor that accepts a single parameter of type com.tangosol.util.ValueExtractor (such as LongMax, DoubleMax, and so on). If an aggregator call within a URL doesn't contain any parameters, the aggregator is created using com.tangosol.util.extractor.IdentityExtractor.

If an aggregator segment within the URL doesn't contain any parameters nor a constructor accepting a single ValueExtractor exists, Coherence REST tries to instantiate the aggregator using a default constructor which is the desired behavior for some built-in aggregators (such as count).

The following example retrieves the oldest person in a cache:

GET http://host:port/people/long-max(age)

The following example calculates the max number in a cache containing only numbers:

GET http://host:port/numbers/comparable-max()

The following example calculates the size of the people cache:

GET http://host:port/people/count()

The following pre-defined aggregators are supported:

Custom aggregator types can be defined by specifying a name to be used in the REST URL and a class implementing either the com.tangosol.util.InvocableMap.EntryAggregator interface or the com.tangosol.coherence.rest.util.aggregator.AggregatorFactory interface.

An EntryAggregator implementation is used for simple scenarios when aggregation is either performed on single property or on cache value itself (as most of the pre-defined aggregators do).

The AggregatorFactory interface is used when a more complex creation strategy is required. The implementation must be able to resolve the URL segment containing aggregator parameters and use the parameters to create the appropriate aggregator.

Custom aggregators are configured in the coherence-rest-config.xml file within the <aggregators> elements. See aggregator. The following example configures both a custom EntryAggregator implementation and a custom AggregatorFactory implementation:

<aggregators>
   <aggregator>
      <name>my-simple-aggr</name>
      <class-name>com.foo.MySimpleAggregator</class-name>
   </aggregator>
   <aggregator>
      <name>my-complex-aggr</name>
      <class-name>com.foo.MyAggreagatorFactory</class-name>
   </aggregator>
</aggregators>

The following examples demonstrate how to perform entry processing using REST. If the processing succeeds, a 200 (OK) status code returns with the processing result as an entity.

• Process all entries in the cache.

  POST http://host:port/cacheName/processor(args, ...)
  

• Process query results.

  POST http://host:port/cacheName/processor(args, ...)?q=query
  
  POST http://host:port/cacheName/namedQuery?param1=value1/processor(args, ...)
  

• Process specified entries.

  POST http://host:port/cacheName/(key1, key2, ...)/processor (args, ...)
  

Unlike aggregators, processors (even the pre-defined processors) have more diverse creation patterns, so Coherence REST does not assume anything about processor creation. Instead, for each entry processor implementation, there needs to be an implementation of the com.tangosol.coherence.rest.util.processor.ProcessorFactory interface that can handle an input string from a URL section and instantiate the processor instance. Out-of-box, Coherence REST provides two such factories for NumberIncrementor and NumberMultiplier.

The following example increments each person's age in a cache by 5:

POST http://localhost:8080/people/increment(age, 5)

The following example multiplies each number in a cache containing only numbers by the factor 10:

POST http://localhost:8080/numbers/multiply(10)

The following pre-defined processors are supported:

Custom entry processors can be defined by specifying a name to be used in a REST URL and a class that implements the com.tangosol.coherence.rest.util.processor.ProcessorFactory interface.

Custom entry processors are configured in the coherence-rest-config.xml file within the <processors> elements. See processors. The following example configures a custom ProcesorFactory implementation:

<processors>
   <processor>
      <name>my-processor</name>
      <class-name>com.foo.MyProcessorFactory</class-name>
   </processor>
</processors>

Web pages use the EventSource object to receive server-sent events. The EventSource object connects to a specified URI where events are generated and custom EventListeners are added to listen and process the incoming server-sent events. The following code from the Coherence REST example uses JavaScript to create a new EventSource object that listens to the /cache/contacts URI and adds event listeners for insert, update, delete, and error events.

$scope.startListeningContacts = function() {
   $scope.contacts.listening = true;
   $scope.contacts.started   = true;

   if ($scope.contacts.filter == 'all') {
      query = '';
   }
   else if ($scope.contacts.filter == '>=45') {
      query = '?q=age%20>=%2045';
      $scope.contacts.filter = 'age >= 45';
   }
   else {
      query = '?q=age%20<%2045';
      $scope.contacts.filter = 'age < 45';
   }

   $scope.contacts.status  = 'Listening: ' + $scope.contacts.filter;
   var eventSourceContacts = new EventSource('/cache/contacts' + query);

   eventSourceContacts.addEventListener('insert', function(event) {
      $scope.contacts.insertCount++;
      $scope.contacts.allCount++;
      $scope.updateContactEvent(JSON.parse(event.data), 'insert');
      $scope.$apply();
   });

   eventSourceContacts.addEventListener('update', function(event) {
      $scope.contacts.updateCount++;
      $scope.contacts.allCount++;
      $scope.updateContactEvent(JSON.parse(event.data), 'update');
      $scope.$apply();
   });

   eventSourceContacts.addEventListener('delete', function(event) {
      $scope.contacts.deleteCount++;
      $scope.contacts.allCount++;
      $scope.updateContactEvent(JSON.parse(event.data), 'delete');
      $scope.$apply();
   });

   eventSourceContacts.addEventListener('error', function(event) {
      var eventData = JSON.parse(event.data);
      alert('error');
   });
};

When an event is received, an application can choose take some meaningful action based on the event. For example:

$scope.updateContactEvent = function(eventData, eventType) {
   $scope.contacts.eventType = eventType;
   $scope.contacts.eventKey  = eventData.key.firstName + ' ' + 
      eventData.key.lastName;

   $scope.contacts.eventNewValue = 'N/A';
   $scope.contacts.eventOldValue = 'N/A';

   if (eventType == 'insert' || eventType == 'update') {
      $scope.contacts.eventNewValue = $scope.getContactString(eventData.newValue);
   }
   if (eventType == 'delete' || eventType == 'update') {
      $scope.contacts.eventOldValue = $scope.getContactString(eventData.oldValue);
   }
};