com.opmath.util.http
Class HttpServlet

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--com.opmath.util.http.HttpServlet

All Implemented Interfaces:

ParamIndex, Serializable, Servlet, ServletConfig

Direct Known Subclasses:

HttpLogOffServlet, HttpLogOnServlet, HttpProtectedServlet, HttpSessionServlet

public abstract class HttpServlet

extends HttpServlet

implements ParamIndex

Provides an abstract class for a servlet.

The structure and functionality of this class enriches the standard javax.servlet.http.HttpServlet class, with methods that handle parameter parsing, default responses, and configuration using resource .conf files.

NOTE: This class carries some static and instance variables that are used in support of user authentication and user sessions. Refer to the immediate subclasses of this class, in order to understand the use of these variables.

WARNING: It is up to the programmer to ensure that the use of the HttpSession instance variable (or any other instance variable) is thread safe.

Copyright: (c) 2002 The Open Math Company Limited

The Terms of Distribution of this software are stipulated in the javadoc Overview for this project.

Since:

J2SE 1.3.0

Version:

HTTP v2.0

Author:

Bruno Beloff bruno.beloff@opmath.com

See Also:

HttpSessionServlet, HttpLogOnServlet, HttpLogOffServlet, HttpProtectedServlet, Serialized Form

Field Summary

protected static String	EOL The end-of-line character(s) for the server.
protected static String	LOGON_DONE The HttpSession attribute used to specify that the requester has logged on successfully.
protected static String	LOGON_TARGET The HttpSession attribute used to specify the URI of the target of a request.

Constructor Summary

HttpServlet()

Method Summary

void	doGet(HttpServletRequest req, HttpServletResponse rsp) Handles an HTTP GET request.
protected String	doGetDispatch(HttpServletRequest req) Services an HTTP GET request, as caught by the doGet(HttpServletRequest, HttpServletResponse) method on this class.
void	doPost(HttpServletRequest req, HttpServletResponse rsp) Handles an HTTP POST request.
protected String	doPostDispatch(HttpServletRequest req) Handles an HTTP POST request.
int	getIndex(String paramName, String paramValue) Returns the int index associated with the paramName / paramValue pair, as established by registerIndex(String, String, int).
int	getParamIndex(String paramName, HttpServletRequest req) Returns the int index of the parameter value found in the HttpServletRequest whose name is paramName and whose value is found in the HttpServletRequest.
String	getServletInfo() Returns a String carrying some information about the servlet.
int	getValueCount(String paramName) Returns the number of parameter values registered against paramName.
Enumeration	paramIndices(String paramName) Returns an Enumeration of the parameter indices for the values registered against paramName.
Enumeration	paramMappings() Returns an Enumeration of the parameter (value => index) mappings known to the registry.
Enumeration	paramNames() Returns an Enumeration of the parameter names known to the registry.
Enumeration	paramValues(String paramName) Returns an Enumeration of the parameter values registered against paramName.
void	registerIndex(String paramName, String paramValue, int paramValueIndex) Associates the value of a servlet parameter with an int index.
void	registerIndices(String paramName, String[] paramValues) Associates a number of values of a servlet parameter with successive indices.
String	report(HttpServletRequest req, String message) Provides a general-purpose failure reporting mechanism, intended to be triggered within a servlet doGet(HttpServletRequest, HttpServletResponse) or doPost(HttpServletRequest, HttpServletResponse) method.
void	setConfig() Sets static variables, based on the contents of a ServletName.conf file.
void	setConfig(String resourceName) Sets static variables, based on the contents of the named configuration file.

Methods inherited from class javax.servlet.http.HttpServlet

, doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service

Methods inherited from class javax.servlet.GenericServlet

destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletName, init, init, log, log

Methods inherited from class java.lang.Object

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

Field Detail

LOGON_TARGET

protected static final String LOGON_TARGET

The HttpSession attribute used to specify the URI of the target of a request.

See Also:

