Before going any further, I would like to mention that BEA provides some nice tooling for the Event Server.  You may want to set things up yourself, however, if for some reason you cannot use the Event Server Eclipse plug-in.  In my case, I like to use Eclipse 3.3, but the plug-in requires Eclipse 3.2. 

I'm going to show how to automate deployment of the HelloWorld sample application that ships with the Event Server 2.0 release, but the same technique is applicable to any application that is using ant as its build tool.  First, I created an Eclipse project that contains the HelloWorld sample application.  The screenshot below shows this project's contents in the Package Explorer.  Next, I opened the ant build file for the project and added two new targets: install and uninstall.  Like the name implies, these targets uninstall and install the HelloWorld app.  They do this by invoking the command line deployment utility for the Event Server.

The code sample below shows a close-up of the install target. The URL port is the same as the netio port that is specified in the top-level server config.xml configuration file.  The username and password default to "wlevs" for the sample applications.  The install target assumes that the application bundle is available and ready to be deployed.  We shall rely on the existing dist target to create the application bundle in the "dist" subdirectory.

<property name="bundle.file.name" value="com.bea.wlevs.example.helloworld_2.0.0.0.jar"/>
<property name="wlevs.home.dir" value="${base.dir}/../../../.." />
<target name="install">
    <java classname="com.bea.wlevs.deployment.Deployer"
          classpath="${wlevs.home.dir}/bin/com.bea.wlevs.deployment.client_2.0.jar">
        <arg value="-url" />
        <arg value="http://localhost:9002/wlevsdeployer" />
        <arg value="-user" />
        <arg value="wlevs" />
        <arg value="-password" />
        <arg value="wlevs" />
        <arg value="-install" />
        <arg value="${dist.dir}/${bundle.file.name}" />
    </java>
</target>

After updating the ant build file, the next step is to configure Eclipse to invoke the new ant targets.  The figure below shows how to open the ant task configuration window.  Begin by right clicking the build.xml file in the Package Explorer view.

I recommend giving the ant run configuration a nice name since you will want to add the run configuration to your favorites list.  Here, I have chosen the name "helloworld_src install".  I have also selected three ant targets to be run: uninstall, all, and install.  I want them run in that order when this configuration is invoked, so I used to the"Target execution order" box to specify this.  In other words, the task will first uninstall the application, then run the all target to build a new application bundle, and finally deploy the new application bundle to the running server.  After making your changes, click Apply and then Close to save the changes without running the ant build yet.

 

Next, let's add our new ant task to the favorites list.  The figure below shows how to open the "Organize Favorites" window.

Click "Add..." and then select the ant task that you want to add.  Click OK twice.

Next, open the run box and run the helloworld server.

You should see the output from the server in the Eclipse Console view.

Now, let's make a simple code change before redeploying the application.  I have added some text, " After redeploy: ",   to the message printed by the HelloWorld application.

Now, select the "helloworld_src install" and target from the favorites menu.

You should see the message printed by the application change once the application is redeployed, as in the figure below.

Eclipse remembers the last task run from the favorites list, so you can build and automatically redeploy the application repeatedly by simply clicking the favorites icon on the menu bar.  If you want to shut down the server, simply close the console view.  To summarize, the basic steps  were:

1. Add the install and uninstall targets to the ant build file.
2. Create an ant run configuration to invoke the new targets.
3. Add the run configuration to the favorites menu.
4. Invoke ant to build and redeploy the application within Eclipse.

I have been using this style of eclipse config for several months and found that it works well.  I can generally rebuild and redeploy my applications in 10 seconds or so, but this will vary depending on the application complexity, of course.  

Next, let's look at the arguments that are passed to the server.  I have disabled security since I am just doing development.  I have also specified the BEA and WLEVS home directories.  These are the typical arguments that are specified when running the Event Server from the command line.  I have also specified a value for the Working directory.  This is the directory where the event server will be "run".  In this case, I have specified the root directory of my helloworld_domain project.  I did this by clicking on the "Workspace..." button and then selecting the helloworld_domain project.

The next step is to specify the JRE  for the server to use.  The server should use the version of JRockIt that is installed with the Event Server.  You may need to click on "Installed JREs…” and tell Eclipse where to find JRockIt before you can specify it as the Alternate JRE  to use.

