org.apache.cocoon.components.source.impl
Class CachingSource

java.lang.Object
  extended byorg.apache.cocoon.util.AbstractLogEnabled
      extended byorg.apache.cocoon.components.source.impl.CachingSource
All Implemented Interfaces:
Initializable, Serviceable, Source, XMLizable
Direct Known Subclasses:
TraversableCachingSource

public class CachingSource
extends org.apache.cocoon.util.AbstractLogEnabled
implements Serviceable, Initializable, XMLizable, Source

This class implements a proxy like source that uses another source to get the content. This implementation can cache the content for a given period of time.

Syntax for Protocol

   cached:http://www.apache.org/[?cocoon:cache-expires=60&cocoon:cache-name=main][&cocoon:cache-fail=true]
 

The above examples show how the real source http://www.apache.org is wrapped and the cached contents is used for 60 seconds. The second querystring parameter instructs that the cache key be extended with the string main. This allows the use of multiple cache entries for the same source.

The value of the expires parameter holds some additional semantics. Specifying -1 will yield the cached response to be considered valid always. Value 0 can be used to achieve the exact opposite. That is to say, the cached contents will be thrown out and updated immediately and unconditionally.

The cache-fail argument lets subsequent syncronous requests, that have to be refreshed, fail, in the case that the wrapped source can't be reached. The default value for cache-fail is true.

Version:
$Id: CachingSource.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Nested Class Summary
protected static class CachingSource.SourceMeta
          Data holder for caching Source meta info.
 
Field Summary
protected  boolean async
          asynchronic refresh strategy ?
protected  org.apache.cocoon.caching.Cache cache
          The current cache
static String CACHE_EXPIRES_PARAM
           
static String CACHE_FAIL_PARAM
           
static String CACHE_NAME_PARAM
           
protected  org.apache.cocoon.caching.IdentifierCacheKey cacheKey
          The key used in the store
protected  String cacheName
          cache key extension
protected  int expires
          Number of seconds before cached object becomes invalid
protected  boolean fail
          Fail because of a syncronous refresh excpetion
protected  ServiceManager manager
          The ServiceManager
protected  String protocol
          The used protocol
protected  Source source
          The source object for the real content
protected  String sourceUri
          The full URI string of the underlying source
protected  String uri
          The full URI string
 
Constructor Summary
CachingSource(String protocol, String uri, String sourceUri, Source source, int expires, String cacheName, boolean async, CachingSourceValidityStrategy validityStrategy, boolean fail)
          Construct a new object.
 
Method Summary
 void dispose()
          Cleanup.
 boolean exists()
           
protected  byte[] getBinaryResponse()
          Initialize the cached response with meta and binary contents.
protected  String getCacheKey()
          Return the used key.
protected  SourceValidity[] getCacheValidities()
           
 long getContentLength()
          Get the content length of the source or -1 if it is not possible to determine the length.
protected  long getExpiration()
          Expires (in milli-seconds)
 InputStream getInputStream()
          Return an InputStream object to read from the source.
 long getLastModified()
          Get the last modification date.
 String getMimeType()
          The mime-type of the content described by this object.
protected  CachingSource.SourceMeta getResponseMeta()
          Initialize the cached response with meta info.
 String getScheme()
          Return the protocol identifier.
protected  String getSourceURI()
          Return the uri of the cached source.
 String getURI()
          Return the unique identifer for this source
 SourceValidity getValidity()
          Get the Validity object.
protected  byte[] getXMLResponse()
          Initialize the cached response with meta, binary, and XML contents.
 void initialize()
          Initialize the Source.
protected  byte[] readBinaryResponse(Source source)
          Read binary content from source.
protected  CachingSource.SourceMeta readMeta(Source source)
          Read meta data from source.
protected  byte[] readXMLResponse(Source source, byte[] binary, ServiceManager manager)
          Read XML content from source.
 void refresh()
          Refresh this object and update the last modified date and content length.
 void service(ServiceManager manager)
          Set the ServiceManager.
 void setValidityStrategy(CachingSourceValidityStrategy s)
           
 void toSAX(ContentHandler contentHandler)
          Generates SAX events representing the object's state.
 
Methods inherited from class org.apache.cocoon.util.AbstractLogEnabled
getLogger, setLogger
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CACHE_EXPIRES_PARAM

public static final String CACHE_EXPIRES_PARAM
See Also:
Constant Field Values

CACHE_NAME_PARAM

public static final String CACHE_NAME_PARAM
See Also:
Constant Field Values

CACHE_FAIL_PARAM

public static final String CACHE_FAIL_PARAM
See Also:
Constant Field Values

protocol

