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

java.lang.Object
  org.w3c.www.protocol.http.cache.CacheFilter

All Implemented Interfaces:

PropertyMonitoring, PropRequestFilter, RequestFilter

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

See Also:

Constant Field Values

SWEEPER_P

public static final java.lang.String SWEEPER_P

See Also:

Constant Field Values

VALIDATOR_P

public static final java.lang.String VALIDATOR_P

See Also:

Constant Field Values

CACHE_CONNECTED_P

public static final java.lang.String CACHE_CONNECTED_P

Name of the property enabling the connected/disconnected mode

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

STATE_WARNINGS

public static final java.lang.String STATE_WARNINGS

Name of the request state used to collect warnings.

See Also:

Constant Field Values

STATE_ORIGREQ

public static final java.lang.String STATE_ORIGREQ

Name of the request state used tokeep track of original request

See Also:

Constant Field Values

STATE_REVALIDATION

public static final java.lang.String STATE_REVALIDATION

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

See Also:

Constant Field Values

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.

Specified by:

ingoingFilter in interface RequestFilter

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.

Specified by:

exceptionFilter in interface RequestFilter

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.

Specified by:

outgoingFilter in interface RequestFilter

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.

Specified by:

sync in interface RequestFilter

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

Parameters:

manager - The HttpManager initializing the filter.

Throws:

PropRequestFilterException - If the filter couldn't be initialized properly.