org.springframework.extensions.surf

Class DependencyHandler

java.lang.Object

org.springframework.extensions.surf.DependencyHandler

All Implemented Interfaces:

org.springframework.beans.factory.Aware, org.springframework.context.ApplicationContextAware, CacheReporter

public class DependencyHandler
extends Object
implements org.springframework.context.ApplicationContextAware, CacheReporter

This class should be instantiated as a Spring bean that provides a service for locating dependency resources and generating checksums against their contents. It caches the location of the resources (which can be loaded from multiple different sources) to speed up their retrieval. Its primary purpose is to ensure that when resource requests are made that the URL contains a content based checksum to ensure that browsers do not use stale cached versions. This problem is solved because as the content of the file changes the checksum will change and as such the browser will not determine that it already has a cached copy of the resource. Because checksums are cached against resources this class does not support hot-deploy of new resources.

Author:

David Draper, Kevin Roast

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	DependencyHandler.ResourceInfo A protected abstract inner class that is used to allow its parent DependencyHandler to easily retrieve the InputStream for their associated resource.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CLIENT_DEBUG
static String	CSS
static String	FLAGS

Constructor Summary

Constructors

Constructor and Description
DependencyHandler()

Method Summary

Methods

Modifier and Type	Method and Description
protected void	addChecksumPathToCache(String path, String checksumPath) Adds a new generated checksum path to the cache.
protected void	addChecksumToCache(String path, String checksum) Adds a new generated checksum to the cache.
void	clearCaches() Clears the caches stored in the cachedChecksums, cachedResourceInfoMap and cachedChecksumPaths maps.
String	convertResourceToString(InputStream in) Converts the supplied InputStream into a String.
String	generateCheckSum(String source) Generates an checksum from the supplied source String using a MessageDigest with the requested algorithm.
static String	generateCheckSumPath(String path, String checksum) A very basic method of generating a path including the checksum.
List<String>	generatePathsForClientMode(String path) Generates a list of paths to attempt to retrieve for the supplied path.
protected DependencyHandler.ResourceInfo	getCachedResourceInfo(String path) Checks the cache to see if a DependencyHandler.ResourceInfo object has been previously generated for the supplied path.
String	getCharset()
String	getChecksum(String path, DependencyHandlerProcessingCallback callback) Obtains a checksum path for the supplied path by first checking a cache for previously generated values and failing that will attempt to actually retrieve the resource which will in turn actually generate a checksum path and place it in the cache which is then rechecked.
String	getChecksumPath(String path) Obtains a checksum path for the supplied path by first checking a cache for previously generated values and failing that will attempt to actually retrieve the resource which will in turn actually generate a checksum path and place it in the cache which is then rechecked.
CssImageDataHandler	getCssDataImageHandler()
CssThemeHandler	getCssThemeHandler()
String	getRelativePath(String sourcePath, String targetPath) Gets the path of the supplied path assuming it is relative to the supplied sourcePath.
RemoteResourcesHandler	getRemoteResourcesHandler()
String	getResourceControllerMapping()
InputStream	getResourceInputStream(String path) Creates an InputStream to the requested path.
InputStream	getResourceInputStream(String path, DependencyHandlerProcessingCallback callback) Creates an InputStream to the requested path.
javax.servlet.ServletContext	getServletContext() Returns the current ServletContext for the Spring application.
WebFrameworkConfigElement	getWebFrameworkConfigElement()
boolean	isDebugMode() Indicates whether the client should operate in debug mode.
protected String	lookupChecksumInCache(String path) Attempts to retrieve a previously generated checksum from the cache.
protected String	lookupChecksumPathInCache(String path) Attempts to retrieve a previously generated checksum path from the cache.
List<CacheReport>	report()
boolean	resourceInCache(String path) Return the state of a given path in the resource cache.
void	setApplicationContext(org.springframework.context.ApplicationContext applicationContext) This method will be called by the Spring framework when the class is first instantiated.
void	setCharset(String charset) Sets the character set to use when reading dependency resource files into memory.
void	setCssDataImageHandler(CssImageDataHandler cssDataImageHandler)
void	setCssThemeHandler(CssThemeHandler cssThemeHandler)
void	setDebugSuffices(List<String> debugSuffices)
void	setDigest(String digest) Sets the digest to use when generating checksums for dependency resource files
void	setProductionSuffices(List<String> productionSuffices)
void	setRemoteResourcesHandler(RemoteResourcesHandler remoteResourcesHandler)
void	setResourceControllerMapping(String resourceControllerMapping) Sets the resource controller mapping.
void	setScriptConfigModel(org.springframework.extensions.webscripts.ScriptConfigModel scriptConfigModel) Returns the current ScriptConfigModel.
void	setWebFrameworkConfigElement(WebFrameworkConfigElement webFrameworkConfigElement)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CSS