Next, let's configure the classpath for our server instance.  Initially, the Classpath window will look something like this:

We need to configure the "User Entries" portion of the classpath.  First, delete whatever is there for "UserEntries" by default.  Then, you will need to add three jars from the bin directory of your Event Server installation.  In the example below,I have done this by selecting"Add External JARs..." , and selecting each jar from my Event Server installation's bin directory.

That's it!  Now, if you click on Run the server should boot and deploy the helloworld sample application.

To recap, we specified the following:

1. The Main class for the server.
2. The commandline arguments to the server.
3. The server's working directory.
4. The JRE for the server to use.
5. The classpath for the server.

At this point, you can repeatedly run the server by clicking on the green Run button near the top of the Eclipse window. Eclipse will remember the last application that was run, so a single click is all it takes. You can also run the server in debug mode in order to debug applications using the Eclipse debugger. 

If you want to run the server using a different domain, you can copy your existing run configuration for the server and then just change the working directory so that it is the same as the domain directory for the new

domain you want to use. In other words, you don't need to go through all the steps of creating a new run configuration again.

The first option that I would like to discuss is adding a third-party library jar to the boot classpath of the Event Server.  This is a good option to use if you want to try out a third-party library quickly during development and may also be appropriate for production deployments.  When using JRockit or the Sun JVM adding a jar to the boot classpath requires that one specify an additional argument when starting the Event Server, namely: -Xbootclasspath/a: <path_to_library_jar>\<jar_file_name>.  This will append the library jar to the boot classpath of the virtual machine and make the classes contained within the jar available to all applications deployed in your Event Server instance. 

How does this work exactly?  Well, the Event Server is based on a modular architecture (OSGi) in which each module is given its own classloader for loading the classes and resources needed by that module.  This fact plus the fact that each application is packaged as a module means that each application effectively gets its own classloader.  An application classloader first attempts to load classes from its parent which by default is the Java boot classloader before loading classes from some other module or from itself.  So, adding a class to the boot classpath will guarantee that the application loads the class from there.  If you would like more details about how OSGi bundle classloaders search for classes, see Section 3.8.4 of the OSGi Release 4 Core Specification. 

This approach works well for simple third-party libraries, but it has some limitations.  For example, all of the classes needed by the third-party library must be visible to the boot classloader.  This means you might end up needing to add several jars to the boot classpath if the jars reference each other's classes.  It also means that the third-party library cannot load classes contained in the application bundle since they are not visible to the boot classloader.  Another thing to keep in mind is that adding a class to the boot classpath makes it visible to all applications running in the server which may not be what you want.

Another technique that is quite similar to adding your library to the boot classpath is to place the library in the extensions subdirectory of the JVM.  The extension subdirectory is located here: <JAVA_HOME>/jre/lib/ext.  This can be useful if your library needs to load classes contained in other extension libraries.  If you decide to do things this way you need to specify the following command line argument to the JVM in addition to copying your library into the extensions directory.

-Dosgi.parentClassloader=ext

This argument tells the application classloaders to use the extension classloader as their parent and delegate to it instead of delegating to the boot classloader. 

You may be wondering why I recommend adding libraries to the boot or extension classpaths rather than simply using the -classpath option of the JVM.  This is because the Event Server uses java's -jar feature to specify the Java executable, like so

java  ... -jar <WLEVS_HOME>/bin/wlevs_2.0.jar

When the -jar option is used the user classpath setting is ignored, which means you can't use -classpath.  Of course, you could try to start the event server without using -jar, but this is not recommended.

So far, we've discussed what I would call "quick and dirty" techniques for configuring third-party libraries.  These techniques are great for prototyping during development.  A second, more elegant approach is to package the third-party library inside the application bundle itself.  You can do this by "exploding" the third-party jar or by including it directly.  If you include the third-party jar directly, you need to add it to what is called the "bundle classpath" by adding an entry like the following in the Manifest.mf file for your application.

Bundle-Classpath: <path_name>/<file_ name>.jar

