Skip Headers
Oracle® Coherence Client Guide
Release 3.7.1

Part Number E22839-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

28 Using the Coherence REST API

The Coherence REST API pre-defines many operations that can be used to interact with a cache. In addition, custom operations such aggregators and entry processors can be created as required.

The following sections are included in this chapter:

28.1 Specifying Key and Value Types

The Coherence REST services require metadata about the cache that they expose. The metadata includes the cache entry's key and value types as well as key converters and value marshallers. The key and value types are required in order for Coherence to be able to use built-in converters and marshallers (both XML and JSON are supported).

To define the key and value types for a cache entry, edit the coherence-rest-config.xml file and include the <key-class> and the <value-class> elements within the <resource> element whose values are set to key and value types, respectively. See "resource" for a detailed reference of the <resource> element.

The following example defines a String key class and a value class for a Person user type:

<resources>
   <resource>
      <cache-name>dist-http-example</cache-name>
      <key-class>java.lang.String</key-class>
      <value-class>example.Person</value-class>
   </resource>
</resources>

28.2 Performing Single-Object REST Operations

The RESTful API includes support for performing GET, PUT, and DELETE operations on a single object in a cache.

GET Operation

GET http://host:port/cacheName/key

Returns a single object from the cache based on a key. A 404 (Not Found) message is returned if the object with the specified key does not exist. The get operation supports partial results (see "Performing Partial-Object REST Operations" for details).

The following sample output demonstrates the response of a GET operation:

* Client out-bound request
> GET http://127.0.0.1:8080/dist-http-example/1
> Accept: application/xml
 
* Client in-bound response
< 200
< Content-Length: 212
< Content-Type: application/xml
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Person><id>1</id><name>
Mark</name><address><street>500 Oracle Parkway</street><city>Redwood Shores</city>
<country>United States</country></address></Person>

* Client out-bound request
> GET http://127.0.0.1:8080/dist-http-example/1
> Accept: application/json

* Client in-bound response
< 200
< Content-Type: application/json
<
{"@type":"rest.Person","address":{"@type":"rest.Address","city":"Redwood Shores",
"country":"United States","street":"500 Oracle Parkway"},"id":1,"name":"Mark"}

PUT Operations

PUT http://host:port/cacheName/key

Creates or updates a single object in the cache. A 200 (OK) message returns if the object was updated. If optimistic concurrency check fails, a 409 (Conflict) message returns with the current object as an entity. See "Understanding Concurrency Control" for details.

The following sample output demonstrates the response of a PUT operation:

* Client out-bound request
> PUT http://127.0.0.1:8080/dist-test-sepx/1
> Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Person><id>1</id><name>
Mark</name><address><street>500 Oracle Parkway</street><city>Redwood Shores</city>
<country>United States</country></address></Person>
 
* Client in-bound response
< 200
< Content-Length: 0
<
 
