org.apache.catalina
Interface Resources

All Known Implementing Classes:
ResourcesBase

public interface Resources

A Resources is a generic interface for the resource acquisition and lookup methods of the ServletContext interface.

A Resources object is generally attached to a Context, or higher level, Container. However, a Connector may also provide a Resources object associated with a particular Request, which should be treated by any Container processing this request as overriding any Resources object normally configured for this Container.

Version:
$Revision: 1.2 $ $Date: 2000/10/21 14:37:21 $
Author:
Craig R. McClanahan, Remy Maucherat

Method Summary
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Add a property change listener to this component.
 boolean createCollection(java.lang.String path)
          Create a collection at the specified path.
 boolean deleteResource(java.lang.String path)
          Delete the specified resource.
 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().
 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.
 boolean getExpand()
          Return the "expand directory resources into listings" property.
 java.lang.String getInfo()
          Return descriptive information about this Resources implementation and the corresponding version number, in the format <description>/<version>.
 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.
 java.lang.String getRealPath(java.lang.String path)
          Return the real path for a given virtual path.
 java.net.URL getResource(java.lang.String path)
          Return a URL to the resource that is mapped to the specified path.
 java.io.InputStream getResourceAsStream(java.lang.String path)
          Return the resource located at the named path as an InputStream object.
 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().
 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().
 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().
 java.lang.String[] getResourcePaths()
          Return the set of context-relative paths of all available resources.
 boolean isCollection(java.lang.String path)
          Return true if the resource at the specified path is a collection.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Remove a property change listener from this component.
 void setContainer(Container container)
          Set the Container with which this Resources has been associated.
 void setExpand(boolean expand)
          Set the "expand directory resources into listings" property.
 boolean setResource(java.lang.String path, java.io.InputStream content)
          Set the content of the resource at the specified path.
 

Method Detail

getContainer

public Container getContainer()
Return the Container with which this Resources has been associated.

setContainer

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

getExpand

public boolean getExpand()
Return the "expand directory resources into listings" property.

setExpand

public void setExpand(boolean expand)
Set the "expand directory resources into listings" property.
Parameters:
expand - The new expand flag

getInfo

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

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Add a property change listener to this component.
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".
Parameters:
file - Name of the file whose MIME type is to be determined

getRealPath

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

Parameters:
path - The virtual path to be translated

getResource

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

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

getResourceAsStream

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

Parameters:
path - The path to the desired resource

exists

public 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.
Parameters:
path - The path to the desired resource

getResourceModified

public 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.
Parameters:
path - The path to the desired resource

getResourcePaths

public java.lang.String[] getResourcePaths()
Return the set of context-relative paths of all available resources. Each path will begin with a "/" character.

getResourceCreated

public 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).
Parameters:
path - The path to the desired resource

getResourceLength

public 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 determinedof if the resource is a collection, return -1. If no content is available, return 0.
Parameters:
path - The path to the desired resource

isCollection

public 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.
Parameters:
path - The path to the desired resource

getCollectionMembers

public 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.
Parameters:
path - The path to the desired resource

setResource

public 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.
Parameters:
path - The path to the desired resource
content - InputStream to the content to be set

createCollection

public 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.
Parameters:
path - The path to the desired resource

deleteResource

public 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.
Parameters:
path - The path to the desired resource

removePropertyChangeListener

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


Copyright © 2000 Apache Software Foundation. All Rights Reserved.