cache.java

oscache-2.4.1-full

    /**
     * Retrieves the currently configured <code>PersistenceListener</code>.
     *
     * @return the cache's <code>PersistenceListener</code>, or <code>null</code>
     * if no listener is configured.
     */
    public PersistenceListener getPersistenceListener() {
        return cacheMap.getPersistenceListener();
    }

    /**
     * Register a listener for Cache events. The listener must implement
     * one of the child interfaces of the {@link CacheEventListener} interface.
     *
     * @param listener  The object that listens to events.
     * @since 2.4
     */
    public void addCacheEventListener(CacheEventListener listener) {
        // listenerList.add(CacheEventListener.class, listener);
        listenerList.add(listener.getClass(), listener);
    }
    
    /**
     * Register a listener for Cache events. The listener must implement
     * one of the child interfaces of the {@link CacheEventListener} interface.
     *
     * @param listener  The object that listens to events.
     * @param clazz the type of the listener to be added
     * @deprecated use {@link #addCacheEventListener(CacheEventListener)}
     */
    public void addCacheEventListener(CacheEventListener listener, Class clazz) {
        if (CacheEventListener.class.isAssignableFrom(clazz)) {
            listenerList.add(clazz, listener);
        } else {
            log.error("The class '" + clazz.getName() + "' is not a CacheEventListener. Ignoring this listener.");
        }
    }
    
    /**
     * Returns the list of all CacheEventListeners.
     * @return the CacheEventListener's list of the Cache
     */
    public EventListenerList getCacheEventListenerList() {
        return listenerList;
    }

    /**
     * Cancels any pending update for this cache entry. This should <em>only</em>
     * be called by the thread that is responsible for performing the update ie
     * the thread that received the original {@link NeedsRefreshException}.<p/>
     * If a cache entry is not updated (via {@link #putInCache} and this method is
     * not called to let OSCache know the update will not be forthcoming, subsequent
     * requests for this cache entry will either block indefinitely (if this is a new
     * cache entry or cache.blocking=true), or forever get served stale content. Note
     * however that there is no harm in cancelling an update on a key that either
     * does not exist or is not currently being updated.
     *
     * @param key The key for the cache entry in question.
     * @throws IllegalStateException if the cache entry isn't in the state UPDATE_IN_PROGRESS
     */
    public void cancelUpdate(String key) {
        EntryUpdateState state;

        if (key != null) {
            synchronized (updateStates) {
                state = (EntryUpdateState) updateStates.get(key);

                if (state != null) {
                    synchronized (state) {
                        int usageCounter = state.cancelUpdate();
                        state.notify();
                        
                        checkEntryStateUpdateUsage(key, state, usageCounter);
                    }
                } else {
                    if (log.isErrorEnabled()) {
                        log.error("internal error: expected to get a state from key [" + key + "]");
                    }
                }
            }
        }
    }

    /**
     * Utility method to check if the specified usage count is zero, and if so remove the corresponding EntryUpdateState from the updateStates. This is designed to factor common code.
     * 
     * Warning: This method should always be called while holding both the updateStates field and the state parameter
     * @throws Exception
     */
    private void checkEntryStateUpdateUsage(String key, EntryUpdateState state, int usageCounter) {
        //Clean up the updateStates map to avoid a memory leak once no thread is using this EntryUpdateState instance anymore.
        if (usageCounter == 0) {
            EntryUpdateState removedState = (EntryUpdateState) updateStates.remove(key);
            if (state != removedState) {
                if (log.isErrorEnabled()) {
                    try {
                        throw new Exception("OSCache: internal error: removed state [" + removedState + "] from key [" + key + "] whereas we expected [" + state + "]");
                    } catch (Exception e) {
                        log.error(e);
                    }
                }
            }
        }
    }

    /**
     * Flush all entries in the cache on the given date/time.
     *
     * @param date The date at which all cache entries will be flushed.
     */
    public void flushAll(Date date) {
        flushAll(date, null);
    }

    /**
     * Flush all entries in the cache on the given date/time.
     *
     * @param date The date at which all cache entries will be flushed.
     * @param origin The origin of this flush request (optional)
     */
    public void flushAll(Date date, String origin) {
        flushDateTime = date;

        if (listenerList.getListenerCount() > 0) {
            dispatchCachewideEvent(CachewideEventType.CACHE_FLUSHED, date, origin);
        }
    }

    /**
     * Flush the cache entry (if any) that corresponds to the cache key supplied.
     * This call will flush the entry from the cache and remove the references to
     * it from any cache groups that it is a member of. On completion of the flush,
     * a <tt>CacheEntryEventType.ENTRY_FLUSHED</tt> event is fired.
     *
     * @param key The key of the entry to flush
     */
    public void flushEntry(String key) {
        flushEntry(key, null);
    }

    /**
     * Flush the cache entry (if any) that corresponds to the cache key supplied.
     * This call will mark the cache entry as flushed so that the next access
     * to it will cause a {@link NeedsRefreshException}. On completion of the
     * flush, a <tt>CacheEntryEventType.ENTRY_FLUSHED</tt> event is fired.
     *
     * @param key The key of the entry to flush
     * @param origin The origin of this flush request (optional)
     */
    public void flushEntry(String key, String origin) {
        flushEntry(getCacheEntry(key, null, origin), origin);
    }

    /**
     * Flushes all objects that belong to the supplied group. On completion
     * this method fires a <tt>CacheEntryEventType.GROUP_FLUSHED</tt> event.
     *
     * @param group The group to flush
     */
    public void flushGroup(String group) {
        flushGroup(group, null);
    }

    /**
     * Flushes all unexpired objects that belong to the supplied group. On
     * completion this method fires a <tt>CacheEntryEventType.GROUP_FLUSHED</tt>
     * event.
     *
     * @param group The group to flush
     * @param origin The origin of this flush event (optional)
     */
    public void flushGroup(String group, String origin) {
        // Flush all objects in the group
        Set groupEntries = cacheMap.getGroup(group);

        if (groupEntries != null) {
            Iterator itr = groupEntries.iterator();
            String key;
            CacheEntry entry;

            while (itr.hasNext()) {
                key = (String) itr.next();
                entry = (CacheEntry) cacheMap.get(key);

                if ((entry != null) && !entry.needsRefresh(CacheEntry.INDEFINITE_EXPIRY)) {
                    flushEntry(entry, NESTED_EVENT);
                }
            }
        }

        if (listenerList.getListenerCount() > 0) {
            dispatchCacheGroupEvent(CacheEntryEventType.GROUP_FLUSHED, group, origin);
        }
    }

    /**
     * Flush all entries with keys that match a given pattern
     *
     * @param  pattern The key must contain this given value
     * @deprecated For performance and flexibility reasons it is preferable to
     * store cache entries in groups and use the {@link #flushGroup(String)} method
     * instead of relying on pattern flushing.
     */
    public void flushPattern(String pattern) {
        flushPattern(pattern, null);
    }

    /**
     * Flush all entries with keys that match a given pattern
     *
     * @param  pattern The key must contain this given value
     * @param origin The origin of this flush request
     * @deprecated For performance and flexibility reasons it is preferable to
     * store cache entries in groups and use the {@link #flushGroup(String, String)}
     * method instead of relying on pattern flushing.
     */
    public void flushPattern(String pattern, String origin) {
        // Check the pattern
        if ((pattern != null) && (pattern.length() > 0)) {
            String key = null;
            CacheEntry entry = null;
            Iterator itr = cacheMap.keySet().iterator();

            while (itr.hasNext()) {
                key = (String) itr.next();

                if (key.indexOf(pattern) >= 0) {
                    entry = (CacheEntry) cacheMap.get(key);

                    if (entry != null) {
                        flushEntry(entry, origin);
                    }
                }
            }

            if (listenerList.getListenerCount() > 0) {
                dispatchCachePatternEvent(CacheEntryEventType.PATTERN_FLUSHED, pattern, origin);
            }
        } else {
            // Empty pattern, nothing to do
        }
    }

    /**
     * Put an object in the cache specifying the key to use.
     *
     * @param key       Key of the object in the cache.
     * @param content   The object to cache.
     */
    public void putInCache(String key, Object content) {
        putInCache(key, content, null, null, null);
    }

    /**
     * Put an object in the cache specifying the key and refresh policy to use.
     *
     * @param key       Key of the object in the cache.
     * @param content   The object to cache.
     * @param policy   Object that implements refresh policy logic
     */
    public void putInCache(String key, Object content, EntryRefreshPolicy policy) {
        putInCache(key, content, null, policy, null);
    }

    /**
     * Put in object into the cache, specifying both the key to use and the
     * cache groups the object belongs to.
     *
     * @param key       Key of the object in the cache
     * @param content   The object to cache
     * @param groups    The cache groups to add the object to
     */
    public void putInCache(String key, Object content, String[] groups) {
        putInCache(key, content, groups, null, null);
    }

    /**
     * Put an object into the cache specifying both the key to use and the
     * cache groups the object belongs to.
     *
     * @param key       Key of the object in the cache
     * @param groups    The cache groups to add the object to
     * @param content   The object to cache
     * @param policy    Object that implements the refresh policy logic
     */
    public void putInCache(String key, Object content, String[] groups, EntryRefreshPolicy policy, String origin) {
        CacheEntry cacheEntry = this.getCacheEntry(key, policy, origin);
        boolean isNewEntry = cacheEntry.isNew();

        // [CACHE-118] If we have an existing entry, create a new CacheEntry so we can still access the old one later
        if (!isNewEntry) {
            cacheEntry = new CacheEntry(key, policy);
        }

        cacheEntry.setContent(content);
        cacheEntry.setGroups(groups);
        cacheMap.put(key, cacheEntry);

        // Signal to any threads waiting on this update that it's now ready for them
        // in the cache!
        completeUpdate(key);

        if (listenerList.getListenerCount() > 0) {
            CacheEntryEvent event = new CacheEntryEvent(this, cacheEntry, origin);

            if (isNewEntry) {
                dispatchCacheEntryEvent(CacheEntryEventType.ENTRY_ADDED, event);
            } else {
                dispatchCacheEntryEvent(CacheEntryEventType.ENTRY_UPDATED, event);
            }
        }
    }

    /**
     * Unregister a listener for Cache events.
     *
     * @param listener  The object that currently listens to events.
     * @param clazz  The registrated class of listening object.
     * @deprecated use instead {@link #removeCacheEventListener(CacheEventListener)}
     */
    public void removeCacheEventListener(CacheEventListener listener, Class clazz) {
        listenerList.remove(clazz, listener);
    }

    /**
     * Unregister a listener for Cache events.
     *
     * @param listener  The object that currently listens to events.
     * @since 2.4
     */
    public void removeCacheEventListener(CacheEventListener listener) {
        // listenerList.remove(CacheEventListener.class, listener);
        listenerList.remove(listener.getClass(), listener);
    }

    /**
     * Get an entry from this cache or create one if it doesn't exist.
     *