2 Overview of Oracle CEP Events

This chapter introduces developing event types, essential parts of Oracle Complex Event Processing (Oracle CEP) event processing networks. Event types can be developed as JavaBeans, tuples, Java classes, and Java Map instances.

2.1 Oracle CEP Event Types

Event types define the properties of the events that are handled by Oracle CEP applications. Adapters receive incoming events from different event sources, such as the Java Messaging System (JMS), or financial market data feeds. You must define an Oracle CEP event type for these events before a processor is able to handle them. You then use these event types in adapter and POJO Java code, and in the Oracle CQL and EPL rules you associate with the processors.

Events are JavaBean or Java class instances in which each property represents a data item from the event source. Oracle CEP supports the following event type implementations:

Oracle recommends that you define your events using the JavaBean (or Java class and factory) approach. Doing so allows you greater flexibility to deal with event types as part of your application logic and can simplify integration with existing systems.

Alternatively, you can specify the properties of the event type declaratively in the EPN assembly file using wlevs:property tags, in which case Oracle CEP will use a java.util.Map or tuple. Tuple is the default and is similar to the Oracle CQL tuple. It essentially provides the user with an optimized implementation, however, the user must always set and get its value using the EventTypeRepository APIs. This approach is best used for quick prototyping or when the application developer does not need to deal with JavaBean events as part of the application logic or due to integration to some legacy system.

For more information, see:

2.1.1 Event Type Instantiation and Immutability

In Oracle CEP, events are conceptually immutable. Once an event is instantiated (created and initialized), the Oracle CEP server will not change it and application developers should not change it, either.

In Oracle CEP, an event can be instantiated either by the application developer or by the Oracle CEP server. For example:

  • An application developer can instantiate an event in an inbound Spring-bean, event-bean, or adapter.

  • Oracle CEP server can instantiate an event when a CQL processor outputs an event to a downstream component.

The Oracle CEP server uses the following procedure to instantiate an event for a JavaBean event type:

  • It invokes an empty-argument public constructor for the Java class.

  • It invokes a public setter method following JavaBean conventions for each event property.

Note that even though the event is conceptually immutable, setter methods must be available in this case. The Oracle CEP server will invoke these setter methods only once during event initialization.

If a JavaBean event is only being created by the application developer, then making the Java class immutable can help improve performance. A truly immutable bean is read only (provides only getters) and has public constructors with arguments that satisfy immutability. Note that immutability is not possible if the event is being output from a CQL processor, but it is possible if the event is used only as input.

The Oracle CEP server uses the following procedure to instantiate an event for a Java class event type:

  • It acquires an instance of the com.bea.wlevs.ede.api.EventBuilder.Factory you associate with the event type by calling the factory's createBuilder method.

  • It instantiates an event by calling the createEvent method.

Note that again, even though the event is conceptually immutable, setter methods must be available in this case. And, again, the Oracle CEP server will invoke these setter methods only once, indirectly, when the factory initializes the event.

2.1.2 Event Type and Serialization

In general, Oracle CEP events need not be serializable.

However, if you are caching events in Oracle Coherence, then events must be serializable.

2.1.3 Event Type Data Types

When creating event types, observe the following data type restrictions:

For more information, see:

2.1.3.1 Event Types Specified as JavaBean or Java Class

When you define an event type as a JavaBean or Java class, you may use any Java type for its properties.

Using the Oracle Java data cartridge, you may also combine JavaBean or Java class event types with other events types. Example 2-1 shows a tuple event type Student that defines its address property as Java class event type Address.

Example 2-1 Event Type Repository

<event-type-repository>
    <event-type name="Student">
        <property name="name" type="char"/>
        <property name="address" type="Address"/>
    </event-type>

    <event-type name="Address">
        <class-name>test.Address</class-name>
    </event-type>
<event-type-repository>

For more information, see

2.1.3.2 Event Types Specified as java.util.Map

When you specify the event type properties declaratively in the EPN assembly file as a java.util.Map, you may use any Java type for its properties. However, you specify the "type" of the event properties as either:

  • The fully qualified name of a Java class that must conform to the same rules as Class.forName() and must be available in the application's class loader.

  • A Java primitive (for example, int or float).

You may specify an array by appending the characters [] to the event type name.

Example 2-2 shows how to use these types:

Example 2-2 Specifying Java Data Types for java.util.Map Event Type Properties

<wlevs:event-type-repository>
    <wlevs:event-type type-name="AnotherEvent">
        <wlevs:properties type="map">
          <wlevs:property>
             <entry key="name" value="java.lang.String"/>
             <entry key="employeeId" value="java.lang.Integer[]"/>
             <entry key="salary" value="float"/>
             <entry key="projectIds" value="short[]"/>
          </wlevs:property>
        <wlevs:properties>
    </wlevs:event-type>
</wlevs:event-type-repository>

For more information, see Section 2.5.1, "How to Create an Oracle CEP Event Type as a java.util.Map".

2.1.3.3 Event Types Specified as a Tuple

