12 Configuring Caching

12.1 Overview of Oracle CEP Cache Configuration

A cache is a temporary storage area for events, created exclusively to improve the overall performance of your Oracle CEP application; it is not necessary for the application to function correctly. Oracle CEP applications can optionally publish or consume events to and from a cache to increase the availability of the events and increase the performance of their applications.

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.

Oracle CEP supports the following caching systems:

• Oracle CEP local cache: a local, in-memory single-JVM cache.

• 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 CEP 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 CEP to work with other, third-party cache implementations.

A cache can be considered a stage in the event processing network in which an external element (the cache) consumes or produces events; this is similar to an adapter that uses a JMS destination. A cache, however, 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.

A caching system is always configured at the application level. Other Oracle CEP applications in separate bundles can also use the caching system.

For each caching system in your application, you must create a caching-system element in a component configuration file. In this caching-system element you specify the caching system name and one or more cache elements. In the cache elements, you define optional cache configuration such as:

• Maximum cache size

• Eviction policy

• Time-to-live

• Idle time

• Write policy (write-none, write-through, or write-behind)

• Work manager

The component configuration file caching-system element's name element must match the EPN assembly file caching-system element's id attribute. For example, given the EPN assembly file caching-system element shown in Example 12-1, the corresponding component configuration file caching-system element is shown in Example 12-2.

<wlevs:caching-system id="cacheSystem">
    ...
</wlevs:caching-system>

<wlevs:cache id="cache1">
    <wlevs:caching-system ref="cacheSystem"/>
</wlevs:cache>

<caching-system>
    <name>cacheSystem</name>
    <cache>
        <name>cache1</name>
        ...
    </cache>
</caching-system>

Similarly, the component configuration file cache element's name element must match the EPN assembly file cache element's id attribute. For example, given the EPN assembly file cache element shown in Example 12-1, the corresponding component configuration file cache element is shown in Example 12-2.

<wlevs:caching-system id="cacheSystem">
    ...
</wlevs:caching-system>

<wlevs:cache id="cache1">
    <wlevs:caching-system ref="cacheSystem"/>
</wlevs:cache>

<caching-system>
    <name>cacheSystem</name>
    <cache>
        <name>cache1</name>
        ...
    </cache>
</caching-system>

You can create a caching-system element in any of the following component configuration files:

• The default Oracle CEP application configuration file (by default, META-INF/wlevs/config.xml).

• A separate configuration file.

If your application has more than one caching system, you can create a caching-system element for each of them in the default config.xml file, you can create separate XML files in META-INF/wlevs for each, or create a single XML file in META-INF/wlevs that contains the configuration for all caching systems, or even all components of your application (adapters, processors, and channels). Choose the method that best suits your development environment.

By default, Oracle CEP IDE for Eclipse creates one component configuration file and one EPN assembly file. When you add a cache to the EPN using Oracle CEP IDE for Eclipse, it adds a cache element to the EPN assembly file. You must manually add caching-system elements to the EPN assembly file and component configuration file.

Component configuration files are deployed as part of the Oracle CEP application bundle. You can later update this configuration at runtime using Oracle CEP Visualizer, the wlevs.Admin utility, or manipulating the appropriate JMX Mbeans directly.

For more information, see:

• Section 1.1.5, "Component Configuration Files"

• Section 1.1.7, "EPN Assembly File"

• Section 1.4, "Creating the EPN Assembly File"

• Oracle CEP Visualizer User's Guide

• "wlevs.Admin Command-Line Reference" in the Oracle CEP Administrator's Guide

• "Configuring JMX for Oracle CEP" in the Oracle CEP Administrator's Guide

For more information on configuring caching, see:

• Section 12.1.1, "Caching Use Cases"

• Section 12.1.2, "Additional Caching Features"

• Section 12.1.3, "Caching APIs"

12.2 Configuring an Oracle CEP Local Caching System and Cache

You can configure your application to use the Oracle CEP local caching system and cache. The Oracle CEP 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 12.3, "Configuring an Oracle Coherence Caching System and Cache").

To configure an Oracle CEP local caching system and cache:

