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. 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.
TTL evictors are associated with BackingMap instances. The following snippet of code demonstrates how the BackingMap interface can be used to set the needed attributes so that when each entry is created, it has an expiration time set to ten minutes after it was created.
enabling time-to-live evictor programmaticallyimport 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.
If an application requires that the expiration time be set to the last access time plus ten minutes, one line of the preceding code must be changed. The argument that is passed to the setTtlEvictorType method is changed 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.
When the TTLType.LAST_ACCESS_TIME argument is used, the ObjectMap and JavaMap interfaces can be used 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 the preceding snippet of code was used to set the ttlType attribute to LAST_ACCESS_TIME and the time to live value was set to ten minutes on the BackingMap instance. 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. 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.
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. 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 to 1800.
The previous example shows two map entries being inserted in the myMap map for key values key1 and key2. At a later point in time the application from a new thread might want to update these map entries with new map values. However, the application wants to retain 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 warns you that an IllegalStateException exception results if the BackingMap.getTtlEvictorType() method returns anything other than the TTLType.LAST_ACCESS_TIME value. ObjectMap and JavaMap can only be used to override the time to live value when you are using the LAST_ACCESS_TIME TTL evictor type. This method cannot be used to override the time to live value when you are using the CREATION_TIME TTL evictor type or the NONE TTL evictor type.
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" timeToLive="1800" /> <backingMap name="map3" ttlEvictorType="CREATION_TIME" timeToLive="1200" /> </objectgrid> </objectGrids>
The preceding example shows that the map1 BackingMap uses a NONE TTL evictor type. The map2 BackingMap uses a LAST_ACCESS_TIME TTL evictor type and has a time to live value of 1800 seconds, or 30 minutes. The map3 BackingMap is defined to use a CREATION_TIME TTL evictor type and has a time to live value of 1200 seconds, or 20 minutes.