This tells the server which nested jars in the application bundle contain classes that should be loaded by the application classloader.  This approach has a couple of advantages.  One advantage is that it helps to keep the application self-contained.  This makes it easier to deliver the application to another group for testing or deployment on a production system.  Another advantage is that the third-party library can now load any class that is visible to the bundle, including user-written classes.  This can be useful if the third-party library loads application classes by name.

The final option for configuring a third-party library is to package the library in its own bundle and deploy it to the server as a separate application.  The library bundle must export a set of packages containing classes that other bundles can use and it must also import any packages that contain classes that the library itself needs.  Getting these lists of exported and imported packages right usually requires some knowledge of the internal workings of the third-party library, so if your vendor hasn't provided you with a bundle up front, this option may be rather difficult.  It's worth noting, however, that tools like bnd can help immensely with the bundle creation process.  Conversely, if the third-party library needs to load application classes, your application bundle will need to export them.  Exporting classes from an application bundle has a subtle disadvantage which is that hot redeploy of the application may not work as expected once other bundles in the system have imported the application classes.  This is because a bundle can only import one version of a class, so if you hot redeploy your application and have made changes to an application class, those changes will not be visible to other bundles that have imported your application class until you restart the server.  For this reason, it's generally a good idea to avoid exporting classes from your applications.

That completes the list of alternatives for configuring third-party libraries.  To sum things up, the quick and dirty approaches are great for prototyping but make the application less self-contained.  Packaging third-party libraries in a separate bundle works well unless the third-party library needs to import application classes in which case it probably a better idea to package the third-party library within the application bundle itself.

These are the major differences, but there are many additional things that could be mentioned such as the fact that the Event Server is designed for applications that have strict latency requirements.  This should be enough to give a general sense of how these two application servers stack up.

1. How to automate generation of the OSGi manifest when packaging an application as a bundle.
2. How to use Spring to inject dependencies into a user-defined function for an EPL query.
3. Deploying and undeploying, starting and stopping applications using ant.
4. Using group by in EPL queries.
5. Packaging third-party libraries with an Event Server application.
6. A more complex example of how to extend the configuration system of the Event Server.

If you have any questions about the paper or sample application, send them my way.

There are three conference sessions related to the Event Server:

eBay builds high performance applications with BEA and EDA
Thomson Financial - Examining the impact of Event Driven Architectures in Financial Services
Introduction to Event-Driven SOA

The "Introduction to Event-Driven SOA" takes place at 2 p.m. on Wednesday, but I'm not sure about the others. I don't see any times listed on the BEAWorld website.

There is also a roundtable session

Event-Driven SOA

In addition to these, the Event Server development team will be hosting a series of Meet the Experts sessions at the BEA Pavilion on the show floor.  Here is the schedule for the Meet the Experts sessions:

I will be hosting the Meet the Experts session on Tuesday at 1:15.

The members of the development team will also be staffing the Event Server booth from 12-6 on Tuesday and Wednesday.  If you are interested, stop by and take a look at the demos that we will have running and hear about the latest performance results for the Event Server---they are pretty amazing. 

For example, if you have the following Spring component definition:

<bean id="cache"
        class="com.bea.wlevs.example.caching.gemfire.GemfireCache"
        destroy-method="destroy">
</bean> 

then the XML in the dynamic configuration file for this component must look something like this:

<cache-system>
        <name>cache</name>
        <multi-cast-port>0</multi-cast-port>
        <locators>localhost[10987]</locators>
        ...
</cache-system>

Note that the name and id values must match exactly and are case-sensitive.  If they do not match then the container won't realize that the dynamic metadata should be injected into the Spring "cache" component and the prepare, activate, and rollback methods will not be called.

Another thing to make sure of when your component has dynamic configuration, is that the component implements the com.bea.wlevs.ede.api.Stage interface.  This is a marker interface that the container uses to identify Spring beans that are part of an event processing network -- a stage in the network essentially.  If your bean doesn't implement this interface, then it won't get Prepare, Activate, or Rollback callbacks.  It's okay if your component isn't really a stage, but just a regular Spring bean.  Implementing this interface will allow your bean to get the lifecycle callbacks.

Another problem that I have run into occurred when I wanted a Pojo component to receive a DisposableBean.destroy callback. 

