org.apache.catalina.resources
Class ResourcesBase

java.lang.Object
  |
  +--org.apache.catalina.resources.ResourcesBase
All Implemented Interfaces:
java.util.EventListener, Lifecycle, java.beans.PropertyChangeListener, Resources, java.lang.Runnable
Direct Known Subclasses:
FileResources, JarResources

public abstract class ResourcesBase
extends java.lang.Object
implements Resources, Lifecycle, java.beans.PropertyChangeListener, java.lang.Runnable

Convenience base class for implementations of the Resources interface. It is expected that subclasses of this class will be created for each flavor of document root to be supported.

Included in the basic support provided by this class is provisions for caching of resources according to configurable policy properties. This will be especially useful for web applications with relatively small amounts of static content (such as a 100% dynamic JSP based application with just a few images), as well as environments where accessing the underlying resources is relatively time consuming (such as a local or remote JAR file).

Version:
$Revision: 1.3 $ $Date: 2000/10/17 19:45:25 $
Author:
Craig R. McClanahan

Field Summary
protected  int checkInterval
          The interval (in seconds) at which our background task should check for out-of-date cached resources, or zero for no checks.
protected  Container container
          The Container this component is associated with (normally a Context).
protected  int debug
          The debugging detail level for this component.
protected  java.lang.String docBase
          The document root for this component.
protected  boolean expand
          Should "directory" entries be expanded?
protected static java.lang.String info
          The descriptive information string for this implementation.
protected  LifecycleSupport lifecycle
          The lifecycle event support for this component.
protected  int maxCount
          The maximum number of resources to cache.
protected  long maxSize
          The maximum size of resources to be cached.
protected  long minSize
          The minimum size of resources to be cached.
protected static java.lang.String prefix
          The prefix to the log messages we will be creating.
protected  java.util.HashMap resourcesCache
          The set of ResourceBean entries for this component, keyed by the normalized context-relative resource URL.
protected  int resourcesCount
          The count of ResourceBean entries for which we have actually cached data.
protected static StringManager sm
          The string manager for this package.
protected  boolean started
          Has this component been started?
protected  java.beans.PropertyChangeSupport support
          The property change support for this component.
protected  java.lang.Thread thread
          The background thread.
protected  boolean threadDone
          The background thread completion semaphore.
protected  java.lang.String threadName
          The name to register for the background thread.
 
Fields inherited from interface org.apache.catalina.Lifecycle
START_EVENT, STOP_EVENT
 
Constructor Summary
ResourcesBase()
          Construct a new instance of this class with default values.
 
Method Summary
 void addLifecycleListener(LifecycleListener listener)
          Add a lifecycle event listener to this component.
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Add a property change listener to this component.
protected  boolean cacheable(java.lang.String name, long size)
          Should the resource specified by our parameters be cached?
abstract  boolean createCollection(java.lang.String path)
          Create a collection at the specified path.
abstract  boolean deleteResource(java.lang.String path)
          Delete the specified resource.
