Program guide > Programming with system APIs and plug-ins > Plug-ins for evicting cache objects
TimeToLive (TTL) evictor
WebSphere eXtreme Scale provides a default mechanism for evicting cache entries and a plug-in for creating custom evictors. An evictor controls the membership of entries in each BackingMap instance.
Enable the TTL evictor programmatically
TTL evictors are associated with BackingMap instances. The default evictor uses a time-to-live (TTL) eviction policy for each BackingMap instance. If you provide a pluggable evictor mechanism, it typically uses an eviction policy that is based on the number of entries instead of on time.
The following snippet of code uses the BackingMap interface to set the expiration time for each entry to 10 minutes after the entry was created.
programmatic time-to-live evictor import com.ibm.websphere.objectgrid.ObjectGridManagerFactory; import com.ibm.websphere.objectgrid.ObjectGridManager; import com.ibm.websphere.objectgrid.ObjectGrid; import com.ibm.websphere.objectgrid.BackingMap; import com.ibm.websphere.objectgrid.TTLType; ObjectGridManager ogManager = ObjectGridManagerFactory.getObjectGridManager(); ObjectGrid og = ogManager.createObjectGrid( "grid" ); BackingMap bm = og.defineMap( "myMap" ); bm.setTtlEvictorType( TTLType.CREATION_TIME ); bm.setTimeToLive( 600 );
The setTimeToLive method argument is 600 because it indicates the time-to-live value is in seconds. The preceding code must run before the initialize method is invoked on the ObjectGrid instance. These BackingMap attributes cannot be changed after the ObjectGrid instance is initialized. After the code runs, any entry that is inserted into the myMap BackingMap has an expiration time. After the expiration time is reached, the TTL evictor removes the entry.
To set the expiration time to the last access time plus 10 minutes, change the argument that is passed to the setTtlEvictorType method from TTLType.CREATION_TIME to TTLType.LAST_ACCESS_TIME. With this value, the expiration time is computed as the last access time plus 10 minutes. When an entry is first created, the last access time is the creation time.
To base the expiration time on the last update, instead of merely the last access (whether or not it involved an update), substitute the TTLType.LAST_UPDATE_TIME setting for the TTLType.LAST_ACCESS_TIME setting.
When using the TTLType.LAST_ACCESS_TIME or TTLType.LAST_UPDATE_TIME setting, you can use the ObjectMap and JavaMap interfaces to override the BackingMap time-to-live value. This mechanism allows an application to use a different time-to-live value for each entry that is created. Assume that the preceding snippet of code set the ttlType attribute to LAST_ACCESS_TIME and set the time-to-live value to 10 minutes. An application can then override the time-to-live value for each entry by running the following code prior to creating or modifying an entry:
import com.ibm.websphere.objectgrid.Session; import com.ibm.websphere.objectgrid.ObjectMap; Session session = og.getSession(); ObjectMap om = session.getMap( "myMap" ); int oldTimeToLive1 = om.setTimeToLive( 1800 ); om.insert("key1", "value1" ); int oldTimeToLive2 = om.setTimeToLive( 1200 ); om.insert("key2", "value2" );
In the previous snippet of code, the entry with the key1 key has an expiration time of the insert time plus 30 minutes as a result of the setTimeToLive( 1800 ) method invocation on the ObjectMap instance. The oldTimeToLive1 variable is set to 600 because the time-to-live value from the BackingMap is used as a default value if the setTimeToLive method was not previously called on the ObjectMap instance.
The entry with the key2 key has an expiration time of insert time plus 20 minutes as a result of the setTimeToLive( 1200 ) method call on the ObjectMap instance. The oldTimeToLive2 variable is set to 1800 because the time-to-live value from the previous ObjectMap.setTimeToLive method invocation set the time-to-live value to 1800.
The previous example shows two map entries being inserted in the myMap map for keys key1 and key2. At a later point in time, the application can still update these map entries while retaining the time-to-live values that are used at insert time for each map entry. The following example illustrates how to retain the time-to-live values by using a constant defined in the ObjectMap interface:
Session session = og.getSession(); ObjectMap om = session.getMap( "myMap" ); om.setTimeToLive( ObjectMap.USE_DEFAULT ); session.begin(); om.update("key1", "updated value1" ); om.update("key2", "updated value2" ); om.insert("key3", "value3" ); session.commit();
Since the ObjectMap.USE_DEFAULT special value is used on the setTimeToLive method call, the key1 key retains its time-to-live value of 1800 seconds and the key2 key retains its time-to-live value of 1200 seconds because those values were used when these map entries were inserted by the prior transaction.
The previous example also shows a new map entry for the key3 key insert. In this case, the USE_DEFAULT special value indicates to use the default setting of time-to-live value for this map. The default value is defined by the time-to-live BackingMap attribute. See BackingMap interface attributes for information about how the time-to-live attribute is defined on the BackingMap instance.
See the API documentation for the setTimeToLive method on the ObjectMap and JavaMap interfaces. The documentation explains that an IllegalStateException exception results if the BackingMap.getTtlEvictorType method returns anything other than the TTLType.LAST_ACCESS_TIME or TTLType.LAST_UPDATE_TIME value. The ObjectMap and JavaMap interfaces can override the time-to-live value only when you are using the LAST_ACCESS_TIME or TTLType.LAST_UPDATE_TIME setting for the TTL evictor type. The setTimeToLive method cannot be used to override the time-to-live value when you are using the evictor type setting CREATION_TIME or NONE.
Enable the TTL evictor using XML configuration
Instead of using the BackingMap interface to programmatically set the BackingMap attributes to be used by the TTL evictor, you can use an XML file to configure each BackingMap instance. The following code demonstrates how to set these attributes for three different BackingMap maps:
enabling time-to-live evictor using XML <?xml version="1.0" encoding="UTF-8"?> <objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd" xmlns="http://ibm.com/ws/objectgrid/config"> <objectGrids> <objectGrid name="grid1"> <backingMap name="map1" ttlEvictorType="NONE" /> <backingMap name="map2" ttlEvictorType="LAST_ACCESS_TIME|LAST_UPDATE_TIME" timeToLive="1800" /> <backingMap name="map3" ttlEvictorType="CREATION_TIME" timeToLive="1200" /> </objectgrid> </objectGrids>
The preceding example shows that the map1 BackingMap instance uses a NONE TTL evictor type. The map2 BackingMap instance uses either a LAST_ACCESS_TIME or LAST_UPDATE_TIME TTL evictor type – specify only one or the other of these settings – and has a time-to-live value of 1800 seconds, or 30 minutes. The map3 BackingMap instance is defined to use a CREATION_TIME TTL evictor type and has a time-to-live value of 1200 seconds, or 20 minutes.
Parent topic:
Plug-ins for evicting cache objects
Related concepts
Plug-in evictor performance best practices