doc/api/Servlet/ServletContext.html

<HTML>
<HEAD>
<TITLE>Servlet::ServletContext - servlet context interface</TITLE>
<LINK REL="stylesheet" HREF="../../libservlet.css" TYPE="text/css">
<LINK REV="made" HREF="mailto:feedback@suse.de">
</HEAD>

<BODY>

<A NAME="__index__"></A>
<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#name">NAME</A></LI>
	<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
	<LI><A HREF="#description">DESCRIPTION</A></LI>
	<LI><A HREF="#methods">METHODS</A></LI>
	<LI><A HREF="#see also">SEE ALSO</A></LI>
	<LI><A HREF="#author">AUTHOR</A></LI>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="name">NAME</A></H1>
<P>Servlet::ServletContext - servlet context interface</P>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<PRE>
  for my $name ($context-&gt;getAttributeNames()) {
      my $value = $context-&gt;getAttribute($name);
      $context-&gt;removeAttribute($name);
      $cnotext-&gt;setAttribute($name, $value);
  }</PRE>
<PRE>
  my $context = $context-&gt;getContext($uripath);</PRE>
<PRE>
  for my $name ($context-&gt;getInitParameterNames()) {
      my $value = $context-&gt;getInitParameter($name);
  }</PRE>
<PRE>
  for my $uripath ($context-&gt;getResourcePaths()) {
      my $url = $context-&gt;getResource($uripath);
      my $handle = $context-&gt;getResourceAsHandle($uripath);
      my $realpath = $context-&gt;getRealPath($uripath);
      my $dispatcher = $context-&gt;getRequestDispatcher($uripath);
  }</PRE>
<PRE>
  my $type = $context-&gt;getMimeType($file);</PRE>
<PRE>
  my $dispatcher = $context-&gt;getNamedDispatcher($name);</PRE>
<PRE>
  my $major = $context-&gt;getMajorVersion();
  my $minor = $context-&gt;getMinorVersion();
  my $info = $context-&gt;getServerInfo();
  my $name = $context-&gt;getServletContextName();</PRE>
<PRE>
  $contxt-&gt;log($message, $e);</PRE>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P>Defines a set of methods that a servlet uses to communicate with its