1. Declare the caching system in the EPN assembly file.

   To declare a caching system that uses the Oracle CEP implementation declaratively in the EPN assembly file, use the wlevs:caching-system element without any additional attributes, as shown in the following example:

   <wlevs:caching-system id="caching-system-id"/>
   

   The value of the id attribute must match the name specified for the caching system in the external configuration metadata.

   To allow other applications to use the caching system, specify that the caching system be advertised using the advertise attribute (by default set to false):

   <wlevs:caching-system id="caching-system-id" advertise="true"/>
   

2. 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"/>
   ...
   <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.

3. Open your application's component configuration XML file using your favorite XML editor.

4. Update the config root element to add a caching-system child element; use the name child element to uniquely identify it.

   This name must match the wlevs:caching-system element id attribute you specified in the EPN assembly file in step 1. This is how Oracle CEP 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 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>
   

5. 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 it.

   This name must match the wlevs:cache element id attribute you specified in the EPN assembly file in step 2. This is how Oracle CEP knows to which particular cache in the EPN assembly file this configuration applies.

   The following example shows two caches in the caching system:

   <caching-system>
       <name>caching-system-id</name>
       <cache>
           <name>cache-id</name>
           ...
       </cache>
       <cache>
           <name>second-cache-id</name>
           ...
       </cache>
   </caching-system>
   

6. 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 2³¹-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 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>
   

7. 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 (<rite-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.

   • 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>
   

8. 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 CEP 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>
   

9. Optionally, override the default cache configuration by updating the EPN assembly 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.

     See Section 12.2.1, "Configuring an Oracle CEP Local Cache as an Event Listener."

   • Specify that a cache is an event source to which another component in the event processing network listens.

     See Section 12.2.2, "Configuring an Oracle CEP Local Cache as an Event Source."

   • Configure a cache loader for a cache.

     See Section 12.2.3, "Configuring an Oracle CEP Local Cache Loader."

   • Configure a cache store for a cache.

     See Section 12.2.4, "Configuring an Oracle CEP Local Cache Store."

10. Access the Oracle CEP local cache:

    • Optionally reference the Oracle CEP local cache in a query statement.

      See:

      • Section 12.5, "Accessing a Cache From an Oracle CQL Statement"

      • Section 12.6, "Accessing a Cache From an EPL Statement"

    • Optionally configure and program a custom adapter, business POJO, or Oracle CQL or EPL user-defined function to access the Oracle CEP local cache.

      The configuration is done in the EPN assembly file and the programming is done in the Java file that implements the adapter, POJO, or user-defined function.

      See:

      • Section 12.7, "Accessing a Cache From an Adapter"

      • Section 12.8, "Accessing a Cache From a Business POJO"

      • Section 12.9, "Accessing a Cache From an Oracle CQL User-Defined Function"

      • Section 12.10, "Accessing a Cache From an EPL User-Defined Function"

    • Optionally, access the Oracle CEP local cache using JMX.

      See Section 12.11, "Accessing a Cache Using JMX".

11. When you assemble your application, verify that the META-INF/MANIFEST.MF file includes the following import as Figure 12-1 shows:

    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.

    Figure 12-1 Editing the MANIFEST.MF File

    
    Description of "Figure 12-1 Editing the MANIFEST.MF File"
    
    

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

<wlevs:cache id="cache-id" key-properties="key-property-name">
    <wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>

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;
    }
 ...
}

<wlevs:cache id="cache-id" key-properties="key">
    <wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>

import com.bea.wlevs.ede.api.Key;
public class MyEvent {
    @Key
    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;
    }
 ...
}

<wlevs:cache id="cache-id" key-class="key-class-name">
    <wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>

<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="cache-listener-id" class="wlevs.example.MyCacheListener"/>

<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-loader ref="cache-loader-id" />
</wlevs:cache>
...
<bean id="cache-loader-id" class="wlevs.example.MyCacheLoader"/>

<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-store ref="cache-store-id" />
</wlevs:cache>
...
<bean id="cache-store-id" class="wlevs.example.MyCacheStore"/>

12.3 Configuring an Oracle Coherence Caching System and Cache

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 CEP will ignore any other caching systems you might configure.

To configure an Oracle Coherence caching system and cache:

