NAME

Wombat::Connector::RequestBase - internal request base class


SYNOPSIS

  package My::Connector::Request;
  use base qw(Wombat::Connector::RequestBase);


DESCRIPTION

Convenience base implementation of Wombat::Request and Servlet::ServletRequest which can be used for most connectors. Only connector-specific methods need to be implemented.


CONSTRUCTOR

new()
Construct and return a Wombat::Connector::RequestBase instance, initializing fields appropriately. If subclasses override the constructor, they must be sure to call
  $self->SUPER::new();


ACCESSOR METHODS

getApplication()
Return the Application within which this request is being processed.

setApplication($application)
Set the Application within which this request is being processed. This must be called as soon as the appropriate Application is identified, because it enables parsing of the request URI.

Parameters:

$application
the Wombat::Application within which the request is being processed

getAttribute($name)
Return the value of the named attribute.

Parameters:

$name
the name of the attribute

getAttributeNames()
Return an array containing the names of the attributes available to this request.

removeAttribute($name)
Remove the named attribute from this request.

Parameters:

$name
the name of the attribute

setAttribute($name, $value)
Set the named attribute in this request.

Parameters:

$name
the name of the attribute

$value
the value to be set, a scalar or a reference

getAuthorization()
Return the authorization credentials sent with this request.

setAuthorization($authorization)
Sets the authorization credentials sent with this request.

Parameters:

$authorization
the authorization credentials

getCharacterEncoding()
Return the name of the character encoding used in the body of this request.

setCharacterEncoding($name)
Set the name of the character encoding used for the body of this request. This method must be called prior to reading request parameters or reading input using getReader().

Parameters:

$name
the name of the encoding

Throws:

Servlet::Util::UnsupportedEncodingException
if this is not a valid encoding

getConnector()
Return the Connector through which this request was received.

setConnector($connector)
Set the Connector through which this request was received.

Parameters:

$connector
the Wombat::Connector that received the request

getContentLength()
Return the content length, in bytes, of the request body provided by the input handle.

setContentLength($length)
Set the length, in bytes, of the request body provided by the input handle.

Parameters:

$length
the content length in bytes

getContentType()
Return the MIME type of the body of the request.

setContentType($type)
Set the MIME type of the body of this Request. If the charset parameter is specified, the character encoding of this Request is also set.

Parameters:

$type
the MIME type

getHandle()
Return the underlying input handle associated with this request. Usually the Socket and Handle for the request are the same object, but this is not required.

setHandle($handle)
Set the input handle ssociated with this request.

Parameters:

$handle
the IO::Handle associated with this request

getInputHandle()
Return the Servlet::ServletInputHandle that wraps the underlying input handle (see getHandle(). The default implementation returns a handle created by createInputHandle().

Throws:

Servlet::Util::IllegalStateException
if getReader() has already been called for this request

Servlet::Util::IOException
if an input or output exception occurred

getLocale()
Return the preferred locale that the client will accept content in, based on the value for the first Accept-Language header that was encountered. If the request did not specify a preferred language, the server's default locale is returned.

getLocales()
Return the set of preferred locales specified by the client, based on the values for any Accept-Language headers that were encountered. If the request did not specify a preferred language, the server's default locale is returned.

addLocale($loc)
Add a locale to the set of preferred Locales for this Request.

Parameters:

$loc
the locale to add

clearLocales()
Clear the list of locales for this Request.

getParameter($name)
Return the value of the named request parameter. If more than one value is defined, return only the first one.

Parameters:

$name
the name of the parameter

getParameterMap()
Return a hash of the parameters of this Request. The keys of the hash are the parameter names, and the values of the hash are arrays of parameter values.

getParameterNames()
Return an array containing the names of the parameters contained in this Request.

getParameterValues($name)
Return an array containing all of the values of the named request parameter.

Parameters:

$name
the name of the parameter

addParameter($name, @values)
Add a named parameter with one or more values to this Request.

Parameters:

$name
the name of the parameter to add

@values
a list of one or more parameter values, scalar or undef

clearParameters()
Clear the set of parameters for this Request.

getProtocol()
Return the name and version of the protocol used for the request.

setProtocol($protocol)
Set the name and version of the protocol used for the request in the form protocol/majorVersion.minorVersion.

Parameters:

$protocol
the name and version of the protocol

getReader()
Return the XXX that wraps the ServletInputHandle for this request (see getInputHandle(). The default implementation returns a XXX wrapped around handle created by createInputHandle().

Throws:

Servlet::Util::UnsupportedEncodingException
if the character encoding used is not supported and the text cannot be decoded

Servlet::Util::IllegalStateException
if getInputHandle() has already been called for this request

Servlet::Util::IOException
if an input or output exception occurred

getRemoteAddr()
Return the remote IP address of the client making this request.

setRemoteAddr($addr)
Set the remote IP address of the client making this request. This value will be used to resolve the name of the remote host if necessary (see getRemoteHost()).

Parameters:

$addr
the remote IP address

getRemoteHost()
Return the remote host name of the client making this request.

setRemoteHost($host)
Set the remote host name of the client making this request.

Parameters:

$host
the remote host name

getRequest()
Return the ServletRequest for which this object is the facade.

getRequestDispatcher($path)
Return a Servlet::RequestDispatcher object that acts as a wrapper for the resource located at the given path. The path may be absolute (relative to the context path) or relative to the current request URI.

Parameters:

$path
The path to the resource

getResponse()
Return the Response with which this request is associated.

setResponse()
Set the Response with which this request is associated.

Parameters:

$response
the Wombat::Response with which this request is associated

getScheme()
Return the name of the scheme used to make this request.

setScheme($scheme)
Set the name of the scheme used to make this request, for example http, https, or ftp.

Parameters:

$scheme
the name of the scheme

isSecure()
Return a flag indicating whether or not this request was made using a secure channel.

setSecure($flag)
Set a flag indicating whether or not the request was made using a secure channel.

Parameters:

$flag
a boolean value

getServerName()
Return the host name of the server which received this request.

setServerName($name)
Set the host name of the server which received this request.

Parameters:

$name
the host name

getServerPort()
Return the port number on which this request was received.

setServerPort($port)
Set the port number on which this request was received.

Parameters:

$port
the port number

getSocket()
Return the Socket (if any) through which this request was received. This should only be used to access underlying state information about the Socket, such as the SSL information of a IO::Socket::SSL.

setSocket($socket)
Set the Socket (if any) through which this request was received.

Parameters:

$socket
the IO::Socket through which this request was received

getWrapper()
Return the Wrapper within which this request is being processed.

setWrapper($wrapper)
Set the Wrapper within which this request is being processed. This must be called as soon as the appropriate Wrapper is identified, and before the request is ultimately passed to an application servlet.

Parameters:

$wrapper
the Wombat::Wrapper associated with this request


PUBLIC METHODS

createInputHandle()
Create and return a Servlet::ServletInputHandle to read the content associated with this request.

Throws:

Servlet::Util::IOException
if an input or output error occurs

finishRequest()
Perform whatever actions are required to flush and close the input handle or reader.

Throws:

Servlet::Util::IOException
if an input or output error occurs

recycle()
Release all object references and initialize instances variables in preparation for use or reuse of this object.


SEE ALSO

the IO::Handle manpage, the IO::Socket manpage, the Servlet::ServletRequest manpage, the Servlet::ServletServletInputHandle manpage, the Servlet::Util::Exception manpage, the Wombat::Application manpage, the Wombat::Connector manpage, the Wombat::Request manpage, the Wombat::Response manpage, the Wombat::Wrapper manpage


AUTHOR

Brian Moseley, bcm@maz.org