SK.gnome.dwarf.http
Class Application

java.lang.Object
  extended bySK.gnome.dwarf.GenericService
      extended bySK.gnome.dwarf.GenericServer
          extended bySK.gnome.dwarf.http.Application
All Implemented Interfaces:
SK.gnome.dwarf.Reportable, SK.gnome.dwarf.Server, SK.gnome.dwarf.Service, javax.servlet.ServletContext
Direct Known Subclasses:
WebApplication

public class Application
extends SK.gnome.dwarf.GenericServer
implements javax.servlet.ServletContext

This class implements the javax.servlet.ServletContext interface.

It provides mainly a container for the servlets. Each servlet must be wrapped by the ServletWrapper in order to be added to the Application.

Each Application can contain a HTTPLogFormat service, which defines the format of the HTTP transfer log messages.

The Application must be added to a Host instance - it is the only useful (and possible) container for this class.


Field Summary
protected  boolean clearTempDir
          Whether or not to clear the web application's temporary directory.
protected  java.lang.String contextPath
          The context path.
protected  java.lang.String defaultEncoding
          Default MIME encoding.
protected  SK.gnome.dwarf.utils.StringProperties errorPages
          Mapping between HTTP status codes or Java exceptions and error pages.
 javax.security.auth.Subject EVERYONE
          This subject represents an anonymous (unauthenticated) remote user.
protected  boolean followSymlinks
          Whether or not to follow symbolic links.
protected  boolean forceAuthentication
          Enables or disables forced Basic Authentication.
protected  java.util.Map implicitMappings
          Implicit servlet extension mappings.
protected  HTTPLogFormat logFormat
          HTTP transfer log format.
protected  SK.gnome.dwarf.utils.StringProperties mimeTypes
          Mapping between file extensions and MIME types.
protected  java.lang.Class rolePrincipalClass
          The class representing the role principal.
protected  java.io.File rootDir
          Document root directory.
protected  java.lang.String runtimeServletPath
          Servlet path prefix for automatically loaded servlets.
protected  java.util.Map servlets
          Mapping between URL patterns and servlet wrappers.
protected  int sessionTimeout
          Session expiration time in seconds.
protected  boolean SSLRequired
          Whether or not this application will require the SSL connection.
protected  java.io.File tempDir
          Temporary directory.
protected  java.lang.Class userPrincipalClass
          The class representing the user principal.
 
Fields inherited from class SK.gnome.dwarf.GenericService
initParameters, parent
 
Fields inherited from interface SK.gnome.dwarf.Service
INITIALIZED, LOG_DEBUG, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_TRACE, LOG_WARN, LOG_XFER, SHUTDOWN, STARTED, STOPPED
 
Constructor Summary
Application(java.lang.String name)
          Creates a new Application.
 
Method Summary
 void addService(SK.gnome.dwarf.Service service)
          Adds a service to the server.
 java.lang.Object getAttribute(java.lang.String name)
          Returns the servlet application attribute with the given name, or null if there is no attribute by that name.
 java.util.Enumeration getAttributeNames()
          Returns an Enumeration containing the attribute names available within this servlet context.
 javax.servlet.ServletContext getContext(java.lang.String path)
          Returns a ServletContext object that corresponds to a specified URL on the server.
 java.lang.String getContextPath()
          Returns the application context path.
 java.lang.String getDefaultEncoding()
          Returns the default MIME encoding.
 java.lang.String getErrorPage(java.lang.String key)
          Returns the error page path.
 boolean getForceAuthentication()
          Whether or not the Basic Authentication will be forced.
 java.lang.String getInitParameter(java.lang.String name)
          Returns a String containing the value of the named context-wide initialization parameter, or null if the parameter does not exist.
 java.util.Enumeration getInitParameterNames()
          Returns the names of the context's initialization parameters as an Enumeration of String objects, or an empty Enumeration if the context has no initialization parameters.
 int getMajorVersion()
          Returns the major version of the Java Servlet API that this servlet application supports.
 java.lang.String getMimeType(java.lang.String file)
          Returns the MIME type of the specified file, or null if the MIME type is not known.
 int getMinorVersion()
          Returns the minor version of the Servlet API that this servlet application supports.
 javax.servlet.RequestDispatcher getNamedDispatcher(java.lang.String name)
          Returns a RequestDispatcher object that acts as a wrapper for the named servlet.
 java.lang.String getRealmName()
          Returns the authentication realm name.
 java.lang.String getRealPath(java.lang.String path)
          Returns a String containing the real path for a given virtual path.
 javax.servlet.RequestDispatcher getRequestDispatcher(java.lang.String path)
          Returns a RequestDispatcher object that acts as a wrapper for the resource located at the given path.
 java.net.URL getResource(java.lang.String path)
          Returns a URL to the resource that is mapped to a specified path.
 java.io.InputStream getResourceAsStream(java.lang.String path)
          Returns the resource located at the named path as an InputStream object.
 java.lang.String getServerInfo()
          Returns the name and version of the servlet application on which the servlet is running.
 javax.servlet.Servlet getServlet(java.lang.String name)
          Deprecated. As of Java Servlet API 2.1, with no direct replacement.