public static final String CSS

See Also:

Constant Field Values

FLAGS

public static final String FLAGS

See Also:

Constant Field Values

CLIENT_DEBUG

public static final String CLIENT_DEBUG

See Also:

Constant Field Values

Constructor Detail

DependencyHandler

public DependencyHandler()

Method Detail

setCharset

public void setCharset(String charset)

Sets the character set to use when reading dependency resource files into memory.

Parameters:

charset - The character set to use.

getCharset

public String getCharset()

Returns:

the character set to use when processing dependency resource files in memory.

setDigest

public void setDigest(String digest)

Sets the digest to use when generating checksums for dependency resource files

Parameters:

digest - The digest to use.

setApplicationContext

public void setApplicationContext(org.springframework.context.ApplicationContext applicationContext)
                           throws org.springframework.beans.BeansException

This method will be called by the Spring framework when the class is first instantiated. It both sets the ApplicationContext and also sets a ServletContext providing that the ApplicationContext is an instance of a WebApplicationContext (which it should be).

Specified by:

setApplicationContext in interface org.springframework.context.ApplicationContextAware

Throws:

org.springframework.beans.BeansException

getServletContext

public javax.servlet.ServletContext getServletContext()

Returns the current ServletContext for the Spring application.

setScriptConfigModel

public void setScriptConfigModel(org.springframework.extensions.webscripts.ScriptConfigModel scriptConfigModel)

Returns the current ScriptConfigModel.

Parameters:

scriptConfigModel - ScriptConfigModel

setCssDataImageHandler

public void setCssDataImageHandler(CssImageDataHandler cssDataImageHandler)

getCssDataImageHandler

public CssImageDataHandler getCssDataImageHandler()

setCssThemeHandler

public void setCssThemeHandler(CssThemeHandler cssThemeHandler)

getCssThemeHandler

public CssThemeHandler getCssThemeHandler()

setWebFrameworkConfigElement

public void setWebFrameworkConfigElement(WebFrameworkConfigElement webFrameworkConfigElement)

getWebFrameworkConfigElement

public WebFrameworkConfigElement getWebFrameworkConfigElement()

getResourceControllerMapping

public String getResourceControllerMapping()

Returns:

The mapping to the resource controller.

setResourceControllerMapping

public void setResourceControllerMapping(String resourceControllerMapping)

Sets the resource controller mapping.

Parameters:

resourceControllerMapping - String

getRemoteResourcesHandler

public RemoteResourcesHandler getRemoteResourcesHandler()

setRemoteResourcesHandler

public void setRemoteResourcesHandler(RemoteResourcesHandler remoteResourcesHandler)

isDebugMode

public boolean isDebugMode()

Indicates whether the client should operate in debug mode. This means that all dependency resources should not be compressed or collated.

Returns:

boolean

setDebugSuffices

public void setDebugSuffices(List<String> debugSuffices)

setProductionSuffices

public void setProductionSuffices(List<String> productionSuffices)

generatePathsForClientMode

public List<String> generatePathsForClientMode(String path)

Generates a list of paths to attempt to retrieve for the supplied path. The paths generated are dependent upon the current mode that Surf is running in (i.e. "debug" or "production") and the list of suffices defined for that mode. The suffices are defined in the Spring application context

Parameters:

path - The path to generate new paths from.

Returns:

A List of paths generated from the supplied path and the list of suffices defined for the current Surf mode.

getCachedResourceInfo

protected DependencyHandler.ResourceInfo getCachedResourceInfo(String path)

Checks the cache to see if a DependencyHandler.ResourceInfo object has been previously generated for the supplied path. It will not generate the DependencyHandler.ResourceInfo object if it does not exist.

Parameters:

path - The path to check the cache for.

Returns:

A previously generated DependencyHandler.ResourceInfo object or null if one could not be found.

resourceInCache

public boolean resourceInCache(String path)

Return the state of a given path in the resource cache.

Parameters:

path - to test for existence in the cache

Returns:

true if a resource exists in the cache for the given path.

getResourceInputStream