When you specify the properties of the event type declaratively in the EPN assembly file as a tuple, you may use any CQL primitive types or Java types.

Example 2-3 shows the use of different types:

Example 2-3 Specifying com.bea.welvs.ede.api.Type Data Types for Tuple Event Type Properties

<wlevs:event-type-repository>
        <wlevs:event-type type-name="SimpleEvent">
            <wlevs:properties>
                <wlevs:property name="id" type="char" length="1000" />
                <wlevs:property name="msg" type="char" />
                <wlevs:property name="count" type="double" />
                <wlevs:property name="time_stamp" type="timestamp" />
        </wlevs:properties>
    </wlevs:event-type>
...
</wlevs:event-type-repository>

For more information, see Section 2.3, "Creating an Oracle CEP Event Type as a Tuple".

2.1.3.4 Event Types for use With a Database Table Source

When you specify the properties of an event type (as any of a JavaBean, Java class, java.util.Map, or tuple) for use with a relational database table, you must observe the following additional JDBC type restrictions:

For more information, see:

2.1.3.5 Event Types for use With the csvgen Adapter

When you specify the properties of an event type (as any of a JavaBean, Java class, java.util.Map, or tuple) for use with the csvgen adapter, you may only use the data types that Table 2-1 describes.

Table 2-1 csvgen Adapter Types

Type Usage

char

Single or multiple character values. Use for both char and java.lang.String values.

Optionally, you may used the length attribute to specify the maximum length of the char value as Example 2-3 shows for the property with name id. The default length is 256 characters. If you need more than 256 characters you should specify an adequate length.

int

Numeric values in the range that java.lang.Integer specifies.

long

Numeric values in the range that java.lang.Long specifies.

double

Numeric values in the range that java.lang.Double specifies.

For more information, see:

2.1.4 Creating Oracle CEP Event Types

Event types define the properties of the events that are handled by Oracle CEP applications. Adapters receive incoming events from different event sources, such as JMS, or financial market data feeds. You must define these events by an event type before a processor is able to handle them. You then use these event types in the adapter and POJO Java code, as well as in the Oracle CQL and EPL rules you associate with the processors.

This section describes:

For more information, see Section 2.1, "Oracle CEP Event Types".

2.2 Creating an Oracle CEP Event Type as a JavaBean

Creating an event type as a JavaBean gives you the greatest level of flexibility when using instance of the type in your application logic. As a result, using a JavaBean class is the best practice for creating an event type.

Note:

Oracle CQL does not support expressions in GROUP BY, PARTITION BY, and ORDER BY. As a result, these do not support Java properties and will fail. When those features are needed, use Oracle CQL views as a workaround.

Part of the flexibility in using a JavaBean event type comes from the two different ways to have the type instantiated: by the server or by an event type builder class that you provide. By providing an event type builder class as an instance factory, you can create the instance yourself, controlling how they are created, including how event data values are bound to JavaBean properties. For more information, see Section 2.6, "Using an Event Type Builder Factory".

When creating an event type as a JavaBean class, use the following guidelines to ensure the best integration with the Oracle CEP system:

  • Create an empty-argument public constructor with which the Oracle CEP server can instantiate the class.

  • For each event property, implement public accessors (get and set methods) following JavaBean conventions. These will be used by the server to access event property values. When you design your event, you must restrict your design to the event data types that Section 2.1.3.1, "Event Types Specified as JavaBean or Java Class" describes.

    If you're unfamiliar with JavaBeans conventions, see the JavaBeans Tutorial at http://java.sun.com/docs/books/tutorial/javabeans/ for additional details.

  • Implement the hashCode and equals methods. This optimizes the class for use by the Oracle CEP server, which sometimes uses a hash index whose composite key is created from the event type instance hash codes.

    If you're using the Eclipse IDE, you can easily implement hashCode and equals methods through the Source context menu for a class after you have added its accessors.

  • Make the class serializable if you intend to cache events in Oracle Coherence.

This topic describes:

2.2.1 Accessing Event Type Property Values

With event types created as Java classes, Oracle CQL code can get property values by using standard JavaBeans-style property access or as a regular Java class.

The following configuration snippet declares a StudentType event type that's a JavaBean class.

<event-type-repository>
    <event-type name="StudentType">
        <class-name>school.Student</class-name>
    </event-type>
</event-type-repository>

The school.Student class is a JavaBean with an address property that is itself an Address JavaBean class. The following query suggests how you might access values of the Address object underlying the address property. This query selects student addresses whose postal code begins with "97".

<query id="studentAddresses">
    SELECT
        student.address
    FROM
        StudentType as student
    WHERE
        student.address.postalCode LIKE '^97'
</query>

2.2.1.1 Limitations

Oracle CQL does not support expressions in GROUP BY, PARTITION BY, and ORDER BY. As a result, these do not support Java properties and will fail. In these cases, use views instead.

2.2.2 How to Create an Oracle CEP Event Type as a JavaBean Using the Event Type Repository Editor