1. Declare the Oracle Coherence caching system in the EPN assembly file.

   To declare a caching system that uses the Oracle Coherence implementation declaratively in the EPN assembly file, use the wlevs:caching-system element as shown in the following example:

   <wlevs:caching-system id="caching-system-id" provider="coherence"/>
   

   The value of the id attribute must match the name you specify for the caching system in the application's component configuration file (see step 3).

   To allow other applications to use the caching system, specify that the caching system be advertised using the advertise attribute (by default set to false):

   <wlevs:caching-system id="caching-system-id" provider="coherence" advertise="true"/>
   

2. 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="coherence" />
   ...
   <wlevs:cache id="myCache" advertise="false"> 
       <wlevs:caching-system ref="caching-system-id"/>
   </wlevs:cache>
   

   The wlevs:cache element id attribute is mandatory. This attribute maps to the name of a cache in the Oracle Coherence configuration files (see step 3).

   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" 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>
   

   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.

3. Configure the caching system and its caches by updating the caching configuration file for the application.

   See Section 12.3.1, "Configuring the Oracle Coherence Caching System and Caches."

4. Optionally, override the default cache configuration by updating the EPN assembly 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.

     See Section 12.3.1, "Configuring the Oracle Coherence Caching System and Caches."

   • Specify that a cache is an event source to which another component in the event processing network listens.

     See Section 12.3.2, "Configuring an Oracle Coherence Cache as an Event Listener."

   • Configure either a <wlevs:cache-loader> or a <wlevs:cache-store> child element of the <wlevs:cache> element in the EPN assembly file, but not both.

     This is because Oracle Coherence combines the loader and store into a single component. You specify a cache loader when the backing store is read-only and a cache store when the backing store is read-write

     See Section 12.3.4, "Configuring an Oracle Coherence Cache Loader or Store."

5. Access the Oracle Coherence cache:

   • Optionally reference the Oracle Coherence cache in a query statement.

     See:

     • Section 12.5, "Accessing a Cache From an Oracle CQL Statement"

     • Section 12.6, "Accessing a Cache From an EPL Statement"

   • Optionally configure and program a custom adapter, business POJO, or Oracle CQL or EPL user-defined function to access the Oracle Coherence cache.

     The configuration is done in the EPN assembly file and the programming is done in the Java file that implements the adapter, POJO, or user-defined function.

     See:

     • Section 12.7, "Accessing a Cache From an Adapter"

     • Section 12.8, "Accessing a Cache From a Business POJO"

     • Section 12.9, "Accessing a Cache From an Oracle CQL User-Defined Function"

     • Section 12.10, "Accessing a Cache From an EPL User-Defined Function"

   • Optionally, access the Oracle Coherence cache using JMX.

     See Section 12.11, "Accessing a Cache Using JMX".

6. When you assemble your application, verify that the META-INF/MANIFEST.MF file includes the following import as Figure 12-1 shows:

   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.

   Figure 12-2 Editing the MANIFEST.MF File

   
   Description of "Figure 12-2 Editing the MANIFEST.MF File"
   
   

<coherence-caching-system>
    <name>caching-system-id</name>
    <coherence-cache-config>
        ../wlevs/coherence/coherence-cache-config.xml
    </coherence-cache-config>
</coherence-caching-system>

<?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>

<wlevs:cache id="myCoherenceCache" advertise="false"> 
    <wlevs:caching-system ref="coherence-cache"/>
    <wlevs:cache-loader ref="localLoader"/> 
    <wlevs:cache-listener ref="localListener"/>
</wlevs:cache>

<?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>

<wlevs:coherence-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>

<wlevs:cache id="myCache" key-properties="key-property-name">
    <wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>

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;
    }
...
}

<wlevs:cache id="myCache" key-properties="key">
    <wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>

import com.bea.wlevs.ede.api.Key;
public class MyEvent {
    @Key
    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;
    }
 ...
}

<wlevs:cache id="myCache" key-class="key-class-name">
    <wlevs:caching-system ref="caching-system-id"/>
</wlevs:cache>

