9 Defining and Using Event Types

This chapter describes how to define the Oracle Event Processing event types you will need to carry event data through an event processing network, including how to implement and configure event types and how to access the event type repository.

Through the event types you define, your code has access to event data. As described in this chapter, you define event types that are based on one of several data types such as JavaBean classes you write. You add your event types to your application by configuring them as part of the event type repository. Although event types are typically added to the repository through configuration XML, you can also write code to access the repository programmatically.

This chapter includes the following sections:

• Section 9.1, "Overview of Oracle Event Processing Event Types"

• Section 9.2, "Designing Event Types"

• Section 9.3, "Creating Event Types"

• Section 9.4, "Accessing the Event Type Repository"

• Section 9.5, "Sharing Event Types Between Application Bundles"

9.1 Overview of Oracle Event Processing Event Types

An event type is how you represent event data in an Oracle Event Processing application. An event is structured data related to something that occurred at a particular time. For example, if your application is designed to react to changes in a server room's environment, event data could include snapshot information collected by a device that monitors the environment. Or if your application pays attention to trends and patterns related to stock market trades, event data could be values corresponding to a trade, including what stock was traded, what the trade volume was, what the share price was, and so on.

Event data entering your application can arrive in any of a wide variety of forms. By creating an event type to represent the data inside the application, you create a predictable way for your application's logic to work with the data. Because event types are the transport vehicles for event data, defining them is an essential part of building an Oracle Event Processing application.

For a hands-on look at creating and using event types, take a look at Section 8.3, "Create an Event Type to Carry Event Data".

9.1.1 Where Event Type Instances are Used

Instances of event types you create carry event data through the event processing network (EPN) of your application. Keep in mind how you're going to be using the events in code to make better decisions about designing and implementing event types.

Event type instances are used by either the Oracle Event Processing server or your own application logic. Typically, the Oracle Event Processing server creates an instance of the type and binds the data to it. However, for more control over how the event type instance is created, you can create an event type builder. For more information, see Section 9.3.1.5, "Controlling Event Type Instantiation with an Event Type Builder Class".

The following lists the primary places where an event type instance is used:

• When incoming event data arrives from an external source, it is bound to an event type instance.

• When an Oracle CQL processor executes a query and outputs a result, an instance of the event type is created for carrying result event data to a stage that is downstream in the EPN.

• In your application's Java logic, such as Java code for handling events, you can create new event type instances and send them to a stage that is downstream in the EPN. Java code that creates events is known as an event source. For more information about implementing event sources, see Section 16.2.2, "Implementing an Event Source".

9.1.2 High-Level Process for Creating Event Types

At a high level, the process for creating an event type is a matter of identifying the event data that the event type will need to carry, then implement the type as one of the data types supported by Oracle Event Processing.

Here are high-level steps:

1. Design the event type. Essentially, this is a matter of identifying the set of event data that's relevant for your application, then choosing how that data should be represented by an event type. For more information, see Section 9.2, "Designing Event Types".

2. Create the event type. Once you know how data should be represented by the type, you can create the type in one of three ways: by implementing it as a JavaBean class, by configuring it as a tuple, or by configuring it as a java.util.Map. You might also want to implement an event type builder for more control over how the type is instantiated. For more information, see Section 9.3, "Creating Event Types".

9.2 Designing Event Types

When you design an event type, you map raw event data to the implementation options that Oracle Event Processing supports.

Designing an event includes the following tasks:

• Identify the structure of event data that the event type will represent. This could be the structure of raw event data coming from an external source such as a monitor in a server room. It could also be a data structure required by a downstream stage or component to which your code will send instances of the type. For more information, see Section 9.2.1, "Identifying the Structure of Event Data".

• Choose the data type that will be the basis of the event type you're creating. Your event type will be based on one of three data types supported by Oracle Event Processing: a JavaBean class, a tuple, or a java.util.Map instance. For more information, see Section 9.2.2, "Choosing a Data Type for an Event Type".

• Keeping in mind the planned uses for the event type, and being aware of potential constraints imposed by those uses. For more information, see Section 9.2.3, "Constraints on Design of Event Types".

Finally, note that when configuring event types in the application's EPN XML file, you can mix type usage. For more information, see Section 9.2.4, "Mixing Use of Event Type Data Types".

9.2.1 Identifying the Structure of Event Data

An early task (though typically a simple one) in defining an event processing network is clarifying the structure of event data, then defining the form in which that data will be handled inside the EPN. The event type you create will include a property for each piece of event data your application cares about. Each of those properties will have its own data type.