This procedure describes how to create and register an Oracle CEP event type as a JavaBean using the Oracle CEP IDE for Eclipse event type repository editor. For more information about the Oracle CEP IDE for Eclipse, see Example 3-0, "Overview of the Oracle CEP IDE for Eclipse".

Alternatively, you can create and register your event type as a JavaBean manually (see Section 2.2.3, "How to Create an Oracle CEP Event Type as a JavaBean Manually").

To create an Oracle CEP event type as a Java Bean using the event type repository editor:

  1. Create a JavaBean class to represent your event type.

    Follow standard JavaBeans programming guidelines. See the JavaBeans Tutorial at http://java.sun.com/docs/books/tutorial/javabeans/ for additional details.

    Oracle recommends that, if possible, you make your event type JavaBeans immutable to improve performance. For more information, see Section 2.1.1, "Event Type Instantiation and Immutability".

    When you design your event, you must restrict your design to the even data types that Section 2.1.3.1, "Event Types Specified as JavaBean or Java Class" describes.

    Example 2-5 shows the MarketEvent which is implemented by the com.bea.wlevs.example.algotrading.event.MarketEvent class.

    Example 2-4 MarketEvent Class

    package com.bea.wlevs.example.algotrading.event;
 
import java.util.Date;
 
public final class MarketEvent {
    private final Long timestamp;
 
    private final String symbol;
 
    private final Double price;
 
    private final Long volume;
 
    private final Long latencyTimestamp;
 
    public MarketEvent(final Long timestamp, final String symbol,
            final Double price, final Long volume, final Long latencyTimestamp) {
        this.timestamp = timestamp;
        this.symbol = symbol;
        this.price = price;
        this.volume = volume;
        this.latencyTimestamp = latencyTimestamp;
    }
 
    public Double getPrice() {
        return price;
    }
 
    public String getSymbol() {
        return symbol;
    }
 
    public Long getTimestamp() {
        return timestamp;
    }
 
    public Long getLatencyTimestamp() {
        return latencyTimestamp;
    }
 
    public Long getVolume() {
        return volume;
    }
 
}

  2. Compile the JavaBean that represents your event type.

  3. Open the EPN in the Oracle CEP IDE for Eclipse.

    The EPN editor opens as Figure 2-1 shows.

    Figure 2-1 EPN Editor

    Description of Figure 2-1 follows
    Description of "Figure 2-1 EPN Editor"

    For more information, see Section 6.1, "Opening the EPN Editor".

  4. Click the Event Types tab.

    The Event Type tab appears as Figure 2-2 shows.

    Figure 2-2 Event Type Repository Editor

    Description of Figure 2-2 follows
    Description of "Figure 2-2 Event Type Repository Editor"

  5. Click Add Event Type (green plus sign).

    A new event is added to the Event Type Definitions list with default name newEvent as Figure 2-3 shows.

    Figure 2-3 Event Type Repository Editor - JavaBean Event

    Description of Figure 2-3 follows
    Description of "Figure 2-3 Event Type Repository Editor - JavaBean Event"

  6. In the Event Type Definitions list, select newEvent.

    The properties of this event appear in the Event Type Details area as Figure 2-3 shows.

  7. Enter a name for this event in the Type name field.

  8. Click Properties defined in Java bean.

  9. Enter the fully qualified class name of your JavaBean class in the Class field.

    For example com.bea.wlevs.example.algotrading.event.MarketEvent.

  10. Click the Save button in the Eclipse tool bar (or type CTRL-S).

    The event is now in the event type repository.

    You can use the event type repository editor:

    1. To view the corresponding event type definition in the EPN assembly file, double-click the event type in the Event Type Definitions area.

    2. To delete this event, select the event type in the Event Type Definitions area and click Delete Event Type (red x).

  11. Use the event type:

    • Reference the event types as standard JavaBeans in the Java code of the adapters and business logic POJO in your application.

      public void onEvent(List newEvents)
        throws RejectEventException {
    for (Object event : newEvents) {
            MarketEvent marketEvent = (MarketEvent) event;
        System.out.println("Price: " + marketEvent.getPrice());
    }
}

    • Access the event types from Oracle CQL and EPL rules:

      The following Oracle CQL rule shows how you can reference the MarketEvent in a SELECT statement:

      <query id="helloworldRule">
    <![CDATA[ select MarketEvent.price from marketEventChannel [Now] ]]>
</query>

2.2.3 How to Create an Oracle CEP Event Type as a JavaBean Manually

This procedure describes how to create and register an Oracle CEP event type as a JavaBean manually.

Alternatively, you can create and register your event type as a JavaBean using the Oracle CEP IDE for Eclipse event type repository editor (see Section 2.2.2, "How to Create an Oracle CEP Event Type as a JavaBean Using the Event Type Repository Editor").

