org.locomotive.loco.servlet
Class LocoServletRequest

java.lang.Object
  |
  +--org.locomotive.loco.servlet.LocoServletRequest

public class LocoServletRequest
extends java.lang.Object
implements javax.servlet.ServletRequest, javax.servlet.http.HttpServletRequest

The Locomotive Servlet Request class provides all the methods in ServletRequest and HttpServletRequest, and also provides a number of useful attributes. See the getAttribute() method for more information.


Inner Class Summary
protected  class LocoServletRequest.RequestInputStream
          Simple InputStream class that implements ServletInputStream
 
Constructor Summary
protected LocoServletRequest(int request_id, java.net.Socket sock, java.util.Hashtable cgi_envars_hash, java.util.Hashtable attributes, java.io.InputStream is, LocoServletResponse resp, java.util.Hashtable form_hash, Session session)
          Package protected constructor should be called only by ServletRoutingTable
 
Method Summary
protected  HandlerData generateForward()
          Will create a HandlerData object with this Request's fields.
 java.lang.Object getAttribute(java.lang.String name)
          returns the attribute with the specified name, if any.
 java.util.Enumeration getAttributeNames()
          returns an Enumeration of the names of all the attributes associated with this request.
 java.lang.String getAuthType()
          Returns the authentification type, if any.
 java.lang.String getCharacterEncoding()
          Returns the character encoding for the input body of the request, or null if none has been specified.
 int getContentLength()
          Returns the length of the input content, or -1 if not known
 java.lang.String getContentType()
          Returns the content (MIME) type of the request body data, or null if not available.
 javax.servlet.http.Cookie[] getCookies()
          Returns an array of Cookie objects that came in with this request.
 long getDateHeader(java.lang.String name)
          Returns the value of the requested header converted to a long representing a date expressed in milliseconds since January 1, 1970, 00:00:00GMT.
 java.lang.String getDocumentRoot()
          Returns the web server's document root filesystem path that was sent in with the request.
 java.lang.String getHeader(java.lang.String headerName)
          Gets the value of the Header field with the requested name.
 java.util.Enumeration getHeaderNames()
          This method returns an enumeration of String objects representing the header names for this request.
 javax.servlet.ServletInputStream getInputStream()
          Returns a ServletInputStream for the request body data.
 int getIntHeader(java.lang.String headerName)
          Returns an integer representation of the value of the header field with the specified name.
 java.lang.String getMethod()
          Returns the HTTP method for this request.
 java.lang.String getParameter(java.lang.String name)
          Returns the value of the input parameter with the specified name
 java.util.Enumeration getParameterNames()
          Returns an Enumeration of all the form input names.
 java.lang.String[] getParameterValues(java.lang.String name)
          Returns an array of all the values for a specified name
 java.lang.String getPathInfo()
          Returns the path information that preceded the servlet path of this request's URI, if any.
 java.lang.String getPathTranslated()
          This method gets any extra path information following the servlet path of this request's URL and translates it into a real path.
 java.lang.String getProtocol()
          Returns the request Protocol- for example, HTTP/1.1.
 java.lang.String getQueryString()
          Returns the part of the request URI that is a query String, if any.
 java.io.BufferedReader getReader()
          Returns a BufferedReader of the request body data.
 java.lang.String getRealPath(java.lang.String path)
          Deprecated. Use ServletContext.getRealPath() instead!
 java.lang.String getRemoteAddr()
          Returns the IP address of the requestor, or null if not available.
 java.lang.String getRemoteHost()
          Returns the Host name of the requestor, if available.
 java.lang.String getRemoteUser()
          Returns the name of the user making this request, if it has been set via HTTP authentification.
 java.lang.String getRequestedSessionId()
          Returns the session id specified with this request.
 int getRequestID()
          Returns the unique id for this request.
 java.lang.String getRequestURI()
          Returns, from the first line of the HTTP request, the part of this request's URL that defines the resource being requested.
 java.lang.String getScheme()
          Returns the scheme of the URL used for this request- For example: http, https, ftp.
 java.lang.String getScriptName()
          Returns the "script name".
 java.lang.String getServerName()
          Returns the server name.
 int getServerPort()
          Returns the Server Port.
 java.lang.String getServletPath()
          Returns the part of this request's URI that identifies this the servlet to be invoked.
 javax.servlet.http.HttpSession getSession()
          Gets the current valid session associated with this request
 javax.servlet.http.HttpSession getSession(boolean create)
          Gets the current valid session associated with this request, if create is false or, if necessary, creates a new session for the request, if create is true.
 boolean isRequestedSessionIdFromCookie()
          Checks whether the session id specified by this request came in as a cookie.
 boolean isRequestedSessionIdFromUrl()
          Deprecated. in favor of isRequestSessionIdFromURL()
 boolean isRequestedSessionIdFromURL()
          Checks whether the session id specified by this request came in as part of the URL.
 boolean isRequestedSessionIdValid()
          Checks whether this request is associated with a session that is valid in the current session context.
 void setAttribute(java.lang.String name, java.lang.Object obj)
          Sets an attribute with the specified name to the specified object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LocoServletRequest

