## org.w3c.www.protocol.http.cache
Class CacheFilter

    java.lang.Object
      |
      +--org.w3c.www.protocol.http.cache.CacheFilter

Direct Known Subclasses:
  PushCacheFilter

public class CacheFilter
extends java.lang.Object
implements PropRequestFilter, PropertyMonitoring

Field Summary
`static java.lang.String` `CACHE_CONNECTED_P` Name of the property enabling the connected/disconnected mode
`static java.lang.String` `CACHE_SIZE_P` The name of the properties indicating the size of the cache (in bytes).
`protected boolean` `connected`
`protected boolean` `debug`
`static java.lang.String` `DEBUG_P` Name of the property indicating if the cache is in debug mode.
`protected java.io.File` `directory`
`protected java.util.Hashtable` `precache`
`protected ObservableProperties` `props` The properties we initialized ourself from.
`protected CacheSerializer` `serializer`
`static java.lang.String` `SERIALIZER_P`
`protected boolean` `shared`
`static java.lang.String` `SHARED_P` Name of the property indicating if this cache is shared.
`protected long` `size`
`static java.lang.String` `STATE_NOCACHE` The state used to disable that filter per request.
`static java.lang.String` `STATE_ORIGREQ` Name of the request state used tokeep track of original request
`static java.lang.String` `STATE_REVALIDATION` Name of the request state that marks a request as being a revalidation.
`static java.lang.String` `STATE_WARNINGS` Name of the request state used to collect warnings.
`protected CacheStore` `store`
`protected CacheSweeper` `sweeper`
`static java.lang.String` `SWEEPER_P`
`protected java.util.Hashtable` `uritable`
`protected CacheValidator` `validator`
`static java.lang.String` `VALIDATOR_P`
`protected static HttpWarning` `WARN_DISCONNECTED` The HTTP warning used to notify of a disconnected cache.
`protected static HttpWarning` `WARN_HEURISTIC` The HTTP warning used to indicate a heuristic expiration time.
`protected static HttpWarning` `WARN_STALE` The HTTP warning used to mark invalid entries

Constructor Summary
`CacheFilter()`

Method Summary
`protected void` `addWarning(Request request, HttpWarning warning)` Add a warning, to be emitted at reply time.
`boolean` `canCache(Request req, Reply rep)` Checks if, according to the headers of the reply, an entity may be cached or not, it decorates also the reply
`boolean` `canStore(Request req, Reply rep)` Checks if, according to the headers of a reply we can store the resource.
`boolean` `canUseCache(Request req)` check if we can use the cache or not for this request It marks the request as being not cachable if false.
`protected void` `cleanUpload(CachedResource cr)` do what is needed when an upload is done! ie: remove from the precache and put in the store
`boolean` `exceptionFilter(Request request, HttpException ex)` This filter handle exceptions.
`CacheSerializer` `getSerializer()` return the serializer used by the cache
`CacheStore` `getStore()`
`CacheSweeper` `getSweeper()` return the cache sweeper used by the cache
`CacheValidator` `getValidator()` return the cache validator used by the cache
`Reply` `ingoingFilter(Request request)` The request pre-processing hook.
`void` `initialize(HttpManager manager)` Initialize this filter, using the provided manager.
`boolean` `isConnected()` is the cache connected?
`boolean` `isShared()` is the cache shared?
`Reply` `outgoingFilter(Request request, Reply reply)` The request post-processing hook.
`boolean` `propertyChanged(java.lang.String name)` Property monitoring for the CacheFilter.
`void` `pushDocument(Request request, Reply reply)` Push a document in the cache.
`protected Request` `setRequestRevalidation(CachedResource res, Request req)` Modify a request to ask for a revalidation
`protected void` `setWarnings(Request request, Reply reply)` Copy all warnings colllected into the given reply.
`void` `sync()` Synchronized any pending state into stable storage.
`protected void` `trace(Request request, java.lang.String msg)` Display some output, related to the request (used for debugging)

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### SERIALIZER_P

    public static final java.lang.String SERIALIZER_P

### SWEEPER_P

    public static final java.lang.String SWEEPER_P

### VALIDATOR_P

    public static final java.lang.String VALIDATOR_P

