Thank you for your feedback!

- best for offline viewing and printing

ePub

- best for most mobile devices

Mobi

- best for Amazon Kindle devices

Share to:

A REST Configuration Elements

This appendix provides a detailed reference of the REST configuration deployment descriptor and includes a brief overview of the descriptor.

This appendix includes the following sections:

REST Configuration File
Element Reference

A.1 REST Configuration File

The REST configuration deployment descriptor specifies the configuration for the REST implementation. The default name of the descriptor is coherence-rest-config.xml and must be found on the classpath. The name can be overridden using the tangosol.coherence.rest.config system property. For example:

-Dtangosol.coherence.rest.config=MyConfig.xml

The REST configuration deployment descriptor schema is defined in the coherence-rest-config.xsd file. The XSD file is located in the root of the coherence.jar library and at the following Web URL:

http://xmlns.oracle.com/coherence/coherence-rest-config/1.1/coherence-rest-config.xsd

The <rest> element is the root element of the configuration file and typically includes an XSD and Coherence namespace reference and the location of the coherence-rest-config.xsd file. For example:

<?xml version='1.0'?>

<rest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-rest-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-rest-config
   coherence-rest-config.xsd">

Notes:

The schema located in the coherence.jar library is always used at run time even if the xsi:schemaLocation attribute references the Web URL.
The xsi:schemaLocation attribute can be omitted to disable schema validation.
When deploying Coherence into environments where the default character set is EBCDIC rather than ASCII, ensure that the deployment descriptor file is in ASCII format and is deployed into its run-time environment in the binary format.

Element Reference

Table A-1 Opens a new window lists all non-terminal REST configuration elements.

Table A-1 REST Configuration Elements

Element	Used In
aggregator	aggregators
aggregators	rest
engine	query-engines
marshaller	resource
processor	processors
processors	rest
query	resource
query-engines	rest
resource	resources
resources	rest
rest	root element

aggregator

Used in: aggregators Opens a new window

Description

The aggregator element is used to define custom aggregators that are used to aggregate data in a cache. Each aggregator element must contain a single binding between a name and an aggregator class or aggregator factory class.

Elements

Table A-2 Opens a new window describes the subelements of the aggregator element.

Table A-2 aggregator Subelements

Element	Required/ Optional	Description
<`name`>	Required	Specifies a name to be used in a REST URL that is bound to an aggregator class or aggregator factory class.
<`class`>	Required	Specifies the fully qualified name of a custom aggregator class or custom aggregator factory class that is bound to a name. The class must implement the `com.tangosol.util.EntryAggregator` or `com.tangosol.coherence.rest.util.aggregator.AggregatorFactory` interfaces, respectively.

aggregators

Used in: rest Opens a new window

Description

The aggregators element contains any number of custom aggregator definitions.

Elements

Table A-3 Opens a new window describes the subelements of the aggregators element.

Table A-3 aggregators Subelements

Element	Required/ Optional	Description
`<aggregator>`	Required	Specifies a single binding between a name and an aggregator class or aggregator factory class.

engine

Used in: query-engines Opens a new window

Description

The engines element contains a single binding between a name and a query engine implementation class. Custom query engines must implement the com.tangosol.coherence.rest.query.QueryEngine and com.tangosol.coherence.rest.query.Query interfaces. Custom implementations can also extend the com.tangosol.coherence.rest.query.AbstractQueryEngine base class which provides useful methods for parsing query expressions and handling parameter bindings.

Elements

Table A-4 Opens a new window describes the subelements of the engine element.

Table A-4 engine Subelements

Element	Required/ Optional	Description
`<name>`	Required	Specifies a name for the query engine.
`<class-name>`	Required	Specifies the fully qualified name of the query engine implementation class.

marshaller

Used in: resource Opens a new window

Description

The marshaller element contains bindings between cache entry key/value classes and a marshaller class that is used to marshall and unmarshall instances of those classes.

Elements

Table A-5 Opens a new window describes the subelements of the marshaller element.

Table A-5 marshaller Subelements

Element	Required/ Optional	Description
`<media-type>`	Required	Specifies the name of the medium that is used to for marshalling. Coherence provides default implementations for XML and JSON data output.
`<class-name>`	Required	Specifies the fully qualified name of a custom class that implements the `com.tangosol.coherence.rest.io.Marshaller` interface. The implementation is used to marshall/unmarshall cache entry values that are stored in the cache. Marshallers are configured for each object type and media type.

processor

Used in: processors Opens a new window

Description

The processor element is used to define custom entry processors that are used to process data in a cache. Each processor element must contain a single binding between a name and the processor factory class.

Elements

Table A-6 Opens a new window describes the subelements of the processor element.

Table A-6 processor Subelements

Element	Required/ Optional	Description
`<name>`	Required	Specifies a name to be used in a REST URL that is bound to a processor factory class.
`<class-name>`	Required	Specifies the fully qualified name of a custom processor factory class that is bound to a name. The class must implement the `com.tangosol.coherence.rest.util.processor.ProcessorFactory` interface.

processors

Used in: rest Opens a new window

Description

The processors element contains any number of custom processor definitions.

Elements

Table A-7 Opens a new window describes the subelements of the processors element.

Table A-7 processors Subelements

Element	Required/ Optional	Description
`<processor>`	Required	Specifies a single binding between a name and a processor factory class.