To create an Oracle CEP event type as a Java bean manually:

  1. Create a JavaBean class to represent your event type.

    Follow standard JavaBeans programming guidelines. See the JavaBeans Tutorial at http://java.sun.com/docs/books/tutorial/javabeans/ for additional details.

    Oracle recommends that, if possible, you make your event type JavaBeans immutable to improve performance. For more information, see Section 2.1.1, "Event Type Instantiation and Immutability".

    When you design your event, you must restrict your design to the even data types that Section 2.1.3.1, "Event Types Specified as JavaBean or Java Class" describes.

    Example 2-5 shows the MarketEvent which is implemented by the com.bea.wlevs.example.algotrading.event.MarketEvent class.

    Example 2-5 MarketEvent Class

    package com.bea.wlevs.example.algotrading.event;
 
import java.util.Date;
 
public final class MarketEvent {
    private final Long timestamp;
 
    private final String symbol;
 
    private final Double price;
 
    private final Long volume;
 
    private final Long latencyTimestamp;
 
    public MarketEvent(final Long timestamp, final String symbol,
            final Double price, final Long volume, final Long latencyTimestamp) {
        this.timestamp = timestamp;
        this.symbol = symbol;
        this.price = price;
        this.volume = volume;
        this.latencyTimestamp = latencyTimestamp;
    }
 
    public Double getPrice() {
        return price;
    }
 
    public String getSymbol() {
        return symbol;
    }
 
    public Long getTimestamp() {
        return timestamp;
    }
 
    public Long getLatencyTimestamp() {
        return latencyTimestamp;
    }
 
    public Long getVolume() {
        return volume;
    }
 
}

  2. Compile the JavaBean that represents your event type.

  3. Register your JavaBean event type in the Oracle CEP event type repository:

    1. To register declaratively, edit the EPN assembly file using the wlevs:event-type-repository element wlevs:event-type child element as Example 2-6 shows.

      Example 2-6 EPN Assembly File event-type-repository

      <wlevs:event-type-repository>
    <wlevs:event-type type-name="MarketEvent">
      <wlevs:class>
          com.bea.wlevs.example.algotrading.event.MarketEvent
      </wlevs:class>
    </wlevs:event-type>
</wlevs:event-type-repository>

    2. To register programmatically, use the EventTypeRepository class as Example 2-7 shows.

      Example 2-7 Programmatically Registering an Event

      EventTypeRepository rep = getEventTypeRepository();
rep.registerEventType(
    "MarketEvent", 
    com.bea.wlevs.example.algotrading.event.MarketEvent.getClass()
);

      For more information, see Section 2.7, "Accessing the Event Type Repository".

  4. Use the event type:

    • Reference the event types as standard JavaBeans in the Java code of the adapters and business logic POJO in your application.

      public void onEvent(List newEvents)
        throws RejectEventException {
    for (Object event : newEvents) {
            MarketEvent marketEvent = (MarketEvent) event;
        System.out.println("Price: " + marketEvent.getPrice());
    }
}

    • Access the event types from Oracle CQL and EPL rules:

      The following Oracle CQL rule shows how you can reference the MarketEvent in a SELECT statement:

      <query id="helloworldRule">
    <![CDATA[ select MarketEvent.price from marketEventChannel [Now] ]]>
</query>

2.3 Creating an Oracle CEP Event Type as a Tuple

You can create and register an Oracle CEP event type as a tuple.

When you design your event, you must restrict your design to the even data types that Section 2.1.3.3, "Event Types Specified as a Tuple" describes.

This topic describes:

2.3.1 How to Create an Oracle CEP Event Type as a Tuple Using the Event Type Repository Editor

This procedure describes how to create and register an Oracle CEP event type as a tuple using the Oracle CEP IDE for Eclipse event type repository editor. For more information about the Oracle CEP IDE for Eclipse, see Example 3-0, "Overview of the Oracle CEP IDE for Eclipse".

Alternatively, you can create and register your event type as a tuple manually (see Section 2.3.2, "How to Create an Oracle CEP Event Type as a Tuple Manually").