Before you can create an event type, use a sample of the event data to define the type's properties and their data types. For an example, consider a very simple set of event data coming from a stock trade. Represented as a row of comma-separated values, the trade event data might look as follows:

ORCL,14.1,6000

The following table illustrates how you could separate the event data into its distinct values, defining an event type property for each.

Sample Data Value	Role	Type of Data	Event Type Property Name
ORCL	stock symbol	character	symbol
14.1	share price	number	price
6000	volume of shares traded	number	volume

Regardless of how you create your event type, you'll need to have a sense of its properties and their data types. However, how you specify those property data types will vary depending on the data type on which you base your event type. For example, if you implement a JavaBean class as your event type, data types for the three values specified in the table would likely be as follows:

Event Type Property Name	Java Data Type
symbol	String
price	Double
volume	Integer

The data types would be different if you were creating your event type as a tuple or java.util.Map. For more information, see Section 9.2.2, "Choosing a Data Type for an Event Type".

9.2.2 Choosing a Data Type for an Event Type

Event types you create are based on one of three data types supported by Oracle Event Processing: a JavaBean class, a tuple, or a java.util.Map.

Each data type has its own benefits and limitations, but the best practice is to create your event type as a JavaBean class, implementing event type properties as accessor methods. With a JavaBean, you will have greater flexibility to deal with event types as part of your application logic, as well as simplified integration with existing systems. With an event type implemented as a JavaBean class, you can also (if you like) closely control event type instantiation by implementing an event type builder class.

When you create your event type as a tuple or java.util.Map, you do so by defining the event type in the EPN assembly file, specifying its properties declaratively. Unless you explicitly declare that a java.util.Map should be used, Oracle Event Processing will use the tuple type as the default.

For the benefits and limitations of each supported data type, see Table 9-1, "Data Types for Event Types":

Table 9-1 Data Types for Event Types

Data Type	Description	Benefits and Limitations
JavaBean	A Java class written to JavaBean conventions. In addition to being used by logic you write, the type's accessor ("get" and "set") methods will be used by the Oracle Event Processing server and CQL processor to retrieve and set event property values. For more information, see Section 9.3.1, "Creating an Oracle Event Processing Event Type as a JavaBean".	Benefits: This type is the best practice because it provides the greatest flexibility and ease of use for application logic that handles events. You access property values directly through accessor methods. A JavaBean class is more likely to be useful when integrating your Oracle Event Processing application with other systems. For control over how the type is instantiated, you can implement an event type builder class. Limitations: Requires writing a JavaBean class, rather than simply declaring the event type in a configuration file. Oracle CQL does not support JavaBean properties in GROUP BY, PARTITION BY, and ORDER BY, although you can work around this by using an Oracle CQL view.
Tuple	A structure that you create and register declaratively in the EPN assembly file. For more information, see Section 9.3.2, "Creating an Oracle Event Processing Event Type as a Tuple".	Benefits: Requires no Java programming to create the event type. An event type is created by declaring it in the EPN assembly file. Useful for quick prototyping. Limitations: Using instances of this type in Java application logic requires programmatically accessing the event type repository to get the instance's property values. A tuple is also unlikely to be useful when integrating the Oracle Event Processing with other systems.
java.util.Map	Based on an instance of java.util.Map. You don't implement or extend the Map interface. Rather, you specify that the interface should be used when configuring the event type in the EPN assembly file. If you write Java code to access the type instance, you treat it as a Map instance. For more information, see Section 9.3.3, "Creating an Oracle Event Processing Event Type as a java.util.Map".	Benefits: Requires no Java programming to create the type. An event type is created by declaring it in the EPN assembly file. Useful for quick prototyping. Limitations: Does not perform as well as other types.

For more detailed information on how Oracle CQL handles and supports various data types, see:

• "Datatypes" in the Oracle Fusion Middleware CQL Language Reference for Oracle Event Processing

9.2.3 Constraints on Design of Event Types

Depending on how you plan to use an event type, you might need to keep in mind certain constraints. For example, you might need to limit the data types of its properties or how you set values of certain attributes when configuring the event type.

The following sections describe areas of constraints on event type design:

• Section 9.2.3.1, "Constraints on Event Types for Use With the csvgen Adapter"

• Section 9.2.3.2, "Constraints on Event Types for Use With a Database Table Source"

9.2.3.1 Constraints on Event Types for Use With the csvgen Adapter

When you declaratively specify the properties of an event type for use with the csvgen adapter, you may only use the data types that Table 9-2 describes.