This method was originally defined to retrieve a servlet from a ServletContext. In this version, this method always returns null and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.

In lieu of this method, servlets can share information using the ServletContext class and can perform shared business logic by invoking methods on common non-servlet classes.

 java.lang.ClassLoader getServletClassLoader()
          Returns the sevlet class loader.
 java.lang.String getServletMapping(java.lang.String path)
          Returns servlet mapping pattern for the given URI path.
 java.util.Enumeration getServletNames()
          Deprecated. As of Java Servlet API 2.1, with no replacement.

This method was originally defined to return an Enumeration of all the servlet names known to this context. In this version, this method always returns an empty Enumeration and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.

 java.util.Enumeration getServlets()
          Deprecated. As of Java Servlet API 2.0, with no replacement.

This method was originally defined to return an Enumeration of all the servlets known to this servlet context. In this version, this method always returns an empty enumeration and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.

 int getSessionTimeout()
          Returns the session expiration timeout.
 java.lang.Class getUserPrincipalClass()
          Returns the principal class for representing the authenticated users.
 void checkAccess(Request request)
          Checks the access to the given resource.
 void init(SK.gnome.dwarf.Server parent)
          Initializes the service.
 boolean isUserInRole(Request request, java.lang.String role)
          Checks whether the user is in the given role.
 void log(java.lang.Exception exception, java.lang.String message)
          Deprecated. As of Java Servlet API 2.1, use log(String message, Throwable throwable) instead.

This method was originally defined to write an exception's stack trace and an explanatory error message to the servlet log file.

 void log(java.lang.String message)
          Writes the specified message to a servlet log file, usually an event log.
 void log(java.lang.String message, java.lang.Throwable throwable)
          Writes an explanatory message and a stack trace for a given Throwable exception to the servlet log file.
 void logFinished(long time, Request request, Response response)
          Logs the finished request.
 void removeAttribute(java.lang.String name)
          Removes the attribute with the given name from the servlet context.
 java.lang.String report()
          Returns the service report.
 void setAttribute(java.lang.String name, java.lang.Object object)
          Binds an object to a given attribute name in this servlet context.
 void setClearTempDir(boolean enable)
          Enable or disable clearing of the temporary directory.
 void setContextPath(java.lang.String path)
          Sets the application context path.
 void setDefaultEncoding(java.lang.String encoding)
          Sets the default MIME encoding.
 void setErrorPages(SK.gnome.dwarf.utils.StringProperties properties)
          Sets the error page mappings.
 void setFollowSymlinks(boolean enable)
          Whether or not to follow the symbolic links.
 void setForceAuthentication(boolean enable)
          Enables or disables the forced Basic Authentication.
 void setImplicitMappings(java.lang.String mappings)
          Sets the implicit servlet extension mappings.
 void setMimeTypes(SK.gnome.dwarf.utils.StringProperties properties)
          Sets the MIME type mappings.
 void setRolePrincipalClass(java.lang.Class cl)
          Sets the class to use for representing the user roles.
 void setRootDir(java.io.File dir)
          Sets the document root directory.
 void setRuntimeServletPath(java.lang.String path)
          Sets the servlet path prefix for the runtime loaded servlets.
 void setSessionTimeout(int timeout)
          Sets the session expiration timeout.
 void setSSLRequired(boolean enable)
          Whether or not the application will require the SSL connection.
 void setTempDir(java.io.File dir)
          Sets the temporary directory.
 void setUserPrincipalClass(java.lang.Class cl)
          Sets the principal class for representing the authenticated users.
 
