Overview of Creating WebLogic Event Server Applications

Because WebLogic Event Server applications are low latency high-performance driven applications, they run on a lightweight container and are developed using a POJO-based programming model. In POJO (Plain Old Java Object) programming, business logic is implemented in the form of POJOs, and then injected with the services they need. This is popularly called dependency injection. The injected services can range from those provided by WebLogic Event Services, such as configuration management, to those provided by another BEA product such as BEA Kodo, to those provided by a third party.

WebLogic Event Server defines a set of core services or components used together to assemble event-driven applications; these services are adapters, streams, and processors. In addition to these, WebLogic Event Server includes other infrastructure services, such as configuration, monitoring, logging, and so on.

WebLogic Event Server Components

Component Configuration Files

Each component in your event processing network (adapter, processor, or stream) can have an associated configuration file, although only processors are required to have a configuration file. Component configuration files in WebLogic Event Server are XML documents whose structure is defined using standard XML Schema. The following two schema documents define the default structure of application configuration files:

The structure of application configuration files is as follows. There is a top-level root element named <config> that contains a sequence of sub-elements. Each individual sub element contains the configuration data for a WebLogic Event Server component (processor, stream, or adapter). For example:

How Components Fit Together

WebLogic Event Server applications are made of services that are assembled together to form an Event Processing Network (EPN).

The server uses the Spring framework as its assembly mechanism due to Spring's popularity and simplicity. WebLogic Event Server has extended the Spring framework to further simplify the process of assembling applications. This approach allows WebLogic Event Server applications to be easily integrated with existing Spring-beans, and other light-weight programming frameworks that are based upon a dependency injection mechanism.

A common approach for dependency injection is the usage of XML configuration files to declaritively specify the dependencies and assembly of an application. You assemble a WebLogic Event Server application an EPN assembly file before deploying it to the server; this EPN assembly file is an extension of the Spring framework XML configuration file.

After an application is assembled, it must be package so that it can be deployed into WebLogic Event Server. This is a simple process. The deployment unit of an application is a plain JAR file, which must contain, at a minimum, the following artifacts:

After you assemble the artifacts into a JAR file, you deploy this bundle to WebLogic Event Server so it can immediately start receving incoming data.

WebLogic Event Server APIs

WebLogic Event Server provides a variety of Java APIs that you use in your adapter implementation or business logic POJO. These APIs are all packaged in the com.bea.wlevs.api package.

This section describes the APIs that you will most typically use in your adapters and POJOs; see the Javadoc for the full reference documentation for all classes and interfaces. See Creating Adapters and Programming the Business Logic Component, as well as the HelloWorld and FX examples in the installed product, for sample Java code that uses these APIs.

EventSink—Components that receive events from an EventSource, such as the business logic POJO, must implement this interface. The interface has a callback method, onEvent(), in which programmers put the code that handles the received events.
EventSource—Components that send events, such as adapters, must implement this interface. The interface has a setEventSender() method for setting the EventSender, which actually sends the event to the next component in the network.
EventSender—The interface that actually sends the events to the next component in the network.
Component lifecycle interfaces—If you want some control over the lifecycle of the component you are programming, then your component should implement one or more of the following interfaces:

DisposableBean—Use if you want to release resources when the application is undeployed. Implement the destroy() method in your component code.
InitializingBean—Use if you require custom initialization after WebLogic Event Server has set all the properties of the component. Implement the afterPropertiesSet() method.
ActivatableBean—Use if you want to run some code after all dynamic configuration has been set and the event processing network has been activated. Implement the afterConfigurationActive() method.
SuspendableBean—Use if you want to suspend resources or stop processing events when the event processing network is suspended. Implement the suspend() method.

The Spring framework implements similar bean lifecycle interfaces; however, the equivalent Spring interfaces do not allow you to manipulate beans that were created by factories, while the WebLogic Event Server interfaces do.

Adapter, AdapterFactory—Adapters and adapter factories must implement these interfaces respectively.
EventBuilder—Use to create events whose Java representation does not expose the necessary setter and getter methods for its properties. If your event type is represented with a JavaBean with all required getter and setter methods, then you do not need to create an EventBuilder.
EventBuilder.Factory—Factory for creating EventBuilders.

Creating WebLogic Event Server Applications: Typical Steps

The following procedure shows the suggested start-to-finish steps to create a WebLogic Event Server application. Although it is not required to program and configure the various components in the order shown, the procedure shows a typical and logical flow recommended by BEA.

It is assumed in the procedure that you are using an IDE, although it is not required and the one you use is your choice.

Set up your environment as described in Setting Up Your Development Environment.
Design your event processing network (EPN).

This step involves creating the EPN assembly file, adding the full list of components that make up the application and how they are connected to each other, as well as registering the event types used in your application.

This step combines both designing of your application, in particular determining the components that you need to configure and code, as well as creating the actual XML file that specifies all the components. You will likely be constantly updating this XML file as you implement your application, but BEA recommends you start with this step so you have a high-level view of your application.

For details, see Creating the EPN Assembly File.

