xdocs/ElementEventHandling.xml (172 lines of code) (raw):
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<document>
<properties>
<title>Element Event Handling</title>
<author email="ASmuts@apache.org">Aaron Smuts</author>
</properties>
<body>
<section name="Element Event Handling">
<p>
JCS allows you to attach event handlers to elements in
the local memory cache.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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:
</p>
<table>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
<tr>
<td>ELEMENT_EVENT_EXCEEDED_MAXLIFE_BACKGROUND</td>
<td>
The element exceeded its max life. This was
detected in a background cleanup.
</td>
</tr>
<tr>
<td>ELEMENT_EVENT_EXCEEDED_MAXLIFE_ONREQUEST</td>
<td>
The element exceeded its max life. This was
detected on request.
</td>
</tr>
<tr>
<td>ELEMENT_EVENT_EXCEEDED_IDLETIME_BACKGROUND</td>
<td>
The element exceeded its max idle. This was
detected in a background cleanup.
</td>
</tr>
<tr>
<td>ELEMENT_EVENT_EXCEEDED_IDLETIME_ONREQUEST</td>
<td>
The element exceeded its max idle time. This was
detected on request.
</td>
</tr>
<tr>
<td>ELEMENT_EVENT_SPOOLED_DISK_AVAILABLE</td>
<td>
The element was pushed out of the memory store,
there is a disk store available for the region,
and the element is marked as spoolable.
</td>
</tr>
<tr>
<td>ELEMENT_EVENT_SPOOLED_DISK_NOT_AVAILABLE</td>
<td>
The element was pushed out of the memory store,
and there is not a disk store available for the
region.
</td>
</tr>
<tr>
<td>ELEMENT_EVENT_SPOOLED_NOT_ALLOWED</td>
<td>
The element was pushed out of the memory store,
there is a disk store available for the region,
but the element is marked as not spoolable.
</td>
</tr>
</table>
<p>
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:
</p>
<source>
<![CDATA[
public void handleElementEvent( IElementEvent event );
]]>
</source>
<p>
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.
</p>
<p>
Here is how to extract the event and source from the
IElementEvent:
</p>
<source>
<![CDATA[
public void handleElementEvent( IElementEvent event )
{
int eventType = event.getElementEvent();
CacheElement element = (CacheElement)((EventObject)event).getSource();
. . .
}
]]>
</source>
<p>
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.
</p>
<source>
<![CDATA[
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 );
]]>
</source>
<p>
Here is how to setup an event handler as a default
setting for a region:
</p>
<source>
<![CDATA[
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 );
]]>
</source>
</section>
</body>
</document>