protected  java.io.File engineBase()
          Return a File object representing the base directory for the entire servlet container (i.e.
abstract  boolean exists(java.lang.String path)
          Returns true if a resource exists at the specified path, where path would be suitable for passing as an argument to getResource() or getResourceAsStream().
 int getCheckInterval()
          Return the resource cache check interval.
abstract  java.lang.String[] getCollectionMembers(java.lang.String path)
          Return the children of the resource at the specified path, if any.
 Container getContainer()
          Return the Container with which this Resources has been associated.
 int getDebug()
          Return the debugging detail level for this component.
 java.lang.String getDocBase()
          Return the document root for this component.
 boolean getExpand()
          Return the "expand directories" flag.
 java.lang.String getInfo()
          Return descriptive information about this Resources implementation and the corresponding version number, in the format <description>/<version>.
 int getMaxCount()
          Return the maximum number of resources to cache.
 long getMaxSize()
          Return the maximum size of resources to be cached.
 java.lang.String getMimeType(java.lang.String file)
          Return the MIME type of the specified file, or null if the MIME type is not known.
 long getMinSize()
          Return the minimum size of resources to be cached.
abstract  java.lang.String getRealPath(java.lang.String path)
          Return the real path for a given virtual path.
abstract  java.net.URL getResource(java.lang.String path)
          Return a URL to the resource that is mapped to the specified path.
abstract  java.io.InputStream getResourceAsStream(java.lang.String path)
          Return the resource located at the named path as an InputStream object.
abstract  long getResourceCreated(java.lang.String path)
          Return the creation date/time of the resource at the specified path, where path would be suitable for passing as an argument to getResource() or getResourceAsStream().
abstract  long getResourceLength(java.lang.String path)
          Return the content length of the resource at the specified path, where path would be suitable for passing as an argument to getResource() or getResourceAsStream().
abstract  long getResourceModified(java.lang.String path)
          Return the last modified date/time of the resource at the specified path, where path would be suitable for passing as an argument to getResource() or getResourceAsStream().
protected  java.io.File hostBase()
          Return a File object representing the base directory for the current virtual host (i.e.
abstract  boolean isCollection(java.lang.String path)
          Return true if the resource at the specified path is a collection.
protected  void log(java.lang.String message)
          Log a message on the Logger associated with our Container (if any)
protected  void log(java.lang.String message, java.lang.Throwable throwable)
          Log a message on the Logger associated with our Container (if any)
protected  java.lang.String normalize(java.lang.String path)
          Return a context-relative path, beginning with a "/", that represents the canonical version of the specified path after ".." and "." elements are resolved out.
 void propertyChange(java.beans.PropertyChangeEvent event)
          Process property change events from our associated Context.
 void removeLifecycleListener(LifecycleListener listener)
          Remove a lifecycle event listener from this component.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Remove a property change listener from this component.
 void run()
          The background thread that checks for session timeouts and shutdown.
 void setCheckInterval(int checkInterval)
          Set the resource cache check interval.
 void setContainer(Container container)
          Set the Container with which this Resources has been associated.
 void setDebug(int debug)
          Set the debugging detail level for this component.
 void setDocBase(java.lang.String docBase)
          Set the document root for this component.
 void setExpand(boolean expand)
          Set the "expand directories" flag.
 void setMaxCount(int maxCount)
          Set the maximum number of resources to cache.
 void setMaxSize(long maxSize)
          Set the maximum size of resources to be cached.
 void setMinSize(long minSize)
          Set the minimum size of resources to be cached.
abstract  boolean setResource(java.lang.String path, java.io.InputStream content)
          Set the content of the resource at the specified path.
 void start()
          Prepare for the beginning of active use of the public methods of this component.
 void stop()
          Gracefully terminate the active use of the public methods of this component.
protected  void threadProcess()
          Scan our cached resources, looking for cases where the underlying resource has been modified since we cached it.
protected  void threadSleep()
          Sleep for the duration specified by the checkInterval property.
protected  void threadStart()
          Start the background thread that will periodically check for session timeouts.
protected  void threadStop()
          Stop the background thread that is periodically checking for session timeouts.
protected  void validate(java.lang.String path)
          Validate the format of the specified path, which should be context relative and begin with a slash character.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.catalina.Resources
getResourcePaths
 

Field Detail

checkInterval

protected int checkInterval
The interval (in seconds) at which our background task should check for out-of-date cached resources, or zero for no checks.

container

protected Container container
The Container this component is associated with (normally a Context).

debug

protected int debug
The debugging detail level for this component.

docBase

protected java.lang.String docBase
The document root for this component.

expand

protected boolean expand
Should "directory" entries be expanded?

info

protected static final java.lang.String info
The descriptive information string for this implementation.

lifecycle

protected LifecycleSupport lifecycle
The lifecycle event support for this component.

maxCount

protected int maxCount
The maximum number of resources to cache.

maxSize

protected long maxSize
The maximum size of resources to be cached.

minSize

protected long minSize
The minimum size of resources to be cached.

prefix

protected static final java.lang.String prefix
The prefix to the log messages we will be creating.

resourcesCache

protected java.util.HashMap resourcesCache
The set of ResourceBean entries for this component, keyed by the normalized context-relative resource URL.

resourcesCount

protected int resourcesCount
The count of ResourceBean entries for which we have actually cached data. This can be different from the number of elements in the resourcesCache collection.

sm

protected static final StringManager sm
The string manager for this package.

started

protected boolean started
Has this component been started?

support

protected java.beans.PropertyChangeSupport support
The property change support for this component.

thread

protected java.lang.Thread thread
The background thread.

threadDone

protected boolean threadDone
The background thread completion semaphore.

threadName

protected java.lang.String threadName
The name to register for the background thread.
Constructor Detail

ResourcesBase

public ResourcesBase()
Construct a new instance of this class with default values.
Method Detail

getCheckInterval

public int getCheckInterval()
Return the resource cache check interval.

setCheckInterval

public void setCheckInterval(int checkInterval)
Set the resource cache check interval.
Parameters:
checkInterval - The new check interval

getContainer

public Container getContainer()
Return the Container with which this Resources has been associated.
Specified by:
getContainer in interface Resources

setContainer

public void setContainer(Container container)
Set the Container with which this Resources has been associated.
Specified by:
setContainer in interface Resources
Parameters:
container - The associated Container

getDebug

public int getDebug()
Return the debugging detail level for this component.

setDebug

public void setDebug(int debug)
Set the debugging detail level for this component.
Parameters:
debug - The new debugging detail level

getDocBase

public java.lang.String getDocBase()
Return the document root for this component.

setDocBase

public void setDocBase(java.lang.String docBase)
Set the document root for this component.
Parameters:
docBase - The new document root
Throws:
java.lang.IllegalArgumentException - if the specified value is not supported by this implementation
java.lang.IllegalArgumentException - if this would create a malformed URL

getExpand

public boolean getExpand()
Return the "expand directories" flag.
Specified by:
getExpand in interface Resources

setExpand

public void setExpand(boolean expand)
Set the "expand directories" flag.
Specified by:
setExpand in interface Resources
Parameters:
expand - The new "expand directories" flag

getInfo

public java.lang.String getInfo()
Return descriptive information about this Resources implementation and the corresponding version number, in the format <description>/<version>.
Specified by:
getInfo in interface Resources

getMaxCount

public int getMaxCount()
Return the maximum number of resources to cache.

setMaxCount

public void setMaxCount(int maxCount)
Set the maximum number of resources to cache.
Parameters:
maxCount - The new maximum count

getMaxSize

public long getMaxSize()
Return the maximum size of resources to be cached.

setMaxSize

public void setMaxSize(long maxSize)
Set the maximum size of resources to be cached.
Parameters:
maxSize - The new maximum size

getMinSize

public long getMinSize()
Return the minimum size of resources to be cached.

setMinSize

public void setMinSize(long minSize)
Set the minimum size of resources to be cached.
Parameters:
minSize - The new minimum size

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Add a property change listener to this component.
Specified by:
addPropertyChangeListener in interface Resources
Parameters:
listener - The listener to add

getMimeType

public java.lang.String getMimeType(java.lang.String file)
Return the MIME type of the specified file, or null if the MIME type is not known. The MIME type is determined by the configuration of the servlet container, and may be specified in a web application descriptor. Common MIME types are "text/html" and "image/gif".

The default implementation consults the MIME type mappings that have been registered in our associated Context, if any.

Specified by:
getMimeType in interface Resources
Parameters:
file - Name of the file whose MIME type is to be determined

getRealPath

public abstract java.lang.String getRealPath(java.lang.String path)
Return the real path for a given virtual path. For example, the virtual path "/index.html" has a real path of whatever file on the server's filesystem would be served by a request for "/index.html".

The real path returned will be in a form appropriate to the computer and operating system on which the servlet container is running, including the proper path separators. This method returns null if the servlet container cannot translate the virtual path to a real path for any reason (such as when the content is being made available from a .war archive).

Specified by:
getRealPath in interface Resources
Parameters:
path - The virtual path to be translated

getResource

public abstract java.net.URL getResource(java.lang.String path)
                                  throws java.net.MalformedURLException
Return a URL to the resource that is mapped to the specified path. The path must begin with a "/" and is interpreted as relative to the current context root.

This method allows the Container to make a resource available to servlets from any source. Resources can be located on a local or remote file system, in a database, or in a .war file.

The servlet container must implement the URL handlers and URLConnection objects that are necessary to access the resource.

This method returns null if no resource is mapped to the pathname.

Some Containers may allow writing to the URL returned by this method, using the methods of the URL class.

The resource content is returned directly, so be aware that requesting a .jsp page returns the JSP source code. Use a RequestDispatcher instead to include results of an execution.

This method has a different purpose than java.lang.Class.getResource(), which looks up resources based on a class loader. This method does not use class loaders.

Specified by:
getResource in interface Resources
Parameters:
path - The path to the desired resource
Throws:
java.net.MalformedURLException - if the pathname is not given in the correct form

getResourceAsStream

public abstract java.io.InputStream getResourceAsStream(java.lang.String path)
Return the resource located at the named path as an InputStream object.

The data in the InputStream can be of any type or length. The path must be specified according to the rules given in getResource(). This method returns null if no resource exists at the specified path.

Meta-information such as content length and content type that is available via the getResource() method is lost when using this method.

The servlet container must implement the URL handlers and URLConnection objects that are necessary to access the resource.

This method is different from java.lang.Class.getResourceAsStream(), which uses a class loader. This method allows servlet containers to make a resource available to a servlet from any location, without using a class loader.

Specified by:
getResourceAsStream in interface Resources
Parameters:
path - The path to the desired resource

exists

public abstract boolean exists(java.lang.String path)
Returns true if a resource exists at the specified path, where path would be suitable for passing as an argument to getResource() or getResourceAsStream(). If there is no resource at the specified location, return false.
Specified by:
exists in interface Resources
Parameters:
path - The path to the desired resource

getResourceModified

public abstract long getResourceModified(java.lang.String path)
Return the last modified date/time of the resource at the specified path, where path would be suitable for passing as an argument to getResource() or getResourceAsStream(). If there is no resource at the specified location, return -1.

IMPLEMENTATION NOTE: This method should bypass any cached resources and reference the underlying resource directly, because it will be used by the background thread that is checking for resources that have been modified.

Specified by:
getResourceModified in interface Resources
Parameters:
path - The path to the desired resource

getResourceCreated

public abstract long getResourceCreated(java.lang.String path)
Return the creation date/time of the resource at the specified path, where path would be suitable for passing as an argument to getResource() or getResourceAsStream(). If there is no resource at the specified location, return -1. If this time is unknown, the implementation should return getResourceModified(path).
Specified by:
getResourceCreated in interface Resources
Parameters:
path - The path to the desired resource

getResourceLength

public abstract long getResourceLength(java.lang.String path)
Return the content length of the resource at the specified path, where path would be suitable for passing as an argument to getResource() or getResourceAsStream(). If the content length of the resource can't be determined, return -1. If no content is available (when for exemple, the resource is a collection), return 0.
Specified by:
getResourceLength in interface Resources
Parameters:
path - The path to the desired resource

isCollection

public abstract boolean isCollection(java.lang.String path)
Return true if the resource at the specified path is a collection. A collection is a special type of resource which has no content but contains child resources.
Specified by:
isCollection in interface Resources
Parameters:
path - The path to the desired resource

getCollectionMembers

public abstract java.lang.String[] getCollectionMembers(java.lang.String path)
Return the children of the resource at the specified path, if any. This will return null if the resource is not a collection, or if it is a collection but has no children.
Specified by:
getCollectionMembers in interface Resources
Parameters:
path - The path to the desired resource

setResource

public abstract boolean setResource(java.lang.String path,
                                    java.io.InputStream content)
Set the content of the resource at the specified path. If the resource already exists, its previous content is overwritten. If the resource doesn't exist, its immediate parent collection (according to the path given) exists, then its created, and the given content is associated with it. Return false if either the resource is a collection, or no parent collection exist.
Specified by:
setResource in interface Resources
Parameters:
path - The path to the desired resource
content - InputStream to the content to be set

createCollection

public abstract boolean createCollection(java.lang.String path)
Create a collection at the specified path. A parent collection for this collection must exist. Return false if a resource already exist at the path specified, or if the parent collection doesn't exist.
Specified by:
createCollection in interface Resources
Parameters:
path - The path to the desired resource

deleteResource

public abstract boolean deleteResource(java.lang.String path)
Delete the specified resource. Non-empty collections cannot be deleted before deleting all their member resources. Return false is deletion fails because either the resource specified doesn't exist, or the resource is a non-empty collection.
Specified by:
deleteResource in interface Resources
Parameters:
path - The path to the desired resource

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Remove a property change listener from this component.
Specified by:
removePropertyChangeListener in interface Resources
Parameters:
listener - The listener to remove

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent event)
Process property change events from our associated Context.
Specified by:
propertyChange in interface java.beans.PropertyChangeListener
Parameters:
event - The property change event that has occurred

addLifecycleListener

public void addLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.
Specified by:
addLifecycleListener in interface Lifecycle
Parameters:
listener - The listener to add

removeLifecycleListener

public void removeLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.
Specified by:
removeLifecycleListener in interface Lifecycle
Parameters:
listener - The listener to remove

start

public void start()
           throws LifecycleException
Prepare for the beginning of active use of the public methods of this component. This method should be called after configure(), and before any of the public methods of the component are utilized.
Specified by:
start in interface Lifecycle
Throws:
IllegalStateException - if this component has already been started
LifecycleException - if this component detects a fatal error that prevents this component from being used

stop

public void stop()
          throws LifecycleException
Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component.
Specified by:
stop in interface Lifecycle
Throws:
IllegalStateException - if this component has not been started
LifecycleException - if this component detects a fatal error that needs to be reported

cacheable

protected boolean cacheable(java.lang.String name,
                            long size)
Should the resource specified by our parameters be cached?
Parameters:
name - Name of the proposed resource
size - Size (in bytes) of the proposed resource

engineBase

protected java.io.File engineBase()
Return a File object representing the base directory for the entire servlet container (i.e. the Engine container if present).

hostBase

protected java.io.File hostBase()
Return a File object representing the base directory for the current virtual host (i.e. the Host container if present).

log

protected void log(java.lang.String message)
Log a message on the Logger associated with our Container (if any)
Parameters:
message - Message to be logged

log

protected void log(java.lang.String message,
                   java.lang.Throwable throwable)
Log a message on the Logger associated with our Container (if any)
Parameters:
message - Message to be logged
throwable - Associated exception

normalize

protected java.lang.String normalize(java.lang.String path)
Return a context-relative path, beginning with a "/", that represents the canonical version of the specified path after ".." and "." elements are resolved out. If the specified path attempts to go outside the boundaries of the current context (i.e. too many ".." path elements are present), return null instead.
Parameters:
path - Path to be normalized

threadProcess

protected void threadProcess()
Scan our cached resources, looking for cases where the underlying resource has been modified since we cached it.

threadSleep

protected void threadSleep()
Sleep for the duration specified by the checkInterval property.

threadStart

protected void threadStart()
Start the background thread that will periodically check for session timeouts.

threadStop

protected void threadStop()
Stop the background thread that is periodically checking for session timeouts.

validate

protected void validate(java.lang.String path)
Validate the format of the specified path, which should be context relative and begin with a slash character.
Parameters:
path - Context-relative path to be validated
Throws:
java.lang.IllegalArgumentException - if the specified path is null or does not have a valid format

run

public void run()
The background thread that checks for session timeouts and shutdown.
Specified by:
run in interface java.lang.Runnable


Copyright © 2000 Apache Software Foundation. All Rights Reserved.