protected final String protocol
The used protocol


uri

protected final String uri
The full URI string


sourceUri

protected final String sourceUri
The full URI string of the underlying source


source

protected Source source
The source object for the real content


manager

protected ServiceManager manager
The ServiceManager


cache

protected org.apache.cocoon.caching.Cache cache
The current cache


cacheKey

protected final org.apache.cocoon.caching.IdentifierCacheKey cacheKey
The key used in the store


expires

protected final int expires
Number of seconds before cached object becomes invalid


fail

protected final boolean fail
Fail because of a syncronous refresh excpetion


cacheName

protected final String cacheName
cache key extension


async

protected final boolean async
asynchronic refresh strategy ?

Constructor Detail

CachingSource

public CachingSource(String protocol,
                     String uri,
                     String sourceUri,
                     Source source,
                     int expires,
                     String cacheName,
                     boolean async,
                     CachingSourceValidityStrategy validityStrategy,
                     boolean fail)
Construct a new object.

Parameters:
validityStrategy -
Method Detail

service

public void service(ServiceManager manager)
             throws ServiceException
Set the ServiceManager.

Specified by:
service in interface Serviceable
Throws:
ServiceException

initialize

public void initialize()
                throws Exception
Initialize the Source.

Specified by:
initialize in interface Initializable
Throws:
Exception

dispose

public void dispose()
Cleanup.


getResponseMeta

protected CachingSource.SourceMeta getResponseMeta()
                                            throws IOException
Initialize the cached response with meta info.

Throws:
IOException - if an the binary response could not be initialized

getBinaryResponse

protected byte[] getBinaryResponse()
                            throws IOException
Initialize the cached response with meta and binary contents.

Throws:
IOException - if an the binary response could not be initialized

getXMLResponse

protected byte[] getXMLResponse()
                         throws SAXException,
                                IOException
Initialize the cached response with meta, binary, and XML contents.

Throws:
SAXException - if something happened during xml processing
IOException - if an IO level error occured
org.apache.cocoon.CascadingIOException - wraps all other exception types

getScheme

public String getScheme()
Return the protocol identifier.

Specified by:
getScheme in interface Source

getContentLength

public long getContentLength()
Get the content length of the source or -1 if it is not possible to determine the length.

Specified by:
getContentLength in interface Source

getLastModified

public long getLastModified()
Get the last modification date.

Specified by:
getLastModified in interface Source
Returns:
The last modification in milliseconds since January 1, 1970 GMT or 0 if it is unknown

getMimeType

public String getMimeType()
The mime-type of the content described by this object. If the source is not able to determine the mime-type by itself this can be null.

Specified by:
getMimeType in interface Source

getInputStream

public InputStream getInputStream()
                           throws IOException
Return an InputStream object to read from the source.

Specified by:
getInputStream in interface Source
Throws:
IOException

getURI

public String getURI()
Return the unique identifer for this source

Specified by:
getURI in interface Source

exists

public boolean exists()
Specified by:
exists in interface Source
See Also:
Source.exists()

getValidity

public SourceValidity getValidity()
Get the Validity object. This can either wrap the last modification date or the expires information or... If it is currently not possible to calculate such an information null is returned.

Specified by:
getValidity in interface Source

refresh

public void refresh()
Refresh this object and update the last modified date and content length. This method will try to refresh the cached meta data and content only if cached content is expired.

Specified by:
refresh in interface Source

toSAX

public void toSAX(ContentHandler contentHandler)
           throws SAXException
Generates SAX events representing the object's state.

Specified by:
toSAX in interface XMLizable
Throws:
SAXException

getSourceURI

protected String getSourceURI()
Return the uri of the cached source.


getCacheKey

protected String getCacheKey()
Return the used key.


getExpiration

protected long getExpiration()
Expires (in milli-seconds)


readXMLResponse

protected byte[] readXMLResponse(Source source,
                                 byte[] binary,
                                 ServiceManager manager)
                          throws SAXException,
                                 IOException
Read XML content from source.

Returns:
content from source
Throws:
SAXException
IOException
org.apache.cocoon.CascadingIOException

readBinaryResponse

protected byte[] readBinaryResponse(Source source)
                             throws IOException
Read binary content from source.

Returns:
content from source
Throws:
IOException
SourceNotFoundException

readMeta

protected CachingSource.SourceMeta readMeta(Source source)
                                     throws SourceException
Read meta data from source.

Throws:
SourceException

getCacheValidities

protected SourceValidity[] getCacheValidities()

setValidityStrategy

public void setValidityStrategy(CachingSourceValidityStrategy s)


Copyright 1999-2008 The Apache Software Foundation. All Rights Reserved.