public InputStream getResourceInputStream(String path)
                                   throws IOException

Creates an InputStream to the requested path. This will look in both the defined classpath and within the META-INF of the application.

Parameters:

path - The path to generate an InputStream to.

Returns:

The InputStream for the requested resource and null if the resource could not be found.

Throws:

IOException - Thrown when an error occurs attempting to generate an InputStream

getResourceInputStream

public InputStream getResourceInputStream(String path,
                                 DependencyHandlerProcessingCallback callback)
                                   throws IOException

Creates an InputStream to the requested path. This will look in both the defined classpath and within the META-INF of the application.

Parameters:

path - The path to generate an InputStream to.

Returns:

The InputStream for the requested resource and null if the resource could not be found.

Throws:

IOException - Thrown when an error occurs attempting to generate an InputStream

generateCheckSumPath

public static String generateCheckSumPath(String path,
                          String checksum)

A very basic method of generating a path including the checksum. This basically concatenates the both String arguments together (separated by an underscore). Although this method is incredibly simple the function has been abstracted into a separate method to support overwriting.

Parameters:

path - The path of the file

checksum - The checksum generated from the file contents.

Returns:

A new path consisting of the combination of the path and checksum.

convertResourceToString

public String convertResourceToString(InputStream in)
                               throws IOException

Converts the supplied InputStream into a String. This has been provided with the intention of facilitating the generation of checksum values from dependency resource file contents.

Parameters:

in - The InputStream to read into a String.

Returns:

A String containing the contents of the supplied InputStream.

Throws:

IOException - Thrown when an error occurs reading from the InputStream

getChecksumPath

public String getChecksumPath(String path)

Obtains a checksum path for the supplied path by first checking a cache for previously generated values and failing that will attempt to actually retrieve the resource which will in turn actually generate a checksum path and place it in the cache which is then rechecked.

Parameters:

path - The path of the resource to attempt to generate a checksum path for

Returns:

If the requested resource could be found then this will return a checksum generated against the contents of the file. If the resource could not be found (or an error occurred attempted to read the resource contents into memory) then this will return null

getChecksum

public String getChecksum(String path,
                 DependencyHandlerProcessingCallback callback)

Obtains a checksum path for the supplied path by first checking a cache for previously generated values and failing that will attempt to actually retrieve the resource which will in turn actually generate a checksum path and place it in the cache which is then rechecked.

Parameters:

path - The path of the resource to attempt to generate a checksum path for

Returns:

If the requested resource could be found then this will return a checksum generated against the contents of the file. If the resource could not be found (or an error occurred attempted to read the resource contents into memory) then this will return null

lookupChecksumPathInCache

protected String lookupChecksumPathInCache(String path)

Attempts to retrieve a previously generated checksum path from the cache.

Parameters:

path - The path to look up in the cache.

Returns:

A previously generated checksum path or null if one has not previously been created.

lookupChecksumInCache

protected String lookupChecksumInCache(String path)

Attempts to retrieve a previously generated checksum from the cache.

Parameters:

path - The path to look up in the cache.

Returns:

A previously generated checksum or null if one has not previously been created.

addChecksumPathToCache

protected void addChecksumPathToCache(String path,
                          String checksumPath)

Adds a new generated checksum path to the cache. This method is called when new DependencyHandler.ResourceInfo objects are added to their respective cache because in order to do that the checksum path needs to be generated.

Parameters:

path - The original path requested.

checksumPath - The generated checksum path.

addChecksumToCache

protected void addChecksumToCache(String path,
                      String checksum)

Adds a new generated checksum to the cache.

Parameters:

path - The original path requested.

checksum - The generated checksum.

clearCaches

public void clearCaches()

Clears the caches stored in the cachedChecksums, cachedResourceInfoMap and cachedChecksumPaths maps. This method has been provided to allow a WebScript to clear the caches of running systems.

Specified by:

clearCaches in interface CacheReporter

report

public List<CacheReport> report()

Specified by:

report in interface CacheReporter

generateCheckSum

public String generateCheckSum(String source)

Generates an checksum from the supplied source String using a MessageDigest with the requested algorithm.

Parameters:

source - A source String to generate the MD4 checksum from.

Returns:

An MD5 checksum.

getRelativePath

public String getRelativePath(String sourcePath,
                     String targetPath)

Gets the path of the supplied path assuming it is relative to the supplied sourcePath.

Parameters:

sourcePath - String

targetPath - String

Returns:

String