Table 9-2 csvgen Adapter Types

Type	Usage
char	Single or multiple character values. Use for both char and java.lang.String values. Optionally, you may use the length attribute to specify the maximum length of the char value as Example 9-6 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.
float	Numeric values in the range that java.lang.Float 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:

• Chapter 21, "Testing Applications With the Load Generator and csvgen Adapter"

9.2.3.2 Constraints on Event Types for Use With a Database Table Source

You can use a relational database table as a source of event data, binding data from the table to your event type instance at runtime. When your event data source is a database table, you must follow the guidelines represented by the following tables.

When an event type will receive data from a database table, a property configured for the type will each receive data from a particular column in the database. When configuring the event type, note that its property child elements have attributes that have particular meanings and value constraints, as described in Table 9-3, "EPN Assembly File event-type Element Property Attributes".

Table 9-3 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 Event Processing Java type from Table 9-4 that corresponds to the column's SQL data type.
length	The column size as specified in the SQL create table statement.

When you specify the properties of an event type for use with a relational database table, you must observe the additional JDBC type restrictions listed in Table 9-4, "SQL Column Types and Oracle Event Processing Type Equivalents".

Table 9-4 SQL Column Types and Oracle Event Processing Type Equivalents

SQL Type	Oracle Event Processing 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	byte[]		Array, of depth 1, of byte.
BIT	java.lang.Boolean	boolean	An instance of java.lang.Boolean.
BLOB	byte[]		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	byte[]		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.
BINARY_DOUBLEFoot 1  or DOUBLEFoot 2	java.lang.Double	double	An instance of java.lang.Double
BINARY_FLOATFootref 1 or FLOATFootref 2	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	char[]	char	Array, of depth 1, of char.
LONGVARBINARY	byte[]		Array, of depth 1, of byte.
LONGVARCHAR	char[]	char	Array, of depth 1, of char.
NCHAR	char[]	char	Array, of depth 1, of char.
NCLOB	byte[]		Array, of depth 1, of byte.
NUMERIC	java.math.BigDecimal		An instance of java.math.BigDecimal.
NVARCHAR	char[]	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 Fusion Middleware CQL Language Reference for Oracle Event Processing.
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	byte[]		Array, of depth 1, of byte.
VARCHAR	char[]	char	Array, of depth 1, of char.

^Footnote 1 Oracle SQL.

^Footnote 2 Non-Oracle SQL.

For more information, see:

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

9.2.4 Mixing Use of Event Type Data Types

When defining an event type in the EPN assembly file, you can use a JavaBean-based event type as another event type's property data type.

Example 9-1 shows a tuple event type Student that defines its address property as JavaBean event type Address.

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

9.3 Creating Event Types

Event types define the event properties that provide access to event data within Oracle Event Processing applications. You then use these event types in the adapter and Java code, as well as in the Oracle CQL rules.

When you create an event type, you choose one of the three supported data types as a base for the type you're creating. The best practice is that you can create the type as a JavaBean class, writing a little Java code to handle event data in properties. You can also create the type declaratively as a tuple or java.util.Map.

Before you create types, you might want to see Section 9.2, "Designing Event Types" for design considerations.

This section describes:

• Section 9.3.1, "Creating an Oracle Event Processing Event Type as a JavaBean"

• Section 9.3.2, "Creating an Oracle Event Processing Event Type as a Tuple"

• Section 9.3.3, "Creating an Oracle Event Processing Event Type as a java.util.Map"

9.3.1 Creating an Oracle Event Processing Event Type as a JavaBean

Creating an event type as a JavaBean gives you the greatest level of flexibility when using instances 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 9.3.1.5, "Controlling Event Type Instantiation with an Event Type Builder Class".

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

• Create an empty-argument public constructor with which the Oracle Event Processing 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 define an event type as a JavaBean, you may use any Java type for its properties.

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

• Implement the hashCode and equals methods. This optimizes the class for use by the Oracle Event Processing 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:

• Section 9.3.1.1, "How to Create an Oracle Event Processing Event Type as a JavaBean Using the Event Type Repository Editor"

• Section 9.3.1.2, "How to Create an Oracle Event Processing Event Type as a JavaBean Manually"

