This chapter describes how to configure a caching system for use with Oracle Event Processing event processing networks. It includes information on how to configure caches that are based on Oracle Coherence, Oracle Event Processing, and third-party caching providers and to access them from Oracle Continuous Query Language, Java classes, and other code.
This chapter includes the following sections:
Section 13.2, "Configuring an Oracle Coherence Caching System and Cache"
Section 13.3, "Configuring an Oracle Event Processing Local Caching System and Cache"
Section 13.4, "Configuring a Third-Party Caching System and Cache"
Section 13.5, "Adding Caching to an Event Processing Network"
You can integrate a cache system with your Oracle Event Processing application so that the cache is available as source or destination for data your application uses, including event data. Integrating a cache can provide access to relatively static data at a speed that is well suited to an application that handles streaming data.
A cache is a temporary storage area for events, created to improve the overall performance of your Oracle Event Processing application (a cache is not necessary for the application to function correctly). To increase the availability of the events and increase the performance of their applications, Oracle Event Processing applications can publish to or consume events from a cache.
A caching system refers to a configured instance of a caching implementation. A caching system defines a named set of configured caches as well as the configuration for remote communication if any of the caches are distributed across multiple machines.
By integrating a cache, you can:
Load into the cache frequently-used data for access from application code, improving application performance.
Write to the cache processed event data for use by another application.
For more complete cache integration uses case descriptions, see Section 13.1.3, "Caching Use Cases".
Note that a cache does not have to be an actual stage in the network; another component or Spring bean can access a cache programmatically using the caching APIs.
Oracle Event Processing caching includes the following features:
Pre-load a cache with data before an application is deployed.
Periodically refresh, invalidate, and flush the data in a cache. All these tasks happen incrementally and without halting the application or causing latency spikes.
Dynamically update a cache's configuration.
Although configuration steps vary for each of the caching implementations, the high-level steps are as follows:
Configure the caching system and caches. How you do this will vary depending on the caching implementation you're using.
For more information, see Section 13.1.2, "Overview of Cache Configuration".
Declare the caching system and its caches by updating a component configuration file.
For more information, see Section 13.1.2, "Overview of Cache Configuration".
Add the caching system and caches to the event provcessing network by editing the EPN assembly file. Note that you can use the IDE's EPN editor to add a cache.
For more information, see Section 13.5, "Adding Caching to an Event Processing Network".
Write code to access the cache in your Oracle Event Processing application.
For more information, see Section 13.6, "Accessing a Cache from Application Code".
Oracle Event Processing supports the following caching implementations:
Oracle Event Processing local cache: a local, in-memory single-JVM cache. This implementation is best for local use (it cannot be used in a cluster). It might also be useful for development in the early stages because it is relatively simple to set up.
Oracle Coherence: a JCache-compliant in-memory distributed data grid solution for clustered applications and application servers. It coordinates updates to the data using cluster-wide concurrency control, replicates data modifications across the cluster using the highest performing clustered protocol available, and delivers notifications of data modifications to any servers that request them. You take advantage of Oracle Coherence features using the standard Java collections API to access and modify data, and use the standard JavaBean event model to receive data change notifications.
Note:
Before you can use Oracle Event Processing with Oracle Coherence, you must obtain a valid Oracle Coherence license such as a license for Coherence Enterprise Edition, Coherence Grid Edition, or Oracle WebLogic Application Grid. For more information on Oracle Coherence, see http://www.oracle.com/technology/products/coherence/index.html
.
Third-party caches: you can create a plug-in to allow Oracle Event Processing to work with other, third-party cache implementations.
You configure caching systems and caches before adding them to the event processing network (EPN). How you add configuration depends on which caching implementation you will be using.
You integrate caching systems and caches by updating the following configuration files:
If you are using Oracle Coherence for caching, use a coherence-cache-config.xml file to configure it. This is the same kind of file you use to configure Coherence in other contexts.
For more information, see Section 13.2.1, "Configuring the Oracle Coherence Caching System and Caches".
If you are using Oracle Coherence, you can optionally use a tangosol-coherence-override.xml file to make global, server-wide configuration changes if you are caching with Oracle Coherence.
For more information, see Section 13.2.1, "Configuring the Oracle Coherence Caching System and Caches".
Use a component configuration file for basic configuration of caching systems and caches. In this file, you essentially declare the existence of the cache and provide configuration for it. If the cache is an Oracle Coherence cache, you can use this file to reference Coherence-specific configuration in a coherence-cache-config.xml file.
For each caching system your application uses, you add a separate caching-system
element in a component configuration file. You also add a cache
element for each cache.
For more information, see Section 13.2.1, "Configuring the Oracle Coherence Caching System and Caches" or Section 13.3.1, "Configuring an Oracle Event Processing Caching System".
Use the application's EPN assembly file to add configured caching systems and caches to the event processing network, connecting the caches to other components in the EPN.
For more information, see Section 13.5, "Adding Caching to an Event Processing Network".
Basically, though, you create, configure, and wire caching systems and caches using component configuration and EPN assembly files. By default, when you create a project, the IDE creates one component configuration file and one EPN assembly file. When you add a cache to the EPN using the IDE, it adds a cache element to the EPN assembly file. You must manually add caching-system
elements to the EPN assembly and component configuration files.
When adding configured caching systems and caches to an application's event processing network, you specify entries in the EPN assembly file with entries in the component configuration file by referencing configured names.
In Example 13-1 (a component configuration file excerpt) and Example 13-2 (an EPN assembly file excerpt), EPN id
attribute values must have the same values as configuration name
attribute values:
Example 13-1 Component Configuration File Name Values
<caching-system> <name>cacheSystem</name> <cache> <name>cache1</name> ... </cache> </caching-system>
Example 13-2 EPN Assembly File ID and Ref Values
<wlevs:caching-system id="cacheSystem"> ... </wlevs:caching-system> <wlevs:cache id="cache1"> <wlevs:caching-system ref="cacheSystem"/> </wlevs:cache>
If your application has more than one caching system, you can create a caching-system
element for each of them in a config.xml
file. You can use one XML file or several, putting all in the META-INF/wlevs
directory. Choose the method that best suits your development environment.
For more information, see:
Oracle Fusion Middleware Visualizer User's Guide for Oracle Event Processing
"wlevs.Admin Command-Line Reference" in the Oracle Fusion Middleware Administrator's Guide for Oracle Event Processing
"Configuring JMX for Oracle Event Processing" in the Oracle Fusion Middleware Administrator's Guide for Oracle Event Processing
For more information on configuring caching, see:
Caching technology is a great fit for streaming data use cases, where high throughput can be particularly important. Getting data from a cache will usually be much faster than getting the same data from a relational database.
The following describes common use cases for caching in Oracle Event Processing applications.
Publishing events to a cache
An example of this use case is a financial application that publishes events to a cache while the financial market is open and then processes data in the cache after the market closes.
Publishing events to a cache makes them highly available or available to other Oracle Event Processing applications running in the server. Publishing events to a cache also allows for asynchronous writes to a secondary storage by the cache implementation. You can configure any stage in an Oracle Event Processing application that generates events (input adapter, channel, business POJO, or processor) to publish its events to the cache.
Consuming data from a cache
Oracle Event Processing applications may sometimes need to access non-streaming data in order to do its work; caching this data can increase the performance of the application.
The standard components of an Oracle Event Processing application that are allowed direct programming access to a cache are input- and output-adapters and business POJOs.
Additionally, applications can access a cache from Oracle CQL or EPL, either by a user-defined function or directly from an Oracle CQL or EPL statement.
In the case of a user-defined function, programmers use Spring to inject the cache resource into the implementation of the function. For more information, see Section 1.4.3, "Configuring Oracle Event Processing Resource Access".
Applications can also query a cache directly from anOracle CQL or EPL statement that runs in a processor. In this case, the cache essentially functions as another type of data source to a processor so that querying a cache is very similar to querying a channel except that data is pulled from a cache.
An example of using Oracle CQL to query a cache is from a financial application that publishes orders and the trades used to execute the orders to a cache. At the end of the day when the markets are closed, the application queries the cache in order to find all the trades related to a particular order.
Updating and deleting data in a cache
An Oracle Event Processing application can both update and delete data in a cache when required.
For example, a financial application may need to update an order in the cache each time individual trades that fulfill the order are executed, or an order may need to be deleted if it has been cancelled. The components of an application that are allowed to consume data from a cache are also allowed to update it.
Using a cache in a multi-server domain
If you build an Oracle Event Processing application that uses a cache, and you plan to deploy that application in a multi-server domain, then you must use a caching-system that supports a distributed cache.
In this case, you must use either Oracle Coherence or a third-party caching system that supports a distributed cache.
For more information, see:
"Administering Multi-Server Domains With Oracle Event Processing Native Clustering" in the Oracle Fusion Middleware Administrator's Guide for Oracle Event Processing
Section 13.2, "Configuring an Oracle Coherence Caching System and Cache"
Section 13.4, "Configuring a Third-Party Caching System and Cache"
Oracle Event Processing provides caching APIs that you can use in your application to perform certain tasks. The APIs are in the com.bea.cache.jcache
package, which includes the APIs used to access a cache and create cache loader, listeners, and stores. Also, if you intend to use that functionality, you will need to import the com.tangosol.net
and com.tangosol.net.cache
packages.
You create, configure, and wire caching systems and caches using the EPN assembly file and component configuration files. This means that you typically never explicitly use the Cache
and CachingSystem
interfaces in your application; the only reason to use them is if you have additional requirements than the standard configuration. For example, if you want to provide integration with a third-party cache provider, then you must use the CachingSystem
interface; if you want to perform operations on a cache that are not part of the java.util.Map
interface, then you can use the Cache
interface.
If you create cache listeners, loaders, or stores for an Oracle Event Processing local cache, then the beans you write must implement the CacheListener
, CacheLoader
, or CacheStore
interfaces.
If you create cache listeners, loaders, or stores for an Oracle Coherence cache, then the beans you write must implement the appropriate Oracle Coherence interfaces.
If you create cache listeners, loaders, or stores for a third-party cache, then the beans you write must implement the appropriate third-party cache interfaces.
For more information, see:
Section 13.2, "Configuring an Oracle Coherence Caching System and Cache"
Section 13.3, "Configuring an Oracle Event Processing Local Caching System and Cache"
Section 13.4, "Configuring a Third-Party Caching System and Cache"
Oracle Fusion Middleware Java API Reference for Oracle Event Processing.
You can configure your application to use the Oracle Coherence caching system and cache. Use this caching system if you plan to deploy your application to a multi-server domain.
Using Oracle Coherence, only the first caching-system can be configured in a server. Oracle Event Processing will ignore any other caching systems you might configure.
Note:
Before you can legally use Oracle Event Processing with Oracle Coherence, you must obtain a valid Coherence license such as a license for Coherence Enterprise Edition, Coherence Grid Edition, or Oracle WebLogic Application Grid. For more information on Oracle Coherence, see http://www.oracle.com/technology/products/coherence/index.html
.
To configure an Oracle Coherence caching system and cache:
Decide whether or not your Oracle Coherence cache will be used exclusively by this application or shared amongst two or more applications.
For more information, see Section 13.2.2, "Configuring a Shared Oracle Coherence Cache".
Configure the cache and caching system using a coherence-cache-config.xml
file (and possibly a tangosol-coherence-override.xml
file) and place the file in your application's META-INF/wlevs/coherence
directory.
Configure the caching system and its caches by updating the caching configuration file for the application.
See Section 13.2.1, "Configuring the Oracle Coherence Caching System and Caches."
Configure the caching system and its caches by updating the EPN assembly file with one or more cache
element child elements.
Before assembling and deploying the application, edit your META-INF/MANIFEST.MF
to import packages that might be required in your implementation. If your applications implements cache listeners, loaders or stores, your manifest should import com.tangosol.net.cache
packages.
For more information, see Section 5.7.5, "How to Import a Package".
When configuring an Oracle Coherence cache for integration with an Oracle Event Processing application, you use Coherence configuration files, then reference those files in Oracle Event Processing component configuration.
Oracle Event Processing leverages the native configuration provided by Oracle Coherence. You do this by packaging the following two Oracle Coherence configuration files, using the file names indicated in the following list, in the application bundle that uses the Oracle Coherence cache:
coherence-cache-config.xml
—Oracle Coherence cache configuration information. Individual caches are identified with the cache-name
element; the value of this element maps to the id
attribute of the wlevs:cache
element in the EPN assembly file. See Section 13.2.1.1, "The coherence-cache-config.xml File" for information about this file as well as an example of the mapping.
This is a per-application configuration file; put this file in the META-INF/wlevs/coherence
directory of the bundle JAR. Note that this directory is different from the directory that stores the component configuration file for the local in-memory Oracle Event Processing caching provider (META-INF/wlevs
).
tangosol-coherence-override.xml
—Oracle Coherence cluster configuration. See Section 13.2.1.2, "The tangosol-coherence-override.xml File" for information about this file as well as an example.
This is a global per-server file (referred to as "operational configuration" in the Oracle Coherence documentation); put this file in the Oracle Event Processing server config
directory.
Once you have configured Oracle Coherence using the files in the preceding list, update your component configuration file as shown in Example 13-3. Here, you declare a Coherence caching system for use in the application by referencing the coherence-cache-config.xml
file where you configured the cache.
Example 13-3 Component Configuration File: Coherence Cache
<coherence-caching-system> <name>caching-system-id</name> <coherence-cache-config> ../wlevs/coherence/coherence-cache-config.xml </coherence-cache-config> </coherence-caching-system>
When you declare that a caching system uses the Oracle Coherence provider, be sure that all of the caches of this caching system also map to an Oracle Coherence configuration and not an Oracle Event Processing local configuration. Otherwise, Oracle Event Processing will throw an exception. For reference information on this file, see Section D.23, "coherence-caching-system" and Section D.22, "coherence-cache-config".
The coherence-cache-config.xml
file is the basic Oracle Coherence configuration file and must conform to the Oracle Coherence DTDs, as is true for any Oracle Coherence application.
The following sample shows a simple configuration. See the explanation after the sample for information about the sections in bold.
<?xml version="1.0"?> <!DOCTYPE cache-config SYSTEM "cache-config.dtd"> <cache-config> <caching-scheme-mapping> <cache-mapping> <cache-name>myCoherenceCache</cache-name> <scheme-name>new-replicated</scheme-name> </cache-mapping> <cache-mapping> <cache-name>myLoaderCache</cache-name> <scheme-name>test-loader-scheme</scheme-name> </cache-mapping> <cache-mapping> <cache-name>myStoreCache</cache-name> <scheme-name>test-store-scheme</scheme-name> </cache-mapping> </caching-scheme-mapping> <caching-schemes> <replicated-scheme> <scheme-name>new-replicated</scheme-name> <service-name>ReplicatedCache</service-name> <backing-map-scheme> <local-scheme> <scheme-ref>my-local-scheme</scheme-ref> </local-scheme> </backing-map-scheme> </replicated-scheme> <local-scheme> <scheme-name>my-local-scheme</scheme-name> <eviction-policy>LRU</eviction-policy> <high-units>100</high-units> <low-units>50</low-units> </local-scheme> <local-scheme> <scheme-name>test-loader-scheme</scheme-name> <eviction-policy>LRU</eviction-policy> <high-units>100</high-units> <low-units>50</low-units> <cachestore-scheme> <class-scheme> <class-factory-name> com.bea.wlevs.cache.coherence.configuration.SpringFactory </class-factory-name> <method-name>getLoader</method-name> <init-params> <init-param> <param-type>java.lang.String</param-type> <param-value>{cache-name}</param-value> </init-param> </init-params> </class-scheme> </cachestore-scheme> </local-scheme> <local-scheme> <scheme-name>test-store-scheme</scheme-name> <eviction-policy>LRU</eviction-policy> <high-units>100</high-units> <low-units>50</low-units> <cachestore-scheme> <class-scheme> <class-factory-name> com.bea.wlevs.cache.coherence.configuration.SpringFactory </class-factory-name> <method-name>getStore</method-name> <init-params> <init-param> <param-type>java.lang.String</param-type> <param-value>{cache-name}</param-value> </init-param> </init-params> </class-scheme> </cachestore-scheme> </local-scheme> </caching-schemes> </cache-config>
In the Oracle Coherence configuration file, the cache-name
element that is a child element of cache-mapping
identifies the name of the Oracle Coherence cache. The value of this element must exactly match the value of the id
attribute of the wlevs:cache
element in the EPN assembly file. For example, the following EPN assembly file snippet refers to the myCoherenceCache
cache in the Oracle Coherence configuration file:
<wlevs:cache id="myCoherenceCache" advertise="false">
<wlevs:caching-system ref="coherence-cache"/>
<wlevs:cache-loader ref="localLoader"/>
<wlevs:cache-listener ref="localListener"/>
</wlevs:cache>
The Oracle Coherence configuration file illustrates another requirement when using Oracle Coherence with Oracle Event Processing: an Oracle Coherence factory must be declared when using Spring to configure a loader or store for a cache. You do this using the cachestore-scheme
element in the Oracle Coherence configuration file to specify a factory class that allows Oracle Coherence to call into Oracle Event Processing and retrieve a reference to the loader or store that is configured for the cache. The only difference between configuring a loader or store is that the method-name
element has a value of getLoader
when a loader is used and getStore
when a store is being used. You pass the cache name to the factory as an input parameter.
Refer to your Oracle Coherence documentation (see http://www.oracle.com/technology/products/coherence/index.html
) for detailed information about the coherence-cache-config.xml
file.
The tangosol-coherence-override.xml
file configures Oracle Coherence caching. Include this file if you are using Oracle Coherence for caching only. Do not include this file if you are using Oracle Coherence for clustering.
The following sample shows a simple configuration. See the explanation after the sample for information about the sections in bold.
<?xml version='1.0'?>
<coherence xml-override="/tangosol-coherence-override.xml">
<cluster-config>
<member-identity>
<cluster-name>com.bea.wlevs.example.provider</cluster-name>
</member-identity>
...
</coherence>
This configuration file is fairly standard. The main thing to note is that you should specify a cluster-name
element to prevent Oracle Coherence from attempting to join existing Oracle Coherence clusters when Oracle Event Processing starts up; this can cause problems and sometimes even prevent Oracle Event Processing from starting.
Refer to your Oracle Coherence documentation (see http://www.oracle.com/technology/products/coherence/index.html
) for detailed information about the tangosol-coherence-override.xml
file.
For more information on Oracle Event Processing clusters, see "Administrating Multi-Server Domains With Oracle Event Processing Native Clustering" in the Oracle Fusion Middleware Administrator's Guide for Oracle Event Processing.
When declaring Oracle Coherence caches in the EPN assembly files of one or more applications deployed to the same Oracle Event Processing server, you should never configure multiple instances of the same cache with a loader or store. You might inadvertently do this by employing multiple applications that each configure the same Oracle Coherence cache with a loader or store in their respective EPN assembly file. If you do this, Oracle Event Processing throws an exception.
If multiple application bundles need to share Oracle Coherence caches, then you should put the EPN assembly file that contains the appropriate wlevs:cache
and wlevs:caching-system
in a separate bundle and set their advertise
attributes to true
.
To export both the caching system and the cache as an OSGi service, set the advertise
attribute to true
.
<wlevs:caching-system id="caching-system-id" provider="coherence" advertise="true"/> ... <wlevs:cache id="cache-id" name="alternative-cache-name" advertise="true" > <wlevs:caching-system ref="caching-system-id"/> </wlevs:cache>
If the cache is advertised, then a component in the EPN of an application in a separate bundle can then reference it. The following example shows how a processor in one bundle can use as a cache source the cache with ID cache-id
located in a separate bundle called cacheprovider
:
<wlevs:processor id="myProcessor2">
<wlevs:cache-source ref="cacheprovider:cache-id"/>
</wlevs:processor>
You can configure your application to use the Oracle Event Processing local caching system and cache. The Oracle Event Processing local caching system is appropriate if you do not plan to deploy your application to a multi-server domain. If you plan to deploy your application to a multi-server domain, consider using an Oracle Coherence cache (see Section 13.2, "Configuring an Oracle Coherence Caching System and Cache").
To configure an Oracle Event Processing local caching system and cache:
Declare the caching system and caches by updating a component configuration file by adding caching-system
and cache elements.
For more information, see Section 13.3.1, "Configuring an Oracle Event Processing Caching System"
Optionally, override the default cache configuration by updating the EPN assembly file with one or more additional cache
element child elements.
For more information, see Section 13.5, "Adding Caching to an Event Processing Network".
Before assembling and deploying the application, verify that the META-INF/MANIFEST.MF
file includes the following import:
com.bea.wlevs.cache.spi; version ="11.1.0.0"
For more information, see Section 5.7.5, "How to Import a Package".
In order to use an Oracle Event Processing caching system cache in an application, you need to first configure the cache. Afterward, you can reference the cache in other places, such as an event processing network. This section describes the settings you can make in a component configuration file. For reference information on the file, see Section D.18, "caching-system" and Section D.17, "cache".
In a component configuration file (such as a config.xml file), to the config
root element, add a caching-system
child element; use its name
child element to uniquely identify the caching system. This name will match the EPN assembly file's wlevs:caching-system
element id
attribute. This is how Oracle Event Processing knows to which particular caching system in the EPN assembly file this caching configuration applies.
For example, assume your configuration file already contains a processor and an adapter (contents removed from this example for simplicity); then the updated file might look like the following:
<?xml version="1.0" encoding="UTF-8"?> <n1:config xmlns:n1="http://www.bea.com/ns/wlevs/config/application" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <processor> ... </processor> <adapter> ... </adapter <caching-system> <name>caching-system-id</name> </caching-system> </n1:config>
For each cache you want to create, update the caching-system
element to add a cache
child element; use the name
child element to uniquely identify each.
This name
must match the wlevs:cache
element id
attribute you specify in the EPN assembly file. This is how Oracle Event Processing knows to which particular cache in the EPN assembly file this configuration applies.
For each cache, optionally add the following elements that take simple data types to configure the cache:
max-size
: The number of cache elements in memory after which eviction/paging occurs. The maximum cache size is 231-1 entries; default is 64.
eviction-policy
: The eviction policy to use when max-size
is reached. Supported values are: FIFO, LRU, LFU, and NRU; default value is LFU.
time-to-live
: The maximum amount of time, in milliseconds, that an entry is cached. Default value is infinite.
idle-time
: Amount of time, in milliseconds, after which cached entries are actively removed from the cache. Default value is infinite.
work-manager-name
: The work manager to be used for all asynchronous operations. The value of this element corresponds to the name
child element of the work-manager
element in the server's config.xml
configuration file.
For more information, see Section F.45, "work-manager".
For example:
<caching-system> <name>caching-system-id</name> <cache> <name>cache-id</name> <max-size>100000</max-size> <eviction-policy>LRU</eviction-policy <time-to-live>3600</time-to-live> </cache> </caching-system>
Optionally add either write-through
or write-behind
as a child element of cache
to specify synchronous or asynchronous writes to the cache store, respectively. By default, writes to the store are synchronous (<write-through
) which means that as soon as an entry is created or updated the write occurs.
If you specify the write-behind
element, then the cache store is invoked from a separate thread after a create or update of a cache entry. Use the following optional child elements to further configure the asynchronous writes to the store:
work-manager-name
: The work manager that handles asynchronous writes to the cache store. If a work manager is specified for the cache itself, this value overrides it for store operations only. The value of this element corresponds to the name
child element of the work-manager
element in the server's config.xml
configuration file.
For more information, see Section F.45, "work-manager".
batch-size
: The number of updates that are picked up from the store buffer to write back to the backing store. Default value is 1.
buffer-size
: The size of the internal store buffer that temporarily holds the asynchronous updates that need to be written to the store. Default value is 100.
buffer-write-attempts
: The number of attempts that the user thread makes to write to the store buffer. The user thread is the thread that creates or updates a cache entry. If all attempts by the user thread to write to the store buffer fail, it will invoke the store synchronously. Default value is 1.
buffer-write-timeout
: The time in milliseconds that the user thread waits before aborting an attempt to write to the store buffer. The attempt to write to the store buffer fails only in case the buffer is full. After the timeout, further attempts may be made to write to the buffer based on the value of buffer-write-attempts
. Default value is 100.
For example:
<caching-system> <name>caching-system-id</name> <cache> <name>cache-id</name> <max-size>100000</max-size> <eviction-policy>LRU</eviction-policy <time-to-live>3600</time-to-live> <write-behind> <buffer-size>200</buffer-size> <buffer-write-attempts>2</buffer-write-attempts> <buffer-write-timeout>200</buffer-write-timeout> </write-behind> </cache> </caching-system>
Optionally add a cache
element listeners
child element to configure the behavior of components that listen to the cache.
Use the asynchronous
Boolean attribute to specify whether listeners should be invoked:
asynchronously: true
.
synchronously: false
, which means listeners are invoked synchronously (Default).
The listeners
element has a single child element, work-manager-name
, that specifies the work manager to be used for asynchronously invoking listeners. This value is ignored if synchronous invocations are enabled. If a work manager is specified for the cache itself, this value overrides it for invoking listeners only. The value of this element corresponds to the work-manager
element name
child element in the Oracle Event Processing server config.xml
configuration file.
For example:
<caching-system> <name>caching-system-id</name> <cache> <name>cache-id</name> <max-size>100000</max-size> <eviction-policy>LRU</eviction-policy <time-to-live>3600</time-to-live> <write-behind> <buffer-size>200</buffer-size> <buffer-write-attempts>2</buffer-write-attempts> <buffer-write-timeout>200</buffer-write-timeout> </write-behind> <listeners asynchronous="true"> <work-manager-name>cachingWM</work-manager-name> </listeners> </cache> </caching-system>
For more information, see Section F.45, "work-manager"
You can configure your application to use a third-party caching system and cache.
To configure a third-party caching system and cache:
Create a plug-in to define the third-party caching system as an Oracle Event Processing caching system provider.
This involves:
Implementing the com.bea.wlevs.cache.spi.CachingSystem
interface
Creating a factory that creates caching systems of this type.
Registering the factory with an attribute that identifies its provider type.
Declare the caching system in the EPN assembly file.
Use the wlevs:caching-system
element to declare a third-party implementation; use the class
or provider
attribute to specify additional information.
For simplicity, you can include the third-party implementation code inside the Oracle Event Processing application bundle itself to avoid having to import or export packages and managing the lifecycle of a separate bundle that contains the third-party implementation. In this case the wlevs:caching-system
element appears in the EPN assembly file as shown in the following example:
<wlevs:caching-system id="caching-system-id" class="third-party-implementation-class"/>
The class
attribute specifies a Java class that must implement the com.bea.wlevs.cache.spi.CachingSystem
interface. For details about this interface, see the Oracle Fusion Middleware Java API Reference for Oracle Event Processing.
Sometimes, however, you might not be able, or want, to include the third-party caching implementation in the same bundle as the Oracle Event Processing application that is using it. In this case, you must create a separate bundle whose Spring application context includes the wlevs:caching-system
element, with the advertise
attribute mandatory:
<wlevs:caching-system id ="caching-system-id" class="third-party-implementation-class" advertise="true"/>
Alternatively, if you want to decouple the implementation bundle from the bundle that references it, or you are plugging in a caching implementation that supports multiple caching systems per Java process, you can specify a factory as a provider:
<wlevs:caching-system id ="caching-system-id" provider="caching-provider"/> <factory id="factory-id" provider-name="caching-provider"> <class>the.factory.class.name</class> </factory>
The factory class (the.factory.class.name
in the example) must implement the com.bea.wlevs.cache.spi.CachingSystemFactory
interface. This interface has a single method, create
, that returns a com.bea.wlevs.cache.spi.CachingSystem
instance.
You must deploy this bundle alongside the application bundle so that the latter can start using it.
Declare one or more caches for this caching system in the EPN assembly file.
After you have declared a caching system for an application, you configure one or more caches using the wlevs:cache
element:
<wlevs:caching-system id ="caching-system-id" provider="caching-provider"/> ... <wlevs:cache id="cache-id" name="alternative-cache-name"> <wlevs:caching-system ref="caching-system-id"/> </wlevs:cache>
The name
attribute is optional; specify it only if the name of the cache in the caching system is different from its ID. The wlevs:caching-system
child element references the already-declared caching system that contains the cache. You must specify this child element only if the caching system is ambiguous: there is more than one caching system declared (either implicitly or explicitly) or if the caching system is in a different application or bundle.
You can export both the caching system and the cache as an OSGI service using the advertise
attribute.
<wlevs:caching-system id="caching-system-id" advertise="true"/> ... <wlevs:cache id="cache-id" name="alternative-cache-name" advertise="true" > <wlevs:caching-system ref="caching-system-id"/> </wlevs:cache>
If the cache is advertised, then a component in the EPN of an application in a separate bundle can then reference it. The following example shows how a processor in one bundle can use as a cache source the cache with ID cache-id
located in a separate bundle (called cacheprovider
):
<wlevs:processor id="myProcessor2">
<wlevs:cache-source ref="cacheprovider:cache-id"/>
</wlevs:processor>
The caching system is responsible for creating the cache associated with a particular name and returning a reference to the cache. The resulting cache bean implements the java.util.Map
interface.
Configure the third-party caching system and its caches by updating the third-party caching configuration file or files for the application.
Refer to your third-party cache documentation.
Optionally, override the default third-party cache configuration by updating the appropriate configuration file with one or more additional cache
element child elements.
Specify that a cache is an event sink by configuring it as a listener to another component in the event processing network.
Refer to your third-party cache documentation.
Specify that a cache is an event source to which another component in the event processing network listens.
Refer to your third-party cache documentation.
Configure a cache loader or store.
Refer to your third-party cache documentation.
When you assemble your application, verify that the META-INF/MANIFEST.MF
file includes the following import:
com.bea.wlevs.cache.spi; version ="11.1.0.0"
If the MANIFEST.MF
files does not include this import, update the MANIFEST.MF
file to add this import before deploying your application.
Once you have configured the caching provider your application will be using, you can add it to the applications event processing network (EPN).
For information about adding caching to the EPN and configuring it to be reused, see the following sections:
Section 13.5.1, "Adding the Caching System and Caches to an EPN"
Section 13.5.2, "Configuring a Cache for Reuse Among Applications"
When you add a cache to the EPN, you can specify other functionality, as described in the following sections:
To declare a caching system that uses the Oracle Coherence implementation declaratively in the EPN assembly file, use the wlevs:caching-system
element, whose id
attribute must match the name you specified for the caching system in the application's component configuration file.
After you have declared a caching system for an application, you configure one or more caches using the wlevs:cache
element. The element's mandatory id
attribute maps to the name of a cache in the configuration file.
The following example illustrates a caching system and cache declared in an EPN assembly file:
<wlevs:caching-system id="caching-system-id" provider="coherence" advertise="false"/> ... <wlevs:cache id="myCache" advertise="false"> <wlevs:caching-system ref="caching-system-id"/> </wlevs:cache>
The name
attribute is optional; specify it only if the name of the cache in the caching system is different from its ID. The wlevs:caching-system
child element references the already-declared caching system that contains the cache. You must specify this child element only if the caching system is ambiguous: there is more than one caching system declared (either implicitly or explicitly) or if the caching system is in a different application or bundle.
You can export both the caching system and the cache as OSGI services using the advertise
attribute. If the cache is advertised, then a component in the EPN of an application in a separate bundle can then reference it.
The following example illustrates the advertise
attribute.
<wlevs:caching-system id="caching-system-id" advertise="true"/> ... <wlevs:cache id="cache-id" name="alternative-cache-name" advertise="true" > <wlevs:caching-system ref="caching-system-id"/> </wlevs:cache>
The following example shows how a processor in one bundle can use as a cache source the cache with ID cache-id
located in a separate bundle (called cacheprovider
):
<wlevs:processor id="myProcessor2">
<wlevs:cache-source ref="cacheprovider:cache-id"/>
</wlevs:processor>
For more information, see Section 13.2.2, "Configuring a Shared Oracle Coherence Cache".
You can configure a cache in an EPN to receive events as they pass through the network.
For example, to specify that a cache listens to a channel, configure the channel with a wlevs:listener
element that has a reference to the cache, as shown in the following example:
<wlevs:caching-system id="caching-system-id"/>
<wlevs:cache id="cache-id" name="alternative-cache-name">
<wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>
<wlevs:channel id="tradeStream">
<wlevs:listener ref="cache-id"/>
</wlevs:channel>
As the channel sends new events to the cache, they are inserted into the cache. If the channel sends a remove event (an old event that exits the output window), then the event is removed from the cache.
When you configure a cache to be a listener, events are inserted into the cache. This section describes the variety of options available to you to specify the key used to index a cache in this instance.
If you do not explicitly specify a key, the event object itself serves as both the key and value when the event is inserted into the cache. In this case, the event class must include a valid implementation of the equals
and hashcode
methods that take into account the values of the key properties.
See the following for ways to explicitly specify a key:
Section 13.5.3.1.1, "Specifying a Key Property in EPN Assembly File"
Section 13.5.3.1.2, "Using a Metadata Annotation to Specify a Key"
The first option is to specify a property name for the key property when a cache is declared in the EPN assembly file using the key-properties
attribute, as shown in the following example:
<wlevs:cache id="myCache" key-properties="key-property-name"> <wlevs:caching-system ref="caching-system-id"/> </wlevs:cache>
In this case, all events that are inserted into the cache are required to have a property of this name at runtime, otherwise Oracle Event Processing throws an exception.
For example, assume the event type being inserted into the cache looks something like the following; note the key
property (only relevant Java source shown):
public class MyEvent { private String key; public MyEvent() { } public MyEvent(String key) { this.key = key; } public String getKey() { return key; } public void setKey(String key) { this.key = key; } }
The corresponding declaration in the EPN assembly file would look like the following:
<wlevs:cache id="myCache" key-properties="key">
<wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>
The second option is to use the metadata annotation com.bea.wlevs.ede.api.Key
to annotate the event property in the Java class that implements the event type. This annotation does not have any attributes.
To use a metadata annotation to specify a key:
Import the com.bea.wlevs.ede.api.Key
package.
For more information, see Section 5.7.5, "How to Import a Package".
Apply the @Key
annotation to a method.
The following example shows how to specify that the key
property of the MyEvent
event type is the key; only relevant code is shown:
import com.bea.wlevs.ede.api.Key; public class MyEvent { private String key; public MyEvent() { } public MyEvent(String key) { this.key = key; } public String getKey() { return key; } @Key public void setKey(String key) { this.key = key; } }
The final option is to use the key-class
attribute of the wlevs:cache
element to specify a composite key in which multiple properties form the key. The value of the key-class
attribute must be a JavaBean whose public fields match the fields of the event class. The matching is done according to the field name. For example:
<wlevs:cache id="myCache" key-class="key-class-name"> <wlevs:caching-system ref="caching-system-id"/> </wlevs:cache>
You can configure a cache as a source of events to which another component in the event processing network listens. The listening component can be an adapter or a bean.
A class that listens to a cache must implement an interface that provides methods for receiving events, as follows:
A class that listens to a Coherence cache must implement the com.tangosol.util.MapListener
interface.
A class that listens to an Oracle Event Processing local cache must implement the com.bea.cache.jcache.CacheListener
interface.
<wlevs:caching-system id="caching-system-id"/> ... <wlevs:cache id="cache-id" name="alternative-cache-name"> <wlevs:caching-system ref="caching-system-id"/> <wlevs:cache-listener ref="cache-listener-id" /> </wlevs:cache> ... <bean id="cacheListenerId" class="wlevs.example.LocalListener"/>
In the example, the cacheListenerId
Spring bean listens to events coming from the cache. In this case, the class that implements this component, com.bea.wlevs.example.MyCacheListener
, is listening to an Oracle Coherence cache. It must implement the appropriate Oracle Coherence-specific Java interfaces, including com.tangosol.util.MapListener
. Example 13-4 illustrates this implementation.
Example 13-4 Oracle Coherence Cache LocalListener Implementation
package com.bea.wlevs.example.provider.coherence; import com.tangosol.util.MapEvent; import com.tangosol.util.MapListener; public class LocalListener implements MapListener { public static int deleted = 0; public static int inserted = 0; public static int updated = 0; public void entryDeleted(MapEvent event) { deleted++; } public void entryInserted(MapEvent event) { inserted++; } public void entryUpdated(MapEvent event) { updated++; } }
You can have a cache in an EPN exchange data with another data source, including a database. For example, you can load a cache with data when the application starts or create a read/write relationship between the cache and a database.
If the cache will only be reading data, including when the backing store is read-only, you should use a cache loader. If the cache will read and write data, use a cache store. In both cases, creating the relationship involves specific configuration and a Java class that knows how to communicate with the data source.
For more information, see the following topics:
Section 13.5.5.1, "Loading Cache Data from a Read-Only Data Source"
Section 13.5.5.2, "Exchanging Data with a Read-Write Data Source"
Using a cache loader, you can have a cache in your EPN load data from a read-only data source. A cache loader is a Java class that loads cache objects into a cache. You create a cache loader by writing a Java class that implements the appropriate interfaces to enable the loader class to communicate with the cache. Then you configure a cache loader by using the wlevs:cache-loader
child element of the wlevs:cache
element to specify the bean that does the loading work.
If the backing store is read-write, use a cache store instead (see Section 13.5.5.2, "Exchanging Data with a Read-Write Data Source").
When creating a cache loader, you implement interfaces as follows:
To load cache data into an Oracle Coherence cache, create a class that implements the appropriate Oracle Coherence-specific Java interfaces, including com.tangosol.net.cache.CacheLoader
. See Example 13-6 for an example.
To load cache data into an Oracle Event Processing local cache, create a class that implements com.bea.cache.jcache.CacheLoader
interface. This interface includes the load
method to customize loading a single object into the cache; Oracle Event Processing calls this method when the requested object is not in the cache. The interface also includes loadAll
methods that you implement to customize the loading of the entire cache.
In Example 13-5, the localLoader
bean loads events into an Oracle Coherence cache when the backing store is read-only.
When working with a Coherence cache, note that if you specify a cache loader in your configuration file, you must also specify the corresponding class factory method name in your Coherence cache configuration file. For a cache loader, you specify the getLoader
method of com.bea.wlevs.cache.coherence.configuration.SpringFactory
. For example code, see Section 13.2.1.1, "The coherence-cache-config.xml File".
Example 13-5 Oracle Coherence Cache EPN Assembly File for a Cache Loader
<wlevs:caching-system id="caching-system-id"/> <wlevs:cache id="myCache" advertise="false"> <wlevs:caching-system ref="caching-system-id"/> <wlevs:cache-loader ref="localLoader"/> </wlevs:cache> <bean id="localLoader" class="com.bea.wlevs.example.provider.coherence.LocalLoader"/>
Example 13-6 Oracle Coherence Cache LocalLoader Implementation
package com.bea.wlevs.example.provider.coherence; import java.util.Collection; import java.util.HashMap; import java.util.HashSet; import java.util.Map; import java.util.Set; import com.bea.wlevs.example.provider.event.ProviderData; import com.tangosol.net.cache.CacheLoader; public class LocalLoader implements CacheLoader { public static int loadCount = 0; public static Set keys = new HashSet(); public LocalLoader() { } public Object load(Object key) { loadCount++; keys.add(key); return new ProviderData((String) key); } public Map loadAll(Collection keys) { Map result = new HashMap(); for (Object key : keys) { result.put(key, load(key)); } return result; } }
Using a cache store, you can have a cache in your EPN exchange data with a read-write data source. A cache store is a Java class that exchanges cache objects with a cache. You create a cache store by writing a Java class that implements the appropriate interfaces to enable the it to communicate with the data source. Then you add the cache store to the EPN by using the wlevs:cache-loader
child element of the wlevs:cache
element to specify the bean that communicates with the data source.
If the backing store is read-only, use a cache loader instead (see Section 13.5.5.1, "Loading Cache Data from a Read-Only Data Source").
When creating a cache store, you implement interfaces as follows:
To exchange cache data with an Oracle Coherence cache, create a class that implements the appropriate Oracle Coherence-specific Java interfaces, including com.tangosol.net.cache.CacheStore
. See Example 13-8 for an example.
To exchange cache data with an Oracle Event Processing local cache, create a class that implements the com.bea.cache.jcache.CacheStore
interface. This interface includes the store
method that stores the data in the backing store using the passed key; Oracle Event Processing calls this method when it inserts data into the cache. The interface also includes the storeAll
method for storing a batch of data to a backing store in the case that you have configured asynchronous writes for a cache with the write-behind
configuration element.
In Example 13-7, the localStore
bean loads events into the cache when the backing store is read-write.
Note that if you specify a cache store in your Spring configuration file, you must also specify the corresponding class factory method name in your Coherence cache configuration file. For a cache store, you specify the getStore
method of com.bea.wlevs.cache.coherence.configuration.SpringFactory
. For example code, see Section 13.2.1.1, "The coherence-cache-config.xml File".
Example 13-7 Oracle Coherence Cache EPN Assembly File for a Cache Store
<wlevs:caching-system id="caching-system-id"/> <wlevs:cache id="myCache" advertise="false"> <wlevs:caching-system ref="caching-system-id"/> <wlevs:cache-store ref="localStore"/> </wlevs:cache> <bean id="localStore" class="com.bea.wlevs.example.provider.coherence.LocalStore"/>
Example 13-8 Oracle Coherence Cache LocalStore Implementation
package com.bea.wlevs.example.provider.coherence; import java.util.Collection; import java.util.HashMap; import java.util.Map; import java.util.Set; import com.bea.wlevs.example.provider.event.ProviderData; import com.tangosol.net.cache.CacheStore; public class LocalStore implements CacheStore { public static int eraseCount = 0; public static int storeCount = 0; public static int loadCount = 0; public void erase(Object key) { eraseCount++; } public void eraseAll(Collection keys) { for (Object key : keys) { erase(key); } } public void store(Object key, Object value) { // // Do the store operation here. // } public void storeAll(Map entries) { for (Map.Entry entry : (Set <Map.Entry>)entries.entrySet()) { store(entry.getKey(), entry.getValue()); } } public Object load(Object key) { loadCount++; return new ProviderData((String) key); } public Map loadAll(Collection keys) { Map result = new HashMap(); for (Object key : keys) { result.put(key, load(key)); } return result; } }
Once you have configured a cache, you can access the cache from several components in an Oracle Event Processing application. This section describes how to do that.
For more information, see the following sections:
Section 13.6.1, "Accessing a Cache from an Oracle CQL Statement"
Section 13.6.5, "Accessing a Cache From an Oracle CQL User-Defined Function"
Section 13.6.6, "Accessing a Cache From an EPL User-Defined Function"
You can reference a cache from an Oracle CQL statement in much the same way you reference an event source such as a channel; this feature enables you to enrich standard streaming data with data from a separate source. Example 13-9 shows a valid Oracle CQL query that joins trade events from a standard channel named S1
with stock symbol data from a cache named stockCache
:
Example 13-9 Valid Oracle CQL Query Against a Cache
SELECT S1.symbol, S1.lastPrice, stockCache.description FROM S1 [Now], stockCache WHERE S1.symbol = stockCache.symbol
You must abide by these restrictions when using a cache in an Oracle CQL query:
Whenever you query a cache, you must join against the [Now]
window.
This guarantees that the query will execute against a snapshot of the cache. If you join against any other window type, then if the cache changes before the window expires, the query will be incorrect.
The following example shows an invalid Oracle CQL query that joins a Range
window against a cache. If the cache changes before this window expires, the query will be incorrect. Consequently, this query will raise Oracle Event Processing server error "external relation must be joined with s[now]
".
SELECT trade.symbol, trade.price, trade.numberOfShares, company.name FROM TradeStream [Range 8 hours] as trade, CompanyCache as company WHERE trade.symbol = company.id
When you use data from a cache in an Oracle CQL query, Oracle Event Processing pulls the data rather than it being pushed, as is the case with a channel. This means that, continuing with Example 13-9, the query executes only when a channel pushes a trade
event to the query; the stock symbol data in the cache never causes a query to execute, it is only pulled by the query when needed.
You must specify the key property needed to do a lookup based on the cache key.
Consider two streams S
and C
with schemas (id
, group
, value
) where the cache key is id
. A valid query is:
select count(*) as n from S [now], C where S.id = C.id
For instructions on specifying the cache key, see:
Joins must be executed only by referencing the cache key.
You cannot use a cache in a view. Instead, use a join.
Only a single channel source may occur in the FROM
clause of an Oracle CQL statement that joins cache data source(s).
If the cache is a processor source, you connect the cache directly to the processor on the EPN as Figure 13-1 shows.
If the cache is a processor sink, you connect the processor to the cache using a channel as Figure 13-2 shows.
This section describes how to reference a cache in an Oracle CQL query statement.
This procedure assumes that you have already configured the caching system and caches. For more information, see:
Section 13.3, "Configuring an Oracle Event Processing Local Caching System and Cache"
Section 13.2, "Configuring an Oracle Coherence Caching System and Cache"
Section 13.4, "Configuring a Third-Party Caching System and Cache"
To access a cache from an Oracle CQL statement:
If you have not already done so, create the event type that corresponds to the cache data and register it in the event repository.
Specify the key properties for the data in the cache.
For instructions on specifying the cache key, see:
In the EPN assembly file, update the configuration of the cache to declare the event type of its values; use the value-type
attribute of the wlevs:cache
element. For example:
<wlevs:caching-system id="caching-system-id"/>
...
<wlevs:cache id="cache-id"
name="alternative-cache-name"
value-type="CompanyEvent">
<wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>
The value-type attribute specifies the type for the values contained in the cache. This must be a valid type name in the event type repository.
This attribute is required only if the cache is referenced in an Oracle CQL query. This is because the query processor needs to know the type of events in the cache.
In the EPN assembly file, update the configuration of the processor that executes the Oracle CQL query that references a cache:
If the cache is a processor source: you connect the cache directly to the processor on the EPN as Figure 13-1 shows.
Update the wlevs:processor
element a wlevs:cache-source
child element that references the cache. For example:
<wlevs:channel id="S1"/>
<wlevs:processor id="cacheProcessor">
<wlevs:source ref="S1">
<wlevs:cache-source ref="cache-id">
</wlevs:processor>
In the example, the processor will have data pushed to it from the S1
channel as usual; however, the Oracle CQL queries that execute in the processor can also pull data from the cache-id
cache. When the query processor matches an event type in the FROM
clause to an event type supplied by a cache, such as CompanyEvent
, the processor pulls instances of that event type from the cache.
If the cache is a processor sink: you must connect the processor to the cache using a channel on the EPN (that is, there must be a channel between the processor and the cache sink) as Figure 13-2 shows.
In this case, the application assembly file looks like this:
<wlevs:channel id="channel1" event-type="StockTick">
<wlevs:listener ref="processor" />
</wlevs:channel>
<wlevs:processor id="processor">
<wlevs:listener ref="channel2" />
</wlevs:processor>
<wlevs:channel id="channel2" event-type="StockTick">
<wlevs:listener ref="cache-id" />
</wlevs:channel>
You can reference a cache from an Event Processing Language (EPL) statement in much the same way you reference a channel; this feature enables you to enrich standard streaming data with data from a separate source.
Note:
The EPL language is deprecated. For new development, use Oracle CQL. For information on accessing a cache from CQL, see Section 13.6.1, "Accessing a Cache from an Oracle CQL Statement".
For example, the following EPL query joins trade events from a standard channel with company data from a cache:
INSERT INTO EnrichedTradeEvent SELECT trade.symbol, trade.price, trade.numberOfShares, company.name FROM TradeEvent trade RETAIN 8 hours, Company company WHERE trade.symbol = company.id
In the example, both TradeEvent
and Company
are event types registered in the repository, but they have been configured in such a way that TradeEvents
come from a standard stream of events but Company
maps to a cache in the event processing network. This configuration happens outside of the EPL query, which means that the source of the data is transparent in the query itself.
When you use data from a cache in an EPL query, Oracle Event Processing pulls the data rather than it being pushed, as is the case with a channel. This means that, continuing with the preceding sample, the query executes only when a channel pushes a trade event to the query; the company data in the cache never causes a query to execute, it is only pulled by the query when needed.
You must abide by these restrictions when using a cache in an EPL query:
You must specify the key properties for data in the cache.
For instructions on specifying the cache key, see:
Joins must be executed only by referencing the cache key.
You cannot specify a RETAIN
clause for data pulled from a cache. If an event type that gets its data from a cache is included in a RETAIN
clause, Oracle Event Processing ignores it.
You cannot use a cache in a correlated sub-query. Instead, use a join.
Only a single channel source may occur in the FROM
clause of an EPL statement that joins cache data source(s). Using multiple cache sources and parameterized SQL queries is supported.
This section describes how to reference a cache in an EPL query statement.
This procedure assumes that you have already configured the caching system and caches. For more information, see:
Section 13.3, "Configuring an Oracle Event Processing Local Caching System and Cache"
Section 13.2, "Configuring an Oracle Coherence Caching System and Cache"
Section 13.4, "Configuring a Third-Party Caching System and Cache"
To access a cache from an EPL statement:
If you have not already done so, create the event type that corresponds to the cache data, such as Company
in the preceding example, and registered it in the event repository. See Section 9.3, "Creating Event Types".
Specify the key properties for the data in the cache. There are a variety of ways to do this; see
In the EPN assembly file, update the configuration of the cache in the EPN assembly file to declare the event type of its values; use the value-type
attribute of the wlevs:cache
element. For example:
<wlevs:caching-system id="caching-system-id"/>
...
<wlevs:cache id="cache-id"
name="alternative-cache-name"
value-type="Company">
<wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>
The value-type attribute specifies the type for the values contained in the cache. This must be a valid type name in the event type repository.
This attribute is required only if the cache is referenced in an EPL query. This is because the query processor needs to know the type of events in the cache.
In the EPN assembly file, update the configuration of the processor that executes the EPL query that references a cache, adding a wlevs:cache-source
child element that references the cache. For example:
<wlevs:channel id="stream-id"/>
<wlevs:processor id="processor-id">
<wlevs:cache-source ref="cache-id">
<wlevs:source ref="stream-id">
</wlevs:processor>
In the example, the processor will have data pushed to it from the stream-id
channel as usual; however, the EPL queries that execute in the processor can also pull data from the cache-id
cache. When the query processor matches an event type in the FROM
clause to an event type supplied by a cache, such as Company
, the processor pulls instances of that event type from the cache.
An adapter can also be injected with a cache using the standard Spring mechanism for referencing another bean. A cache bean implements the java.util.Map
interface which is what the adapter uses to access the injected cache.
First, the configuration of the adapter in the EPN assembly file must be updated with a wlevs:instance-property
child element, as shown in the following example:
<wlevs:caching-system id="caching-system-id"/>
...
<wlevs:cache id="cache-id" name="alternative-cache-name">
<wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>
...
<wlevs:adapter id="myAdapter" provider="myProvider">
<wlevs:instance-property name="map" ref="cache-id"/>
</wlevs:adapter>
In the example, the ref
attribute of wlevs:instance-property
references the id
value of the wlevs:cache
element. Oracle Event Processing automatically injects the cache, implemented as a java.util.Map
, into the adapter.
In the adapter Java source, add a setMap
(Map)
method with the code that implements whatever you want the adapter to do with the cache:
package com.bea.wlevs.example;
…
import java.util.Map;
public class MyAdapter implements Runnable, Adapter, EventSource, SuspendableBean {
...
public void setMap (Map map) {...}
}
A business POJO, configured as a standard Spring bean in the EPN assembly file, can be injected with a cache using the standard Spring mechanism for referencing another bean. In this way the POJO can view and manipulate the cache. A cache bean implements the java.util.Map
interface which is what the business POJO uses to access the injected cache. A cache bean can also implement a vendor-specific sub-interface of java.util.Map
, but for portability it is recommended that you implement Map
.
First, the configuration of the business POJO in the EPN assembly file must be updated with a property
child element, as shown in the following example based on the Output bean of the FX example (see Section 2.5, "HelloWorld Example"):
<wlevs:caching-system id="caching-system-id"/>
...
<wlevs:cache id="cache-id" name="alternative-cache-name">
<wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>
...
<bean class="com.bea.wlevs.example.helloworld.HelloWorldBean">
<property name="map" ref="cache-id"/>
</bean>
In the example, the ref
attribute of the property
element references the id
value of the wlevs:cache
element. Oracle Event Processing automatically injects the cache, implemented as a java.util.Map
, into the business POJO bean.
In the business POJO bean Java source, add a setMap
(Map)
method with the code that implements whatever you want the POJO to do with the cache:
package com.bea.wlevs.example.helloworld;
…
import java.util.Map;
public class HelloWorldBean implements EventSink {
...
public void setMap (Map map) {...}
}
In addition to standard event streams, Oracle CQL rules can also invoke the member methods of a user-defined function.
These user-defined functions are implemented as standard Java classes and are declared in the component configuration file of the Oracle CQL processor, as shown in the following example:
<bean id="orderFunction" class="orderFunction-impl-class"/>
The processor in which the relevant Oracle CQL rule runs must then be injected with the user-defined function using the wlevs:function
child element, referencing the Spring bean with the ref
attribute:
<wlevs:processor id= "tradeProcessor">
<wlevs:function ref="orderFunction"/>
</wlevs:processor>
Alternatively, you can specify the bean class in the wlevs:function
element:
<wlevs:processor id="testProcessor"> <wlevs:listener ref="providerCache"/> <wlevs:listener ref="outputCache"/> <wlevs:cache-source ref="testCache"/> <wlevs:function function-name="mymod" exec-method=”execute” /> <bean class="com.bea.wlevs.example.function.MyMod"/> </wlevs:function> </wlevs:processor>
The following Oracle CQL rule, assumed to be configured for the tradeProcessor
processor, shows how to invoke the existsOrder
method of the orderFunction
user-defined function:
INSERT INTO InstitutionalOrder
SELECT er.orderKey AS key, er.symbol AS symbol, er.shares as cumulativeShares
FROM ExecutionRequest er [Range 8 hours]
WHERE NOT orderFunction.existsOrder(er.orderKey)
You can also configure the user-defined function to access a cache by injecting the function with a cache using the standard Spring mechanism for referencing another bean. A cache bean implements the java.util.Map
interface which is what the user-defined function uses to access the injected cache.
First, the configuration of the user-defined function in the EPN assembly file must be updated with a wlevs:property
child element, as shown in the following example:
<wlevs:caching-system id="caching-system-id"/>
...
<wlevs:cache id="cache-id" name="alternative-cache-name">
<wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>
...
<bean id="orderFunction" class="orderFunction-impl-class">
<wlevs:property name="cache" ref="cache-id"/>
</bean>
In the example, the ref
attribute of the wlevs:property
element references the id
value of the wlevs:cache
element. Oracle Event Processing automatically injects the cache, implemented as a java.util.Map
, into the user-defined function.
In the user-defined function's Java source, add a setMap
(Map)
method with the code that implements whatever you want the function to do with the cache:
package com.bea.wlevs.example;
…
import java.util.Map;
public class OrderFunction {
...
public void setMap (Map map) {...}
}
For more information on user-defined functions, see "Functions: User-Defined" in the Oracle Fusion Middleware CQL Language Reference for Oracle Event Processing.
In addition to standard event streams, EPL rules can also invoke the member methods of a user-defined function.
These user-defined functions are implemented as standard Java classes and are declared in the EPN assembly file using the standard Spring bean tags, as shown in the following example:
<bean id="orderFunction" class="orderFunction-impl-class"/>
The processor in which the relevant EPL rule runs must then be injected with the user-defined function using the wlevs:function
child element, referencing the Spring with the ref
attribute:
<wlevs:processor id= "tradeProcessor">
<wlevs:function ref="orderFunction"/>
</wlevs:processor>
The following EPL rule, assumed to be configured for the tradeProcessor
processor, shows how to invoke the existsOrder
method of the orderFunction
user-defined function:
INSERT INTO InstitutionalOrder
SELECT er.orderKey AS key, er.symbol AS symbol, er.shares as cumulativeShares
FROM ExecutionRequest er RETAIN 8 HOURS WITH UNIQUE KEY
WHERE NOT orderFunction.existsOrder(er.orderKey)
You can also configure the user-defined function to access a cache by injecting the function with a cache using the standard Spring mechanism for referencing another bean. A cache bean implements the java.util.Map
interface which is what the user-defined function uses to access the injected cache.
First, the configuration of the user-defined function in the EPN assembly file must be updated with a wlevs:property
child element, as shown in the following example:
<wlevs:caching-system id="caching-system-id"/>
...
<wlevs:cache id="cache-id" name="alternative-cache-name">
<wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>
...
<bean id="orderFunction" class="orderFunction-impl-class">
<wlevs:property name="cache" ref="cache-id"/>
</bean>
In the example, the ref
attribute of the wlevs:property
element references the id
value of the wlevs:cache
element. Oracle Event Processing automatically injects the cache, implemented as a java.util.Map
, into the user-defined function.
In the user-defined function's Java source, add a setMap
(Map)
method with the code that implements whatever you want the function to do with the cache:
package com.bea.wlevs.example;
…
import java.util.Map;
public class OrderFunction {
...
public void setMap (Map map) {...}
}
For more information on user-defined functions, see "User-Defined Functions" in the Oracle Fusion Middleware EPL Language Reference for Oracle Event Processing.
At runtime, you can access a cache programatically using JMX and the MBeans that Oracle Event Processing deploys for the caching systems and caches you define.
This section describes:
Section 13.6.7.1, "How to Access a Cache With JMX Using Oracle Event Processing Visualizer"
Section 13.6.7.2, "How to Access a Cache With JMX Using Java"
For more information, "Configuring JMX for Oracle Event Processing" in the Oracle Fusion Middleware Administrator's Guide for Oracle Event Processing
The simplest and least error-prone way to access a caching system or cache with JMX is to use the Oracle Event Processing Visualizer.
For more information, see "Server and Domain Tasks" in the Oracle Fusion Middleware Visualizer User's Guide for Oracle Event Processing.
The simplest and least error-prone way to access a caching system or cache with JMX is to use the Oracle Event Processing Visualizer (see Section 13.6.7.1, "How to Access a Cache With JMX Using Oracle Event Processing Visualizer"). Alternatively, you can access a caching system or cache with JMX using Java code that you write.
Oracle Event Processing creates a StageMBean
for each cache that your application uses as a stage. The Type
of this MBean is Stage
.
To access a cache with JMX using Java:
Connect to the JMX service that Oracle Event Processing server provides.
For more information, see "Configuring JMX for Oracle Event Processing" in the Oracle Fusion Middleware Administrator's Guide for Oracle Event Processing
Get a list of cache StageMbean
using either of:
CachingSystemMBean.getCacheMBeans()
ApplicationMBean.getStageMBeans()
Get the ObjectName
for a given StageMBean
that represents a cache in your caching system:
ObjectName cacheName = ObjectName.getInstance ( 'com.bea.wlevs:Name = newCache,Type=Stage,CachingSystem=newCachingSystem,Application=provider' );
Get a proxy instance for the StageMBean
with this ObjectName
:
StageMBean cache = (StageMBean) MBeanServerInvocationHandler.newProxyInstance( server, cacheName, StageMBean.class, false );
Use the methods of the StageMBean
to access the cache.