Configuring a Third-Party Caching System and Cache

12-28 Oracle Complex Event Processing Developers Guide 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-INFMANIFEST.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

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: Configuring Caching 12-29 Example 12–11 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 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 specify all of the key properties 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, group. The following query is invalid because although the WHERE clause specifies both key properties id and group, the query does not supply a value for one of the key properties id: select count as n from S [now], C where S.group = C.group and S.id is not null A valid query is: select count as n from S [now], C where S.group = C.group and S.id = C.id 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 sources. ■ If the cache is a processor source, you connect the cache directly to the processor on the EPN as Figure 12–3 shows. 12-30 Oracle Complex Event Processing Developers Guide ■ If the cache is a processor sink, you connect the processor to the cache using a channel as Figure 12–4 shows.

12.5.1 How to Access a Cache From an Oracle CQL Statement

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 12.2, Configuring an Oracle CEP Local Caching System and Cache ■ Section 12.3, Configuring an Oracle Coherence Caching System and Cache ■ Section 12.4, Configuring a Third-Party Caching System and Cache To access a cache from an Oracle CQL statement: 1. If you have not already done so, create the event type that corresponds to the cache data and register it in the event repository. See Chapter 2.1.4, Creating Oracle CEP Event Types .

2. Specify the key properties for the 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

3. 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. 4. In the EPN assembly file, update the configuration of the processor that executes the Oracle CQL query that references a cache: a. If the cache is a processor source: you connect the cache directly to the processor on the EPN as Figure 12–3 shows. Configuring Caching 12-31 Figure 12–3 Cache as Processor Source 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. b. 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 12–4 shows. Figure 12–4 Cache as Processor Sink 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

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