9.3.1.1 How to Create an Oracle Event Processing Event Type as a JavaBean Using the Event Type Repository Editor

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

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

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

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

   Be sure to follow the guidelines described in Section 9.3.1, "Creating an Oracle Event Processing Event Type as a JavaBean".

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

   Example 9-2 MarketEvent Class

   package com.bea.wlevs.example.algotrading.event;
    
   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() {}
    
       public Double getPrice() {
           return this.price;
       }
       public void setPrice(Double price) {
           this.price = price;
       }
    
       public String getSymbol() {
           return this.symbol;
       }
       public void setSymbol(String symbol) {
           this.symbol = symbol;
       }
    
       public Long getTimestamp() {
           return this.timestamp;
       }
       public void setTimestamp(Long timestamp) {
           this.timestamp = timestamp;
       }
    
       public Long getLatencyTimestamp() {
           return this.latencyTimestamp;
       }
       public void setLatencyTimestamp(Long latencyTimestamp) {
           this.latencyTimestamp = latencyTimestamp;
       }
    
       public Long getVolume() {
           return this.volume;
       }
       public void setVolume(Long volume) {
           this.volume = volume;
       } 
   
       // Implementation for hashCode and equals methods.
   }
   

2. Compile the JavaBean that represents your event type.

3. In the IDE, open the EPN in the EPN editor.

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

4. Click the Event Types tab.

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 9-1 shows.

   Figure 9-1 Event Type Repository Editor - JavaBean Event

   
   Description of "Figure 9-1 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 9-1 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 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).

9.3.1.2 How to Create an Oracle Event Processing Event Type as a JavaBean Manually

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

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

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

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

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

   When you design your event, you must restrict your design to the even data types that Section 9.2.4, "Mixing Use of Event Type Data Types" describes.

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

   Example 9-3 MarketEvent Class

   package com.bea.wlevs.example.algotrading.event;
    
   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() {}
    
       public Double getPrice() {
           return this.price;
       }
       public void setPrice(Double price) {
           this.price = price;
       }
    
       public String getSymbol() {
           return this.symbol;
       }
       public void setSymbol(String symbol) {
           this.symbol = symbol;
       }
    
       public Long getTimestamp() {
           return this.timestamp;
       }
       public void setTimestamp(Long timestamp) {
           this.timestamp = timestamp;
       }
    
       public Long getLatencyTimestamp() {
           return this.latencyTimestamp;
       }
       public void setLatencyTimestamp(Long latencyTimestamp) {
           this.latencyTimestamp = latencyTimestamp;
       }
    
       public Long getVolume() {
           return this.volume;
       }
       public void setVolume(Long volume) {
           this.volume = volume;
       } 
   
       // Implementation for hashCode and equals methods.
   }
   

2. Compile the JavaBean that represents your event type.

3. Register your JavaBean event type in the Oracle Event Processing 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 9-4 shows.

      Example 9-4 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 9-5 shows.

      Example 9-5 Programmatically Registering an Event

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

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

9.3.1.3 Using JavaBean Event Type Instances in Java Code

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

The following code implements the onEvent method from an event sink class. For more information on event sinks, see Section 16.2.1, "Implementing an Event Sink".

public void onInsertEvent(Object event)
        throws EventRejectedException {
    if (event instanceof MarketEvent){
        MarketEvent marketEvent = (MarketEvent) event;
        System.out.println("Price: " + marketEvent.getPrice());
    }
}

9.3.1.4 Using JavaBean Event Type Instances in Oracle CQL Code

The following Oracle CQL rule shows how you can reference the MarketEvent in a SELECT statement. It assumes an upstream channel called marketEventChannel whose event type is MarketEvent.

<query id="helloworldRule">
    <![CDATA[ SELECT MarketEvent.price FROM marketEventChannel [NOW] ]]>
</query>

Also, with property data types implemented as JavaBeans, Oracle CQL code can get values within those properties by using standard JavaBean-style property access.

For example, the following configuration snippet declares a StudentType event type that is implemented as a JavaBean class. 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>

9.3.1.5 Controlling Event Type Instantiation with an Event Type Builder Class

You can create an event type builder to have more control over how event type instances are created. For example, using an event type builder you can ensure that the properties of a configured event are correctly bound to the properties of an event type class, such as one you have implemented as a JavaBean. You would need an event type builder in a case, for example, where event property names assumed in CQL code are different from the names of properties declared in the class.

For example, assume the event type has a firstname property, but the CQL rule that executes on the event type assumes the property is called fname. Assume also that you cannot change either the event type class (because you are using a shared event class from another bundle, for example) or the CQL 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.

At runtime, an event type builder class receives property values from the Oracle Event Processing server and uses those values to create an instance of the event type class you created. Your event type builder then returns the instance to the server. In this way, your builder class is in effect an intermediary, instantiating event types in cases where the server is unable to determine how to map configured properties to event type properties.

