com.ibm.websphere.cache

Interface DistributedNioMap

  • All Known Implementing Classes:
    DistributedObjectCache


    public interface DistributedNioMap
    The DistributedNioMap is a high performance map specifically designed for storing java.nio.Buffer objects. When a cached object is being removed from cache and the cached object implements the DistributedNioMapObject interface, the DistributedNioMapObject.release() method will be called to notify the cache object it is being removed from cache.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void addAlias(java.lang.Object key, java.lang.Object[] aliasArray)
      Adds an alias for the given key in the cache's mapping table.
      boolean addChangeListener(ChangeListener listener)
      addChangeListener - adds a change listener for this DistributedMap.
      boolean addInvalidationListener(InvalidationListener listener)
      addInvalidationListener - adds an invalidation listener for this DistributeMap.
      boolean addPreInvalidationListener(PreInvalidationListener listener)
      addPreInvalidationListener - adds a pre-invalidation listener for this DistributeMap.
      void clear()
      Removes all mappings from this DistributedNioMap.
      boolean containsKey(java.lang.Object key, boolean includeDiskCache)
      Returns true if this map contains mapping for the specified key.
      boolean enableListener(boolean enable)
      enableListener - enable or disable the invalidation and change listener support.
      CacheEntry getCacheEntry(java.lang.Object key)
      Returns the cache entry which maps the specified key.
      void invalidate(java.lang.Object key)
      Invalidates the given key.
      void invalidate(java.lang.Object key, boolean wait)
      Invalidates the given key.
      void invalidate(java.lang.Object key, boolean wait, boolean checkPreInvalidationListener)
      invalidate - invalidates the given key.
      boolean isEmpty(boolean includeDiskCache)
      Returns true if this map contains no key-value mappings.
      void put(java.lang.Object key, java.lang.Object value, java.lang.Object userMetaData, int priority, int timeToLive, int inactivityTime, int sharingPolicy, java.lang.Object[] dependencyIds, java.lang.Object[] alias)
      Associates the specified value with the specified key in this map.
      void put(java.lang.Object key, java.lang.Object value, java.lang.Object userMetaData, int priority, int timeToLive, int inactivityTime, int sharingPolicy, java.lang.Object[] dependencyIds, java.lang.Object[] alias, boolean skipMemoryAndWriteToDisk)
      Associates the specified value with the specified key in this map.
      void put(java.lang.Object key, java.lang.Object value, java.lang.Object userMetaData, int priority, int timeToLive, int sharingPolicy, java.lang.Object[] dependencyIds, java.lang.Object[] alias)
      Associates the specified value with the specified key in this map.
      CacheEntry putAndGet(java.lang.Object key, java.lang.Object value, java.lang.Object userMetaData, int priority, int timeToLive, int inactivityTime, int sharingPolicy, java.lang.Object[] dependencyIds, java.lang.Object[] alias)
      Associates the specified value with the specified key in this map.
      CacheEntry putAndGet(java.lang.Object key, java.lang.Object value, java.lang.Object userMetaData, int priority, int timeToLive, int sharingPolicy, java.lang.Object[] dependencyIds, java.lang.Object[] alias)
      Associates the specified value with the specified key in this map.
      void releaseLruEntries(int numOfEntries)
      Use this method to release LRU cache entries (regular objects or ByteByffers/MetaData).
      void removeAlias(java.lang.Object alias)
      Removes an alias from the cache's mapping table.
      boolean removeChangeListener(ChangeListener listener)
      removeChangeListener - removes a change listener for this DistributedMap.
      boolean removeInvalidationListener(InvalidationListener listener)
      removeInvalidationListener - removes an invalidation listener for this DistributedMap.
      boolean removePreInvalidationListener(PreInvalidationListener listener)
      removePreInvalidationListener - removes a pre-invalidation listener for this DistributedMap.
      int size(boolean includeDiskCache)
      Returns the total number of key-value mappings.
    • Method Detail

      • getCacheEntry

        CacheEntry getCacheEntry(java.lang.Object key)
        Returns the cache entry which maps the specified key. Returns null if specified key does not exist in cache's mapping table or the cache entry is in invalidated state.
        You must call CacheEntry.finish() when you are finished using the entry. This will release resources associated with this CacheEntry.
        Parameters:
        key - key whose associated value is to be returned.
        Returns:
        the cache entry to which maps the specified key, or null if the specified key does not exist or the cache entry is in invalidated state.
        Throws:
        java.lang.ClassCastException - if the key is not of an inappropriate type for this map. (Currently supports only type String)
        java.lang.NullPointerException - key is null and this map does not not permit null keys.
      • put

        void put(java.lang.Object key,
               java.lang.Object value,
               java.lang.Object userMetaData,
               int priority,
               int timeToLive,
               int sharingPolicy,
               java.lang.Object[] dependencyIds,
               java.lang.Object[] alias)
        Associates the specified value with the specified key in this map. If specified key does not exists, put new cache entry to cache's mapping table. If specified key exists, replaces the old cache entry in cache's mapping table with new one and then delete the old cache entry after reference count becomes zero.
        Parameters:
        key - key with which the specified value is to be associated.
        value - value to be associated with the specified key.
        userMetaData - userMetaData for the cache entry.
        priority - the priority value for the cache entry. entries with higher priority will remain in the cache longer than those with a lower priority in the case of cache overflow.
        timeToLive - the time in seconds that the cache entry should remain in the cache
        sharingPolicy - how the cache entry should be shared in a cluster. values are EntryInfo.NOT_SHARED, EntryInfo.SHARED_PUSH, and EntryInfo.SHARED_PUSH_PULL.
        dependencyIds - an optional set of dependency ids to associate with the cache entry
        alias - an optional set of alias ids to associate with the cache entry
        Throws:
        java.lang.UnsupportedOperationException - if the put operation is not supported by this map.
        java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.
        java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.
        java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.
        See Also:
        DistributedNioMapObject
      • put

        void put(java.lang.Object key,
               java.lang.Object value,
               java.lang.Object userMetaData,
               int priority,
               int timeToLive,
               int inactivityTime,
               int sharingPolicy,
               java.lang.Object[] dependencyIds,
               java.lang.Object[] alias)
        Associates the specified value with the specified key in this map. If specified key does not exists, put new cache entry to cache's mapping table. If specified key exists, replaces the old cache entry in cache's mapping table with new one and then delete the old cache entry after reference count becomes zero.
        Parameters:
        key - key with which the specified value is to be associated.
        value - value to be associated with the specified key.
        userMetaData - userMetaData for the cache entry.
        priority - the priority value for the cache entry. entries with higher priority will remain in the cache longer than those with a lower priority in the case of cache overflow.
        timeToLive - the time in seconds that the cache entry should remain in the cache
        inactivityTime - the time in seconds that a cache entry should remain in the cache if not accessed. inactivityTime is reset to 0 every time an entry is accessed.
        sharingPolicy - how the cache entry should be shared in a cluster. values are EntryInfo.NOT_SHARED, EntryInfo.SHARED_PUSH, and EntryInfo.SHARED_PUSH_PULL.
        dependencyIds - an optional set of dependency ids to associate with the cache entry
        alias - an optional set of alias ids to associate with the cache entry
        Throws:
        java.lang.UnsupportedOperationException - if the put operation is not supported by this map.
        java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.
        java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.
        java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.
        See Also:
        DistributedNioMapObject
      • put

        void put(java.lang.Object key,
               java.lang.Object value,
               java.lang.Object userMetaData,
               int priority,
               int timeToLive,
               int inactivityTime,
               int sharingPolicy,
               java.lang.Object[] dependencyIds,
               java.lang.Object[] alias,
               boolean skipMemoryAndWriteToDisk)
                 throws com.ibm.websphere.cache.exception.DynamicCacheException
        Associates the specified value with the specified key in this map. If specified key does not exists, put new cache entry to cache's mapping table. If specified key exists, replaces the old cache entry in cache's mapping table with new one and then delete the old cache entry after reference count becomes zero.
        Parameters:
        key - key with which the specified value is to be associated.
        value - value to be associated with the specified key.
        userMetaData - userMetaData for the cache entry.
        priority - the priority value for the cache entry. entries with higher priority will remain in the cache longer than those with a lower priority in the case of cache overflow.
        timeToLive - the time in seconds that the cache entry should remain in the cache
        inactivityTime - the time in seconds that a cache entry should remain in the cache if not accessed. inactivityTime is reset to 0 every time an entry is accessed.
        sharingPolicy - how the cache entry should be shared in a cluster. values are EntryInfo.NOT_SHARED, EntryInfo.SHARED_PUSH, and EntryInfo.SHARED_PUSH_PULL. If skipMemoryAndWriteToDisk is set to true, the sharing policy will be set to "not-shared".
        dependencyIds - an optional set of dependency ids to associate with the cache entry
        alias - an optional set of alias ids to associate with the cache entry
        skipMemoryAndWriteToDisk - if true, the cache entry will not put in the memory cache but written to disk cache directly. When getting the entry from the disk cache, the entry will not be promoted to the memory cache instead it will be passed it to the caller. In addition, the entry will not be replicated to other servers. The sharing policy will be set to "not-shared".
        Throws:
        java.lang.UnsupportedOperationException - if the put operation is not supported by this map.
        java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.
        java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.
        java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.
        com.ibm.websphere.cache.exception.DynamicCacheException - When skipMemoryAndWriteToDisk is set to true, the following exceptions which extend DynamicCacheException can occur: (1) DiskOffloadNotEnabledException The code detects that the disk offload feature for cache instance is not enabled. The put operation is aborted. (2) DiskIOException The code detects an unrecoverable disk IO exception when putting cache entry to the disk. The disk offload feature will be disabled. (3) DiskSizeOverLimitException The code detects out of disk space or the disk cache size has reached the limit of diskCacheSizeInGB. The put operation is aborted. (4) SerializationException The code detects a serialization exception when serializing the cache entry. The put operation is aborted. (5) DiskSizeInEntriesOverLimitException The disk cache size in entries has reached the limit of diskCacheSize. The put operation is aborted. (6) DiskCacheEntrySizeOverLimitException The disk cache entry size has reached the limit of diskCacheEntrySizeInMB. The put operation is aborted. (7) MiscellaneousException The code detects a runtime exception other than a disk IO exception. The put operation is aborted.
        See Also:
        DistributedNioMapObject, DiskOffloadNotEnabledException, DiskIOException, DiskSizeOverLimitException, SerializationException, DiskSizeInEntriesOverLimitException, DiskCacheEntrySizeOverLimitException, MiscellaneousException
      • putAndGet

        CacheEntry putAndGet(java.lang.Object key,
                           java.lang.Object value,
                           java.lang.Object userMetaData,
                           int priority,
                           int timeToLive,
                           int sharingPolicy,
                           java.lang.Object[] dependencyIds,
                           java.lang.Object[] alias)
        Associates the specified value with the specified key in this map. If specified key does not exists, put new cache entry to cache's mapping table. If specified key exists, replaces the old cache entry in cache's mapping table with new one and then delete the old cache entry after reference count becomes zero.
        Parameters:
        key - key with which the specified value is to be associated.
        value - value to be associated with the specified key.
        userMetaData - userMetaData for the cache entry.
        priority - the priority value for the cache entry. entries with higher priority will remain in the cache longer than those with a lower priority in the case of cache overflow.
        timeToLive - the time in seconds that the cache entry should remain in the cache
        sharingPolicy - how the cache entry should be shared in a cluster. values are EntryInfo.NOT_SHARED, EntryInfo.SHARED_PUSH, and EntryInfo.SHARED_PUSH_PULL.
        dependencyIds - an optional set of dependency ids to associate with the cache entry
        alias - an optional set of alias ids to associate with the cache entry
        Returns:
        The newly created CacheEntry. You must call CacheEntry.finish() when you are finished using the entry.
        Throws:
        java.lang.UnsupportedOperationException - if the put operation is not supported by this map.
        java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.
        java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.
        java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.
        See Also:
        DistributedNioMapObject
      • putAndGet

        CacheEntry putAndGet(java.lang.Object key,
                           java.lang.Object value,
                           java.lang.Object userMetaData,
                           int priority,
                           int timeToLive,
                           int inactivityTime,
                           int sharingPolicy,
                           java.lang.Object[] dependencyIds,
                           java.lang.Object[] alias)
        Associates the specified value with the specified key in this map. If specified key does not exists, put new cache entry to cache's mapping table. If specified key exists, replaces the old cache entry in cache's mapping table with new one and then delete the old cache entry after reference count becomes zero.
        Parameters:
        key - key with which the specified value is to be associated.
        value - value to be associated with the specified key.
        userMetaData - userMetaData for the cache entry.
        priority - the priority value for the cache entry. entries with higher priority will remain in the cache longer than those with a lower priority in the case of cache overflow.
        timeToLive - the time in seconds that the cache entry should remain in the cache
        inactivityTime - the time in seconds that a cache entry should remain in the cache if not accessed. inactivityTime is reset to 0 every time an entry is accessed.
        sharingPolicy - how the cache entry should be shared in a cluster. values are EntryInfo.NOT_SHARED, EntryInfo.SHARED_PUSH, and EntryInfo.SHARED_PUSH_PULL.
        dependencyIds - an optional set of dependency ids to associate with the cache entry
        alias - an optional set of alias ids to associate with the cache entry
        Returns:
        The newly created CacheEntry. You must call CacheEntry.finish() when you are finished using the entry.
        Throws:
        java.lang.UnsupportedOperationException - if the put operation is not supported by this map.
        java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.
        java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.
        java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.
        See Also:
        DistributedNioMapObject
      • invalidate

        void invalidate(java.lang.Object key,
                      boolean wait,
                      boolean checkPreInvalidationListener)
        invalidate - invalidates the given key. If the key is for a specific cache entry, then only that object is invalidated. If the key is for a dependency id, then all objects that share that dependency id will be invalidated.
        Parameters:
        key - the key which will be invalidated
        wait - if true, then the method will not complete until the invalidation has occured. if false, then the invalidation will occur in batch mode
        checkPreInvalidationListener - if true, first check with PreInvalidationListener to see if invalidation should occur. If false, bypass this check and invalidate immediately.
        See Also:
        PreInvalidationListener
      • invalidate

        void invalidate(java.lang.Object key,
                      boolean wait)
        Invalidates the given key. If the key is for a specific cache entry, then only that object is invalidated. If the key is for a dependency id, then all objects that share that dependency id will be invalidated.
        Parameters:
        key - the key which will be invalidated
        wait - if true, then the method will not complete until the invalidation has occured. if false, then the invalidation will occur in batch mode
      • invalidate

        void invalidate(java.lang.Object key)
        Invalidates the given key. If the key is for a specific cache entry, then only that object is invalidated. If the key is for a dependency id, then all objects that share that dependency id will be invalidated. This method is the same as using invalidate(key, true).
        Parameters:
        key - the key which will be invalidated
      • clear

        void clear()
        Removes all mappings from this DistributedNioMap.
      • addAlias

        void addAlias(java.lang.Object key,
                    java.lang.Object[] aliasArray)
        Adds an alias for the given key in the cache's mapping table. If the alias is already associated with another key, it will be changed to associate with the new key.
        Parameters:
        key - the key assoicated with alias
        aliasArray - the alias to use for lookups
        Throws:
        java.lang.IllegalArgumentException - if the key is not in the cache's mapping table.
      • removeAlias

        void removeAlias(java.lang.Object alias)
        Removes an alias from the cache's mapping table.
        Parameters:
        alias - the alias to move out of the cache's mapping table
      • releaseLruEntries

        void releaseLruEntries(int numOfEntries)
        Use this method to release LRU cache entries (regular objects or ByteByffers/MetaData).
        Parameters:
        numOfEntries - the number of cache entries to be released
      • size

        int size(boolean includeDiskCache)
        Returns the total number of key-value mappings. Returns size of memory map plus disk map if includeDiskCache is true. Returns size of memory map size if includeDiskCache is false.
        Parameters:
        includeDiskCache - true to get the size of the memory and disk maps; false to get the size of memory map.
        Returns:
        the number of key-value mappings in this map.
      • isEmpty

        boolean isEmpty(boolean includeDiskCache)
        Returns true if this map contains no key-value mappings. Checks both memory and disk maps if includeDiskCache is true. Check only memory cache if includeDiskCache is false.
        Parameters:
        includeDiskCache - true to check the memory and disk maps; false to check the memory map.
        Returns:
        true if this map contains no key-value mappings.
      • containsKey

        boolean containsKey(java.lang.Object key,
                          boolean includeDiskCache)
        Returns true if this map contains mapping for the specified key. Checks both memory and disk map if includeDiskCache is true. Check only memory map if includeDiskCache is false.
        Parameters:
        key - whose presence in this map is to be tested.
        includeDiskCache - true to check the specified key contained in the memory or disk maps; false to check the specified key contained in the memory map.
        Returns:
        true if this map contains a mapping for the specified key.
      • enableListener

        boolean enableListener(boolean enable)
        enableListener - enable or disable the invalidation and change listener support. You must call enableListener(true) before calling addInvalidationListner() or addChangeListener().
        Parameters:
        enable - - true to enable support for invalidation and change listeners or false to disable support for invalidation and change listeners
        Returns:
        boolean "true" means listener support was successfully enabled or disabled. "false" means this DistributedMap is configurated to use the listener's J2EE context for event notification and the callback registration failed. In this case, the caller's thread context will be used for event notification.
      • addInvalidationListener

        boolean addInvalidationListener(InvalidationListener listener)
        addInvalidationListener - adds an invalidation listener for this DistributeMap.
        Parameters:
        listener - the invalidation listener object
        Returns:
        boolean "true" means the invalidation listener was successfully added. "false" means either the passed listener object is null or listener support is not enable.
        See Also:
        removeInvalidationListener(com.ibm.websphere.cache.InvalidationListener)
      • removeInvalidationListener

        boolean removeInvalidationListener(InvalidationListener listener)
        removeInvalidationListener - removes an invalidation listener for this DistributedMap.
        Parameters:
        listener - the invalidation listener object
        Returns:
        boolean "true" means the invalidation listener was successfully removed. "false" means either passed listener object is null or listener support is not enable.
        See Also:
        addInvalidationListener(com.ibm.websphere.cache.InvalidationListener)
      • addChangeListener

        boolean addChangeListener(ChangeListener listener)
        addChangeListener - adds a change listener for this DistributedMap.
        Parameters:
        listener - the change listener object
        Returns:
        boolean "true" means the change listener was successfully added. "false" means either the passed listener object is null or listener support is not enable.
        See Also:
        removeChangeListener(com.ibm.websphere.cache.ChangeListener)
      • removeChangeListener

        boolean removeChangeListener(ChangeListener listener)
        removeChangeListener - removes a change listener for this DistributedMap.
        Parameters:
        listener - the change listener object
        Returns:
        boolean "true" means the change listener was successfully removed. "false" means either passed listener object is null or listener support is not enable.
        See Also:
        addChangeListener(com.ibm.websphere.cache.ChangeListener)
IBM WebSphere Application ServerTM
Release 9.0