public class GemfireCache implements Cache, DisposableBean, Stage {

public void destroy() throws Exception {
        if (initialized) {
            cache.close();
            distributedSystem.disconnect();
            initialized = false;
        }
    }
...
}

My Pojo needed to do this because it had allocated a cache resource when it was initialized and it needed to clean up when the application was undeployed/uninstalled.  For some reason, the container just wouldn't call this method for me unless I included a destroy-method attribute in the Spring configuration for the bean, as you see in the Spring bean definition that I included earlier in this entry. This may have been due to something peculiar in my application, but if you run into this problem you may want to give the solution a try.

I'd like to mention just one more thing that I have run into.  If you have a component A that references another component B, and the referenced component B uses dynamic configuration, make sure that you don't invoke any of the methods on component B until it has reached the afterConfigurationActive stage of its lifecycle. 

This rule has a couple implications.   Of course, it means that component A cannot call methods on component B from A's constructor, setter,  afterPropertiesSet, Prepare, Activate, or Rollback lifecycle methods.  It also means that component B cannot be a Spring factory bean, because Spring will attempt to invoke methods on the factory bean before it has reached the afterConfigurationActive lifecycle stage.

Well, that wraps up my list of the top lifecycle issues that I have run into.  If you have run into some additional gotchas, I would like to hear about them!

<jmx>
    <jndi-service-name>JNDI</jndi-service-name>
    <rmi-service-name>RMI</rmi-service-name>
    <rmi-registry-port>1099</rmi-registry-port>
    <rmi-jrmp-port>9999</rmi-jrmp-port>
</jmx> 

In this example, the port to use in jconsole is 1099.

Click Connect.  Once you are connected, navigate to the mBean that you want to invoke.  In this example, I will invoke an operation on the mBean that represents my Gemfire distributed cache configuration in order to change the lock timeout for the cache.

Here I have typed in a new value of 15 seconds for the timeout. Then I just click on the operation button to invoke the mBean.  Now if I look in my Event Server console window I see that the following has been printed.

----------------------------------prepare called.
----------------------------------activate called.

So, we see that the prepare and activate methods have been called in order to update my caching component with its new configuration.  The caching component validates the new timeout value in the prepare method and then updates the cache during activate.  My previous post shows the code for the prepare and activate methods, so take a look at there if you want to see the code.  It is possible to do any number of dynamic configuration updates to an application component while an Event Server application is running.

One of the interesting things about Event Server components is their lifecycle. Event Server components are Spring beans, so they support all of the lifecycle methods that regular Spring beans support. However, Event Server components also provide additional lifecycle methods for dynamically injecting changes made to their configuration metadata while they are running. 

How is this different from other component models?  Consider Spring or EJB 3.0. These each inject a component with its metadata once, when the component is being initialized.  After the component is up and running, dependency injection is finished.  If the configuration metadata for an Event Server component is changed while the application is running, however, the real-time container will notify the component of the changes. The configuration metadata can be reinjected into a component any number of times, essentially, while the component is running.

There are some component frameworks, like Seam, which also perform dependency injection at runtime.  Seam uses the term bijection for this.  The Event Server uses dynamic injection differently than Seam, however.  For example, dynamic configuration data for Event Server components is persistent and changes to the configuration data are transactional, and the data that is injected is component metadata.  Seam, on the other hand, uses dynamic injection as an alternative to passing method parameters to and returning results from the business methods of a component.  Thus, the data being injected is not typically persistent or transactional, or part of the component's configuration.

Let's look at some sample code to illustrate what's been said.

