Element Event Handling

JCS allows you to attach event handlers to elements in the local memory cache.

There are several events that you can listen for. All of the events are local memory related events. Element event handlers are not transmitted to other caches via lateral or remote auxiliaries, nor are they spooled to disk.

You can register multiple handlers for a single item. Although the handlers are associated with particular items, you can also setup default handlers for any region. Each item put into the region, that will take the default element attributes, will be assigned the event default event handlers.

The various events that you can handle have all been assigned integer codes. The codes are defined in the org.apache.commons.jcs3.engine.control.event.behavior.IElementEventConstants interface. The events are named descriptively and include:

To create an event handler you must implement the org.apache.commons.jcs3.engine.control.event.behavior.IElementEventHandler interface. This interface contains only one method:

				
    public void handleElementEvent( IElementEvent event );
        		
			

The IElementEvent object contains both the event code and the source. The source is the element for which the event occurred. The code is the type of event. If you have an event handler registered, it will be called whenever any event occurs. It is up to the handler to decide what it would like to do for the particular event. Since there are not that many events, this does not create too much activity. Also, the event handling is done asynchronously. Events are added to an event queue and processed by background threads.

Here is how to extract the event and source from the IElementEvent:

                
    public void handleElementEvent( IElementEvent event )
    {
        int eventType = event.getElementEvent();
        CacheElement element = (CacheElement)((EventObject)event).getSource();
        . . .
    }
                
            

Once you have an IElementEventHandler implementation, you can attach it to an element via the Element Attributes. You can either add it to the element attributes when you put an item into the cache, add it to the attributes of an item that exist in the cache (which just results in a re-put), or add the event handler to the default element attributes for a region. If you add it to the default attributes, then all elements subsequently added to the region that do not define their own element attributes will be assigned the default event handlers.

				
    CacheAccess<String, String> jcs = JCS.getInstance( "myregion" );

    . . .

    MyEventHandler meh = new MyEventHandler();

    // jcs.getDefaultElementAttributes returns a copy not a reference
    IElementAttributes attributes = jcs.getDefaultElementAttributes();
    attributes.addElementEventHandler( meh );
    jcs.put( "key", "data", attributes );
        		
			

Here is how to setup an event handler as a default setting for a region:

				
    CacheAccess<String, String> jcs = JCS.getInstance( "myregion" );

    . . .

    MyEventHandler meh = new MyEventHandler();

    // this should add the event handler to all items as
    //they are created.
    // jcs.getDefaultElementAttributes returns a copy not a reference
    IElementAttributes attributes = jcs.getDefaultElementAttributes();
    attributes.addElementEventHandler( meh );
    jcs.setDefaultElementAttributes( attributes );