HttpLogOnServlet.doPost(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), HttpProtectedServlet.doGet(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), HttpProtectedServlet.doPost(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

Since:

J2SE 1.3

LOGON_DONE

protected static final String LOGON_DONE

The HttpSession attribute used to specify that the requester has logged on successfully.

See Also:

HttpLogOnServlet.doPost(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), HttpProtectedServlet.doGet(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), HttpProtectedServlet.doPost(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

Since:

J2SE 1.3

EOL

protected static final String EOL

The end-of-line character(s) for the server.

Since:

J2SE 1.3

Constructor Detail

HttpServlet

public HttpServlet()

Method Detail

doGet

public void doGet(HttpServletRequest req,
                  HttpServletResponse rsp)
           throws ServletException,
                  IOException

Handles an HTTP GET request. This method provides generic i/o and exception handling facilities. Thus, it simplifies the task of writing code to respond to a GET, and makes that code more reliable in practical use.

Subclasses of com.opmath.util.http.HttpServlet need only override doGetDispatch(HttpServletRequest, HttpServletResponse), unless the default behaviour of doGet(HttpServletRequest, HttpServletResponse) must be altered.

Overrides:

doGet in class HttpServlet

Parameters:

req - a javax.servlet.http.HttpServletRequest carrying the request environmental variables.

rsp - a javax.servlet.http.HttpServletResponse carrying the response objects.

Throws:

ServletException - an exception thrown if the request could not be handled.

IOException - an exception thrown if an input or output error is detected when the servlet handles the request.

Since:

J2SE 1.3

See Also:

doGetDispatch(com.opmath.util.http.HttpServletRequest)

doGetDispatch

protected String doGetDispatch(HttpServletRequest req)
                        throws Exception

Services an HTTP GET request, as caught by the doGet(HttpServletRequest, HttpServletResponse) method on this class. This method should be overriden by any real-world application.

Parameters:

req - a javax.servlet.http.HttpServletRequest carrying the request environmental variables.

Returns:

A String carrying the report.

Throws:

Exception - if a subclass's method encounters any error state.

Since:

J2SE 1.3

See Also:

doGet(HttpServletRequest, HttpServletResponse)

doPost

public void doPost(HttpServletRequest req,
                   HttpServletResponse rsp)
            throws ServletException,
                   IOException

Handles an HTTP POST request. This method provides generic i/o and exception handling facilities. Thus, it simplifies the task of writing code to respond to a POST, and makes that code more reliable in practical use.

Subclasses of com.opmath.util.http.HttpServlet need only override doPostDispatch(HttpServletRequest, HttpServletResponse), unless the default behaviour of doGet(HttpServletRequest, HttpServletResponse) must be altered.

Overrides:

doPost in class HttpServlet

Parameters:

req - a javax.servlet.http.HttpServletRequest carrying the request environmental variables.

rsp - a javax.servlet.http.HttpServletResponse carrying the response objects.

Throws:

ServletException - an exception thrown if the request could not be handled.

IOException - an exception thrown if an input or output error is detected when the servlet handles the request.

Since:

J2SE 1.3

See Also:

doPostDispatch(com.opmath.util.http.HttpServletRequest)

doPostDispatch

protected String doPostDispatch(HttpServletRequest req)
                         throws Exception

Handles an HTTP POST request. This method instantiates the session object of the servlet, then arranges that the doPostDispatch(com.opmath.util.http.HttpServletRequest) method is invoked.

Parameters:

req - a javax.servlet.http.HttpServletRequest carrying the request environmental variables.

Throws:

Exception - if a subclass's method encounters any error state.

Since:

J2SE 1.3

See Also:

doPost(HttpServletRequest, HttpServletResponse)

setConfig

public void setConfig(String resourceName)
               throws ServletException

Sets static variables, based on the contents of the named configuration file.

The purpose of setConfig() is to simplify the deployment of servlet-based applications. It achieves this by allowing the developer to place all the environment-specific properties of a servlet in a textual configuration file. setConfig() can assign these properties to static variables; this should normally be done in the servlet's init() or init(ServletConfig) method.

Although a similar effect can be achieved with parameters passed to the servlet via its ServletConfig argument, packaging all the parameters in a configuration file is ofetn the better option.

The resource should be in the same package as the receiver's class, although the package containing the configuration file may be anywhere on the runtime classpath.

Entries in the configuration file are as follows:

• Comments - Lines beginning with the character '#'. The comment continues until the end of the line.

• Assignments - Must contain only two tokens, seperated by whitespace. The first is the case-sensitive name of the static variable, the second is its value.

NOTE 1: This version of setConfig() only allows for static variables of class String.

NOTE 2: setConfig() issues a warning if the static variable had already been assigned a value. Under normal circumstances, the variable should not be assigned a value in the servlet code (thus it would carry the value null.

If setConfig() encounters an error with the configuration file then it throws a ServletException. In such a case, further processing of the servlet should not proceed.

Throws:

ServletException - An exception thrown if configuration file could not be found, the configuration entries were malformed, or the static variables could not be accessed.

Since:

J2SE 1.3

setConfig

public void setConfig()
               throws ServletException

Sets static variables, based on the contents of a ServletName.conf file.

setConfig() always looks for a resource file named ServletName.conf, where ServletName is the name of the class of the receiving object. The resource file should be in the same package as the receiver's class, although the package containing the configuration file may be anywhere on the runtime classpath.

For further details, see setConfig(String).

Throws:

ServletException - An exception thrown if configuration file could not be found, the configuration entries were malformed, or the static variables could not be accessed.

Since:

J2SE 1.3

See Also:

setConfig(String)

registerIndex

public void registerIndex(String paramName,
                          String paramValue,
                          int paramValueIndex)

Associates the value of a servlet parameter with an int index.

The main use of the register is to enable switch statements to work over commands handed to the servlet; to do this, the int must be declared by the servlet as static final.

Specified by:

registerIndex in interface ParamIndex

Parameters:

paramName - the String name of the parameter.

paramValue - the String value of the parameter.

paramValueIndex - the int value associated with the parameter value.

Since:

J2SE 1.3

See Also:

ParamTable.registerIndex(String, String, int)

registerIndices

public void registerIndices(String paramName,
                            String[] paramValues)

Associates a number of values of a servlet parameter with successive indices.

The Strings contained in paramValues are associated with indices starting at 0. If duplicate values occur in paramValues, the last value is used. Values in paramValues overwrite matching values that are already present in the register.

Parameters:

paramName - the String name of the parameter.

paramValues - the String[] carrying the values of the parameter.

Since:

J2SE 1.3

See Also:

ParamTable.registerIndex(String, String, int)

getIndex

public int getIndex(String paramName,
                    String paramValue)

Returns the int index associated with the paramName / paramValue pair, as established by registerIndex(String, String, int).

Specified by:

getIndex in interface ParamIndex

Parameters:

paramName - the String name of the parameter.

paramValue - the String value of the parameter.

Returns:

the associated int value of the parameter, or the int value com.opmath.util.http.ParamIndex.PARAM_INDEX_FAIL.

Since:

J2SE 1.3

See Also:

ParamTable.getIndex(String, String)

getParamIndex

public int getParamIndex(String paramName,
                         HttpServletRequest req)

Returns the int index of the parameter value found in the HttpServletRequest whose name is paramName and whose value is found in the HttpServletRequest.

Specified by:

getParamIndex in interface ParamIndex

Parameters:

paramName - the String name of the parameter.

req - the HttpServletRequest containing the parameter.

Returns:

the associated int value of the parameter, or the int value com.opmath.util.http.ParamIndex.PARAM_INDEX_FAIL.

Since:

J2SE 1.3

See Also:

ParamTable.getParamIndex(String, HttpServletRequest)

getValueCount

public int getValueCount(String paramName)

Returns the number of parameter values registered against paramName.

Specified by:

getValueCount in interface ParamIndex

Parameters:

paramName - the String name of the parameter.

Returns:

the int total number of values held against this name.

Since:

J2SE 1.3

See Also:

ParamTable.getValueCount(String)

paramNames

public Enumeration paramNames()

Returns an Enumeration of the parameter names known to the registry. Use the Enumeration methods on the returned object to fetch the keys sequentially. The enumerated objects can be cast to String.

Specified by:

paramNames in interface ParamIndex

Returns:

an Enumeration of parameter names.

Since:

J2SE 1.3

See Also:

ParamTable.paramNames()

paramMappings

public Enumeration paramMappings()

Returns an Enumeration of the parameter (value => index) mappings known to the registry. Use the Enumeration methods on the returned object to fetch the keys sequentially. The enumerated objects can be cast to com.opmath.util.dmldoc.OrderedHashTable.

Specified by:

paramMappings in interface ParamIndex

Returns:

an Enumeration of parameter (value => index) mappings.

Since:

J2SE 1.3

See Also:

ParamTable.paramMappings()

paramValues

public Enumeration paramValues(String paramName)

Returns an Enumeration of the parameter values registered against paramName. Use the Enumeration methods on the returned object to fetch the keys sequentially. The enumerated objects can be cast to String.

Specified by:

paramValues in interface ParamIndex

Parameters:

paramName - the String name of the parameter.

Returns:

an Enumeration of parameter values.

Since:

J2SE 1.3

See Also:

ParamTable.paramValues(String)

paramIndices

public Enumeration paramIndices(String paramName)

Returns an Enumeration of the parameter indices for the values registered against paramName. Use the Enumeration methods on the returned object to fetch the keys sequentially. The enumerated objects can be cast to Integer.

Specified by:

paramIndices in interface ParamIndex

Parameters:

paramName - the String name of the parameter.

Returns:

an Enumeration of parameter names.

Since:

J2SE 1.3

See Also:

ParamTable.paramIndices(String)

report

public String report(HttpServletRequest req,
                     String message)

Provides a general-purpose failure reporting mechanism, intended to be triggered within a servlet doGet(HttpServletRequest, HttpServletResponse) or doPost(HttpServletRequest, HttpServletResponse) method.

The advantage of report(HttpServletRequest) is that is give a simple way in which the doGet(HttpServletRequest, HttpServletResponse) or doPost(HttpServletRequest, HttpServletResponse) method can always return some valid HTML.

NOTE: The template resource for this report is held at com.opmath.util.http.tpl_ServletReport.html. This template may be edited, but all of its <!-- SUB .. --> commands should remain unaltered.

Parameters:

req - the javax.servlet.http.HttpServletRequest of the calling servlet.

message - a descriptive String.

Returns:

a String containing the instantiated com.opmath.util.http.tpl_ServletReport.html template.

Since:

J2SE 1.3

getServletInfo

public String getServletInfo()

Returns a String carrying some information about the servlet. This method should be overridden by the subclass of com.opmath.util.http.HttpServlet

Overrides:

getServletInfo in class GenericServlet

Returns:

a descriptive String.

Since:

J2SE 1.3