<wlevs:coherence-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-listener ref="localListener"/>
</wlevs:cache>
<bean id="localListener" 
      class="com.bea.wlevs.example.provider.coherence.LocalListener"/>

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++;
    }
}

<wlevs:coherence-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"/>

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;
    }
}

<wlevs:coherence-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"/>

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;
    }
}

12.4 Configuring a Third-Party Caching System and Cache

You can configure your application to use a third-party caching system and cache.

To configure a third-party caching system and cache:

1. Create a plug-in to define the third-party caching system as an Oracle CEP 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.

2. 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 attributes to specify additional information.

   For simplicity, you can include the third-party implementation code inside the Oracle CEP 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 CEP Java API Reference.

   Sometimes, however, you might not be able, or want, to include the third-party caching implementation in the same bundle as the Oracle CEP 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.

3. 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.

4. 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.

5. 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.

6. Access the third-party cache:

   • Optionally reference the third-party cache in a query statement.

     See:

     • Section 12.5, "Accessing a Cache From an Oracle CQL Statement"

     • Section 12.6, "Accessing a Cache From an EPL Statement"

   • Optionally configure and program a custom adapter, business POJO, or Oracle CQL or EPL user-defined function to access the third-party cache.

     The configuration is done in the EPN assembly file and the programming is done in the Java file that implements the adapter, POJO, or user-defined function.

     See:

     • Section 12.7, "Accessing a Cache From an Adapter"

     • Section 12.8, "Accessing a Cache From a Business POJO"

     • Section 12.9, "Accessing a Cache From an Oracle CQL User-Defined Function"

     • Section 12.10, "Accessing a Cache From an EPL User-Defined Function"

   • Optionally, access the third-party cache using JMX.

     See Section 12.11, "Accessing a Cache Using JMX".

7. When you assemble your application, verify that the META-INF/MANIFEST.MF file includes the following import as Figure 12-1 shows:

   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.

   Figure 12-3 Editing the MANIFEST.MF File

   
   Description of "Figure 12-3 Editing the MANIFEST.MF File"
   
   

12.5 Accessing a Cache From an Oracle CQL Statement

You can reference a cache from an Oracle CQL 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. Example 12-11 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:

SELECT  S1.symbol, S1.lastPrice, stockCache.description
FROM    S1 [Now], stockCache
WHERE   S1.symbol = stockCache.symbol 

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.

Example 12-12 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 CEP 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 CEP pulls the data rather than it being pushed, as is the case with a channel. This means that, continuing with Example 12-11, 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 abide by these restrictions when using a cache in an Oracle CQL query:

• You must specify the key properties for data in the cache.

  For instructions on specifying the cache key, see:

  • Section 12.2.1.1, "Specifying the Key Used to Index an Oracle CEP Local Cache"

  • Section 12.3.2.1, "Specifying the Key Used to Index an Oracle Coherence Cache"

• 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).

12.6 Accessing a Cache From an EPL Statement

You can reference a cache from an 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. 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 CEP 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:

  • Section 12.2.1.1, "Specifying the Key Used to Index an Oracle CEP Local Cache"

  • Section 12.3.2.1, "Specifying the Key Used to Index an Oracle Coherence Cache"

• 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 CEP 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.

12.7 Accessing a Cache From an Adapter

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 CEP 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) {...}
}

12.8 Accessing a Cache From a Business POJO

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 "HelloWorld Example" in the Oracle CEP Getting Started):

<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 CEP 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) {...}
}

12.9 Accessing a Cache From an Oracle CQL User-Defined Function

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 with the ref attribute:

<wlevs:processor id= "tradeProcessor">
    <wlevs:function ref="orderFunction"/>
</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 CEP 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) {...}
}

12.10 Accessing a Cache From an EPL User-Defined Function

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 CEP 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) {...}
}

12.11 Accessing a Cache Using JMX

At runtime, you can access a cache programatically using JMX and the MBeans that Oracle CEP deploys for the caching systems and caches you define.

This section describes:

• Section 12.11.1, "How to Access a Cache With JMX Using Oracle CEP Visualizer"

• Section 12.11.2, "How to Access a Cache With JMX Using Java"

For more information, "Configuring JMX for Oracle CEP" in the Oracle CEP Administrator's Guide