protected LocoServletRequest(int request_id,
                             java.net.Socket sock,
                             java.util.Hashtable cgi_envars_hash,
                             java.util.Hashtable attributes,
                             java.io.InputStream is,
                             LocoServletResponse resp,
                             java.util.Hashtable form_hash,
                             Session session)
Package protected constructor should be called only by ServletRoutingTable
Parameters:
request_id - the RM's unique id for this request
cgi_envars_hash - the CGI variables for this request
attibutes - the attributes for this request- set up by ServletRoutingTable.routeRequest
is - the inputStream to read the request body from, if any
resp - the resp to use for sending error messages
form_hash - the parsed form data- leave as null if it isn't parsed yet
session - the session object for this request
url_tokens - the request URI, tokenified
Method Detail

getRequestID

public int getRequestID()
Returns the unique id for this request. Ids may be reused, but the IDs for any two concurrent requests will never be identical.

getAttribute

public java.lang.Object getAttribute(java.lang.String name)
returns the attribute with the specified name, if any. The following attributes are provided with the Locomotive SerlvetRequest:
   locomotive.bstamp_id       A Long containing this browser's unique
                                identity number.
   locomotive.steam_vars      A hashtable which contains STEAM insertion
                                variables
   locomotive.url_tokens      The request URI, in a tokenized format.
   locomotive.connection      A database connection to the default loco DB
   locomotive.form_data       A FormData object containing any form
                              information posted with this request.
 

The Following are supposed to be included with each Servlet manager, but are not presently part of the Locomotive Servlet Engine:

   javax.net.ssl.cipher_suite       The string name of the SSL cipher 
                                      suite in use, if the request was 
                                      made using SSL
   javax.net.ssl.peer_certificates  The chain of X.509 certificates which
                                      authenticates the client. This is 
                                      only available when SSL is used 
                                      with client authentication is used.
   javax.net.ssl.session            An SSL session object, if the request
                                       was made using SSL.
 
Specified by:
getAttribute in interface javax.servlet.ServletRequest

getAttributeNames

public java.util.Enumeration getAttributeNames()
returns an Enumeration of the names of all the attributes associated with this request.
Specified by:
getAttributeNames in interface javax.servlet.ServletRequest

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object obj)
Sets an attribute with the specified name to the specified object. If an attribute already exists with that name, it is overwritten.
Specified by:
setAttribute in interface javax.servlet.ServletRequest

getInputStream

public javax.servlet.ServletInputStream getInputStream()
                                                throws java.io.IOException
Returns a ServletInputStream for the request body data.
Specified by:
getInputStream in interface javax.servlet.ServletRequest

getReader

public java.io.BufferedReader getReader()
                                 throws java.io.IOException
Returns a BufferedReader of the request body data.
Specified by:
getReader in interface javax.servlet.ServletRequest

getParameter

public java.lang.String getParameter(java.lang.String name)
Returns the value of the input parameter with the specified name
Specified by:
getParameter in interface javax.servlet.ServletRequest

getParameterNames

public java.util.Enumeration getParameterNames()
Returns an Enumeration of all the form input names.
Specified by:
getParameterNames in interface javax.servlet.ServletRequest

getParameterValues

public java.lang.String[] getParameterValues(java.lang.String name)
Returns an array of all the values for a specified name
Specified by:
getParameterValues in interface javax.servlet.ServletRequest

getCharacterEncoding

public java.lang.String getCharacterEncoding()
Returns the character encoding for the input body of the request, or null if none has been specified.
Specified by:
getCharacterEncoding in interface javax.servlet.ServletRequest

getContentLength

public int getContentLength()
Returns the length of the input content, or -1 if not known
Specified by:
getContentLength in interface javax.servlet.ServletRequest