To create an Oracle CEP event type as a tuple using the event type repository editor:

  1. Decide on the properties your event type requires.

    When you design your event, you must restrict your design to the even data types that Section 2.1.3.3, "Event Types Specified as a Tuple" describes.

  2. Open the EPN in the Oracle CEP IDE for Eclipse.

    The EPN editor opens as Figure 2-4 shows.

    Figure 2-4 EPN Editor

    Description of Figure 2-4 follows
    Description of "Figure 2-4 EPN Editor"

    For more information, see Section 6.1, "Opening the EPN Editor".

  3. Click the Event Type tab.

    The Event Type tab appears as Figure 2-5 shows.

    Figure 2-5 Event Type Repository Editor

    Description of Figure 2-5 follows
    Description of "Figure 2-5 Event Type Repository Editor"

  4. Click Add Event Type (green plus sign).

    A new event is added to the Event Type Definitions list with default name newEvent as Figure 2-6 shows.

    Figure 2-6 Event Type Repository Editor - Tuple Event

    Description of Figure 2-6 follows
    Description of "Figure 2-6 Event Type Repository Editor - Tuple Event"

  5. In the Event Type Definitions list, select newEvent.

    The properties of this event appear in the Event Type Details area as Figure 2-6 shows.

  6. Enter a name for this event in the Type name field.

  7. Click Properties defined declaratively.

  8. Add one or more event properties:

    • Click Add Event Property (green plus sign).

      A new row is added to the Event Type Details table.

    • Click in the Name column of this row and enter a property name.

    • Click in the Type column of this row and select a data type from the pull down menu.

      When you design your event, you must restrict your design to the even data types that Section 2.1.3.3, "Event Types Specified as a Tuple" describes.

    • For char data type properties only, click in the 'char' Length column of this row and enter a value for the maximum length of this char property.

      Optionally, you may used the length attribute to specify the maximum length of the char value. The default length is 256 characters. The maximum length is java.lang.Integer.MAX_VALUE. If you need more than 256 characters you should specify an adequate length.

  9. Click the Save button in the Eclipse tool bar (or type CTRL-S).

    The event is now in the event type repository.

    You can use the event type repository editor:

    1. To view the corresponding event type definition in the EPN assembly file, double-click the event type in the Event Type Definitions area.

    2. To delete this event, select the event type in the Event Type Definitions area and click Delete Event Type (red x).

  10. Use the event type:

    • Reference the event types using the EventTypeRepository introspection interface EventType in the Java code of the adapters and business logic POJO in your application:

      @Service
public void setEventTypeRepository(EventTypeRepository etr) {
    etr_ = etr;
}
...
// handle events
public void onInsertEvent(Object event) throws EventRejectedException {
    // get the event type for the current event instance
    EventType eventType = etr_.getEventType(event);

    // get the event type name
    String eventTypeName = eventType.getTypeName();

    // get the event property names
    String[] propNames = eventType.getPropertyNames();

    // test if property is present
    if(eventType.isProperty("fromRate")) {
        // get property value
        Object propValue = 
            eventType.getProperty("fromRate").getValue(event);
    } 
    // Throw com.bea.wlevs.ede.api.EventRejectedException to have an   
    // exception propagated up to senders. Other errors will be
    // logged and dropped.
}

      For more information, see Section 2.7, "Accessing the Event Type Repository".

    • Access the event types from Oracle CQL and EPL rules:

      The following Oracle CQL rule shows how you can reference the CrossRateEvent in a SELECT statement:

      <query id="FindCrossRatesRule"><![CDATA[
    select ((a.price * b.price) + 0.05) as internalPrice, 
        a.fromRate as crossRate1, 
        b.toRate as crossRate2 
    from FxQuoteStream [range 1] as a, FxQuoteStream [range 1] as b   
    where 
        NOT (a.price IS NULL)
    and
        NOT (b.price IS NULL)
    and
        a.toRate = b.fromRate
]]></query>

2.3.2 How to Create an Oracle CEP Event Type as a Tuple Manually

This procedure describes how to create and register an Oracle CEP event type declaratively in the EPN assembly file as a tuple. Oracle recommends that you create an Oracle CEP event type as a JavaBean (see Section 2.2.3, "How to Create an Oracle CEP Event Type as a JavaBean Manually").

For more information on valid event type data types, see Section 2.1.3.3, "Event Types Specified as a Tuple".

To create an Oracle CEP event type as a tuple:

  1. Decide on the properties your event type requires.

    When you design your event, you must restrict your design to the even data types that Section 2.1.3.3, "Event Types Specified as a Tuple" describes.

  2. Register your event type declaratively in the Oracle CEP event type repository:

    To register declaratively, edit the EPN assembly file using the wlevs:event-type-repository element wlevs:event-type child element as Example 2-8 shows.

    Example 2-8 EPN Assembly File event-type-repository

    <wlevs:event-type-repository>
    <wlevs:event-type type-name="CrossRateEvent">
        <wlevs:properties>
            <wlevs:property name="price" type="double"/>
            <wlevs:property name="fromRate" type="char"/>
            <wlevs:property name="toRate" type="char"/>
        </wlevs:properties>
    </wlevs:event-type>
</wlevs:event-type-repository>

    At runtime, Oracle CEP generates a bean instance of CrossRateEvent for you. The CrossRateEvent has three properties: price, fromRate, and toRate.

    For more information on the valid values of the type attribute, see Section 2.1.3.3, "Event Types Specified as a Tuple".

  3. Use the event type:

    • Reference the event types using the EventTypeRepository introspection interface EventType in the Java code of the adapters and business logic POJO in your application:

      @Service
