10 Configuring Oracle CQL Processors

10.2.1 How to Configure an Oracle CQL Processor Using Oracle CEP IDE for Eclipse

The most efficient and least error-prone way to create and edit a processor is to use the Oracle CEP IDE for Eclipse. Optionally, you can create and edit a processor manually (see Section 10.2.2, "How to Create an Oracle CQL Processor Component Configuration File Manually").

To configure an Oracle CQL processor using Oracle CEP IDE for Eclipse:

1. Use Oracle CEP IDE for Eclipse to create a processor.

   See Section 5.4.1.2, "How to Create a Processor Node".

   When you use the EPN editor to create an Oracle CQL processor, Oracle CEP IDE for Eclipse prompts you to choose either the default component configuration file or a new component configuration file. For more information, see Chapter 5, "Oracle CEP IDE for Eclipse and the Event Processing Network".

2. Right-click the processor node and select Go to Configuration Source.

   Oracle CEP IDE for Eclipse opens the appropriate component configuration file. The default processor component configuration is shown in Example 10-3.

   The default processor component configuration includes a name element and rules element.

   Use the rules element to group the child elements you create to contain the Oracle CQL statements this processor executes, including:

   • rule: contains Oracle CQL statements that register or create user-defined windows. The rule element id attribute must match the name of the window.

   • view: contains Oracle CQL view statements (the Oracle CQL equivalent of subqueries). The view element id attribute defines the name of the view.

   • query: contains Oracle CQL select statements. The query element id attribute defines the name of the query.

   The default processor component configuration includes a dummy query element with id Query.

   Example 10-3 Default Processor Component Configuration

   <processor>
       <name>proc</name>
       <rules>
           <query id="Query"><!-- <![CDATA[ select * from MyChannel [now] ]]> -->
           </query>
       </rules>
   </processor>
   

3. Replace the dummy query element with the rule, view, and query elements you create to contain the Oracle CQL statements this processor executes.

   For more information, see "Introduction to Oracle CQL Queries, Views, and Joins" in the Oracle CEP CQL Language Reference.

4. Select File > Save.

5. Optionally, configure additional Oracle CQL processor features in the assembly file:

   • Section 10.3, "Configuring an Oracle CQL Processor Table Source"

   • Section 10.4, "Configuring an Oracle CQL Processor Cache Source"

10.2.2 How to Create an Oracle CQL Processor Component Configuration File Manually

Although the most efficient and least error-prone way to create and edit a processor configuration is to use the Oracle CEP IDE for Eclipse (see Section 10.2.1, "How to Configure an Oracle CQL Processor Using Oracle CEP IDE for Eclipse"), alternatively, you can also create and maintain a processor configuration file manually.

This section describes the main steps to create the processor configuration file manually. 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.

To create an Oracle CQL processor component configuration file manually:

1. Design the set of Oracle CQL 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:

   SELECT *
   FROM   TradeStream [Now]
   WHERE  price > 10000
   

   Oracle CQL 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 Oracle CQL queries take another dimension into account (time), and the processor executes the Oracle CQL continually, rather than SQL queries that are static.

   For more information, see "Introduction to Oracle CQL Queries, Views, and Joins" in the Oracle CEP CQL Language Reference.

2. Create the processor configuration XML file that will contain the Oracle CQL 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 1.4, "Creating the EPN Assembly File" 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 xsi:schemaLocation="http://www.bea.com/xml/ns/wlevs/config/application  wlevs_application_config.xsd"
    xmlns:n1="http://www.bea.com/xml/ns/wlevs/config/application" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <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" ...>
     ...
   </wlevs:processor>
   <wlevs:processor id="secondProcessor" ...>
     ...
   </wlevs:processor>
   

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

   Use the rules element to group the child elements you create to contain the Oracle CQL statements this processor executes, including:

   • rule: contains Oracle CQL statements that register or create user-defined windows. The rule element id attribute must match the name of the window.

   • view: contains Oracle CQL view statements (the Oracle CQL equivalent of subqueries). The view element id attribute defines the name of the view.

   • query: contains Oracle CQL select statements. The query element id attribute defines the name of the query.

   Use the required id attribute of the view and query elements to uniquely identify each rule. Use the XML CDATA type to input the actual Oracle CQL rule. For example:

   <?xml version="1.0" encoding="UTF-8"?>
   <n1:config
       xsi:schemaLocation="http://www.bea.com/ns/wlevs/config/application wlevs_application_config.xsd"
       xmlns:n1="http://www.bea.com/ns/wlevs/config/application"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <processor>
           <name>proc</name>
           <rules>
               <view id="lastEvents" schema="cusip bid srcId bidQty"><![CDATA[ 
                   select mod(price) 
                   from filteredStream[partition by srcId, cusip rows 1]
               ]]></view>
               <query id="q1"><![CDATA[
                   SELECT *
                   FROM   lastEvents [Now]
                   WHERE  price > 10000
               ]]></query>
           </rules>
       </processor>
   </n1:config>]]></query>
   