Methods inherited from class SK.gnome.dwarf.GenericServer
addService, getAuthenticator, getLogger, getParameters, getService, getServices, getServices, removeService, shutdown, start, stop
 
Methods inherited from class SK.gnome.dwarf.GenericService
getAuthFacility, getFullName, getLogFacility, getName, getPrincipal, getShutdownTimeout, getState, log, log, login, logout, setAuthFacility, setInitParameters, setLogFacility, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface SK.gnome.dwarf.Service
getFullName, getName, getState, log, log, login, logout
 

Field Detail

EVERYONE

public final javax.security.auth.Subject EVERYONE
This subject represents an anonymous (unauthenticated) remote user.

The subject is initialized by the class constructor.


contextPath

protected java.lang.String contextPath
The context path.

A request is served by the particular application if the context path returned from the request's getContextPath method is equal to the application's context path.

Note: Context path of the root application always equals to the empty string.

See Also:
getContextPath()

sessionTimeout

protected int sessionTimeout
Session expiration time in seconds.

Default value: HTTPConstants.HTTP_DEFAULT_SESSION_TIMEOUT

See Also:
getSessionTimeout(), setSessionTimeout(int)

servlets

protected java.util.Map servlets
Mapping between URL patterns and servlet wrappers.

This map contains all servlets contained by the application. The mapped values are instances of the ServletWrapper class and the mapping keys are the URI path patterns as returned from the getMapping method of ServletWrapper.


mimeTypes

protected SK.gnome.dwarf.utils.StringProperties mimeTypes
Mapping between file extensions and MIME types.

The property key is an extension without the initial dot character, such as "html", and the property value is the corresponding MIME type, such as "text/html", for example.

See Also:
setMimeTypes(StringProperties)

errorPages

protected SK.gnome.dwarf.utils.StringProperties errorPages
Mapping between HTTP status codes or Java exceptions and error pages.

The property key is either a HTTP error code or a fully qualified class name of the Java exception, and the property value is an URI path to the page to be displayed.

See Also:
setErrorPages(StringProperties)

implicitMappings

protected java.util.Map implicitMappings
Implicit servlet extension mappings.

Contains strings representing the filename extension mappings to be regarded as implicit.

See Also:
setImplicitMappings(String)

rootDir

protected java.io.File rootDir
Document root directory.

The document root directory contains all static and dynamic files served by the Application.

See Also:
setRootDir(File)

tempDir

protected java.io.File tempDir
Temporary directory.

It is used to store temporary files, such as JSP-generated classes, and so on.

Default value: directory referenced by the java.io.tmpdir system property

See Also:
setTempDir(File)

clearTempDir

protected boolean clearTempDir
Whether or not to clear the web application's temporary directory.

Disable the clearing of temporary directory if you wish to save the application's temporary files (like compiled JSP pages, for example). The temp directory is cleared only when the web application is starting. Try to disable this feature if you have a lot of complex JSP pages to speed up the initial application response.

Default value: true

See Also:
setClearTempDir(boolean)

defaultEncoding

protected java.lang.String defaultEncoding
Default MIME encoding.

Default value: ISO-8859-1

See Also:
setDefaultEncoding(String)

forceAuthentication

protected boolean forceAuthentication
Enables or disables forced Basic Authentication.

Default value: true

See Also:
setForceAuthentication(boolean)

SSLRequired

protected boolean SSLRequired
Whether or not this application will require the SSL connection.

Default value: false

See Also:
setSSLRequired(boolean)

runtimeServletPath

protected java.lang.String runtimeServletPath
Servlet path prefix for automatically loaded servlets.

Default value: HTTPConstants.HTTP_DEFAULT_RUNTIME_SERVLET_PATH

See Also:
setRuntimeServletPath(String)

rolePrincipalClass

protected java.lang.Class rolePrincipalClass
The class representing the role principal.

Specifies the principal class which will be used to represent the user roles. This class must implement the java.security.Principal interface and must have a constructor with the single String argument - the name of the role.