public class CacheFacade implements InitializingBean, ActivatableBean,
        SuspendableBean, DisposableBean, Stage {

    private Cache cache;

    public CacheFacade() {
        System.out
                .println("-------------------------------constructor called.");
    }

    public void setCache(Cache cache) {
        System.out.println("-------------------------------setCache called.");
        this.cache = cache;
    }

    public void afterPropertiesSet() {
        System.out.println("-------------------------------afterPropertiesSet called.");
    }

    @Prepare
    public void prepare(CacheConfig configuration) {
        System.out
                .println("----------------------------------prepare called");
        if (configuration.isSetLockTimeout()
                && configuration.getLockTimeout().intValue() < 0) {
            throw new RuntimeException("lock timeout cannot be negative: "
                    + configuration.getLockTimeout().intValue());
        }
    }

    @Activate
    public void activate(CacheConfig configuration) {
        System.out
                .println("----------------------------------activate called");
        cache.setLockTimeout(configuration.getLockTimeout().intValue());
    }

    @Rollback
    public void rollback(CacheConfig configuration) {
        System.out.println("----------------------------------rollback called");
    }

    public void afterConfigurationActive() {
        System.out
                .println("-------------------------------afterConfigurationActive called.");
    }

    public void suspend() {
        System.out.println("-------------------------------suspend called.");
    }

    public void destroy() throws Exception {
        System.out.println("-------------------------------destroy called.");
        cache.close();
    }

    Map getMap(String name) {
        return cache.getRegion(name);
    }    
}

This is a bean from a sample application that I have been working on. Its purpose is to provide a thin facade on top of a Gemfire distributed cache, but I have added a complete set of lifecycle methods to illustrate the component lifecycle. Here is what the Spring configuration for this component looks like.

<bean id="cacheFacade"
        class="com.bea.wlevs.example.caching.cache.CacheFacade" 
        destroy-method="destroy" init-method="afterPropertiesSet">
    <property name="cache">
        <ref bean="gemFireCache" />
    </property>
</bean>

When I deploy my application, the cacheFacade bean prints the following output.

-------------------------------constructor called.
-------------------------------setCache called.
-------------------------------afterPropertiesSet called.
----------------------------------prepare called
----------------------------------activate called
-------------------------------afterConfigurationActive called.

After the constructor is called, the static Spring properties are injected.  In this case there is just one static property named "cache".  Once the static properties are injected, the Spring initialize method is called.  Next, the dynamic metadata for the component is injected by calling the prepare and activate methods (I will discuss these more in a future post.)  Finally, the afterConfigurationActive method is called.  This gives the component a chance to do some final initialization after all dynamic configuration has been set for the application (including other application components).

When the application is undeployed, the cacheFacade bean prints the following.

-------------------------------suspend called.
-------------------------------destroy called.

The component uses the destroy lifecycle method callback to close the Gemfire cache, thus integrating the distributed cache into the lifecycle of the application.

