11 Configuring EPL Processors

This section contains information on the following subjects:

Note:

Oracle CQL replaces Event Processing Language (EPL) in Oracle CEP 11g Release 1 (11.1.1). Oracle CEP supports EPL for backwards compatibility. For more information, see Chapter 10, "Configuring Oracle CQL Processors".

11.1 Overview of EPL Processor Component Configuration

An Oracle CEP application contains one or more complex event processors, or processors for short. Each processor takes as input events from one or more adapters; these adapters in turn listen to data feeds that send a continuous stream of data from a source. The source could be anything, from a financial data feed to the Oracle CEP load generator.

The main feature of an EPL processor is its associated Event Processing Language (EPL) rules that select a subset of the incoming events to then pass on to the component that is listening to the processor. The listening component could be another processor, or the business object POJO that typically defines the end of the event processing network, and thus does something with the events, such as publish them to a client application. For more information about EPL, see the Oracle Complex Event Processing EPL Language Reference.

For each EPL processor in your application, you must create a processor element in a component configuration file. In this processor element you specify the initial set of EPL rules of the processor and any optional processor configuration such as:

  • JDBC datasource reference if your Oracle CEP application requires a connection to a relational database.

  • Enable monitoring of the processor.

You can configure additional optional EPL processor features in the EPL processor EPN assembly file.

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

Example 11-1 EPN Assembly File EPL Processor Id: proc

<wlevs:processor id="proc" provider="epl" >
    <wlevs:table-source ref="Stock" />
</wlevs:processor>

Example 11-2 Component Configuration File EPL Processor Name: proc

<processor>
    <name>proc</name>
    <rules>
        <rule id="myRule"><![CDATA[
            SELECT symbol, AVG(price) 
            FROM (SELECT * FROM MarketTrade WHERE blockSize > 10)
            RETAIN 100 EVENTS PARTITION BY symbol WITH LARGEST price
            GROUP BY symbol
            HAVING AVG(price) >= 100
            ORDER BY symbol
        ]]></rule>
    </rules>
</procesor>

Note:

Because Oracle CQL replaces Event Processing Language (EPL) in Oracle CEP 11g Release 1 (11.1.1), the default processor provider is cql. To specify an EPL processor, in the EPN assembly file, you must set the wlevs:processor element provider attribute to epl as Example 11-1 shows. Oracle CEP supports EPL for backwards compatibility. For more information, see Chapter 10, "Configuring Oracle CQL Processors".

You can create a processor 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 processor, you can create a processor 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 processors, 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 create an EPL processor using Oracle CEP IDE for Eclipse, by default, the processor element is added to the default component configuration file META-INF/wlevs/config.xml 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:

For more information on EPL processor configuration, see:

11.2 Configuring an EPL Processor

This section describes the main steps to create the processor configuration file. For simplicity, it is assumed in the procedure that you are going to configure all processors in a single XML file, although you can also create separate files for each processor.

See Section B.2, "Component Configuration Schema wlevs_application_config.xsd" for the complete XSD Schema that describes the processor configuration file.

See Section 11.4, "Example EPL Processor Configuration Files" for a complete example of a processor configuration file.

11.2.1 How to Configure an EPL Processor Manually

You can configure an EPL processor manually using your preferred text editor.