### CACHE_CONNECTED_P

    public static final java.lang.String CACHE_CONNECTED_P

  Name of the property enabling the connected/disconnected mode

### SHARED_P

    public static final java.lang.String SHARED_P

  Name of the property indicating if this cache is shared.

  This property defaults to true.

### CACHE_SIZE_P

    public static final java.lang.String CACHE_SIZE_P

  The name of the properties indicating the size of the cache (in bytes). This property will give the value of the disk-based cache size. This value only takes into account the size of the entities saved, not the size of the associated headers, and not the physical size on the disc.

  This property defaults to 5000000 bytes.

### DEBUG_P

    public static final java.lang.String DEBUG_P

  Name of the property indicating if the cache is in debug mode.

  This property defaults to false.

### STATE_NOCACHE

    public static final java.lang.String STATE_NOCACHE

  The state used to disable that filter per request. Also set by the cache if the request cannot be fullfilled by caches, as detected by this filter.

### STATE_WARNINGS

    public static final java.lang.String STATE_WARNINGS

  Name of the request state used to collect warnings.

### STATE_ORIGREQ

    public static final java.lang.String STATE_ORIGREQ

  Name of the request state used tokeep track of original request

### STATE_REVALIDATION

    public static final java.lang.String STATE_REVALIDATION

  Name of the request state that marks a request as being a revalidation.

### WARN_DISCONNECTED

    protected static HttpWarning WARN_DISCONNECTED

  The HTTP warning used to notify of a disconnected cache.

### WARN_STALE

    protected static HttpWarning WARN_STALE

  The HTTP warning used to mark invalid entries

### WARN_HEURISTIC

    protected static HttpWarning WARN_HEURISTIC

  The HTTP warning used to indicate a heuristic expiration time.

### props

    protected ObservableProperties props

  The properties we initialized ourself from.

### validator

    protected CacheValidator validator

### store

    protected CacheStore store

### sweeper

    protected CacheSweeper sweeper

### serializer

    protected CacheSerializer serializer

### connected

    protected boolean connected

### shared

    protected boolean shared

### size

    protected long size

### directory

    protected java.io.File directory

### debug

    protected boolean debug

### precache

    protected java.util.Hashtable precache

### uritable

    protected java.util.Hashtable uritable

Constructor Detail

### CacheFilter

    public CacheFilter()

Method Detail

### getSweeper

    public CacheSweeper getSweeper()

  return the cache sweeper used by the cache
  Returns:
    an instance of CacheSweeper

### getSerializer

    public CacheSerializer getSerializer()

  return the serializer used by the cache
  Returns:
    an instance of Serializer

### getValidator

    public CacheValidator getValidator()

  return the cache validator used by the cache
  Returns:
    an instance of CacheValidator

### isShared

    public boolean isShared()

  is the cache shared?
  Returns:
    a boolean, true if the cache is shared

### isConnected

    public boolean isConnected()

  is the cache connected?
  Returns:
    a boolean, true if the cache is connected

### trace

    protected final void trace(Request request,
                               java.lang.String msg)

  Display some output, related to the request (used for debugging)

### addWarning

    protected void addWarning(Request request,
                              HttpWarning warning)

  Add a warning, to be emitted at reply time. The cache filter keeps track, through a specific piece of request state of the warnings to be emitted at reply time (if any).

  During request processing, cached resources can add any kind of warnings, which will be collected and forwarded back to the reply.

  Parameters:
    `request` - The request being process, and whose reply requires some warnings.
    `warning` - The warning to be emitted if ever we use the cache filter to answer the above request.

### setWarnings

    protected final void setWarnings(Request request,
                                     Reply reply)

  Copy all warnings colllected into the given reply. This method collects all HTTP warnings saved during request processing and create (if needed) the approporiate warning header in the given reply.
  Parameters:
    `request` - The request that has been processed by the cache filter.
    `reply` - The reply that has been constructed from the cache.
  See Also:
    `addWarning(org.w3c.www.protocol.http.Request, org.w3c.www.http.HttpWarning)`

### canUseCache

    public boolean canUseCache(Request req)

  check if we can use the cache or not for this request It marks the request as being not cachable if false.
  Parameters:
    `a` - request, the incoming client-side request
  Returns:
    a boolean, true if we can use the cache

