This chapter describes how to code and register custom event beans, including:
Section 15.3, "Configuring the Custom Event Bean EPN Assembly File"
Section 15.4, "Configuring the Custom Event Bean Component Configuration File"
An event bean is a Plain Old Java Object (POJO) managed by the Oracle CEP management framework. You register event beans in the EPN assembly file using the Oracle CEP wlevs:event-bean stage rather than the standard bean element.
An event bean is a type of Stage, it can be monitored by the Oracle CEP monitoring framework, make use of the configuration metadata annotations, and it can be set to record, and play-back events that pass through it. An event bean can also participate in the Oracle CEP server bean lifecycle by specifying methods in its XML declaration, rather than by implementing Oracle CEP server API interfaces.
To add a Plain Old Java Object (POJO) to your Oracle CEP application:
Use an event bean to actively use the capabilities of the Oracle CEP server container.
Use a Spring bean for legacy integration to Spring.
For more information, see Chapter 16, "Configuring Custom Spring Beans".
Event beans can be event sources, event sinks, or both. Event sources generate events, event sinks receive events.
You specify that an event bean component in your EPN is an event source by implementing the com.bea.wlevs.ede.api.StreamSource or RelationSource API.
The implementation class of an event bean that is an event source may be specified as private to the application or as an advertised OSGI service re-usable by other applications.
For the framework to be able to fully manage the custom event bean as an EPN component, it must be specified as an event bean rather than a standard Spring bean. Management tasks include monitoring and record/playback.
You register event beans in the EPN assembly file using the wlevs:event-bean element. For example:
<wlevs:event-bean id="myEventBeanSource" class="com.acme.MySourceEventBean"> </wlevs:event-bean>
In this example, the Java class MySourceEventBean.java implements the com.bea.wlevs.ede.api.StreamSource or RelationSource API.
For more information, see Section 15.2.1, "Implementing a Custom Event Bean as an Event Source".
The functionality of custom event beans as event sinks is very similar to that of event sources except that custom event bean sinks must implement the com.bea.wlevs.ede.api.StreamSink or RelationSink API.
Event sinks are not active which means that if they implement the Runnable interface, Oracle CEP does not run them in a separate thread.
You reference event sinks in the EPN assembly file using the wlevs:listener element:
<wlevs:event-bean id="myEventBeanSink" class="com.acme.MySinkEventBean">
</wlevs:event-bean>
...
<wlevs:channel id="myStream" >
<wlevs:listener ref="myEventBeanSink" />
</wlevs:channel>
In this example, the Java class MySinkEventBean.java implements the com.bea.wlevs.ede.api.StreamSink or RelationSink API.
For more information, see Section 15.2.2, "Implementing a Custom Event Bean as an Event Sink"
If your event bean is going to be used only by a single Oracle CEP application, then you do not need to create a factory. However, if multiple applications are going to use the same event bean, then you should also program a factory. In this case, every application gets its own instance of the adapter.
Event bean factories must implement the com.bea.wlevs.ede.api.Factory interface. This interface has a single method, create, that you implement to create an adapter or event bean instance.
You register factories in the EPN assembly file using the wlevs:factory element:
<wlevs:factory provider-name="myprovider" class="my.Implementation"/>
Note that if you need to specify service properties, then you must use the <osgi:service> to register the factory.
The following procedure describes the typical steps for creating a custom event bean.
To implement a custom event bean:
Note:
The following procedure assumes that the custom event bean is bundled in the same application JAR file that contains the other components of the EPN, such as the processor, streams, and business logic POJO. If you want to bundle the custom event bean in its own JAR file so that it can be shared among multiple applications, see Section 24.2.4.2, "How to Assemble a Custom Event Bean in its Own Bundle."Program the custom event bean Java class.
If your custom event bean is an event source, see Section 15.2.1, "Implementing a Custom Event Bean as an Event Source."
If your custom event bean is an event sink, see Section 15.2.2, "Implementing a Custom Event Bean as an Event Sink."
If your custom event bean is both an event source and event sink, then see both sections.
Optionally program the factory class.
You only need to do this if many applications are going to use the custom event bean.
See Section 15.2.3, "Implementing a Custom Event Bean Factory."
Optionally extend the configuration of the custom event bean if its basic one is not adequate.
Configure the custom event bean.
For more information, see:
The following example shows a custom event bean class as an event source ; see the explanation after the example for coding guidelines that correspond to the Java code in bold.
package com.acme; import com.bea.wlevs.ede.api.StreamSender; import com.bea.wlevs.ede.api.StreamSource; import com.bea.wlevs.ede.api.RunnableBean; public class EventBeanSource implements RunnableBean, StreamSource { public void setEventSender (StreamSender streamSender) { ... } public void run() { ... } public synchronized void suspend() throws Exception { ... } }
Follow these guidelines when programming the custom event bean Java class; code snippets of the guidelines are shown in bold in the preceding example:
Import the interfaces and classes of the Oracle CEP API:
import com.bea.wlevs.ede.api.StreamSender; import com.bea.wlevs.ede.api.StreamSource; import com.bea.wlevs.ede.api.RunnableBean;
Because the custom event bean is an event source it must implement the StreamSource interface. If you want the custom event bean to run in a thread, also implement RunnableBean. The StreamSender interface sends event types to the next component in your application network. For full details of these APIs, see Oracle Fusion Middleware Java API Reference for Oracle Complex Event Processing.
The custom event bean class must implement the StreamSource and RunnableBean interfaces because it is an event source and will run in its own thread:
public class HelloWorldAdapter implements RunnableBean, StreamSource {
The StreamSource interface provides the StreamSender that you use to send events.
Because the custom event bean implements the RunnableBean interface, your adapter must then implement the run method:
public void run() {...
This is where you should put the code that reads the incoming data, such as from a market feed, and convert it into an Oracle CEP event type, and then send the event to the next component in the network. Refer to the documentation of your data feed provider for details on how to read the incoming data. See Section 24.2.2.2, "Accessing Third-Party JAR Files" for information about ensuring you can access the vendor APIs if they are packaged in a third-party JAR file.
Because the custome event bean implements StreamSource, you must implement the setEventSender method, which passes in the StreamSender that you use to send events:
public void setEventSender(StreamSender sender) { ...
If, as is typically the case, your custom event bean implements SuspendableBean, you must implement the suspend method that stops the custom event bean when, for example, the application is undeployed:
public synchronized void suspend() throws Exception { ...
The following sample code shows a Spring bean from HelloWorld application that acts as an event sink; see the explanation after the example for the code shown in bold:
package com.bea.wlevs.example.helloworld; import com.bea.wlevs.ede.api.StreamSink; import com.bea.wlevs.event.example.helloworld.HelloWorldEvent; public class HelloWorldBean implements StreamSink { public void onInsertEvent(Object event) { if (event instanceof HelloWorldEvent) { HelloWorldEvent helloWorldEvent = (HelloWorldEvent) event; System.out.println("Message: " + helloWorldEvent.getMessage()); } } }
The programming guidelines shown in the preceding example are as follows:
Your bean must import the event type of the application, which in the HelloWorld case is HelloWorldEvent:
import com.bea.wlevs.event.example.helloworld.HelloWorldEvent;
Your bean must implement the com.bea.wlevs.ede.api.StreamSink interface:
public class HelloWorldBean implements StreamSink {...
The StreamSink interface has a single method that you must implement, onInsertEvent(java.lang.Object), which is a callback method for receiving events. The parameter of the method is an Object that represents the actual event that the bean received from the component that sent it the event:
public void onInsertEvent(Object event)
The data type of the events is determined by the event type you registered in the EPN assembly file of the application. In the example, the event type is HelloWorldEvent; the code first ensures that the received event is truly a HelloWorldEvent:
if (event instanceof HelloWorldEvent) {
HelloWorldEvent helloWorldEvent = (HelloWorldEvent) event;
This event type is a JavaBean that was configured in the EPN assembly file as shown:
<wlevs:event-type-repository>
<wlevs:event-type type-name="HelloWorldEvent">
<wlevs:class>
com.bea.wlevs.event.example.helloworld.HelloWorldEvent
</wlevs:class>
</wlevs:event-type>
</wlevs:event-type-repository>
See Section 4.3, "Creating EPN Assembly Files" for procedural information about creating the EPN assembly file, and Appendix C, "Schema Reference: EPN Assembly spring-wlevs-v11_1_1_3.xsd" for reference information.
Events are instances of the appropriate JavaBean, so you access the individual properties using the standard getXXX methods. In the example, the HelloWorldEvent has a property called message. You access this property using method getMessage:
System.out.println("Message: " + helloWorldEvent.getMessage());
For complete API reference information about the Oracle CEP APIs described in this section, see the Oracle Fusion Middleware Java API Reference for Oracle Complex Event Processing.
Your adapter factory class must implement the com.bea.wlevs.ede.api.EventBeanFactory interface, which has a single method, create, in which you code the creation of your specific adapter class. Event beans implement Factory.
The following is a possible adapter factory class for the HelloWorld example:
package com.acem;
import com.bea.wlevs.ede.api.EventBean;
import com.bea.wlevs.ede.api.EventBeanFactory;
public class MyEventBeanFactory implements Factory {
public MyEventBeanFactory() {
}
public synchronized EventBean create() throws IllegalArgumentException {
return new MyEventBeanFactory();
}
}
For full details of these APIs, see the Oracle Fusion Middleware Java API Reference for Oracle Complex Event Processing.
The custom event bean and custom event bean factory (if used) must be registered in the EPN assembly file, as discussed in the following sections:
For a complete description of the configuration file, including registration of other components of your application, see Section 4.3, "Creating EPN Assembly Files."
You register factories in the EPN assembly file using the wlevs:factory element:
<wlevs:factory provider-name="myprovider" class="my.Implementation"/>
If you need to specify service properties, then you must use the osgi:service element to register the factory as an OSGI service in the EPN assembly file. The scope of the OSGI service registry is the entire Oracle CEP. This means that if more than one application deployed to a given server is going to use the same adapter factory, be sure to register the adapter factory only once as an OSGI service.
Add an entry to register the service as an implementation of the com.bea.wlevs.ede.api.EventBeanFactory interface. Provide a property, with the key attribute equal to type, and the name by which this adapter provider will be referenced. Finally, add a nested standard Spring bean element to register your specific adapter class in the Spring application context
For example, the following segment of the EPN assembly file registers the MyEventBeanFactory as the provider for type hellomsgs:
<osgi:service interface="com.bea.wlevs.ede.api.EventBeanFactory">
<osgi:service-properties>
<entry key="type" value="myprovider"</entry>
</osgi:service-properties>
<bean class="com.acme.MyEventBeanFactory" />
</osgi:service>
For more information on how to reference a factory by its type, see Section 15.3.2, "Declaring the Custom Event Bean Components in your Application".
In the EPN assembly file, you use the wlevs:event-bean element to declare a custom event bean as a component in the event processor network. For example:
<wlevs:event-bean id="recplayEventSink"
class="com.bea.wlevs.example.recplayRecplayEventSink">
<wlevs:listener ref="playbackHttpPublisher"/>
</wlevs:event-bean>
If you registered an optional factory as an OSGI service, then use the provider attribute to point to the name you specified as the type in your osgi:service entry; for example:
<wlevs:event-bean id="myEventBean" provider="myprovider"/>
This means that an adapter will be instantiated by the factory registered for the type myprovider.
You can also use a wlevs:instance-property child element of wlevs:adapter to set any static properties in the adapter bean. Static properties are those that you will not dynamically change after the adapter is deployed.
For example, if your adapter class has a setPort method, you can pass it the port number as shown:
<wlevs:event-bean id="myEventBean" provider="myProvider">
<wlevs:instance-property name="port" value="9001" />
</wlevs:event-bean>
Each custom event bean in your application has a default configuration, and, optionally, an extended component configuration.
If your application has more than one custom event bean, you can create separate XML files for each, or create a single XML file that contains the configuration for all custom event beans, or even all components of your application (adapters, processors, and streams). Choose the method that best suits your development environment.
The following procedure describes the main steps to create the custom event bean configuration file. For simplicity, it is assumed in the procedure that you are going to configure all components of an application in a single XML file
For more information, see:
The following procedure describes how to configure a custom event bean manually.
To configure the custom event bean component configuration file:
Create an XML file using your favorite XML editor.
You can name this XML file anything you want, provided it ends with the .xml extension.
The root element of the configuration file is config, with namespace definitions shown in the next step.
For each event bean in your application, add an event-bean child element of config.
Uniquely identify each custom event bean with the name child element. This name must be the same as the value of the id attribute in the wlevs:event-bean element of the EPN assembly file that defines the event processing network of your application. This is how Oracle CEP knows to which particular custom event bean component in the EPN assembly file this adapter configuration applies. See Section 4.3, "Creating EPN Assembly Files" for details.
For example, if your application has two custom event beans, the configuration file might initially look like this:
<?xml version="1.0" encoding="UTF-8"?> <helloworld:config xmlns:helloworld="http://www.bea.com/xml/ns/wlevs/example/helloworld"> <processor> ... </processor> <event-bean> <name>firstEventBean</name> ... </event-bean> <event-bean> <name>firstEventBean</name> ... </event-bean> </helloworld:config>
In the example, the configuration file includes two custom event beans called firstEventBean and secondEventBean. This means that the EPN assembly file must include at least two custom event bean registrations with the same identifiers:
<wlevs:event-bean id="firstEventBean" ...> ... </wlevs:event-bean> <wlevs:event-bean id="secondEventBean" ...> ... </wlevs:event-bean>
Caution:
Identifiers and names in XML files are case sensitive, so be sure you specify the same case when referencing the component's identifier in the EPN assembly file.The following sample XML file shows how to configure two custom event beans, firstEventBean and secondEventBean.
<?xml version="1.0" encoding="UTF-8"?> <sample:config xmlns:sample="http://www.bea.com/xml/ns/wlevs/example/sample"> <event-bean> <name>firstEventBean</name> ... </event-bean> <event-bean> <name>firstEventBean</name> ... </event-bean> </sample:config>