getContentType

public java.lang.String getContentType()
Returns the content (MIME) type of the request body data, or null if not available. Same as the CGI variable CONTENT_TYPE.
Specified by:
getContentType in interface javax.servlet.ServletRequest

getProtocol

public java.lang.String getProtocol()
Returns the request Protocol- for example, HTTP/1.1. Same as CGI variable SERVER_PROTOCOL Returns null if not available.
Specified by:
getProtocol in interface javax.servlet.ServletRequest

getRemoteAddr

public java.lang.String getRemoteAddr()
Returns the IP address of the requestor, or null if not available. Same as the CGI variable REMOTE_ADDR. Returns null if not available.
Specified by:
getRemoteAddr in interface javax.servlet.ServletRequest

getRemoteHost

public java.lang.String getRemoteHost()
Returns the Host name of the requestor, if available. If the full name is not available, the Request IP is returned, if that is available. Same as the CGI variable REMOTE_HOST. Returns null if not available.
Specified by:
getRemoteHost in interface javax.servlet.ServletRequest

getScheme

public java.lang.String getScheme()
Returns the scheme of the URL used for this request- For example: http, https, ftp.
Specified by:
getScheme in interface javax.servlet.ServletRequest

getServerName

public java.lang.String getServerName()
Returns the server name. Same as the CGI variable SERVER_NAME. Returns null if not available.
Specified by:
getServerName in interface javax.servlet.ServletRequest

getServerPort

public int getServerPort()
Returns the Server Port. Same as the CGI variable SERVER_PORT Returns -1 if not available.
Specified by:
getServerPort in interface javax.servlet.ServletRequest

getDocumentRoot

public java.lang.String getDocumentRoot()
Returns the web server's document root filesystem path that was sent in with the request.

Returns:
the document root String, or a null String if the document root wasn't found in the cgi environment variables.

getScriptName

public java.lang.String getScriptName()
Returns the "script name". Same as the cgi environment variable called "SCRIPT_NAME".

getRealPath

public java.lang.String getRealPath(java.lang.String path)
Deprecated. Use ServletContext.getRealPath() instead!

Returns a String containing the real path that corresponds to a virtual path. A virtual path contains a servlet name followed by the name of a file the servlet should act upon, in the form /dir/dir/servlet/file.ext. In this form, file.ext is a filename used instead of the path to the file. The servlet locates the file and translates the file name to the path that locates the file.

The real path the servlet returns is in a form appropriate to the computer and operating system on which the servlet engine is running, including the proper path separators. This method returns null if the servlet engine cannot translate the virtual path to a real path for any reason.

Specified by:
getRealPath in interface javax.servlet.ServletRequest
Parameters:
path - a String specifying a virtual path, in the form /dir/dir/servlet/file.ext
Returns:
a String specifying the real path, with path separators appropriate for the system on which the servlet engine is running.

getCookies

public javax.servlet.http.Cookie[] getCookies()
Returns an array of Cookie objects that came in with this request.
Specified by:
getCookies in interface javax.servlet.http.HttpServletRequest

getRequestURI

public java.lang.String getRequestURI()
Returns, from the first line of the HTTP request, the part of this request's URL that defines the resource being requested. If there is a query string, it is not included in the return value. For example a request accessed via the URL path of /catalog/books?id=1 would return /catalog/books. The return value of this method contains both the servlet path and the path info.

If any part of the URL path was URL encoded, the path must be decoded before being returned by this method.

Specified by:
getRequestURI in interface javax.servlet.http.HttpServletRequest
See Also:
javax.servlet.http.HttpRequest#getRequestURI

getQueryString

public java.lang.String getQueryString()
Returns the part of the request URI that is a query String, if any. Same as the CGI variable QUERY_STRING
Specified by:
getQueryString in interface javax.servlet.http.HttpServletRequest

getServletPath

public java.lang.String getServletPath()
Returns the part of this request's URI that identifies this the servlet to be invoked. This will not return any extra path info information for the request- use getPathInfo() or getRequestURI() for that
Specified by:
getServletPath in interface javax.servlet.http.HttpServletRequest

getPathInfo

public java.lang.String getPathInfo()
Returns the path information that preceded the servlet path of this request's URI, if any. Same as the CGI variable PATH_INFO.
Specified by:
getPathInfo in interface javax.servlet.http.HttpServletRequest

getPathTranslated