Creating and using an event type builder involves implementing the builder class and configuring a JavaBean event type to use the builder, as described in the following sections:

• Section 9.3.1.5.1, "Implementing an Event Type Builder Class"

• Section 9.3.1.5.2, "Configuring an Event Type that Uses an Event Type Builder"

9.3.1.5.1 Implementing an Event Type Builder Class

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

    // Called by the server to get an instance of this builder.
    public EventBuilder createBuilder() {
        return new ForeignExchangeBuilder();
    }

    // Inner interface implementation that is the builder.
    static class ForeignExchangeBuilder implements EventBuilder {

        // A Map instance to hold properties until the event type is instantiated.
        private Map<String,Object> values = new HashMap<String,Object>(10);

        // Called by the server to put an event type property. Values from the map 
        // will be used to instantiate the event type.
        public void put(String property, Object value) throws IllegalStateException {
            values.put(property, value);
        }

        // Called by the server to create the event type instance once property
        // values have been received.
        public Object createEvent() {
            return new ForeignExchangeEvent(
                (String) values.get("symbol"),
                (Double) values.get("price"),
                (String) values.get("fromRate"),
                (String) values.get("toRate"));
        }
    }
}

9.3.1.5.2 Configuring an Event Type that Uses an Event Type Builder

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 event type builder class. The hard-coded builderFactory value of the name attribute alerts Oracle Event Processing 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>

9.3.2 Creating an Oracle Event Processing Event Type as a Tuple

You can create an Oracle Event Processing event type as a tuple simply by adding the type's configuration XML to the EPN XML file. As a result, a tuple is the easiest way to create an event type, and so can be useful for quick prototyping. However, both the tuple and java.util.Map data types provide less flexibility than creating an event type as a JavaBean class.

With a tuple-based event type, your Java code using instances of the type must always set and get its property values using EventTypeRepository APIs.

When you design your event, you must restrict design of the type's properties to the data types described in Section 9.3.2.1, "Types for Properties in Tuple-Based Event Types".

Before you get started, consider reading the event type design recommendations in Section 9.2, "Designing Event Types".

This topic describes:

• Section 9.3.2.2, "How to Create an Oracle Event Processing Event Type as a Tuple Using the Event Type Repository Editor"

• Section 9.3.2.3, "How to Create an Oracle Event Processing Event Type as a Tuple Manually"

9.3.2.1 Types for Properties in Tuple-Based Event Types

When you specify the properties of the event type declaratively in the EPN assembly file as a tuple, you may use any of the types specified in com.bea.wlevs.ede.api.Type.

For more information on supported property types, see Section C.23, "wlevs:property".

Example 9-6 shows the use of different types:

Example 9-6 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 9.3.2, "Creating an Oracle Event Processing Event Type as a Tuple".

9.3.2.2 How to Create an Oracle Event Processing Event Type as a Tuple Using the Event Type Repository Editor

This procedure describes how to create and register an Oracle Event Processing event type as a tuple using the Oracle Event Processing IDE for Eclipse event type repository editor. For more information about the Oracle Event Processing IDE for Eclipse, see Chapter 4, "Overview of the Oracle Event Processing IDE for Eclipse".

You can instead create and register your event type as a tuple manually (see Section 9.3.2.3, "How to Create an Oracle Event Processing Event Type as a Tuple Manually").

To create an Oracle Event Processing 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 9.3.2.1, "Types for Properties in Tuple-Based Event Types" describes.

2. In the IDE, open the EPN in the EPN editor.

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

3. Click the Event Type tab.

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 9-2 shows.

   Figure 9-2 Event Type Repository Editor - Tuple Event

   
   Description of "Figure 9-2 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 9-2 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 9.3.2.1, "Types for Properties in Tuple-Based Event Types" 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 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).

9.3.2.3 How to Create an Oracle Event Processing Event Type as a Tuple Manually

This procedure describes how to create and register an Oracle Event Processing event type declaratively in the EPN assembly file as a tuple.

Note, however, that the best practice for creating event types is to create them as JavaBean classes. For more information, see Section 9.3.1, "Creating an Oracle Event Processing Event Type as a JavaBean".

For more information on valid data types, see Section 9.3.2.1, "Types for Properties in Tuple-Based Event Types".

To create an Oracle Event Processing 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 data types that Section 9.3.2.1, "Types for Properties in Tuple-Based Event Types" describes.