public void setEventTypeRepository(EventTypeRepository etr) {
    etr_ = etr;
}
...
// handle events
public void onInsertEvent(Object event) throws EventRejectedException {
    // get the event type for the current event instance
    EventType eventType = etr_.getEventType(event);

    // get the event type name
    String eventTypeName = eventType.getTypeName();

    // get the event property names
    String[] propNames = eventType.getPropertyNames();

    // test if property is present
    if(eventType.isProperty("fromRate")) {
        // get property value
        Object propValue = 
            eventType.getProperty("fromRate").getValue(event);
    }
    // Throw com.bea.wlevs.ede.api.EventRejectedException to have an   
    // exception propagated up to senders. Other errors will be
    // logged and dropped.
}

      For more information, see Section 2.7, "Accessing the Event Type Repository".

    • Access the event types from Oracle CQL and EPL rules:

      The following Oracle CQL rule shows how you can reference the CrossRateEvent in a SELECT statement:

      <query id="FindCrossRatesRule"><![CDATA[
    select ((a.price * b.price) + 0.05) as internalPrice, 
        a.fromRate as crossRate1, 
        b.toRate as crossRate2 
    from FxQuoteStream [range 1] as a, FxQuoteStream [range 1] as b   
    where 
        NOT (a.price IS NULL)
    and
        NOT (b.price IS NULL)
    and
        a.toRate = b.fromRate
]]></query>

2.4 Creating an Oracle CEP Event Type as a Java Class

You can create and register an Oracle CEP event type as a Java class.

This topic describes:

2.4.1 How to Create an Oracle CEP Event Type as a Java Class Manually

This procedure describes how to create and register an Oracle CEP event type as a Java class that does not conform to the JavaBeans programming guidelines.

For more information on valid event type data types, see Section 2.1.3.1, "Event Types Specified as JavaBean or Java Class".

To create an Oracle CEP event type as a Java class manually:

  1. Create a Java class to represent your event type.

    Oracle recommends that, if possible, you make your event type Java class immutable to improve performance. For more information, see Section 2.1.1, "Event Type Instantiation and Immutability".

    Example 2-5 shows the ForeignExchangeEvent which is implemented by the ForeignExchangeEvent inner class of com.bea.wlevs.example.fx.OutputBean.

    Example 2-9 ForeignExchangeEvent Class: Does not Conform to JavaBean Standards

    package com.bea.wlevs.example.fx.OutputBean.ForeignExchangeEvent;

static public class ForeignExchangeEvent {
    private String symbol;
    private Double price;
    private String fromRate;
    private String toRate;
    private Long clientTimestamp;
    private Long adapterTimestamp;
 
    public ForeignExchangeEvent() {

    }
 
    public ForeignExchangeEvent(String symbol, Double price, String fromRate, String toRate) {
        this.symbol = symbol;
        this.price = price;
        this.fromRate = fromRate;
        this.toRate = toRate;
 
        if (clientTimestamp == null)
            this.clientTimestamp = new Long(0);
 
        if (adapterTimestamp == null)
            this.adapterTimestamp = new Long(0);
    }
 
    public String getSymbol() {
        return symbol;
    }
 
    public Double getPrice() {
        return price;
    }
 
    public String getFromRate() {
        return fromRate;
    }
 
    public String getToRate() {
        return toRate;
    }
 
    public Long getClientTimestamp() {
        return clientTimestamp;
    }
 
    public Long getAdapterTimestamp() {
        return adapterTimestamp;
    }
 
}

  2. Create a Java class to represent your event type builder as Example 2-10 shows.

    Example 2-10 ForeignExchangeBuilderFactory

    package com.bea.wlevs.example.fx;
 
import java.util.HashMap;
import java.util.Map;
 
import com.bea.wlevs.ede.api.EventBuilder;
import com.bea.wlevs.example.fx.OutputBean.ForeignExchangeEvent;
 
public class ForeignExchangeBuilderFactory implements EventBuilder.Factory {
 
    public EventBuilder createBuilder() {
        return new ForeignExchangeBuilder();
    }
    
    static class ForeignExchangeBuilder implements EventBuilder {
        private Map<String,Object> values = new HashMap<String,Object>(10);
        
        public Object createEvent() {
            return new ForeignExchangeEvent(
                (String) values.get("symbol"),
                (Double) values.get("price"),
                (String) values.get("fromRate"),
                (String) values.get("toRate"));
        }
 
        public void put(String property, Object value) throws IllegalStateException {
            values.put(property, value);
        }
        
    }
}

    Oracle CEP uses the event builder factory to create event instances that do not follow the JavaBean specification. See Section 2.6, "Using an Event Type Builder Factory" for additional information about using an event type builder factory.

  3. Compile the Java classes that represent your event type and event builder factory.

  4. Register your event type and event builder factory in the Oracle CEP event type repository:

    1. To register declaratively, edit the EPN assembly file using the wlevs:event-type-repository element wlevs:event-type child element as Example 2-6 shows.

      Use the wlevs:class element to point to your JavaBean class, and then use the <wlevs:property name="builderFactory"> element to specify a custom event builder factory for the event type.

      Example 2-11 EPN Assembly File event-type-repository

      <wlevs:event-type-repository>
    <wlevs:event-type type-name="ForeignExchangeEvent">
      <wlevs:class>
          com.bea.wlevs.example.fx.OutputBean.ForeignExchangeEvent
      </wlevs:class>
    <wlevs:property name="builderFactory">
      <bean id="builderFactory"
            class="com.bea.wlevs.example.fx.ForeignExchangeBuilderFactory"/>
    </wlevs:property>
    </wlevs:event-type>