* Client out-bound request
> PUT http://127.0.0.1:8080/dist-test-sepj/1
> Content-Type: application/json
{"@type":"rest.Person","id":1,"name":"Mark","address":{"@type":"rest.Address","str
eet":"500 Oracle Parkway","city":"Redwood Shores","country":"United States"}}
 
* Client in-bound response
< 200
< Content-Length: 0
<

Delete Operation

DELETE http://host:port/cacheName/key

Deletes a single object from the cache based on a key. A 200 (OK) message is returned if the object is successfully deleted, or a 404 (Not Found) message is returned if the object with the specified key does not exist.

28.3 Performing Multi-Object REST Operations

Multi-object operations allow users to retrieve or delete multiple objects in a single network request and can significantly reduce the network usage and improve network performance.

Note:

PUT operations are not supported as it may produce tainted data. Specifically, ut would require that individual objects (in serialized form) within the entity body to be in the same order as the corresponding keys in the URL. In addition, since updates result in a replacement, an entire object serialized form must be provided which can lead to overhead.

GET Operations

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

Returns a set of objects from the cache based on the specified keys. The ordering of returned objects is undefined and does not need to match the key order in the URL. Missing objects are silently omitted from the results. A 200 (OK) message always returns. An empty result set is returned if there are no objects in the result set. The get operation supports partial results (see "Performing Partial-Object REST Operations" for details).

DELETE Operations

DELETE http://host:port/cacheName/(key1, key2, ...)

Deletes multiple objects from the cache based on the specified keys. A 200 (OK) message is always returned even if no objects for the specified keys were present in the cache.

28.4 Performing Partial-Object REST Operations

An application may not want (or need) to retrieve a whole object. For example, in order to populate a drop down with a list of options, the application may only need two properties of a potentially large object with many other properties. In order to support this use case, each read operation should accept a list of object properties that the user is interested in as a matrix parameter p.

The following example performs a get operation that retrieves just the id and name attributes for a person:

GET http://localhost:8080/people/123;p=id,name

To include a country attribute of the address as well, the request URL is as follows:

GET http://localhost:8080/people/123;p=id,name,address:(country)

This approach allows an application to selectively retrieve only the properties that are required using a simple, URL-friendly notation.

The following sample output demonstrates the response of a GET operation:

* Client out-bound request
> GET http://127.0.0.1:8080/dist-test-sepj/1;p=name
> Accept: application/json
 
* Client in-bound response
< 200
< Transfer-Encoding: chunked
< Content-Type: application/json
<
{"name":"Mark"}

28.5 Performing Queries with REST

A cache can be queried by passing a CohQL expression as a query parameter q. In addition, the results can be sorted using a sort matrix parameter, or the set of objects returned can be limited by specifying start and count matrix parameters. See Oracle Coherence Developer's Guide for details on CohQL.

GET http://host:port/cacheName;sort=sortOrder;start=start;count=count?q=query

The query must be specified as a URL-encoded CohQL expression (the predicate part of CohQL). The sort is an optional parameter and represents 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:

sort=lastName,age:desc

The start and count parameters are optional integer arguments that determine the subset of the results to return.

28.6 Performing Aggregations with REST

Aggregations can be performed on data in a cache. Coherence REST includes a set of pre-defined aggergators and custom aggregators can be created as required.

The following topics are included in this section:

28.6.1 Aggregation Syntax for REST

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

Aggregates all entries in the cache. A 200 (OK) message returns with the aggregation result as an entity if the aggregation succeeds.

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

Aggregates query results. A 200 (OK) message returns with the aggregation result as an entity if the aggregation succeeds. The query must be specified as a URL-encoded CohQL expression (the predicate part of CohQL).

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

Aggregates specified entries. A 200 (OK) message returns with the aggregation result as an entity if the aggregation succeeds.

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 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()

28.6.2 Listing of Pre-Defined Aggregators

The following pre-defined aggregators are supported:

Aggregator Name Aggregator
big-decimal-average BigDecimalAverage.class
big-decimal-max BigDecimalMax.class
big-decimal-min BigDecimalMin.class
big-decimal-sum BigDecimalSum.class
double-average DoubleAverage.class
double-max DoubleMax.class
double-min DoubleMin.class
double-sum DoubleSum.class
long-max LongMax.class
long-min LongMin.class
long-sum LongSum.class
comparable-max ComparableMax.class
comparable-min ComparableMin.class
distinct-values DistinctValues.class
Count Count.class

28.6.3 Creating Custom Aggergators

Custom aggregator types can be defined by specifying a name to be used in the RESTful URL and either a class implementing the com.tangosol.util.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 require. 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" for a detailed reference. 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>mny-complex-aggr</name>
      <class-name>com.foo.MyAggreagatorFactory</class-name>
   </aggregator>
</aggregators>

28.7 Performing Entry Processing with REST

Entry Processors can be invoked on one or more objects in a cache. Coherence REST includes a set of pre-defined entry processors and custom entry processors can be created as required.

The following topics are included in this section:

28.7.1 Entry Processor Syntax for REST

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

Process all entries in the cache. A 200 (OK) message returns with the processing result as an entity if the processing succeeds.

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

Process query results. A 200 (OK) message returns with the processing result as an entity if the processing succeeds.

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

Process specified entries. A 200 (OK) message returns with the processing result as an entity if the processing succeeds.

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.processorProcessorFactory interface that can handle input the string from a URL segment and instantiate the processor instance. Out-of-box, Coherence REST provides two such factories for NumberIncrementor and NumberMultiplier.

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

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

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

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

28.7.2 Listing of Pre-defined Entry Processors

The following pre-defined processors are supported:

Processor Name Processor
increment A NumberIncrementor instance that always returns the new (incremented) value
post-increment A NumberIncrementor instance that always returns the old (not incremented) value
multiply A NumberMultiplier instance that always returns the new (multiplied) value
post-multiply A NumberMultiplier instance that always returns the old (not multiplied) value

28.7.3 Creating Custom Entry Processors

Custom entry processors can be defined by specifying a name to be used in a RESTful 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" for a detailed reference. The following example configures a custom ProcesorFactory implementation:

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

28.8 Understanding Concurrency Control

Coherence REST supports optimistic concurrency only as it maps cleanly to the HTTP protocol. When the user submits a PUT request to update an object and the cached objects implements the com.tangosol.util.Versionable interface, Coherence REST performs an update only if the existing and new object versions match; otherwise, a 409 (Conflict) message is returned and the existing entity is returned to the client so that the application can reapply the changes and retry.

28.9 Specifying Cache Aliases

Cache aliases are used to specify simplified cache names that are used when a cache name is not ideal for the RESTful URL path segment. The simplified names are mapped to the real cache names.

To define a cache alias, edit the coherence-rest-config.xml file and include the <alias> element within the <resource> element whose value is set to a simplified cache name.

The following example creates and cache alias named people for a cache with the name dist-extend-not-ideal-name-for-a-cache*:

<resources>
   <resource>
      <cache-name>dist-extend-not-ideal-name-for-a-cache*</cache-name>
      <alias>people</alias>
      ...
   </resource>
</resources>