query

Used in: resources Opens a new window

Description

The query element defines a named query for a resource. Named queries allow configured query expressions to be executed by name in the REST URL.

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

A named query definition consists of a binding between a query name and the query expression to execute. Multiple named queries can be configured for a resource. The query element supports the following attributes:

max-results – Specifies the maximum number of results to return for a named query. This value overrides the <resource> element's max-results attribute.
engine – Specifies a query engine implementation that is responsible for executing query expressions against a cache. The default value if the attribute is not specified is DEFAULT, which indicates a query expression must be specified as a URL-encoded CohQL expression (the predicate part of CohQL). For details on configuring a custom query engine implementation, see the <query-engines> element.

Elements

Table A-8 Opens a new window describes the subelements of the query element.

Table A-8 query Subelements

Element	Required/ Optional	Description
`<name>`	Required	Specifies a name for the query.
`<expression>`	Required	Specifies a query expression that is bound to the query name.

query-engines

Used in: rest Opens a new window

Description

The query-engines element contains any number of custom query engine definitions. A query engine executes query expressions against a cache. Direct queries and named queries rely on an underlying query engine to perform their queries. A default query engine is provided for executing query expression that are specified as a URL-encoded CohQL expression (the predicate part of CohQL). However, custom query engines can be defined as required.

Elements

Table A-9 Opens a new window describes the subelements of the query-engines element.

Table A-9 query-engines Subelements

Element	Required/ Optional	Description
`<engine>`	Required	Specifies a single binding between a name and a query engine implementation class.

resource

Used in: resources Opens a new window

Description

The resource element provides the metadata that is used to marshall and unmarshall cache entries. The metadata includes a single binding between a cache name and cache entry key and value classes.

The following attributes are available:

name – Specifies an alias for the <cache-name> element when the name is not ideal for the REST URL path segment. The value defaults to the value of the <cache-name> element if a value is not specified.
max-results – Specifies the maximum number of results to return for a query. This value is overridden if a max-results attribute is also defined within the <query> or <direct-query> element.

Elements

Table A-10 Opens a new window describes the subelements of the resource element.

Table A-10 resource Subelements

Element	Required/ Optional	Description
`<cache-name>`	Required	Specifies the name of the cache exposed by this resource. The cache must be defined in the cache configuration file.
`<key-class>`	Required	Specifies the type of the entry keys stored in this cache.
`<value-class>`	Required	Specifies the type of the entry values stored in this cache.
`<key-converter>`	Optional	Specifies the fully qualified name of a class that implements the `com.tangosol.coherence.rest.KeyConverter` interface. The class is used to convert cache entry keys to string and string representations of the keys that are used in the REST URL into an appropriate object instance that can be used to access cache entries. The `com.tangosol.coherence.rest.DefaultKeyConverter` class is used by default if no value is provided. The default class offers reasonable to string and from string conversions for Java primitives, dates, and UUIDs. See Java API Reference for Oracle Coherence for details.
`<marshaller>`	Optional	Specifies the fully qualified name of a class that implements the `com.tangosol.coherence.rest.io.Marshaller` interface. The class is used to marshall/unmarshall cache entry values that are stored in a cache. Coherence provides default implementations for XML and JSON data output.
`<query>`	Optional	Specifies the configuration information for named queries, which allow configured query expressions to be executed by name in the REST URL.
`<direct-query>`	Optional	Specifies the configuration information for direct queries, which allow query expressions to be included in the REST URL as the value of the parameter `q`. GET http://host:port/cacheName?q=query The following attributes are available: `enabled` – Specifies whether a resource supports direct queries. Valid values are `true` and `false`. The default value is `false`. `max-results` – Specifies the maximum number of results to return for a direct query. This value overrides the `<resource>` element's `max-results` attribute. `engine` – Specifies a query engine implementation that is responsible for executing query expressions against a cache. The default value if the attribute is not specified is `DEFAULT`, which indicates a query expression must be specified as a URL-encoded CohQL expression (the predicate part of CohQL). For details on configuring a custom query engine implementation, see the `<query-engines>` element.

resources

Used in: rest Opens a new window

Description

The resources element contains any number of resource definitions. A resource definition provides the metadata that is used to marshall and unmarshall cache entries.

Elements

Table A-11 Opens a new window describes the subelements of the resources element.

Table A-11 resources Subelements

Element	Required/ Optional	Description
`<resource>`	Required	Specifies a single binding between a cache name and cache entry key and value classes.

rest

root element

Description

The rest element is the root element of the coherence-rest-config.xml file which is used to configure the Coherence REST implementation. The implementation uses REST Web services to allow remote clients to access data in the cluster over HTTP and does not require the use of POF serialization.

Elements

Table A-12 Opens a new window describes the subelements of each rest element.

Table A-12 rest Subelements

Element	Required/ Optional	Description
`<resources>`	Optional	Specifies any number of resource definitions that provide the metadata that is used to marshall and unmarshall cache entries.
<`processors>`	Optional	Specifies any number of custom processor definitions that are used to process data in a cache.
`<aggregators>`	Optional	Specifies any number of custom aggregator definitions that are used to aggregate data in a cache.
`<query-engines>`	Optional	Specifies any number of custom query engine definitions. A query engine is responsible for executing queries.