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

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

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


Field Summary
static java.lang.String CACHE_CONNECTED_P
          Name of the property indicating wether the cache is connected or not.
static java.lang.String CACHE_DIRECTORY_P
          Name of the property giving the cache's directory.
static java.lang.String CACHE_SIZE_P
          The name of the properties indicating the size of the cache (in bytes).
protected static int CACHEDIR_SPLITS
          Number of sub-levels file system directories in the cache directory.
protected  boolean connected
          Is this cache connected ?
protected  boolean debug
          The debug flag.
static java.lang.String DEBUG_P
          Name of the property indicating if the cache is in debug mode.
protected  java.io.File directory
          The directory where the cache is stored.
protected  long expires_drift
          The expires drift.
static java.lang.String FILE_SIZE_RATIO_P
          Name of the property indicating the max size for files to be cached.
protected  double fileSizeRatio
          The file size quota.
static java.lang.String GARBAGE_COLLECTION_ENABLED_P
          Name of the property enabling garbage collection of the cache.
protected  boolean garbageCollectionEnabled
          Should we enable garbage collection of the cache ?
static java.lang.Integer HOW_HIT
          STATE_HOW value - Indicates request fulfilled through a hot.
static java.lang.Integer HOW_MISS
          STATE_HOW value - Indicates request fulfilled through a miss.
static java.lang.Integer HOW_REVALIDATION_FAILURE
          STATE_HOW value - indicates request fulfilled through unsucessfull revalidation.
static java.lang.Integer HOW_REVALIDATION_SUCCESS
          STATE_HOW value - indicates request fulfilled through sucessfull revalidation.
protected  ObservableProperties props
          The properties we initialized ourself from.
protected  boolean shared
          Is this cached shared ?
static java.lang.String SHARED_P
          Name of the property indicating if this cache is shared.
protected  int size
          The current cache size.
static java.lang.String STATE_CACHABLE
          Name of the property that indicates that the cache cab be used.
static java.lang.String STATE_HOW
          Logging state - for some logger to keep track of what's happening.
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_RESOURCE
           
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  cacheStatistics stats
          Our real time statistics.
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 request, Reply reply)
          Can the given reply to the given request be added to the cache.
 boolean canUseCache(Request request)
          Can the given request be fullfilled by the cache filter ? This method distinguishes two situations.
protected  boolean checkCacheDirectory(java.io.File dir)
           
 boolean exceptionFilter(Request request, HttpException ex)
          This filter doesn't handle exceptions.
 int getCacheSize()
          Get the total size allocated to the cache.
protected  java.io.File getFile(java.net.URL url)
          Get a file to save that URL in.
static java.lang.String getHow(Request request)
          Returns a String indicating what the cache did with that request.
 cacheStatistics getStatistics()
          Get the statistics repository associated with that filter.
protected  java.io.File getSubdirectory(int i)
           
 boolean hasResource(java.lang.String url)
          Does the cache knows about this resource ?
 Reply ingoingFilter(Request request)
           
 void initialize(HttpManager manager)
          Initialize a new reuqest manager.
 boolean isConnected()
          Is this cache connected to the net ?
 boolean isGarbageCollectionEnabled()
          Are we allow to run garbage collections at all ?
 boolean isShared()
          Is this cache shared among multiple users ?
 CachedResource loadResource(java.lang.String url)
          Try to load from the cache the resource's whose URL is gievn.
protected  void markUsed(CachedResource resource)
           
protected  void markUsed(CachedResource resource, int nsize)
           
protected  void markUsed(CachedResource resource, int osize, int nsize)
          Mark the given cached resource as having been used recently.
 Reply outgoingFilter(Request request, Reply reply)
           
 boolean propertyChanged(java.lang.String name)
          PropertyMonitoring implementation - Commit property changes.
 void pushDocument(Request request, Reply reply)
          Push a document in the cache.
 void removeResource(java.lang.String urlloc)
          Remove a resource from the cache.
protected  void setWarnings(Request request, Reply reply)
          Copy all warnings colllected into the given reply.
 void sync()
          Save all cache related infos to stable storage.
protected  void trace(Request request, java.lang.String msg)
           
protected  void updateCacheSpaceCounter(int delta)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CACHEDIR_SPLITS

protected static final int CACHEDIR_SPLITS
Number of sub-levels file system directories in the cache directory.

HOW_HIT

public static final java.lang.Integer HOW_HIT
STATE_HOW value - Indicates request fulfilled through a hot.

HOW_MISS

public static final java.lang.Integer HOW_MISS
STATE_HOW value - Indicates request fulfilled through a miss.

HOW_REVALIDATION_SUCCESS

public static final java.lang.Integer HOW_REVALIDATION_SUCCESS
STATE_HOW value - indicates request fulfilled through sucessfull revalidation.

HOW_REVALIDATION_FAILURE

public static final java.lang.Integer HOW_REVALIDATION_FAILURE
STATE_HOW value - indicates request fulfilled through unsucessfull revalidation.

STATE_HOW

public static final java.lang.String STATE_HOW
Logging state - for some logger to keep track of what's happening.

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.

STATE_CACHABLE

public static final java.lang.String STATE_CACHABLE
Name of the property that indicates that the cache cab be used.

STATE_RESOURCE

public static final java.lang.String STATE_RESOURCE

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.

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.

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.


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_DIRECTORY_P

public static final java.lang.String CACHE_DIRECTORY_P
Name of the property giving the cache's directory. This property defaults to the current directory.

CACHE_CONNECTED_P

public static final java.lang.String CACHE_CONNECTED_P
Name of the property indicating wether the cache is connected or not. This property defaults to true.

GARBAGE_COLLECTION_ENABLED_P