Design the EPL rules that the processors are going to use to select events from the stream.

See the EPL Reference Guide.

Determine the event types that your application is going to use, and, if creating your own JavaBean, program the Java file.

See Creating the Event Types.

Program, and optionally configure, the adapters that listen to the data feed data.

See Creating Adapters.

Configure the processors by creating their configuration XML files; the most important part of this step is designing and declaring the initial EPL rules that are associated with each processor.

See Configuring the Complex Event Processor.

Optionally configure the streams that stream data between adapters, processors, and the business logic POJO by creating their configuration XML files.

See Configuring the Stream Component.

Program the business object POJO that receives the set of events that were selected with the EPL query and contains the application business logic.

See Programming the Business Logic Component.

WebLogic Event Server provides a load generator testing tool that you can use to test your application, in particular the EPL rules. This testing tool can temporarily replace the adapter component in your application, for testing purposes only of course. For details, see Using the Load Generator to Test Your Application.

See Next Steps for the list of steps you should follow after you have completed programming your application, such as packaging and deploying.

Creating the EPN Assembly File

You use the EPN assembly file to declare the components that make up your WebLogic Event Server application and how they are connected to each other. You also use the file to register event types of your application, as well as the Java classes that implement the adapter and POJO components of your application.

As is often true with Spring, there are different ways to use the tags to define your event network. This section shows one way. See WebLogic Event Server Spring Tag Reference or the XSD Schema for the full reference information on the other tags and attributes you can use.

For a typical way to create the EPN assembly file for your application, follow these steps:

Using your favorite XML or plain text editor, create an XML file with the <beans> root element and namespace declarations as follows

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:osgi="http://www.springframework.org/schema/osgi"
       xmlns:wlevs="http://www.bea.com/ns/wlevs/spring"
       xsi:schemaLocation="
  http://www.springframework.org/schema/beans
  http://www.springframework.org/schema/beans/spring-beans.xsd
  http://www.springframework.org/schema/osgi
  http://www.springframework.org/schema/osgi/spring-osgi.xsd
  http://www.bea.com/ns/wlevs/spring
  http://www.bea.com/ns/wlevs/spring/spring-wlevs.xsd">

...

</beans>

If you are not going to use any of the Spring-OSGI tags in the XMLfile, then their corresponding namespace declarations, shown in bold in the preceding example, are not required.

If you have programmed an adapter factory, add an <osgi:service ...> Spring tag to register the factory as an OSGi service. For example:

<osgi:service interface="com.bea.wlevs.ede.api.AdapterFactory">
    <osgi:service-properties>
        <prop key="type">hellomsgs</prop>
    </osgi:service-properties>
    <bean class="com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterFactory" />
</osgi:service>

Specify the WebLogic Event Server-provided adapter factory (com.bea.wlevs.ede.api.AdapterFactory) for the interface attribute. Use the <osgi-service-properties> tag to give the OSGI service a type name, in the example above the name is hellomsgs; you will reference this label later when you declare the adapter components of your application. Finally, use the <bean> Spring tag to register the your adapter factory bean in the Spring application context; this class generates instances of the adapter.

WARNING: Be sure the type name (hellomsgs in the preceding example) is unique across all applications deployed to a particular WebLogic Event Server. The OSGI service registry is per server, not per application, so if two different adapter factory services have been registered with the same type name, it is undefined which adapter factory a particular application will use. To avoid this confusion, be sure that the value of the <prop key="type"> entry for each OSGI-registered adapter factory in each EPN assembly file for a server is unique.

Add a <wlevs:event-type-repository> tag to register the event types that you use throughout your application, such as in the adapter implementations, business logic POJO, and the EPL rules associated with the processor components. For each event type in your application, add a <wlevs:event-type> child tag.

Event types are simple JavaBeans that you either code yourself (recommended) or let WebLogic Event Server automatically generate from the meta data you provide in the <wlevs:event-type> tag. If you code the JavaBean yourself, use a <wlevs:class> tag to specify your JavaBean class. You can optionally use the <wlevs:property name="builderFactory"> tag to specify the Spring bean that acts as a builder factory for the event type, if you have programmed a factory. If you want WebLogic Event Server to automatically generate the JavaBean class, use the <wlevs:metadata> tag to list each property of the event type. The following example is taken from the FX sample:

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

See wlevs:event-type-repository for reference information about this tag. See Creating the Event Types for additional information about creating event types.

For each adapter component in your application, add a <wlevs:adapter> tag to declare that the component is part of the event processing network. Use the required id attribute to give it a unique ID and the provider attribute to specify the type of data feed to which the adapter will be listening. Use the <wlevs:instance-property> child tag to pass the adapter the properties it expects. For example, the csvgen adapter, provided by WebLogic Event Server to test your EPL rules with a simulated data feed, defines a setPort() method and thus expects a port property, among other properties. Use the provider attribute to specify the adapter factory, typically registered as an OSGi service; you can also use the csvgen keyword to specify the csvgen adapter.