public java.lang.String getPathTranslated()
This method gets any extra path information following the servlet path of this request's URL and translates it into a real path. The request URL must be URL decoded before the translation is attempted. If there is no extra path information following the servlet path of the URL, this method returns null.
Specified by:
getPathTranslated in interface javax.servlet.http.HttpServletRequest

getRemoteUser

public java.lang.String getRemoteUser()
Returns the name of the user making this request, if it has been set via HTTP authentification. Same as the CGI variable REMOTE_USER
Specified by:
getRemoteUser in interface javax.servlet.http.HttpServletRequest

getAuthType

public java.lang.String getAuthType()
Returns the authentification type, if any. Same as the CGI variable AUTH_TYPE.
Specified by:
getAuthType in interface javax.servlet.http.HttpServletRequest

getMethod

public java.lang.String getMethod()
Returns the HTTP method for this request. Same as CGI variable REQUEST_METHOD
Specified by:
getMethod in interface javax.servlet.http.HttpServletRequest

getHeader

public java.lang.String getHeader(java.lang.String headerName)
Gets the value of the Header field with the requested name. The match between the given name and the request header is case-insensitive.
Specified by:
getHeader in interface javax.servlet.http.HttpServletRequest

getIntHeader

public int getIntHeader(java.lang.String headerName)
Returns an integer representation of the value of the header field with the specified name.
Specified by:
getIntHeader in interface javax.servlet.http.HttpServletRequest

getDateHeader

public long getDateHeader(java.lang.String name)
Returns the value of the requested header converted to a long representing a date expressed in milliseconds since January 1, 1970, 00:00:00GMT. Accepts one of the following three formats, as specified by the HTTP/1.1 spec (RFC 2068, p 20):
      Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123
      Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
      Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format
Specified by:
getDateHeader in interface javax.servlet.http.HttpServletRequest
Returns:
the date expressed in milliseconds since January 1, 1970, 00:00:00GMT. Returns -1 if the header doesn't exist.

getHeaderNames

public java.util.Enumeration getHeaderNames()
This method returns an enumeration of String objects representing the header names for this request.
Specified by:
getHeaderNames in interface javax.servlet.http.HttpServletRequest

getRequestedSessionId

public java.lang.String getRequestedSessionId()
Returns the session id specified with this request. This may differ from the session id in the current session if the session id given by the client was invalid for whatever reason and a new session was created.
Specified by:
getRequestedSessionId in interface javax.servlet.http.HttpServletRequest

getSession

public javax.servlet.http.HttpSession getSession()
Gets the current valid session associated with this request
Specified by:
getSession in interface javax.servlet.http.HttpServletRequest

getSession

public javax.servlet.http.HttpSession getSession(boolean create)
Gets the current valid session associated with this request, if create is false or, if necessary, creates a new session for the request, if create is true. Returns the present session regardless of the parameter, as new sessions are generated automatically when needed.
Specified by:
getSession in interface javax.servlet.http.HttpServletRequest

isRequestedSessionIdFromCookie

public boolean isRequestedSessionIdFromCookie()
Checks whether the session id specified by this request came in as a cookie. (The requested session may not be one returned by the getSession method.)
Specified by:
isRequestedSessionIdFromCookie in interface javax.servlet.http.HttpServletRequest
Returns:
true always- Locomotive always uses cookies

isRequestedSessionIdFromUrl

public boolean isRequestedSessionIdFromUrl()
Deprecated. in favor of isRequestSessionIdFromURL()

Checks whether the session id specified by this request came in as part of the URL. (The requested session may not be the one returned by the getSession method.)
Specified by:
isRequestedSessionIdFromUrl in interface javax.servlet.http.HttpServletRequest
Returns:
false always- Locomotive always uses cookies

isRequestedSessionIdFromURL

public boolean isRequestedSessionIdFromURL()
Checks whether the session id specified by this request came in as part of the URL. (The requested session may not be the one returned by the getSession method.)
Specified by:
isRequestedSessionIdFromURL in interface javax.servlet.http.HttpServletRequest
Returns:
false always- Locomotive always uses cookies

isRequestedSessionIdValid

public boolean isRequestedSessionIdValid()
Checks whether this request is associated with a session that is valid in the current session context.
Specified by:
isRequestedSessionIdValid in interface javax.servlet.http.HttpServletRequest

generateForward

protected HandlerData generateForward()
Will create a HandlerData object with this Request's fields. Used for the RequestDispatcher.forward() and include() methods