</wlevs:event-type-repository>

    2. To register programmatically, use the EventTypeRepository class as Example 2-7 shows.

      Example 2-12 Programmatically Registering an Event

      EventTypeRepository rep = getEventTypeRepository();
ForeignExchangeBuilderFactory factory = new ForeignExchangeBuilderFactory();
rep.registerEventType(
    "ForeignExchangeEvent", 
    com.bea.wlevs.example.fx.OutputBean.ForeignExchangeEvent.getClass(),
    factory.createBuilder()
);

      For more information, see Section 2.7, "Accessing the Event Type Repository".

  5. Use the event type:

    • Reference the event types as standard JavaBeans in the Java code of the adapters and business logic POJO in your application.

      public void onEvent(List newEvents)
        throws RejectEventException {
    for (Object event : newEvents) {
            ForeignExchangeEvent fxEvent = (ForeignExchangeEvent) event;
        System.out.println("Price: " + fxEvent.getPrice());
    }
}

    • Access the event types from Oracle CQL and EPL rules:

      The following Oracle CQL rule shows how you can reference the MarketEvent in a SELECT statement:

      <query id="helloworldRule">
    <![CDATA[ select ForeignExchangeEvent.price from marketEventChannel [Now] ]]>
</query>

2.5 Creating an Oracle CEP Event Type as a java.util.Map

You can create and register an Oracle CEP event type as a java.util.Map.

This topic describes:

2.5.1 How to Create an Oracle CEP Event Type as a java.util.Map

This procedure describes how to create and register an Oracle CEP event type as a java.util.Map. Oracle recommends that you create an Oracle CEP event type as a JavaBean (see Section 2.2.3, "How to Create an Oracle CEP Event Type as a JavaBean Manually").

For more information on valid event type data types, see Section 2.1.3.2, "Event Types Specified as java.util.Map".

To create an Oracle CEP event type as a java.util.Map:

  1. Decide on the properties your event type requires.

  2. Register your event type in the Oracle CEP event type repository:

    1. To register declaratively, edit the EPN assembly file using the wlevs:event-type-repository element wlevs:event-type child element as Example 2-13 shows.

      Example 2-13 EPN Assembly File event-type-repository

      <wlevs:event-type-repository>
    <wlevs:event-type type-name="AnotherEvent">
        <wlevs:properties type="map">
            <wlevs:property name="name" value="java.lang.String"/>
            <wlevs:property name="age" value="java.lang.Integer"/>
            <wlevs:property name="address" value="java.lang.String"/>
        </wlevs:properties >
    </wlevs:event-type>
</wlevs:event-type-repository>

      At runtime, Oracle CEP generates a bean instance of AnotherEvent for you. The AnotherEvent has three properties: name, age, and address.

    2. To register programmatically, use the EventTypeRepository class as Example 2-14 shows.

      Example 2-14 Programmatically Registering an Event

      EventTypeRepository rep = getEventTypeRepository();
java.util.Map map = new Map({name, java.lang.String}, 
    {age, java.lang.Integer}, {address, java.lang.String});
rep.registerEventType("AnotherEvent", map);

      For more information, see Section 2.7, "Accessing the Event Type Repository".

  3. Use the event type:

    • Reference the event types as standard JavaBeans in the Java code of the adapters and business logic POJO in your application.

      public void onEvent(List newEvents)
        throws RejectEventException {
    for (Object event : newEvents) {
            java.util.Map anEvent = (java.util.Map) event;
        System.out.println("Age: " + anEvent.getAge());
    }
}

    • Access the event types from Oracle CQL and EPL rules:

      The following Oracle CQL rule shows how you can reference the MarketEvent in a SELECT statement:

      <query id="helloworldRule">
    <![CDATA[ select AnotherEvent.age from eventChannel [Now] ]]>
</query>

2.6 Using an Event Type Builder Factory

When you register an event type in the repository using the wlevs:event-type element, Oracle CEP creates instances of the event using the information in the event type class.

Sometimes, however, you might want or need to have more control over how the event type instances are created. This is required if the POJO that represents the event does not expose the necessary getter and setter methods for the event properties. For example, assume the event type has a firstname property, but the EPL rule that executes on the event type assumes the property is called fname. Further assume that you cannot change either the event type class (because you are using a shared event class from another bundle, for example) or the EPL rule to make them compatible with each other. In this case you can use an event type builder factory to change the way the event type instance is created so that the property is named fname rather than firstname.

When you program the event type builder factory, you must implement the EventBuilder.Factory inner interface of the com.bea.wlevs.ede.api.EventBuilder interface; see the Oracle Fusion Middleware Java API Reference for Oracle Complex Event Processing for details about the methods you must implement, such as createBuilder and createEvent.

The following example of an event type builder factory class is taken from the FX sample:

