A REST Configuration Elements
This appendix includes the following sections:
- REST Configuration File
The Coherence REST configuration deployment descriptor specifies the configuration for the REST implementation. - REST Configuration Element Reference
The Coherence REST configuration element reference includes all non-terminal report file configuration elements.
REST Configuration File
coherence-rest-config.xml
and must be found on the classpath. The name can be overridden using the coherence.rest.config
system property. For example:
-Dcoherence.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.2/coherence-rest-config.xsd
The <rest>
element is the root element of the configuration file and includes the XSD and namespace declarations. 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">
Note:
-
The schema located in the
coherence.jar
library is always used at run time even if thexsi: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.
Parent topic: REST Configuration Elements
REST Configuration Element Reference
- REST Configuration Element Index
- aggregator
- aggregators
- engine
- marshaller
- processor
- processors
- query
- query-engines
- resource
- resources
- rest
Parent topic: REST Configuration Elements
REST Configuration Element Index
Table A-1 lists all non-terminal REST configuration elements.
Table A-1 REST Configuration Elements
Element | Used In |
---|---|
root element |
Parent topic: REST Configuration Element Reference
aggregator
Used in: aggregators
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 describes the subelements of the aggregator
element.
Table A-2 aggregator Subelements
Element | Required/ Optional | Description |
---|---|---|
< |
Required |
Specifies a name to be used in a REST URL that is bound to an aggregator class or aggregator factory 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 |
Parent topic: REST Configuration Element Reference
aggregators
Used in: rest
Description
The aggregators
element contains any number of custom aggregator definitions.
Elements
Table A-3 describes the subelements of the aggregators
element.
Table A-3 aggregators Subelements
Element | Required/ Optional | Description |
---|---|---|
Required |
Specifies a single binding between a name and an aggregator class or aggregator factory class. |
Parent topic: REST Configuration Element Reference
engine
Used in: query-engines
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 describes the subelements of the engine
element.
Table A-4 engine Subelements
Element | Required/ Optional | Description |
---|---|---|
|
Required |
Specifies a name for the query engine. |
|
Required |
Specifies the fully qualified name of the query engine implementation class. |
Parent topic: REST Configuration Element Reference
marshaller
Used in: resource
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 describes the subelements of the marshaller
element.
Table A-5 marshaller Subelements
Element | Required/ Optional | Description |
---|---|---|
|
Required |
Specifies the name of the medium that is used to for marshalling. Coherence provides default implementations for XML and JSON data output. |
|
Required |
Specifies the fully qualified name of a custom class that implements the |
Parent topic: REST Configuration Element Reference
processor
Used in: processors
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 describes the subelements of the processor
element.
Table A-6 processor Subelements
Element | Required/ Optional | Description |
---|---|---|
|
Required |
Specifies a name to be used in a REST URL that is bound to a processor factory class. |
|
Required |
Specifies the fully qualified name of a custom processor factory class that is bound to a name. The class must implement the |
Parent topic: REST Configuration Element Reference
processors
Used in: rest
Description
The processors
element contains any number of custom processor definitions.
Parent topic: REST Configuration Element Reference
query
Used in: resources
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 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. This value overrides themax-results
attribute that is set on the<resource>
element. -
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 isDEFAULT
, which indicates a query expression must be specified as a URL-encoded CohQL expression (the predicate part of CohQL). See query-engines.
Elements
Table A-8 describes the subelements of the query
element.
Table A-8 query Subelements
Element | Required/ Optional | Description |
---|---|---|
|
Required |
Specifies a name for the query. |
|
Required |
Specifies a query expression that is bound to the query name. |
Parent topic: REST Configuration Element Reference
query-engines
Used in: rest
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.
Parent topic: REST Configuration Element Reference
resource
Used in: resources
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 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. This value is overridden if amax-results
attribute is also defined within the<query>
or<direct-query>
element.
Elements
Table A-10 describes the subelements of the resource
element.
Table A-10 resource Subelements
Element | Required/ Optional | Description |
---|---|---|
|
Required |
Specifies the name of the cache exposed by this resource. The cache must be defined in the cache configuration file. |
|
Optional |
Specifies the type of the entry keys stored in this cache. |
|
Optional |
Specifies the type of the entry values stored in this cache. |
|
Optional |
Specifies the fully qualified name of a class that implements the |
Optional |
Specifies the fully qualified name of a class that implements the |
|
|
Optional |
Specifies the configuration information for named queries, which allow configured query expressions to be executed by name in the REST URL. |
|
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 GET http://host:port/cacheName?q=query The following attributes are available:
|
Parent topic: REST Configuration Element Reference
resources
Used in: rest
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 describes the subelements of the resources
element.
Table A-11 resources Subelements
Element | Required/ Optional | Description |
---|---|---|
|
Required |
Specifies a single binding between a cache name and cache entry key and value classes. |
Parent topic: REST Configuration Element Reference
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 describes the subelements of each rest
element.
Table A-12 rest Subelements
Element | Required/ Optional | Description |
---|---|---|
Optional |
Specifies any number of resource definitions that provide the metadata that is used to marshall and unmarshall cache entries. |
|
Optional |
Specifies any number of custom processor definitions that are used to process data in a cache. |
|
Optional |
Specifies any number of custom aggregator definitions that are used to aggregate data in a cache. |
|
Optional |
Specifies any number of custom query engine definitions. A query engine is responsible for executing queries. |
Parent topic: REST Configuration Element Reference