servlet container, for example, to get the MIME type of a file,
dispatch requests, or write to a log file.</P>
<P>There is one context per web application per Perl interpreter. A ``web
application'' is a collection of servlets and content installed under a
specific subset of the server's URL namespace.</P>
<P>In the case of a web application marked ``distributed'' in its
deployment descriptor, there will be one context instance for each
interpreter. In this situation, the context cannot be used as a
location to share global information (because the information won't
truly be global). Use an external resource like a database instead.</P>
<P>The <STRONG>Servlet::ServletContext</STRONG> object is contained within the
<STRONG>Servlet::ServletConfig</STRONG> object, which the servlet container provides
the servlet when the servlet is initialized.</P>
<P>
<HR>
<H1><A NAME="methods">METHODS</A></H1>
<DL>
<DT><STRONG><A NAME="item_getAttribute"><CODE>getAttribute($name)</CODE></A></STRONG><BR>
<DD>
Returns the servlet container attribute with the given name, or
<EM>undef</EM> if there is no attribute by that name. An attribute allows a
servlet container 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 <A HREF="#item_getAttributeNames"><CODE>getAttributeNames()</CODE></A>.
<P>The attribute is returned as a Perl scalar or reference. Attribute
names should follow the same convention as package names. The Servlet
API specification reserves names matching <EM>main::*</EM>, <EM>CORE::*</EM>,
<EM>UNIVERSAL::*</EM>, and any other standard reserved package names.</P>
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><A NAME="item_%24name"><EM>$name</EM></A></STRONG><BR>
<DD>
the name of the attribute
<P></P></DL>
<DT><STRONG><A NAME="item_getAttributeNames"><CODE>getAttributeNames()</CODE></A></STRONG><BR>
<DD>
Returns an array containing the attribute names available within this
servlet context, or an empty array if no attributes are available for
the context.
<P></P>
<DT><STRONG><A NAME="item_getContext"><CODE>getContext($uripath)</CODE></A></STRONG><BR>
<DD>
Returns a <STRONG>Servlet::ServletContext</STRONG> object that corresponds to a
specified URL on the server.
<P>This method allows servlets to gain access to the context for various
parts of the server, and as needed obtain
<STRONG>Servlet::RequestDispatcher</STRONG> objects from the context. The given path
must be absolute (beginning with '/') and is intepreted based on the
server's document root.</P>
<P>In a security conscious environment, the servlet container may return
<EM>undef</EM> for a given URL.</P>
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><A NAME="item_%24uripath"><EM>$uripath</EM></A></STRONG><BR>
<DD>
the absolute URL of a resource on the server
<P></P></DL>
<DT><STRONG><A NAME="item_getInitParameter"><CODE>getInitParameter($name)</CODE></A></STRONG><BR>
<DD>
Returns the vlaue of the named context-wide initialization parameter,
or <EM>undef</EM> if the parameter does not exist.
<P>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.</P>
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><EM>$name</EM></STRONG><BR>
<DD>
the name of the init parameter
<P></P></DL>
<DT><STRONG><A NAME="item_getInitParameterNames"><CODE>getInitParameterNames()</CODE></A></STRONG><BR>
<DD>
Returns an array containing the names of the context's initialization
parameters, or an empty array if the context has no initialization
parameters.
<P></P>
<DT><STRONG><A NAME="item_getMajorVersion"><CODE>getMajorVersion()</CODE></A></STRONG><BR>
<DD>
Returns the major version of the Servlet API that this servlet
container supports. All implementations that comply with Version 2.3
must have this method return the integer 2.
<P></P>
<DT><STRONG><A NAME="item_getMimeType"><CODE>getMimeType($file)</CODE></A></STRONG><BR>
<DD>
Returns the MIME type of the specified file, or <EM>undef</EM> 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
deployment descriptor. Common MIME types are ``text/html'' and
``image/gif''.
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><A NAME="item_%24file"><EM>$file</EM></A></STRONG><BR>
<DD>
the name of a file
<P></P></DL>
<DT><STRONG><A NAME="item_getMinorVersion"><CODE>getMinorVersion()</CODE></A></STRONG><BR>
<DD>
Returns the minor version of the Servlet API that this servlet
container supports. All implementations that comply with Version 2.3
must have this method return the integer 3.
<P></P>
<DT><STRONG><A NAME="item_getNamedDispatcher"><CODE>getNamedDispatcher($name)</CODE></A></STRONG><BR>
<DD>
Returns a <STRONG>Servlet::RequestDispatcher</STRONG> object that acts as a wrapper
for the named servlet, or <EM>undef</EM> if the context cannot return a
dispatcher object for any reason.
<P>Servlets may be given names via server administration or via a web
appliation deployment descriptor. A servlet instance can determine its
name using <CODE>getServletName()</CODE>.</P>
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><EM>$name</EM></STRONG><BR>
<DD>
the name of a servlet
<P></P></DL>
<DT><STRONG><A NAME="item_getRealPath"><CODE>getRealPath($uripath)</CODE></A></STRONG><BR>
<DD>
Returns the real path for a given virtual path, or <EM>undef</EM> if the
servlet container cannot translate the virtual path to a real path for
any reason. For example, the path ``/index.html'' returns the absolute
file path on the server's filesystem that would be served by a request
for ``http://host:port/contextPath/index.html'', where contextPath is
the context path of this context.
<P>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.</P>
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><EM>$uripath</EM></STRONG><BR>
<DD>
the virtual path
<P></P></DL>
<DT><STRONG><A NAME="item_getRequestDispatcher"><CODE>getRequestDispatcher($uripath)</CODE></A></STRONG><BR>
<DD>
Returns a <STRONG>Servlet::RequestDispatcher</STRONG> object that acts as a wrapper
for the resource located at the given path, or <EM>undef</EM> if the context
cannot return a dispatcher. A dispatcher 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.
<P>The uripath must begin with a '/' and is interpreted as relative to
the current context root. Use <A HREF="#item_getContext"><CODE>getContext()</CODE></A> to obtain a dispatcher
for resources in foreign contexts.</P>
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><EM>$uripath</EM></STRONG><BR>
<DD>
the uri path to the resource
<P></P></DL>
<DT><STRONG><A NAME="item_getResource"><CODE>getResource($uripath)</CODE></A></STRONG><BR>
<DD>
Returns a URL to the resource that is mapped to a specified uri path,
or <EM>undef</EM> if no resource is mapped to the uri path. The path must
begin with a '/' and is interpreted as relative to the current context
root.
<P>This method allows the servlet 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, etc.</P>
<P>The servlet container must implement any objects that are necessary to
access the resource.</P>
<P>The resource content is returned directly in an unprocessed form. Use
a <STRONG>Servlet::RequestDispatcher</STRONG> instead to include results of an
execution.</P>
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><EM>$uripath</EM></STRONG><BR>
<DD>
the uri path to the resource
<P></P></DL>
<DT><STRONG><A NAME="item_getResourceAsHandle"><CODE>getResourceAsHandle($uripath)</CODE></A></STRONG><BR>
<DD>
Returns the resource located at the named uri path as an opened
<STRONG>IO::Handle</STRONG>, or <EM>undef</EM> if no resource exists at the specified
path).
<P>The data in the filehandle can be of any type or length. The uri path
must be specified according to the rules given in <A HREF="#item_getResource"><CODE>getResource()</CODE></A>.</P>
<P>Meta-information such as content length and content type that is
available via <A HREF="#item_getResource"><CODE>getResource()</CODE></A> is lost when using this method.</P>
<P>The servlet container must implement any objects that are necessary to
access the resource.</P>
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><EM>$uripath</EM></STRONG><BR>
<DD>
the uri path to the resource
<P></P></DL>
<DT><STRONG><A NAME="item_getResourcePaths"><CODE>getResourcePaths()</CODE></A></STRONG><BR>
<DD>
Returns an array containing all the paths to resources held in the web
application. All paths begin with '/' and are relative to the root of
the web application.
<P></P>
<DT><STRONG><A NAME="item_getServerInfo"><CODE>getServerInfo()</CODE></A></STRONG><BR>
<DD>
Returns the name and version of the servlet container on which the
servlet is running.
<P>The form of the returned string is <EM>servername/versionnumber</EM>. For
example:</P>
<PRE>
  Wombat/1.0</PRE>