The isUserInRole method uses this class to create a principal representation for the given user role. This principal is then tested whether or not it is implied by the currently authenticated subject.

Default value: RolePrincipal

See Also:
setRolePrincipalClass(Class)

userPrincipalClass

protected java.lang.Class userPrincipalClass
The class representing the user principal.

Specifies the principal class which will be used to represent the user's identity. This class must implement the java.security.Principal interface and must have a constructor with the single String argument - the name of the user.

Default value: UserPrincipal

See Also:
setUserPrincipalClass(Class)

followSymlinks

protected boolean followSymlinks
Whether or not to follow symbolic links.

If true the server will follow symbolic links on Unix platforms even if they go beyond the scope of the rootDir directory.

Default value: false

See Also:
setFollowSymlinks(boolean)

logFormat

protected HTTPLogFormat logFormat
HTTP transfer log format.

This field is set automatically to a service being added to the Application if it extends the HTTPLogFormat class.

Constructor Detail

Application

public Application(java.lang.String name)
Creates a new Application.

Method Detail

setContextPath

public void setContextPath(java.lang.String path)
Sets the application context path.

If the argument equals to "/", it is changed to the empty string first.

Parameters:
path - the context path
See Also:
contextPath

getContextPath

public java.lang.String getContextPath()
Returns the application context path.

Note: Context path of the root application always equals to the empty string.

Returns:
the context path
See Also:
contextPath

setSessionTimeout

public void setSessionTimeout(int timeout)
Sets the session expiration timeout.

If a session has not been touched for the specified amount of time, it will be automatically invalidated by the session manager.

Parameters:
timeout - the session expiration time in seconds
See Also:
sessionTimeout, getSessionTimeout()

getSessionTimeout

public int getSessionTimeout()
Returns the session expiration timeout.

Returns:
the session expiration time in seconds
See Also:
sessionTimeout, setSessionTimeout(int)

setMimeTypes

public void setMimeTypes(SK.gnome.dwarf.utils.StringProperties properties)
Sets the MIME type mappings.

Sets mapping between MIME types and a file extensions. The property key is a file extension without the initial dot character, and the property value is the particular MIME type.

Parameters:
properties - the MIME type mappings
See Also:
mimeTypes

setErrorPages

public void setErrorPages(SK.gnome.dwarf.utils.StringProperties properties)
Sets the error page mappings.

The property keys must be either a HTTP error codes or a fully qualified class names of the Java exceptions. The property values must be an absolute URI paths to the error pages, but relative to the current servlet context.

Parameters:
properties - the error page mappings
See Also:
errorPages

getErrorPage

public java.lang.String getErrorPage(java.lang.String key)
Returns the error page path.

The key argument must be either a HTTP error code or a fully qualified class name of a Java exception. The method returns null if no error page has been found for the given key.

Parameters:
key - the error code or the exception class name
Returns:
path to the error page or null if not found
See Also:
errorPages

setImplicitMappings

public void setImplicitMappings(java.lang.String mappings)
Sets the implicit servlet extension mappings.

The implicit mappings are defined by the corresponding filename extension patterns. They take precedence over all other servlet mappings defined for the application. For example the *.xml,*.pdf string argument specifies that all requested objects ending with these extensions will be automatically mapped to a ServletWrapper with the corresponding extension mapping defined via its setMapping method.

Parameters:
mappings - the comma-separated list of extension patterns
See Also:
implicitMappings

setRootDir

public void setRootDir(java.io.File dir)
Sets the document root directory.

Parameters:
dir - the root directory
See Also:
rootDir

setTempDir

public void setTempDir(java.io.File dir)
Sets the temporary directory.

Parameters:
dir - the temp directory
See Also:
tempDir

setClearTempDir

public void setClearTempDir(boolean enable)
Enable or disable clearing of the temporary directory.

Parameters:
enable - true to enable temp dir clearing
See Also:
clearTempDir

setDefaultEncoding

public void setDefaultEncoding(java.lang.String encoding)
Sets the default MIME encoding.

By setting this attribute you can instruct the server to use the given default encoding for parsing the request parameters if the encoding information is not present in the requests (i.e. in the Content-Type request header).