5. Save and close the file.

6. Optionally, configure additional Oracle CQL processor features in the assembly file:

   • Section 10.3, "Configuring an Oracle CQL Processor Table Source"

   • Section 10.4, "Configuring an Oracle CQL Processor Cache Source"

10.3.1 How to Configure an Oracle CQL Processor Table Source Using Oracle CEP IDE for Eclipse

The most efficient and least error-prone way to configure an Oracle CQL processor to access a relational database table is to use the Oracle CEP IDE for Eclipse.

To configure an Oracle CQL processor table source using Oracle CEP IDE for Eclipse:

1. Create a data source for the database that contains the table you want to use.

   Example 10-5 shows an example Oracle CEP server config.xml file with data source StockDS.

   Example 10-5 Oracle CEP Server config.xml File With Data Source StockDS

   <?xml version="1.0" encoding="UTF-8"?>
   <n1:config xsi:schemaLocation="http://www.bea.com/ns/wlevs/config/server wlevs_server_config.xsd" xmlns:n1="http://www.bea.com/ns/wlevs/config/server" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <domain>
        <name>ocep_domain</name>
     </domain>
   
   ...
   
     <data-source>
       <name>StockDs</name>
       <connection-pool-params>
         <initial-capacity>1</initial-capacity>
         <max-capacity>10</max-capacity>     
       </connection-pool-params>
       <driver-params>
         <url>jdbc:derby:</url>
         <driver-name>org.apache.derby.jdbc.EmbeddedDriver</driver-name>
         <properties>
           <element>
             <name>databaseName</name>
             <value>db</value>
           </element>
           <element>
             <name>create</name>
             <value>true</value>
           </element>
         </properties>
       </driver-params>
       <!--<data-source-params>
         <jndi-names>
           <element>StockDs</element>
         </jndi-names>
         <global-transactions-protocol>None</global-transactions-protocol>
       </data-source-params>-->
     </data-source>
   
   ...
   
   </n1:config>
   

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

2. Use Oracle CEP IDE for Eclipse to create a table node.

   See Section 5.4.1.1, "How to Create a Basic Node".

3. Use Oracle CEP IDE for Eclipse to create an Oracle CQL processor.

   See Section 5.4.1.2, "How to Create a Processor Node".

4. Connect the table node to the Oracle CQL processor node.

   See Section 5.4.2.1, "How to Connect Nodes".

   The EPN Editor adds a wlevs:table-source element to the target processor node that references the source table.

5. Right-click the table node in your EPN and select Go to Assembly Source.

   Oracle CEP IDE for Eclipse opens the EPN assembly file for this table node.

6. Edit the table element as Example 10-6 shows and configure the table element attributes as shown in Table 10-1.

   Example 10-6 EPN Assembly File table Element

   <wlevs:table id="Stock" event-type="StockEvent" data-source="StockDs" />
   

   Table 10-1 EPN Assembly File table Element Attributes

   Attribute	Description
   id	The name of the table source. Subsequent references to this table source use this name.
   event-type	The type-name you specified for the table event-type you created in step 9.
   data-source	The data-source name you specified in the Oracle CEP server config.xml file in step 1.

   
   

7. Right-click the Oracle CQL processor node connected to the table in your EPN and select Go to Assembly Source.

   Oracle CEP IDE for Eclipse opens the EPN assembly file for this Oracle CQL processor.

8. Edit the Oracle CQL processor element's table-source child element as Example 10-7 shows.

   Set the ref attribute to the id of the table element you specified in step 6.

   Example 10-7 EPN Assembly File table-source Element

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