Ant doesn't have built-in support for creating OSGi bundles the way it does for jar, war, and ear files. Maybe you're thinking, "Hey, OSGi bundles are just fancy jar files, so why not use the jar task?".  This is the approach taken by the sample applications that are part of the Event Server 2.0 release.  Take a look at the build.xml file for the helloworld sample application to see exactly how this works.   The main drawback of doing things this way is having to maintain the manifest file by hand.  (Note that I'm assuming we are not using some other tool, like an IDE, that helps with maintaining the manifest for now, just plain ant.)  For example, if you decide to implement your own adapter, you will likely start by adding some code to your project that looks like this:

import com.bea.wlevs.ede.api.Adapter;

public class MyAdapter implements Runnable, Adapter {
...
}

Import-Package:
    com.bea.wlevs.ede.api;version="2.0.0.0"

Managing these double imports, importing the class and importing the package, can become quite tedious. Fortunately, the OSGi community has been faced with the problem of easily creating bundles for awhile and there are some tools available that can make things easier when using ant.  One that I have been using is the bnd tool which was written by Peter Kriens. (Bnd was previously called Btool.) Here is the task from a sample application that I have been writing that uses bnd to create the application bundle:  

<target name="dist">
        <taskdef resource="aQute/bnd/ant/taskdef.properties"
                 classpath="lib/bnd-0.0.177.zip" />

        <bnd classpath="${output.dir}"
             eclipse="false"
             failok="false"
             exceptions="true"
             files="example.bnd"
             output="${dist.dir}/${bundle.file.name}" />
</target>

You can see from the taskdef element that I have downloaded the bnd zip file and placed it in the lib directory of my project.  The classpath attribute of the bnd task is set to the output directory where my compiled Java classes are located.  The compiled classes together with the example.bnd file constitute  the input to bnd which it uses to generate its output, in this case my application bundle.  Here is what my example.bnd file looks like:

Export-Package: com.bea.wlevs.example.event
Import-Package: javax.xml.bind;version="2.0",\
javax.xml.bind.annotation;version=2.0,\
javax.xml.bind.annotation.adapters;version=2.0,\
javax.xml.bind.attachment;version=2.0,\
javax.xml.bind.helpers;version=2.0,\
javax.xml.bind.util;version=2.0,\
com.bea.wlevs.configuration;version="2.0.0.0",\
com.bea.wlevs.configuration.application;version="2.0.0.0",\
com.sun.xml.bind.v2;version="2.0.2",\
*;resolution:=optional
Private-Package: com.bea.wlevs.example.*
Include-Resource: META-INF/spring=src/main/resources/META-INF/spring,\
META-INF/wlevs=src/main/resources/META-INF/wlevs
Bundle-SymbolicName: myexample

It's important to export the package containing the application's event classes so that server bundles -- like the EPL bundle -- can use them.  It's a best practice to always put the event classes in their own package, hence the single entry in the Export-Package section. 

I'm planning to have a  custom extension to the XML configuration for my application which is the reason for the JAXB imports.  The configuration extension feature of the Event Server uses JAXB.  This is an advanced feature which not every application needs to use.  In my case, I wouldn't have required any entries in the Import-Package section if I wasn't creating custom configuration.

The Private-Package section lists all of the classes for my sample since they need to be included in the application bundle.  The Include-Resource section pulls in my spring application context file and event server configuration files into the application bundle.

I have found bnd to be a useful tool.  If you try it with your own Event Server applications, let me know what you think. I should note that there is another tool called mangen for generating bundle manifests which I have not yet tried.  Developers using maven may also want to try the maven OSGi plug-in.  IDEs, like Eclipse, also have support for maintaining the OSGi manifest.  I will try to post about my experiences using Eclipse in the future.

I joined the WebLogic Event Server (WLEvS) team in January this year.  One thing that got me interested in working as a developer on the Event Server was that it was the first product to be built using BEA's new microService Architecture (mSA).  This is what makes the Event Server a "modular" application server. Now, mSA is based on OSGi, so an Event Server module is really just an OSGi bundle.  In fact, every bit of code in the Event Server is packaged as an OSGi bundle making it a completely modular server. 

Some bundles that make up the Event Server are specific to the Event Server, of course.  These are the bundles that were built by the Event Server development team.  If you download and install the Event Server 2.0 release -- the 2.0 release is actually the first release -- you will find these bundles in the wlevs/modules directory under your BEA_HOME directory.  The Event Server bundles all have names like com.bea.wlevs.<module specific name>_2.0.0.0.jar.  You can tell from the jar file names that the fourteen Event Server bundles include bundles for things like the adapter framework, the CEP engine, the deployment subsystem, the JMX management layer, Spring custom tags and other related Spring classes, among others.

The Event Server also relies on a set of generic bundles that are part of mSA, but that are not specific to the Event Server.  You will find these bundles in the modules directory under your BEA_HOME directory.  The mSA bundles include bundles that were written by the mSA development team, bundles harvested from existing BEA products (like WebLogic Server), and bundles from the open source community.  One of the core ideas of mSA is that mSA bundles can be reused across many BEA products.  If you have only installed in the Event Server then you will only see the mSA bundles required by the Event Server in the modules directory.  I count 141 mSA bundles in this release of the Event Server -- that's a lot of bundles! 

It says a lot about the underlying OSG backplane that it is able to quickly and efficiently load all of the bundles when the server starts. By the way, the mSA uses the Equinox OSGi implementation from the Eclipse project.  Having a large number of relatively fine-grained bundles helps to keep the footprint of the Event Server small since only the code that the Event Server needs is loaded into memory.  If you take a close look at the names of the mSA bundles you will see that there are several bundles that comprise the Spring framework. There is also a bundle for the Jetty web server.  An example of a bundle that was harvested from WebLogic Server is the com.bea.core.datasource bundle which contains the connection pooling implementation from WLS.  The fact that the Event Server leverages a number of bundles from mature projects like WLS and Spring should help to make it a more solid platform.