Parameters:
encoding - the MIME encoding
See Also:
defaultEncoding

getDefaultEncoding

public java.lang.String getDefaultEncoding()
Returns the default MIME encoding.

Returns:
the MIME encoding
See Also:
defaultEncoding

setForceAuthentication

public void setForceAuthentication(boolean enable)
Enables or disables the forced Basic Authentication.

If enabled, the server will require an authentication by sending the 401 (Unauthorized) status code each time it realizes that no session can be identified by the request, even if the request contains a valid Authorization header. This will force the remote subject to be authenticated (i.e. logged-in) before a new session is associated with it, thus preventing a possible break-in attempt.

Parameters:
enable - true to force the authentication

getForceAuthentication

public boolean getForceAuthentication()
Whether or not the Basic Authentication will be forced.

Returns:
true if the authentication will be forced

setSSLRequired

public void setSSLRequired(boolean enable)
Whether or not the application will require the SSL connection.

If set to true, the checkAccess method will throw a SSLRequiredException for each request, whose isSecure method returns false.

Parameters:
enable - true to enable the SSL connection requirement
See Also:
SSLRequired

setRuntimeServletPath

public void setRuntimeServletPath(java.lang.String path)
Sets the servlet path prefix for the runtime loaded servlets.

Usually, it can be set to something like "/servlets", so a request with the "/servlets/test.MyServlet" URI path would cause the Application to try to load the test.MyServlet class and map the corresponding servlet instance to the "/servlets/MyServlet" pattern on the fly.

Parameters:
path - the path prefix
See Also:
runtimeServletPath

setRolePrincipalClass

public void setRolePrincipalClass(java.lang.Class cl)
Sets the class to use for representing the user roles.

A full-qualified class name must be provided. The class must implement the java.security.Principal interface.

Parameters:
cl - the principal class
See Also:
rolePrincipalClass

setUserPrincipalClass

public void setUserPrincipalClass(java.lang.Class cl)
Sets the principal class for representing the authenticated users.

A fully-qualified class name must be provided. The class must implement the java.security.Principal interface.

Parameters:
cl - the principal class
See Also:
userPrincipalClass

getUserPrincipalClass

public java.lang.Class getUserPrincipalClass()
Returns the principal class for representing the authenticated users.

Returns:
the principal class
See Also:
userPrincipalClass

setFollowSymlinks

public void setFollowSymlinks(boolean enable)
Whether or not to follow the symbolic links.

Parameters:
enable - true to enable following of symbolic links
See Also:
followSymlinks

addService

public void addService(SK.gnome.dwarf.Service service)
                throws SK.gnome.dwarf.ServiceException
Adds a service to the server.

If the service being added to the Application is an instance of the HTTPLogFormat class, it is stored also in the logFormat field.

The method does not allow to add a service implementing the Parameters interface since the HTTPParameters must be inherited from the HTTP server object.

Specified by:
addService in interface SK.gnome.dwarf.Server
Throws:
SK.gnome.dwarf.ServiceException

init

public void init(SK.gnome.dwarf.Server parent)
          throws SK.gnome.dwarf.ServiceException
Initializes the service.

If the parent server is not an instance of the Host class, an IllegalServiceClassException is thrown to indicate the incompatible service type.

If the service contains no HTTPLogFormat object, the logFormat field is initialized to the value returned by the containing host's getLogFormat method. In other words, the application will use the log format of the parent host.

The EVERYONE field is initialized as follows:

 EVERYONE = new Subject();
 EVERYONE.getPrincipals().add(EveryonePrincipal.INSTANCE);
 EVERYONE.getPrincipals().add(getPrincipal());
 EVERYONE.setReadOnly();
 

Specified by:
init in interface SK.gnome.dwarf.Service
Throws:
SK.gnome.dwarf.ServiceException

report

public java.lang.String report()
Returns the service report.

Returns the servlet class, init parameters and current/peak/total number of requests serviced by the servlet so far.

Specified by:
report in interface SK.gnome.dwarf.Reportable

getRealmName

public java.lang.String getRealmName()
Returns the authentication realm name.

The realm name is used in the HTTP authentication. By default it returns the service name.

Returns:
the realm name

getServletClassLoader