### canCache

    public boolean canCache(Request req,
                            Reply rep)

  Checks if, according to the headers of the reply, an entity may be cached or not, it decorates also the reply
  Parameters:
    `a` - request, the client side request
    `a` - reply, the client side reply
  Returns:
    a boolean, true if the resource can be cached

### canStore

    public boolean canStore(Request req,
                            Reply rep)

  Checks if, according to the headers of a reply we can store the resource. Note that a resource may be cachable, but not storable (memory cache) although is MUST do its best to get rid of it asap, in our case we just don't store it!
  Parameters:
    `a` - request, the client side request
    `a` - reply, the client side reply
  Returns:
    a boolean, true if the resource can be stored by the cache

### setRequestRevalidation

    protected Request setRequestRevalidation(CachedResource res,
                                             Request req)

  Modify a request to ask for a revalidation
  Parameters:
    `the` - resource to be revalidated
    `request,` - the original request to be modified

### ingoingFilter

    public Reply ingoingFilter(Request request)
                        throws HttpException

  The request pre-processing hook. Before each request is launched, all filters will be called back through this method. They will generally set up additional request header fields to enhance the request.
  Parameters:
    `request` - The request that is about to be launched.
  Returns:
    An instance of Reply if the filter could handle the request, or null if processing should continue normally.
  Throws:
    HttpException - If the filter is supposed to fulfill the request, but some error happened during that processing.

### exceptionFilter

    public boolean exceptionFilter(Request request,
                                   HttpException ex)

  This filter handle exceptions.
  Parameters:
    `request` - The request that triggered the exception.
    `ex` - The triggered exception.
  Returns:
    Always false.

### outgoingFilter

    public Reply outgoingFilter(Request request,
                                Reply reply)
                         throws HttpException

  The request post-processing hook. After each request has been replied to by the target server (be it a proxy or the actual origin server), each filter's outgoingFilter method is called.

  It gets the original request, and the actual reply as a parameter, and should return whatever reply it wants the caller to get.

  Parameters:
    `request` - The original (handled) request.
    `reply` - The reply, as emited by the target server, or constructed by some other filter.
  Throws:
    HttpException - If the reply emitted by the server is not a valid HTTP reply.

### sync

    public void sync()

  Description copied from interface: RequestFilter
  Synchronized any pending state into stable storage. If the filter maintains some in-memory cached state, this method should ensure that cached data are saved to stable storage.

### propertyChanged

    public boolean propertyChanged(java.lang.String name)

  Property monitoring for the CacheFilter. The CacheFilter allows you to dynamically (typically through the property setter) change the class of the sweeper, the validator, the size...
  Specified by:
    propertyChanged in interface PropertyMonitoring
  Parameters:
    `name` - The name of the property that has changed.
  Returns:
    A boolean, true if the change was made, false otherwise.

### pushDocument

    public void pushDocument(Request request,
                             Reply reply)

  Push a document in the cache. The caller has to forge a a request and a reply before being able to make something enter the cache. The request should provide at least:
  URL
  The URL (key for cache lookups)
  Method
  The method that was "applied" to URL to get forged reply.

  It is recommended that the reply provides at least the following informations:

  Status Code
  A valid HTTP/1.1 status code (probably 200)
  InputStream
  Containing the entity to be cached,
  EntityTag
  A valid entity tag for the document,
  CacheControl
  Appropriate HTTP/1.1 cache controls for that document,
  Mime headers
  At least a valid content type, and probably a content length (to check consistency with the reply body).

  ### cleanUpload

      protected void cleanUpload(CachedResource cr)

    do what is needed when an upload is done! ie: remove from the precache and put in the store
    Parameters:
      `the` - CachedResource to be moved.

  ### getStore

      public CacheStore getStore()

    Returns:
      the store used a CacheStore

  ### initialize

      public void initialize(HttpManager manager)
                      throws PropRequestFilterException

    Description copied from interface: PropRequestFilter
    Initialize this filter, using the provided manager. During initialization, it is up to the filter to install itself in the manager, by invoking the appropriate `setFilter` method.
    Specified by:
      initialize in interface PropRequestFilter
    Tags copied from interface: PropRequestFilter
    Parameters:
      `manager` - The HttpManager initializing the filter.
    Throws:
      PropRequestFilterException - If the filter couldn't be initialized properly.