public static final java.lang.String GARBAGE_COLLECTION_ENABLED_P
Name of the property enabling garbage collection of the cache. This property defaults to true.

FILE_SIZE_RATIO_P

public static final java.lang.String FILE_SIZE_RATIO_P
Name of the property indicating the max size for files to be cached. This property gives the ratio (relative to the cache size) of the number of bytes a single entry is able to occupy.

The ratio should be given as a floating point value between 0 and 1. If set to 0.1 and the cache size is 5000000, files larger then 500000 will not be cached (except if garbage collection is disbabled).

This property defaults to 0.1.


props

protected ObservableProperties props
The properties we initialized ourself from.

directory

protected java.io.File directory
The directory where the cache is stored.

size

protected int size
The current cache size.

debug

protected boolean debug
The debug flag.

shared

protected boolean shared
Is this cached shared ?

connected

protected boolean connected
Is this cache connected ?

garbageCollectionEnabled

protected boolean garbageCollectionEnabled
Should we enable garbage collection of the cache ?

fileSizeRatio

protected double fileSizeRatio
The file size quota.

Indicates the percentage of cache size allowed to be occupied by a single file. This is not taken into account when garbage collection is disabled.


expires_drift

protected long expires_drift
The expires drift.

Control if we will cache already expires documents, in the hope that revalidation will be enough to refresh them, or also because the cache will be used in disconnected mode.


stats

protected cacheStatistics stats
Our real time statistics.
Constructor Detail

CacheFilter

public CacheFilter()
Method Detail

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)

trace

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

updateCacheSpaceCounter

protected final void updateCacheSpaceCounter(int delta)

getHow

public static java.lang.String getHow(Request request)
Returns a String indicating what the cache did with that request.
Parameters:
request - A request that may have been processed through the cache filter

isShared

public final boolean isShared()
Is this cache shared among multiple users ?
Returns:
A boolean true if shared, false otherwise.

isConnected

public final boolean isConnected()
Is this cache connected to the net ?
Returns:
A boolean, true if the cache is connected, false otherwise.

isGarbageCollectionEnabled

public final boolean isGarbageCollectionEnabled()
Are we allow to run garbage collections at all ?
Returns:
A boolean true if garbage collection is allowed , false otherwise.

getFile

protected java.io.File getFile(java.net.URL url)
Get a file to save that URL in.
Parameters:
url - The URL to be dumped.
Returns:
A File instance.

markUsed

protected void markUsed(CachedResource resource,
                        int osize,
                        int nsize)
Mark the given cached resource as having been used recently.
Parameters:
resource - The CachedResource instance that has been used.

markUsed

protected void markUsed(CachedResource resource,
                        int nsize)

markUsed

protected void markUsed(CachedResource resource)

checkCacheDirectory

protected boolean checkCacheDirectory(java.io.File dir)

getSubdirectory

protected java.io.File getSubdirectory(int i)

propertyChanged

public boolean propertyChanged(java.lang.String name)
PropertyMonitoring implementation - Commit property changes.
Specified by:
propertyChanged in interface PropertyMonitoring
Parameters:
name - The name of the property that has changed.
Returns:
A boolean true if change was commited, false otherwise.

getCacheSize

public final int getCacheSize()
Get the total size allocated to the cache.
Returns:
The cache size as an integer.

initialize

public void initialize(HttpManager manager)
                throws PropRequestFilterException
Initialize a new reuqest manager. At this time, only one manager is allowed per application. This restriction will be removed either by using several managers, or by providing manager contexts.
Specified by:
initialize in interface PropRequestFilter
Parameters:
manager - The manager to initialize.
Throws:
PropRequestFilterException - If the cache directory couldn't be created.

getStatistics

public cacheStatistics getStatistics()
Get the statistics repository associated with that filter.
Returns:
An instance of cacheStatistics.

loadResource

public CachedResource loadResource(java.lang.String url)
                            throws org.w3c.tools.resources.InvalidResourceException
Try to load from the cache the resource's whose URL is gievn.
Parameters:
url - The String version of the url of the resource to load.
Returns:
An instance of CachedResource (or one of its subclasses), or null if not found.
Throws:
org.w3c.tools.resources.InvalidResourceException - If the resource has been invalidated

hasResource

public boolean hasResource(java.lang.String url)
Does the cache knows about this resource ?
Returns:
A boolean true if this resource is known, false otherwise.

removeResource

public void removeResource(java.lang.String urlloc)
Remove a resource from the cache.
Parameters:
urlloc - The URL of the resource to remove, encoded as a String.

canUseCache

public boolean canUseCache(Request request)
Can the given request be fullfilled by the cache filter ? This method distinguishes two situations. It first check if anything in the request makes it uncachable, if this is the case, processing continues normally. If the request can be answered by the cache, we mark it as such by setting the org.w3c.www.protocol.http.cache state of the request to Boolean.TRUE, ans we return true.
Returns:
A boolean, true if the request can be fullfilled by the cache, false otherwise.

canCache

public boolean canCache(Request request,
                        Reply reply)
Can the given reply to the given request be added to the cache. This method performs all checks to detect wether the given request, reply can be cached.

We don't check for expires or maxage here, since we expect some sites to use negative expires, or zero max age, just for the sake of revalidation (that's fine).

Returns:
A boolean true if we can cache, false otherwise.

exceptionFilter

public boolean exceptionFilter(Request request,
                               HttpException ex)
This filter doesn't handle exceptions.
Parameters:
request - The request that triggered the exception.
ex - The triggered exception.
Returns:
Always false.

ingoingFilter

public Reply ingoingFilter(Request request)
                    throws HttpException

outgoingFilter

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

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).

sync

public void sync()
Save all cache related infos to stable storage.