public java.lang.ClassLoader getServletClassLoader()
Returns the sevlet class loader.

The class loader returned from this method is used to instantiate the servlets. By default it returns the class loader of this Application object.

Returns:
the class loader

getServletMapping

public java.lang.String getServletMapping(java.lang.String path)
Returns servlet mapping pattern for the given URI path.

The path argument must be relative to the current servlet context.

If the path starts with runtimeServletPath prefix and no servlet mapping currently exists for the given path, the Application tries to load the servlet referenced by the request URI path. Let's say that the runtimeServletPath is equal to "/servlet" string. If a client requests the "/servlet/com.acme.MyServlet" URI, the application tries to load and instantiate the com.acme.MyServlet and map it to the "/servlet/com.acme.MyServlet/*" pattern. Note: The implicit extension mappings are not searched if the URI path starts with the "/webdav/" string, because the "/webdav/*" servlet mapping is reserved for the WebDAV requests only, which are processed by a special dedicated servlet.

Parameters:
path - the URL path
Returns:
the servlet mapping pattern

logFinished

public void logFinished(long time,
                        Request request,
                        Response response)
Logs the finished request. This method generates the so-called HTTP transfer log messages. The log messages are formatted via the format method of the HTTPLogFormat object stored in the logFormat field. The method returns silently if no log format is available.

Log messages are generated with the LOG_XFER logging level and the logging facility of the current Application instance:

 if (logFormat != null)
   log(LOG_XFER, logFormat.format(time, request, response));
 

Parameters:
time - the current time
request - the request
response - the response

checkAccess

public void checkAccess(Request request)
Checks the access to the given resource.

Checks whether the subject issuing the request has permission to access the resource referenced by it. An exception is thrown to indicate that the access is denied, otherwise the method returns silently.

This method works as follows:
The resource URI path and the HTTP method are obtained from the request first, and then a new HTTPPathPermission is created according to the given information. The permission is then checked in the context of either the currently authenticated subject, obtained from the HTTP session, or the EVERYONE subject representing an anonymous user. Actual checking operation is performed via the CheckPermissionAction class by utilizing the subject-based security mechanism:

 Permission perm = new HTTPPathPermission(path, method);
 try
 { Subject.doAs(subject, new CheckPermissionAction(perm));
 }
 catch (AccessControlException e)
 { throw new UnauthorizedException("Access denied", perm);
 }
 

This method also throws the SSLRequiredException for each request, whose isSecure method returns false, if the SSLRequired attribute is set to true.

The checkAccess method can be overriden in order to implement a different checking algorithm. One can for example add a feature that would check also the client's IP address or hostname obtained from the request against an internal database of allowed or denied hosts. Such method should throw an instance of the SecurityException in the case of a denied access for any other reason than a failed user authorization. The UnauthorizedException should be thrown only in the case that the current subject, which issued the request, is not authorized to access the resource.

Note: An unauthorized user in the Dwarf HTTP Server is always represented by the EVERYONE subject containing both the ServicePrincipal with the web application's name and the EveryonePrincipal.

Parameters:
request - the HTTP request
Throws:
SSLRequiredException - if the SSL connection is required
UnauthorizedException - if the user is not authorized to access the resource

isUserInRole

public boolean isUserInRole(Request request,
                            java.lang.String role)
Checks whether the user is in the given role.

It obtains the subject instance from the HTTP session object and checks whether it contains a role principal representing the given role. It returns false if there is no authenticated user in the given request.

The principal class used to represent the role is defined by value of the rolePrincipalClass field.

Parameters:
request - the request
role - the security role
Returns:
true if the user is in the given role
See Also:
rolePrincipalClass

getServerInfo

public java.lang.String getServerInfo()
Returns the name and version of the servlet application on which the servlet is running.

The form of the returned string is servername/versionnumber. For example, the JavaServer Web Development Kit may return the string JavaServer Web Dev Kit/1.0.

The servlet application may return other optional information after the primary string in parentheses, for example, JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86).

Specified by:
getServerInfo in interface javax.servlet.ServletContext
Returns:
a String containing at least the servlet application name and version number

getMajorVersion

public int getMajorVersion()
Returns the major version of the Java Servlet API that this servlet application supports. All implementations that comply with Version 2.2 must have this method return the integer 2.