The following example declares the helloWorldAdapter of the HelloWorld example:

    <wlevs:adapter id="helloworldAdapter" provider="hellomsgs" manageable="true">
        <wlevs:instance-property name="message" value="HelloWorld - the currenttime is:"/>
    </wlevs:adapter>

In the example, the property message is passed to the adapter. The adapter factory provider is hellomsgs, which refers to the type name of the adapter factory OSGI service. The manageable attribute, common to all components, enables monitoring for the adapter; by default, manageability of the component is disabled due to possible performance impacts.

See wlevs:adapter for reference information about this tag, in particular additional optional attributes and child tags.

For each processor component in your application, add a <wlevs:processor> tag. Use the id attribute to give it a unique ID. Use either the listeners attribute or <wlevs:listener> child tag to specify the components that listen to the processor. The following two examples are equivalent:

<wlevs:processor id="preprocessorAmer" listeners="spreaderIn"/>

<wlevs:processor id="preprocessorAmer">
        <wlevs:listener ref="spreaderIn"/>
</wlevs:processor>

In the examples, the spreaderIn stream component listens to the preprocessorAmer processor.

See wlevs:processor for reference information about this tag, in particular additional optional attributes, such as manageable for enabling monitoring of the component.

For each stream component in your application, add a <wlevs:stream> tag to declare that the component is part of the event processing network. Use the id attribute to give it a unique ID. Use the <wlevs:listener> and <wlevs:source> child tags to specify the components that act as listeners and sources for the stream. For example:

<wlevs:stream id="fxMarketAmerOut">
    <wlevs:listener ref="preprocessorAmer"/>
    <wlevs:source ref="fxMarketAmer"/>
</wlevs:stream>

In the example, the fxMarketAmerOut stream listens to the fxMarketAmer component, and the preprocessorAmer component in turn listens to the fxMarketAmerOut stream.

Nest the declaration of the business logic POJO, called outputBean in the example, using a standard Spring <bean> tag inside a <wlevs:listener> tag, as shown:

<wlevs:stream id="spreaderOut" advertise="true">
    <wlevs:listener>
       <!-- Create business object -->
        <bean id="outputBean" 
              class="com.bea.wlevs.example.fx.OutputBean" 
              autowire="byName"/>
    </wlevs:listener>
</wlevs:stream>

The advertise attribute is common to all WebLogic Event Server tags and is used to register the component as a service in the OSGI registry.

See wlevs:stream for reference information about this tag, in particular additional optional attributes, such as manageable for enabling monitoring of the component.

Creating the Event Types

Event types define the properties of the events that are handled by WebLogic Event Server applications. Adapters receiving 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. An event type can be created either programmatically using the EventTypeRepository class or declaratively in the EPN assembly file.

You then use these event types in the adapter and POJO Java code, as well as in the EPL rules associated with the processors.

Events are JavaBean instances in which each property represents a data item from the feed. BEA recommends that you create your own JavaBean class that represents the event type and register the class in the EPN assembly file. By creating your own JavaBean, you can reuse it and you have complete control over what the event looks like. Alternatively, you can specify the properties of the event type in the EPN assembly file using <wlevs:metadata> tags and let WebLogic Event Server automatically create JavaBean instances for you; this method is best used for quick prototyping.

Each WebLogic Event Server 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. If an application (the provider) wants to share its classes, the provider must explicitly export the classes in its MANIFEST.MF file, and the consumer of the classes must import them. For details, see Assembling a WebLogic Event Server Application: Main Steps.

The following simple example shows the JavaBean that implements the HelloWorldEvent:

The preceding Java class follows standard JavaBeans programming guidelines. See the JavaBeans Tutorial for additional details.

In addition, BEA recommends that, if possible, you make your JavaBeans immutable for performance reasons because immutable beans help the garbage collection work much better. Immutable beans are read only (only getters) and have public constructors with arguments that satisfy immutability.

Once you have programmed and compiled the JavaBean that represents your event type, you register it in the EPN assembly file using the <wlevs:event-type> child tag of <wlevs:event-type-repository>. Use the <wlevs:class> tag to point to your JavaBean class, and then optionally use the <wlevs:property name="builderFactory"> tag to specify the Spring bean that acts as a builder factory for the event type, if you have programmed a factory. If want WebLogic Event Server to generate the bean instance for you, use the <wlevs:metadata> tag to group standard Spring <entry> tags for each property. The following example shows both ways:

In the example, ForeignExchangeEvent is implemented by the ForeignExchangeEvent inner class of com.bea.wlevs.example.fx.OutputBean. Instances of AnotherEvent will be generated by WebLogic Event Server. The AnotherEvent has three properties: name, age, and address.

You can now reference the event types as standard JavaBeans in the Java code of the adapters and business logic POJO in your application. The following snippet from the business logic POJO HelloWorldBean.java of the HelloWorld application shows an example:

The following EPL rule shows how you can reference the HelloWorldEvent in a SELECT statement:

Next Steps

After you have programmed all components of your application and created their configuration XML files:

Creating WebLogic Event Server Applications