9. Edit the EPN assembly file to update the event-type-repository element with a new event-type child element for the table as Example 10-8shows.

   Create a property child element for each column of the table you want to access and configure the property attributes as shown in Table 10-2.

   Example 10-8 EPN Assembly File event-type element for a Table

   <wlevs:event-type-repository>
       ...
       <wlevs:event-type type-name="StockEvent">
           <wlevs:properties>
               <wlevs:property name="symbol" type="[C" length="16" />
               <wlevs:property name="exchange" type="[C" length="16" />
           </wlevs:properties>
       </wlevs:event-type>
       ...
   </wlevs:event-type-repository>
   

   Table 10-2 EPN Assembly File event-type Element Property Attributes

   Attribute	Description
   name	The name of the table column you want to access as specified in the SQL create table statement. You do not need to specify all columns.
   type	The Oracle CEP Java type from Table 10-3 that corresponds to the column's SQL data type. In Example 10-4, the type value for column symbol is [C.
   length	The column size as specified in the SQL create table statement. In Example 10-4, the length of column symbol is 16.

   
   

   Table 10-3 SQL Column Types and Oracle CEP Type Equivalents

   SQL Type	Oracle CEP Java Type	com.bea.wlevs.ede.api.Type	Description
   ARRAY	[Ljava.lang.Object		Array, of depth 1, of java.lang.Object.
   BIGINT	java.math.BigInteger	bigint	An instance of java.math.BigInteger.
   BINARY	[B		Array, of depth 1, of byte.
   BIT	java.lang.Boolean	boolean	An instance of java.lang.Boolean.
   BLOB	[B		Array, of depth 1, of byte.
   BOOLEAN	java.lang.Boolean	boolean	An instance of java.lang.Boolean.
   CHAR	java.lang.Character	char	An instance of java.lang.Character.
   CLOB	[B		Array, of depth 1, of byte.
   DATE	java.sql.Date	timestamp	An instance of java.sql.Date.
   DECIMAL	java.math.BigDecimal		An instance of java.math.BigDecimal.
   DOUBLE	java.lang.Double	double	An instance of java.lang.Double
   FLOAT	java.lang.Double	float	An instance of java.lang.Double
   INTEGER	java.lang.Integer	int	An instance of java.lang.Integer.
   JAVA_OBJECT	java.lang.Object	object	An instance of java.lang.Object.
   LONGNVARCHAR	[C	char	Array, of depth 1, of char.
   LONGVARBINARY	[B		Array, of depth 1, of byte.
   LONGVARCHAR	[C	char	Array, of depth 1, of char.
   NCHAR	[C	char	Array, of depth 1, of char.
   NCLOB	[B		Array, of depth 1, of byte.
   NUMERIC	java.math.BigDecimal		An instance of java.math.BigDecimal.
   NVARCHAR	[C	char	Array, of depth 1, of char.
   OTHER	java.lang.Object	object	An instance of java.lang.Object.
   REAL	java.lang.Float	float	An instance of java.lang.Float
   SMALLINT	java.lang.Integer	int	An instance of java.lang.Integer.
   SQLXML	xmltype	xmltype	For more information on processing XMLTYPE data in Oracle CQL, see "SQL/XML (SQLX)" in the Oracle CEP CQL Language Reference.
   TIME	java.sql.Time		An instance of java.sql.Time.
   TIMESTAMP	java.sql.Timestamp	timestamp	An instance of java.sql.Timestamp.
   TINYINT	java.lang.Integer	int	An instance of java.lang.Integer.
   VARBINARY	[B		Array, of depth 1, of byte.
   VARCHAR	[C	char	Array, of depth 1, of char.

   
   

   For more information on creating event types, see:

   • Section 1.1.2, "Event Types"

   • Section 1.1.2.2, "Event Type Data Types"

   • Section 1.5, "Creating Oracle CEP Event Types".

10. Edit the EPN assembly file to add Oracle CQL queries that use the table's event-type as shown in Example 10-9.

    Example 10-9 Oracle CQL Query Using Table Event Type StockEvent

    <processor>
        <name>proc</name>
        <rules>
            <query id="q1"><![CDATA[
                SELECT  ExchangeStream.symbol, ExchangeStream.price, Stock.exchange
                FROM    ExchangeStream [Now], Stock
                WHERE   ExchangeStream.symbol = Stock.symbol 
            ]]></query>
        </rules>
    </processor>
    

10.5.1 Oracle CQL Processor Component Configuration File

The following example shows a component configuration file for an Oracle CQL processor.

<?xml version="1.0" encoding="UTF-8"?>
<n1:config
    xsi:schemaLocation="http://www.bea.com/ns/wlevs/config/application wlevs_application_config.xsd"
    xmlns:n1="http://www.bea.com/ns/wlevs/config/application"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <processor>
        <name>proc</name>
        <rules>
            <view id="lastEvents" schema="cusip bid srcId bidQty ask askQty seq"><![CDATA[ 
                select mod(price) 
                from filteredStream[partition by srcId, cusip rows 1]
            ]]></view>
            <query id="q1"><![CDATA[
                SELECT *
                FROM   lastEvents [Now]
                WHERE  price > 10000
            ]]></query>
        </rules>
    </processor>
</n1:config>

In the example, the name element specifies that the processor for which the Oracle CQL rules are being configured is called proc. This in turn implies that the EPN assembly file that defines your application must include a corresponding wlevs:processor element with an id attribute value of proc to link these Oracle CQL rules with an actual proc processor instance (see Section 10.5.2, "Oracle CQL Processor EPN Assembly File").

This Oracle CQL processor component configuration file also defines a view element to specify an Oracle CQL view statement (the Oracle CQL equivalent of a subquery). The results of the view's select are not output to a down-stream channel.

Finally, this Oracle CQL processor component configuration file defines a query element to specify an Oracle CQL query statement. The query statement selects from the view. By default, the results of a query are output to a down-stream channel. You can control this behavior in the channel configuration using a selector element. For more information, see:

• Section 9.2.1, "How to Configure a System-Timestamped Channel Using Oracle CEP IDE for Eclipse"

• Section 9.2.2, "How to Configure an Application-Timestamped Channel Using Oracle CEP IDE for Eclipse"

10.5.2 Oracle CQL Processor EPN Assembly File

The following example shows an EPN assembly file for an Oracle CQL 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_0_0_0.xsd">

    <wlevs:event-type-repository>
        <wlevs:event-type type-name="ExchangeEvent">
            <wlevs:properties>
                <wlevs:property name="symbol" type="[C" length="16" />
                <wlevs:property name="price" type="java.lang.Double" />
            </wlevs:properties>
        </wlevs:event-type>
        <wlevs:event-type type-name="StockExchangeEvent">
            <wlevs:properties>
                <wlevs:property name="symbol" type="[C" length="16" />
                <wlevs:property name="price" type="java.lang.Double" />
                <wlevs:property name="exchange" type="[C" length="16" />
            </wlevs:properties>
        </wlevs:event-type>
        <wlevs:event-type type-name="StockEvent">
            <wlevs:properties>
                <wlevs:property name="symbol" type="[C" length="16" />
                <wlevs:property name="exchange" type="[C" length="16" />
            </wlevs:properties>
        </wlevs:event-type>
    </wlevs:event-type-repository>

    <!-- Assemble EPN (event processing network) -->
    <wlevs:adapter id="adapter" class="com.bea.wlevs.example.db.ExchangeAdapter" >
        <wlevs:listener ref="ExchangeStream"/>
    </wlevs:adapter>

    <wlevs:channel id="ExchangeStream" event-type="ExchangeEvent" >
        <wlevs:listener ref="proc"/>
    </wlevs:channel>

    <wlevs:table id="Stock" event-type="StockEvent" data-source="StockDs" />

    <wlevs:processor id="proc" advertise="true" >
        <wlevs:table-source ref="Stock" />
    </wlevs:processor>

    <wlevs:channel id="OutputStream" advertise="true" event-type="StockExchangeEvent" >
        <wlevs:listener ref="bean"/>
        <wlevs:source ref="proc"/>
    </wlevs:channel>

    <osgi:reference id="ds" interface="com.bea.core.datasource.DataSourceService" cardinality="0..1" />

    <!-- Create business object -->
    <bean id="bean" class="com.bea.wlevs.example.db.OutputBean">
        <property name="dataSourceService" ref="ds"/>
    </bean>

</beans>