Specified by:
getMajorVersion in interface javax.servlet.ServletContext
Returns:
2

getMinorVersion

public int getMinorVersion()
Returns the minor version of the Servlet API that this servlet application supports. All implementations that comply with Version 2.2 must have this method return the integer 2.

Specified by:
getMinorVersion in interface javax.servlet.ServletContext
Returns:
2

getContext

public javax.servlet.ServletContext getContext(java.lang.String path)
Returns a ServletContext object that corresponds to a specified URL on the server.

This method allows servlets to gain access to the context for various parts of the server, and as needed obtain RequestDispatcher objects from the context. The given path must be absolute (beginning with "/") and is interpreted based on the server's document root.

In a security conscious environment, the servlet application may return null for a given URL.

Specified by:
getContext in interface javax.servlet.ServletContext
Parameters:
path - a String specifying the absolute URL of a resource on the server
Returns:
the ServletContext object that corresponds to the named URL

getRequestDispatcher

public javax.servlet.RequestDispatcher getRequestDispatcher(java.lang.String path)
Returns a RequestDispatcher object that acts as a wrapper for the resource located at the given path. A RequestDispatcher object can be used to forward a request to the resource or to include the resource in a response. The resource can be dynamic or static.

The pathname must begin with a "/" and is interpreted as relative to the current context root. Use getContext to obtain a RequestDispatcher for resources in foreign contexts. This method returns null if the ServletContext cannot return a RequestDispatcher.

Specified by:
getRequestDispatcher in interface javax.servlet.ServletContext
Parameters:
path - a String specifying the pathname to the resource
Returns:
a RequestDispatcher object that acts as a wrapper for the resource at the specified path

getNamedDispatcher

public javax.servlet.RequestDispatcher getNamedDispatcher(java.lang.String name)
Returns a RequestDispatcher object that acts as a wrapper for the named servlet.

Servlets (and JSP pages also) may be given names via server administration or via a web application deployment descriptor. A servlet instance can determine its name using ServletConfig.getServletName.

This method returns null if the ServletContext cannot return a RequestDispatcher for any reason.

Specified by:
getNamedDispatcher in interface javax.servlet.ServletContext
Parameters:
name - a String specifying the name of a servlet to wrap
Returns:
a RequestDispatcher object that acts as a wrapper for the named servlet

getRealPath

public java.lang.String getRealPath(java.lang.String path)
Returns a String containing 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 application is running, including the proper path separators. This method returns null if the servlet application 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 javax.servlet.ServletContext
Parameters:
path - a String specifying a virtual path
Returns:
a String specifying the real path, or null if the translation cannot be performed

getMimeType

public java.lang.String getMimeType(java.lang.String file)
Returns 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 application, and may be specified in a web application deployment descriptor. Common MIME types are "text/html" and "image/gif".

Specified by:
getMimeType in interface javax.servlet.ServletContext
Parameters:
file - a String specifying the name of a file
Returns:
a String specifying the file's MIME type

getResource

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

This method allows the servlet application 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 application 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 applications 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 javax.servlet.ServletContext
Parameters:
path - a String specifying the path to the resource
Returns:
the resource located at the named path, or null if there is no resource at that path
Throws:
java.net.MalformedURLException - if the pathname is not given in the correct form

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String path)
Returns 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 getResource method is lost when using this method.

The servlet application must implement the URL handlers and URLConnection objects necessary to access the resource.

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

Specified by:
getResourceAsStream in interface javax.servlet.ServletContext
Parameters:
path - a String specifying the path to the resource
Returns:
the InputStream returned to the servlet, or null if no resource exists at the specified path

getServlet

public javax.servlet.Servlet getServlet(java.lang.String name)
                                 throws javax.servlet.ServletException
Deprecated. As of Java Servlet API 2.1, with no direct replacement.

This method was originally defined to retrieve a servlet from a ServletContext. In this version, this method always returns null and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.

In lieu of this method, servlets can share information using the ServletContext class and can perform shared business logic by invoking methods on common non-servlet classes.

Specified by:
getServlet in interface javax.servlet.ServletContext
Throws:
javax.servlet.ServletException

getServlets