package com.bea.wlevs.example.fx;
import java.util.HashMap;
import java.util.Map;
import com.bea.wlevs.ede.api.EventBuilder;
import com.bea.wlevs.example.fx.OutputBean.ForeignExchangeEvent;
public class ForeignExchangeBuilderFactory implements EventBuilder.Factory {
        public EventBuilder createBuilder() {
                return new ForeignExchangeBuilder();
        }
        static class ForeignExchangeBuilder implements EventBuilder {
                private Map<String,Object> values = new HashMap<String,Object>(10);
                public Object createEvent() {
                        return new ForeignExchangeEvent(
                                (String) values.get("symbol"),
                                (Double) values.get("price"),
                                (String) values.get("fromRate"),
                                (String) values.get("toRate"));
                }
                public void put(String property, Object value) throws IllegalStateException {
                        values.put(property, value);
                }
        }
}

When you register the event type in the EPN assembly file, use the <wlevs:property name="builderFactory"> child element of the wlevs:event-type element to specify the name of the factory class. The hard-coded builderFactory value of the name attribute alerts Oracle CEP that it should use the specified factory class, rather than its own default factory, when creating instances of this event. For example, in the FX example, the builder factory is registered as shown in bold:

<wlevs:event-type-repository>
  <wlevs:event-type type-name="ForeignExchangeEvent">
    <wlevs:class>com.bea.wlevs.example.fx.OutputBean$ForeignExchangeEvent</wlevs:class>
    <wlevs:property name="builderFactory">
      <bean id="builderFactory"
            class="com.bea.wlevs.example.fx.ForeignExchangeBuilderFactory"/>
    </wlevs:property>
  </wlevs:event-type>
</wlevs:event-type-repository>

2.7 Accessing the Event Type Repository

The EventTypeRepository is a singleton OSGi service. Because it is a singleton, you only need to specify its interface name to identify it. You can get a service from OSGi in any of the following ways:

For more information, see Oracle Fusion Middleware Java API Reference for Oracle Complex Event Processing.

2.7.1 Using the EPN Assembly File

You can access the EventTypeRepository by specifying an osgi:reference in the EPN assembly file as Example 2-15 shows.

Example 2-15 EPN Assembly File With OSGi Reference to EventTypeRepository

<osgi:reference id="etr" interface="com.bea.wlevs.ede.api.EventTypeRepository" />
<bean id="outputBean" class="com.acme.MyBean" >
    <property name="eventTypeRepository" ref="etr" />
</bean>

Then, in the MyBean class, you can access the EventTypeRepository using the eventTypeRepository property initialized by Spring as Example 2-16 shows.

Example 2-16 Accessing the EventTypeRepository in the MyBean Implementation

package com.acme;

import com.bea.wlevs.ede.api.EventTypeRepository;
import com.bea.wlevs.ede.api.EventType;

public class MyBean {
    private EventTypeRepository eventTypeRepository;

    public void setEventTypeRepository(EventTypeRepository eventTypeRepository) {
        this.eventTypeRepository = eventTypeRepository;
    }

    public void onInsertEvent(Object event) throws EventRejectedException {
        // get the event type for the current event instance
        EventType eventType = eventTypeRepository.getEventType(event);
       // Throw com.bea.wlevs.ede.api.EventRejectedException to have an   
       // exception propagated up to senders. Other errors will be
       // logged and dropped.
    }
}

2.7.2 Using the Spring-DM @ServiceReference Annotation

You can access the EventTypeRepository by using the Spring-DM @ServiceReference annotation to initialize a property in your Java source as Example 2-17 shows.

Example 2-17 Java Source File Using the @ServiceReference Annotation

import org.springframework.osgi.extensions.annotation.ServiceReference;
import com.bea.wlevs.ede.api.EventTypeRepository;
...
@ServiceReference
setEventTypeRepository(EventTypeRepository etr) {
    ...
}

2.7.3 Using the Oracle CEP @Service Annotation

You can access the EventTypeRepository by using the Oracle CEP @Service annotation to initialize a property in your Java source as Example 2-17 shows.

Example 2-18 Java Source File Using the @Service Annotation

import com.bea.wlevs.util.Service;
import com.bea.wlevs.ede.api.EventTypeRepository;
...
@Service
setEventTypeRepository(EventTypeRepository etr) {
    ...
}

For more information, see:Section I.5, "com.bea.wlevs.util.Service".

2.8 Sharing Event Types Between Application Bundles

Each Oracle CEP application gets its own Java classloader and loads application classes using that classloader. This means that, by default, one application cannot access the classes in another application. However, because the event type repository is a singleton service, you can configure the repository in one bundle and then explicitly export the event type classes so that applications in separate bundles (deployed to the same Oracle CEP server) can use these shared event types.

The event type names in this case are scoped to the entire Oracle CEP server instance. This means that you will get an exception if you try to create an event type that has the same name as an event type that has been shared from another bundle, but the event type classes are different.

To share event type classes, add their package name to the Export-Package header of the MANIFEST.MF file of the bundle that contains the event type repository you want to share.

Be sure you deploy the bundle that contains the event type repository before all bundles that contain applications that use the shared event types, or you will get a deployment exception.

For more information, see: