cacheserverservice.java

java 写的一个新闻发布系统

package org.jahia.services.htmlcache;

/**
 * Title:        Jahia
 * Description:  This is the generic HTML cache server service interface. It will
 * be implemented by various versions, notably in-memory and on-disk implementation
 * that will offer various tradeoff between speed, startup time and memory
 * consumption.
 * Copyright:    Copyright (c) 2002
 * Company:      Jahia
 * @author Serge Huber
 * @version 1.0
 */

import org.jahia.services.JahiaInitializableService;

public abstract class CacheServerService extends JahiaInitializableService {

    /**
     * Retrieves the cache entry for the specified cache entry key.
     *
     * @param pageID the first key is the pageID, which is the main key.
     * @param userName the user to which this cache entry belongs to. This is
     * necessary since page content varies between users.
     * @param userAgent an identifier for the browser. This is needed because a
     * lot of template developper have the (bad) habbit of detecting browsers to
     * generate HTML so we have to use this as a key
     *
     * @return a CacheEntry object that contains all the data as well as metadata
     * about the entry.
     */
    public abstract CacheEntry getEntry(String pageID,
                                        String userName,
                                        String userAgent);

    /**
     * Sets a new or existing cache entry to the object passed in parameter used
     * the combination of the three keys : pageID + userNAme + userAgent.
     *
     * @param pageID the first key is the pageID, which is the main key.
     * @param userName the user to which this cache entry belongs to. This is
     * necessary since page content varies between users.
     * @param userAgent an identifier for the browser. This is needed because a
     * lot of template developper have the (bad) habbit of detecting browsers to
     * generate HTML so we have to use this as a key
     * @param entry the CacheEntry object containing the content data as well
     * as the metadata for it.
     */
    public abstract void setEntry(String pageID,
                                  String userName,
                                  String userAgent,
                                  CacheEntry entry);

    /**
     * Retrieves a single property of a cache entry, corresponding to the
     * combination of the three keys (pageID + userName + userAgent) and the
     * property name.
     *
     * @param pageID the first key is the pageID, which is the main key.
     * @param userName the user to which this cache entry belongs to. This is
     * necessary since page content varies between users.
     * @param userAgent an identifier for the browser. This is needed because a
     * lot of template developper have the (bad) habbit of detecting browsers to
     * generate HTML so we have to use this as a key
     * @param propertyName the name of the property to retrieve in the Cache
     * entry.
     *
     * @return the Object value of the property, or null if the property doesn't
     * exist...
     */
    public abstract Object getEntryProperty(String pageID,
                                            String userName,
                                            String userAgent,
                                            String propertyName);

    /**
     * Set a single property of a cache entry, corresponding to the combination
     * of the three keys (pageID + userName + userAgent) and the property name.
     * If the entry does not exist it is also created.
     *
     * @param pageID the first key is the pageID, which is the main key.
     * @param userName the user to which this cache entry belongs to. This is
     * necessary since page content varies between users.
     * @param userAgent an identifier for the browser. This is needed because a
     * lot of template developper have the (bad) habbit of detecting browsers to
     * generate HTML so we have to use this as a key
     * @param propertyName the name of the property to set in the Cache
     * entry.
     * @param propertyValue the value of the property to set
     */
    public abstract void setEntryProperty(String pageID,
                                          String userName,
                                          String userAgent,
                                          String propertyName,
                                          Object propertyValue);


    /**
     * Retrieves the HTML content in the cache server indexed by the combination
     * of the three keys. This is actually a shortcut method that accesses the
     * CacheEntry.getContentBody property
     *
     * @param pageID the first key is the pageID, which is the main key.
     * @param userName the user to which this cache entry belongs to. This is
     * necessary since page content varies between users.
     * @param userAgent an identifier for the browser. This is needed because a
     * lot of template developper have the (bad) habbit of detecting browsers to
     * generate HTML so we have to use this as a key
     *
     * @return the HTML content string corresponding to the combination of the
     * three keys.
     */
    public abstract String getContentBody(String pageID,
                                          String userName,
                                          String userAgent);

    /**
     * Creates or updates an entry in the cache server. Use this to associate
     * a cache entry identified by the combination of three keys with the
     * specified HTML content. This is actually a shortcut method that accesses
     * the CacheEntry.setContentBody property
     *
     * @param pageID the first key is the pageID, which is the main key.
     * @param userName the user to which this cache entry belongs to. This is
     * necessary since page content varies between users.
     * @param userAgent an identifier for the browser. This is needed because a
     * lot of template developper have the (bad) habbit of detecting browsers to
     * generate HTML so we have to use this as a key
     * @param content a string containing the content to store at the
     * index specified by the keys.
     */
    public abstract void setContentBody(String pageID,
                                        String userName,
                                        String userAgent,
                                        String content);

    /**
     * Removes the cache entry specified by the combination of the three keys.
     * @param pageID the first key is the pageID, which is the main key.
     * @param userName the user to which this cache entry belongs to. This is
     * necessary since page content varies between users.
     * @param userAgent an identifier for the browser. This is needed because a
     * lot of template developper have the (bad) habbit of detecting browsers to
     * generate HTML so we have to use this as a key
     * @return a boolean specifying if the entry was successfully removed (this
     * can fail for example if the entry did not exist).
     */
    public abstract boolean removeEntry(String pageID,
                                        String userName,
                                        String userAgent);

    /**
     * Flushes all caches entries that start with the pageID identifier and the
     * username.
     * Note : this deletes all the user agents entries for a given page and
     * user.
     * @param pageID the pageID to look for in the cache
     * @param userName the user for which to delete the page entry.
     * @return a boolean specifying if the entries were successfully removed,
     * may return false if no entries existed to start with.
     */
    public abstract boolean removeEntry(String pageID, String userName);

    /**
     * Flushes all caches entries that start with the pageID identifier.
     * @param pageID the pageID to look for in the cache
     * @return a boolean specifying if the entries were successfully removed,
     * may return false if no entries existed to start with.
     */
    public abstract boolean removeEntry(String pageID);

    /**
     * Flushes all cache entries for a certain user.
     * @param userName name of the user
     * @return a boolean specifying if the entries were successfully removed,
     * may return false if no entries existed to start with.
     */
    public abstract boolean removeUserEntries(String userName);


    /**
     * Completely destroys the cache server's content. All existing content will
     * be removed. Use this with caution.
     */
    public abstract void flushCache();

    /**
     * Returns the number of entries in the output cache
     * @return an integer representing the total number of entries in the cache
     */
    public abstract int size();

    /**
     * Returns the maximum size allowed for the cache
     * @return an integer representing the maximum cache size. Returns -1 if
     * there is no limit set.
     */
    public abstract int getMaxSize();

}