public java.util.Enumeration getServlets()
Deprecated. As of Java Servlet API 2.0, with no replacement.

This method was originally defined to return an Enumeration of all the servlets known to this servlet context. In this version, this method always returns an empty enumeration and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.

Specified by:
getServlets in interface javax.servlet.ServletContext

getServletNames

public java.util.Enumeration getServletNames()
Deprecated. As of Java Servlet API 2.1, with no replacement.

This method was originally defined to return an Enumeration of all the servlet names known to this context. In this version, this method always returns an empty Enumeration and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.

Specified by:
getServletNames in interface javax.servlet.ServletContext

log

public void log(java.lang.String message)
Writes the specified message to a servlet log file, usually an event log. The name and type of the servlet log file is specific to the servlet application.

Specified by:
log in interface javax.servlet.ServletContext
Parameters:
message - a String specifying the message to be written to the log file

log

public void log(java.lang.Exception exception,
                java.lang.String message)
Deprecated. As of Java Servlet API 2.1, use log(String message, Throwable throwable) instead.

This method was originally defined to write an exception's stack trace and an explanatory error message to the servlet log file.

Specified by:
log in interface javax.servlet.ServletContext

log

public void log(java.lang.String message,
                java.lang.Throwable throwable)
Writes an explanatory message and a stack trace for a given Throwable exception to the servlet log file. The name and type of the servlet log file is specific to the servlet application, usually an event log.

Specified by:
log in interface javax.servlet.ServletContext
Parameters:
message - a String that describes the error or exception
throwable - the Throwable error or exception

getAttribute

public java.lang.Object getAttribute(java.lang.String name)
Returns the servlet application attribute with the given name, or null if there is no attribute by that name. An attribute allows a servlet application to give the servlet additional information not already provided by this interface. See your server documentation for information about its attributes. A list of supported attributes can be retrieved using getAttributeNames.

The attribute is returned as a java.lang.Object or some subclass. Attribute names should follow the same convention as package names. The Java Servlet API specification reserves names matching java.*, javax.*, and sun.*.

Specified by:
getAttribute in interface javax.servlet.ServletContext
Parameters:
name - a String specifying the name of the attribute
Returns:
an Object containing the value of the attribute, or null if no attribute exists matching the given name

getAttributeNames

public java.util.Enumeration getAttributeNames()
Returns an Enumeration containing the attribute names available within this servlet context. Use the getAttribute method with an attribute name to get the value of an attribute.

Specified by:
getAttributeNames in interface javax.servlet.ServletContext
Returns:
an Enumeration of attribute names

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object object)
Binds an object to a given attribute name in this servlet context. If the name specified is already used for an attribute, this method will remove the old attribute and bind the name to the new attribute.

Attribute names should follow the same convention as package names. The Java Servlet API specification reserves names matching java.*, javax.*, and sun.*.

Specified by:
setAttribute in interface javax.servlet.ServletContext
Parameters:
name - a String specifying the name of the attribute
object - an Object representing the attribute to be bound

removeAttribute

public void removeAttribute(java.lang.String name)
Removes the attribute with the given name from the servlet context. After removal, subsequent calls to getAttribute to retrieve the attribute's value will return null.

Specified by:
removeAttribute in interface javax.servlet.ServletContext
Parameters:
name - a String specifying the name of the attribute to be removed

getInitParameter

public java.lang.String getInitParameter(java.lang.String name)
Returns a String containing the value of the named context-wide initialization parameter, or null if the parameter does not exist.

This method can make available configuration information useful to an entire "web application". For example, it can provide a webmaster's email address or the name of a system that holds critical data.

Specified by:
getInitParameter in interface javax.servlet.ServletContext
Parameters:
name - a String containing the name of the parameter whose value is requested
Returns:
a String containing at least the servlet application name and version number

getInitParameterNames

public java.util.Enumeration getInitParameterNames()
Returns the names of the context's initialization parameters as an Enumeration of String objects, or an empty Enumeration if the context has no initialization parameters.

Specified by:
getInitParameterNames in interface javax.servlet.ServletContext
Returns:
an Enumeration of String objects containing the names of the context's initialization parameters


Copyright (c) 1999-2005, Gnome Ltd. All rights reserved.