<P>The servlet container may return other optional information after the
primary string in parentheses. For example:</P>
<PRE>
  Wombat/1.0 (perl 5.6.0; Linux 2.2.18 i686)</PRE>
<P></P>
<DT><STRONG><A NAME="item_getServletContextName"><CODE>getServletContextName()</CODE></A></STRONG><BR>
<DD>
Returns the name of the web application corresponding to this context
as specified in the deployment descriptor for the web appliation.
<P></P>
<DT><STRONG><A NAME="item_log">log($message, [$e])</A></STRONG><BR>
<DD>
Writes the specified message (and stack trace, if an optional
exception is specified) to the servlet log, prepended by the servlet's
name.
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><A NAME="item_%24message"><EM>$message</EM></A></STRONG><BR>
<DD>
the error message
<P></P>
<DT><STRONG><A NAME="item_%24e"><EM>$e</EM></A></STRONG><BR>
<DD>
an instance of <STRONG>Servlet::Util::Exception</STRONG> (optional)
<P></P></DL>
<DT><STRONG><A NAME="item_removeAttribute"><CODE>removeAttribute($name)</CODE></A></STRONG><BR>
<DD>
Removes the attribute with the given name from the servlet
context. After removal, subsequent calls to <A HREF="#item_getAttribute"><CODE>getAttribute()</CODE></A> to
retrieve the attribute's value will return <EM>undef</EM>.
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><EM>$name</EM></STRONG><BR>
<DD>
the name of the attribute
<P></P></DL>
<DT><STRONG><A NAME="item_setAttribute">setAttribute($name, $value)</A></STRONG><BR>
<DD>
Binds an object to a given attribute name in the servlet contxt. If
the name specified is already used for an attribute, the old attribute
is removed and the name bound to the new attribute.
<P>See <A HREF="#item_getAttribute"><CODE>getAttribute()</CODE></A> for details on attribute naming.</P>
<P><STRONG>Parameters:</STRONG></P>
<DL>
<DT><STRONG><EM>$name</EM></STRONG><BR>
<DD>
the name of the attribute
<P></P>
<DT><STRONG><A NAME="item_%24value"><EM>$value</EM></A></STRONG><BR>
<DD>
the attribute to be bound
<P></P></DL>
</DL>
<P>
<HR>
<H1><A NAME="see also">SEE ALSO</A></H1>
<P><A HREF="../../api/IO/Handle.html">the IO::Handle manpage</A>,
<A HREF="../../api/Servlet/GenericServlet.html">the Servlet::GenericServlet manpage</A>,
<A HREF="../../api/Servlet/RequestDispatcher.html">the Servlet::RequestDispatcher manpage</A>,
<A HREF="../../api/Servlet/ServletConfig.html">the Servlet::ServletConfig manpage</A>,
<A HREF="../../api/Servlet/Util/Exception.html">the Servlet::Util::Exception manpage</A></P>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<P>Brian Moseley, <A HREF="mailto:bcm@maz.org">bcm@maz.org</A></P>

</BODY>

</HTML>
	Global
`s`	Focus search bar
`?`	Bring up this help dialog
	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)
	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse
	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)