2. Register your event type declaratively in the Oracle Event Processing 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 9-7 shows.

   Example 9-7 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 Event Processing 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 9.3.2.1, "Types for Properties in Tuple-Based Event Types".

   For reference information on the configuration XML, see Section C.13, "wlevs:event-type", Section C.22, "wlevs:properties", and Section C.23, "wlevs:property"

9.3.2.4 Using a Tuple Event Type Instance in Java Code

When using a tuple-based event type in Java code, you must use a com.bea.wlevs.ede.api.EventTypeRepository instance to get the names of the type's properties before getting their values. (For information on getting an EventTypeRepository instance, see Section 9.4, "Accessing the Event Type Repository".)

The following example uses the repository in a class acting as an event sink.

@Service
public void setEventTypeRepository(EventTypeRepository etr) {
    etr_ = etr;
}
...
// Called by the server to pass in the event type instance.
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();

    // See if property you're looking for 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.
}

9.3.2.5 Using a Tuple Event Type Instance in Oracle CQL Code

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>

9.3.3 Creating an Oracle Event Processing Event Type as a java.util.Map

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

You can create an Oracle Event Processing event type as a java.util.Map simply by adding the type's configuration XML to the EPN XML file. As a result, this is an easy way to create an event type. However, both the tuple and java.util.Map data types provide less flexibility than creating an event type as a JavaBean class.

Creating and using an event type as a Map is something of a hybrid of the processes for the tuple type and a JavaBean class. As with a tuple-based event type, you create the Map-based type declaratively, by configuring it in the EPN XML file. And as with a JavaBean-based event type, you needn't use com.bea.wlevs.ede.api.EventTypeRepository APIs to access instance property values.

This topic describes:

• Section 9.3.3.2, "How to Create an Oracle Event Processing Event Type as a java.util.Map"

9.3.3.1 Types for Properties in java.util.Map-Based Event Types

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 9-8 shows how to use these types:

Example 9-8 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 9.3.3.2, "How to Create an Oracle Event Processing Event Type as a java.util.Map".

9.3.3.2 How to Create an Oracle Event Processing Event Type as a java.util.Map

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

For more information on valid event type data types, see Section 9.3.3.1, "Types for Properties in java.util.Map-Based Event Types".

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

1. Decide on the properties your event type requires.

2. Register your event type in the Oracle Event Processing 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 9-9 shows.

      Example 9-9 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 Event Processing 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 9-10 shows.

      Example 9-10 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 9.4, "Accessing the Event Type Repository".

9.3.3.3 Using a Map Event Type Instance in Java Code

When using a Map-based event type instance in Java code, you access its properties as you would with any java.util.Map instance.

public void onInsertEvent(Object event)
        throws EventRejectedException {

        java.util.Map anEvent = (java.util.Map) event;
        System.out.println("Age: " + anEvent.get("age"));
}

9.3.3.4 Using a Map Event Type Instance in Oracle CQL Code

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 age from eventChannel [now] ]]>
</query>

9.4 Accessing the Event Type Repository

The Oracle Event Processing event type repository keeps track of the event types defined for your application. When you create an event type, you make it available for use in the application by configuring it in the event type repository. In some cases, you might need to write code that explicitly accesses the repository.

For example, when your event type is created as a tuple, Java logic that accesses instance of the type will need to first retrieve the type definition using the repository API, then use the API to access the instance property values.

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:

• Section 9.4.1, "Using the EPN Assembly File"

• Section 9.4.2, "Using the Spring-DM @ServiceReference Annotation"

• Section 9.4.3, "Using the Oracle Event Processing @Service Annotation"

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

9.4.1 Using the EPN Assembly File

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

Example 9-11 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 9-12 shows.

Example 9-12 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.
    }
}

9.4.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 9-13 shows.

Example 9-13 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) {
    ...
}

9.4.3 Using the Oracle Event Processing @Service Annotation

You can access the EventTypeRepository by using the Oracle Event Processing @Service annotation to initialize a property in your Java source as Example 9-14 shows.

Example 9-14 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".

9.5 Sharing Event Types Between Application Bundles

Each Oracle Event Processing 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 Event Processing server) can use these shared event types.

The event type names in this case are scoped to the entire Oracle Event Processing 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:

• Section 9.2.4, "Mixing Use of Event Type Data Types"

• Section 23.2.3, "Assembling Applications With Foreign Stages"

• "Oracle Java Data Cartridge" in the Oracle Fusion Middleware CQL Language Reference for Oracle Event Processing