To configure an EPL processor:

  1. Design the set of EPL rules that the processor executes. These rules can be as simple as selecting all incoming events to restricting the set based on time, property values, and so on, as shown in the following two examples:

    SELECT * from Withdrawal RETAIN ALL
    SELECT symbol, AVG(price) 
    FROM (SELECT * FROM MarketTrade WHERE blockSize > 10)
    RETAIN 100 EVENTS PARTITION BY symbol WITH LARGEST price
    GROUP BY symbol
    HAVING AVG(price) >= 100
    ORDER BY symbol
    

    EPL is similar in many ways to Structure Query Language (SQL), the language used to query relational database tables, although the syntax between the two differs in many ways. The other big difference is that EPL queries take another dimension into account (time), and the processor executes the EPL continually, rather than SQL queries that are static.

    For additional conceptual information about EPL, and examples and reference information to help you design and write your own EPL rules, see Oracle Complex Event Processing EPL Language Reference.

  2. Create the processor configuration XML file that will contain the EPL rules you designed in the preceding step, as well as other optional features, for each processor in your application.

    You can name this XML file anything you want, provided it ends with the .xml extension.

    The root element of the processor configuration file is config, with namespace definitions shown in the next step.

  3. For each processor in your application, add a processor child element of config.

    Uniquely identify each processor with the name child element. This name must be the same as the value of the id attribute in the wlevs:processor element of the EPN assembly file that defines the event processing network of your application. This is how Oracle CEP knows to which particular processor component in the EPN assembly file this processor configuration applies. See Section 4.3, "Creating EPN Assembly Files" for details.

    For example, if your application has two processors, the configuration file might initially look like:

    <?xml version="1.0" encoding="UTF-8"?>
    <n1:config xmlns:n1="http://www.bea.com/ns/wlevs/config/application">
      <processor>
        <name>firstProcessor</name>
         ...
      </processor>
      <processor>
        <name>secondProcessor</name>
         ...
       </processor>
    </n1:config>
    

    In the example, the configuration file includes two processors called firstProcessor and secondProcessor. This means that the EPN assembly file must include at least two processor registrations with the same identifiers:

    <wlevs:processor id="firstProcessor" provider="epl"...>
      ...
    </wlevs:processor>
    <wlevs:processor id="secondProcessor" provider="epl"...>
      ...
    </wlevs:processor>
    

    Note:

    Because Oracle CQL replaces Event Processing Language (EPL) in Oracle CEP 11g Release 1 (11.1.1), the default processor provider is cql. To specify an EPL processor, in the EPN assembly file, you must set the wlevs:processor element provider attribute to epl. Oracle CEP supports EPL for backwards compatibility. For more information, see Chapter 10, "Configuring Oracle CQL Processors".

    Caution:

    Identifiers and names in XML files are case sensitive, so be sure you specify the same case when referencing the component's identifier in the EPN assembly file.
  4. Add a rules child element to each processor to group together one or more rule elements that correspond to the set of EPL rules you have designed for this processor.

    Use the required id attribute of the rule element to uniquely identify each rule. Use the XML CDATA type to input the actual EPL rule. For example:

    <processor>
        <name>firstProcessor</name>
        <rules>
          <rule id="myFirstRule"><![CDATA[
          SELECT * from Withdrawal RETAIN ALL
          ]]></rule>
          <rule id="mySecondRule"><![CDATA[
          SELECT * from Checking RETAIN ALL
          ]]></rule>
        </rules>
    </processor>
    
  5. Optionally, override the default processor configuration by adding additional processor child elements:

    • Optionally add a database child element of the processor element to define a JDBC data source for your application. This is required if your EPL rules join a stream of events with an actual relational database table.

      Use the name child element of database to uniquely identify the datasource.

      Use the data-source-name child element of database to specify the actual name of the data source; this name corresponds to the name child element of the data-source configuration object in the config.xml file of your domain.

      For more information, see "Configuring Access to a Relational Database" in the Oracle Complex Event Processing Administrator's Guide.

      For example:

      <processor>
          <name>firstProcessor</name>
          <rules>
          ....
          </rules>
          <database>
            <name>myDataSource</name>
            <data-source-name>rdbmsDataSource</data-source-name>
          </database>
      </processor>
      
  6. Save and close the file.

  7. Optionally, configure additional EPL processor features in the assembly file:

11.3 Configuring an EPL Processor Cache Source

You can configure an EPL processor to access the Oracle CEP cache.

For more information, see:

11.4 Example EPL Processor Configuration Files

This section provides example Oracle CQL processor configuration files, including:

11.4.1 EPL Processor Component Configuration File

The following example shows how to configure one of the sample EPL queries shown in Section 11.2, "Configuring an EPL Processor" for the myProcessor EPL processor:

<?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>
        <name>myProcessor</name>
        <rules>
            <rule id="myRule"><![CDATA[
                SELECT symbol, AVG(price) 
                FROM (SELECT * FROM MarketTrade WHERE blockSize > 10)
                RETAIN 100 EVENTS PARTITION BY symbol WITH LARGEST price
                GROUP BY symbol
                HAVING AVG(price) >= 100
                ORDER BY symbol
            ]]></rule>
        </rules>
    </processor>
</n1:config>

In the example, the name element specifies that the processor for which the single EPL rule is being configured is called myProcessor. This in turn implies that the EPN assembly file that defines your application must include a corresponding <wlevs:processor id="myProcessor" provider="epl" /> element to link these EPL rules with an actual myProcessor EPL processor instance (see Section 11.4.2, "EPL Processor EPN Assembly File").

11.4.2 EPL Processor EPN Assembly File

The following example shows an EPN assembly file for an EPL processor.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:osgi="http://www.springframework.org/schema/osgi"
      xmlns:wlevs="http://www.bea.com/ns/wlevs/spring"
      xsi:schemaLocation="
          http://www.springframework.org/schema/beans
          http://www.springframework.org/schema/beans/spring-beans.xsd
          http://www.springframework.org/schema/osgi
          http://www.springframework.org/schema/osgi/spring-osgi.xsd
          http://www.bea.com/ns/wlevs/spring
          http://www.bea.com/ns/wlevs/spring/spring-wlevs-v11_1_1_3.xsd">
    <wlevs:event-type-repository>
        <wlevs:event-type type-name="HelloWorldEvent">
            <wlevs:class>com.bea.wlevs.event.example.helloworld.HelloWorldEvent</wlevs:class>
        </wlevs:event-type>
    </wlevs:event-type-repository>
    <wlevs:adapter 
        id="helloworldAdapter"
        class="com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapter">
        <wlevs:instance-property name="message" value="HelloWorld - the current time is:"/>
    </wlevs:adapter>
    <wlevs:channel id="helloworldInputChannel" event-type="HelloWorldEvent">
        <wlevs:listener ref="helloworldProcessor"/>
        <wlevs:source ref="helloworldAdapter"/>
    </wlevs:channel>
    <wlevs:processor id="helloworldProcessor" provider="epl" />
    <wlevs:channel 
        id="helloworldOutputChannel" event-type="HelloWorldEvent" advertise="true">
        <wlevs:listener>
            <bean class="com.bea.wlevs.example.helloworld.HelloWorldBean"/>
        </wlevs:listener>
        <wlevs:source ref="helloworldProcessor"/>
    </wlevs:channel>
</beans>