home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 November / PCWorld_2000-11_cd.bin / Komunik / sambar444 / _SETUP.1 / javaeng.jar / javax / servlet / ServletContext.java < prev    next >
Text File  |  2000-08-09  |  11KB  |  355 lines
  1. /*
  2.  * ServletContext.java -- Interface for class containing servlet context data
  3.  *
  4.  * Copyright (c) 1998, 1999 by Free Software Foundation, Inc.
  5.  * Written by Paul Siegmann (pauls@euronet.nl)
  6.  *
  7.  * This program is free software; you can redistribute it and/or modify
  8.  * it under the terms of the GNU Library General Public License as published
  9.  * by the Free Software Foundation, version 2. (see COPYING.LIB)
  10.  *
  11.  * This program is distributed in the hope that it will be useful, but
  12.  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with this program; if not, write to the Free Software Foundation
  18.  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307 USA
  19.  */
  20.  
  21. package javax.servlet;
  22.  
  23. import java.lang.Exception;
  24. import java.io.InputStream;
  25. import java.net.URL;
  26. import java.net.MalformedURLException;
  27. import java.util.Enumeration;
  28. import java.util.Locale;
  29.  
  30. /**
  31.  * A class created by the server to give servlets access to certain
  32.  * environment related objects and methods.<BR>
  33.  * It contains standard information like the names of all the servlets,
  34.  * two kinds of log methods, the server name, etc.<BR>
  35.  * The server can also store extra information here in the form
  36.  * of {String, Object} pairs.
  37.  * Different servlets can live in different ServletContexts,
  38.  * but a servlet engine can group related Servlets in the same
  39.  * ServletContext.<BR>
  40.  * Servlet specific information can be transferred to a servlet using
  41.  * a class implementing the ServletConfig interface.<BR>
  42.  *
  43.  * @version Servlet API 2.2
  44.  * @since Servlet API 1.0
  45.  * @author Paul Siegmann (pauls@euronet.nl)
  46.  */
  47. public interface ServletContext
  48. {
  49.     /**
  50.      * Gets the value of a named attribute
  51.      *
  52.      * @since Servlet API 1.0
  53.      *
  54.      * @param name the name of the attribute
  55.      * @return the value of the attribute or null if there is no attribute with
  56.      * this name
  57.      */
  58.     Object getAttribute (String name);
  59.  
  60.  
  61.     /**
  62.      * Gets an enumeration containing all the attribute names
  63.      *
  64.      * @since Servlet API 2.1
  65.      *
  66.      * @return The enumeration containing all the attribute names
  67.      */
  68.     Enumeration getAttributeNames ();
  69.  
  70.  
  71.     /**
  72.      * Gives the <code>ServletContext</code> of another servlet indicated by
  73.      * the <code>UriPath</code> on the same server. For security reasons this
  74.      * can return null even if there is an active servlet at that location.
  75.      * This can then be used to set attributes in the context of another
  76.      * servlet.
  77.      * @see javax.servlet.ServletContext#setAttribute(java.lang.String, java.lang.Object)
  78.      *
  79.      * @since Servlet API 2.1
  80.      *
  81.      * @param UriPath The path to the servlet,
  82.      * such as <code>/servlet/ShowBook</code>
  83.      * @return ServletContext of the requested servlet or null if there is no
  84.      * servlet at the requested <code>UriPath</code> or when it is unavailable
  85.      * due to security restrictions
  86.      */
  87.     ServletContext getContext (String UriPath);
  88.  
  89.  
  90.     /**
  91.      * Major version number of the Servlet API the servlet engine supports.
  92.      *
  93.      * @since Servlet API 2.1
  94.      *
  95.      * @return 2 if the 2.1 Servlet API is supported
  96.      */
  97.     int getMajorVersion ();
  98.  
  99.     /**
  100.      * Minor version number of the Servlet API the servlet engine supports.
  101.      *
  102.      * @since Servlet API 2.1
  103.      *
  104.      * @return 1 if the 2.1 Servlet API is supported
  105.      */
  106.     int getMinorVersion ();
  107.  
  108.  
  109.     /**
  110.      * Gives the mimetype of the requested file
  111.      *
  112.      * @since Servlet API 1.0
  113.      *
  114.      * @param filename the file
  115.      * @return a String containing the mime type
  116.      * or null if the mime type cannot be determined
  117.      */
  118.     String        getMimeType    (String filename);
  119.     
  120.  
  121.     /**
  122.      * Translates the requested virtual path to the real filesystem path
  123.      * using the servers knowledge of the document root.
  124.      * Use the <code>getResource</code> and <code>getResourceAsStream</code>
  125.      * methods to access the original object in a more abstract way not tied to
  126.      * the filesystem.
  127.      * @see javax.servlet.ServletContext#getResource(java.lang.String)
  128.      * @see javax.servlet.ServletContext#getResourceAsStream(java.lang.String)
  129.      *
  130.      * @since Servlet API 1.0
  131.      *
  132.      * @param virtualPath the path to be translated
  133.      * (e.g. <code>/graphics/baby-gnu.png</code>)
  134.      * @return the translated real filesystem path
  135.      * or null if the real system path cannot be found
  136.      */
  137.     String        getRealPath    (String virtualPath);
  138.  
  139.  
  140.     /**
  141.      * Translates the requested virtual path to an URL object that can be
  142.      * accesed by the servlet. This is more generic than the
  143.      * <code>getRealPath</code> method since it is not tied to the local
  144.      * filesystem. This means that a servlet can access the resource even when
  145.      * loaded in a servlet engine on a different machine. The servlet engine
  146.      * should make sure that the appropriate <code>URLStreamHandlers</code> and
  147.      * <code>URLConnection</code> classes are implemented to acces to resource.
  148.      * <p>
  149.      * This can also be used to write to a resource if the resource
  150.      * (<code>URLConnection</code>) supports it. The following example gives
  151.      * you an <code>OutputStream</code>:<br>
  152.      * <p>
  153.      * <code>
  154.      * URLConnection con = getResource("/logs/mylog.txt").openConnection();<br>
  155.      * con.setDoOutput(true);<br>
  156.      * OutputStream out = con.getOutputStream();<br>
  157.      * </code>
  158.      * <p>
  159.      * Note that a <code>ServerContext</code> does not have to have access to
  160.      * the complete servers document space and is allowed to return null even
  161.      * for valid virtual paths.
  162.      * <p>
  163.      * Note that according to the 2.1 API documentation this method can throw
  164.      * a MalformedURLException. But according to the official spec it does not
  165.      * throw any exceptions.
  166.      *
  167.      * @since Servlet API 2.1
  168.      *
  169.      * @see java.net.URL#openConnection()
  170.      * @see java.net.URLConnection#setDoOutput(boolean)
  171.      * @see java.net.URLConnection#getOutputStream()
  172.      *
  173.      * @param virtualPath the path to the requested resource
  174.      * (e.g. <code>/philosophy/words-to-avoid.html</code>)
  175.      * @return the URL that can be used to access the resource
  176.      * or null if the resource cannot be found
  177.      */
  178.     URL getResource (String virtualPath) throws MalformedURLException;
  179.  
  180.  
  181.     /**
  182.      * XXX
  183.      */
  184.     URL getResource (String virtualPath, Locale locale) throws MalformedURLException;
  185.  
  186.  
  187.     /**
  188.      * A convenience method for
  189.      * <code>getResource(virtualPath).openStream()</code>.
  190.      * But the servlet engine is allowed to implement is in a more efficient
  191.      * way.
  192.      *
  193.      * @see javax.servlet.ServletContext#getResource(java.lang.String)
  194.      * @see java.net.URL#openStream()
  195.      *
  196.      * @since Servlet API 2.1
  197.      *
  198.      * @param virtualPath the path to the requested resource
  199.      * (e.g. <code>/philosophy/words-to-avoid.html</code>)
  200.      * @return the InputStream that can be used to read the resource
  201.      * or null if the resource cannot be found
  202.      */
  203.     InputStream getResourceAsStream(String virtualPath);
  204.  
  205.     /**
  206.      * XXX
  207.      */
  208.     InputStream getResourceAsStream(String virtualPath, Locale locale);
  209.  
  210.     /**
  211.      * Returns a <code>RequestDispatcher</code> to forward requests or
  212.      * include responses from another (active) resource. Some resources can also
  213.      * be accessed by the <code>getResource</code> method.
  214.      *
  215.      * @see javax.servlet.ServletContext#getResource(java.lang.String)
  216.      *
  217.      * @since Servlet API 2.1
  218.      *
  219.      * @param UriPath the path to another (active) resource
  220.      * (e.g. <code>/servlet/OtherServlet</code>)
  221.      * @return an <code>RequestDispatcher</code> for the (active) resource
  222.      * found at <code>UriPath</code>
  223.      */
  224.     RequestDispatcher getRequestDispatcher (String UriPath);
  225.  
  226.     /**
  227.      * XXX
  228.      */
  229.     RequestDispatcher getNamedDispatcher(String name);
  230.  
  231.  
  232.     /**
  233.      * A server supplied string containing the server name, version number, etc
  234.      *
  235.      * @since Servlet API 1.0
  236.      *
  237.      * @return the string
  238.      */
  239.     String getServerInfo ();
  240.  
  241.     /**
  242.      * XXX
  243.      */
  244.     String getInitParameter(String name);
  245.  
  246.     /**
  247.      * XXX
  248.      */
  249.     Enumeration getInitParameterNames();
  250.  
  251.     /**
  252.      * Writes a message to the log
  253.      *
  254.      * @since Servlet API 1.0
  255.      *
  256.      * @param message the message to write
  257.      */
  258.     void log (String message);
  259.  
  260.  
  261.     /**
  262.      * Writes an exception + message to the log
  263.      *
  264.      * @since Servlet API 2.1
  265.      *
  266.      * @param t the exception
  267.      * @param message the message
  268.      */
  269.     void log (String message, Throwable t);
  270.  
  271.  
  272.     /**
  273.      * Writes an exception + message to the log
  274.      *
  275.      * @deprecated Use <code>log(String, Throwable)</code> which is more
  276.      * general.
  277.      *
  278.      * @see javax.servlet.ServletContext#log(java.lang.String, java.lang.Throwable)
  279.      * @since Servlet API 2.0
  280.      *
  281.      * @param exception the exception
  282.      * @param message the message
  283.      */
  284.     void log (Exception exception, String message);
  285.  
  286.  
  287.     /**
  288.      * Puts a named object into the <code>ServletContext</code>.
  289.      * Can be used to communicate with other servlets in this
  290.      * <code>ServletContext</code>. The names used must follow the conventions
  291.      * used for naming java packages.
  292.      *
  293.      * @since Servlet API 2.1
  294.      *
  295.      * @param name - which is used to refer to this object
  296.      * @param object - which should be returned when somebody calls
  297.      * <code>getAttribute(name)</code>
  298.      * @see javax.servlet.ServletContext#getAttribute(java.lang.String)
  299.      */
  300.     void setAttribute(String name, Object o);
  301.  
  302.  
  303.     /**
  304.      * Removes the named object from the <code>ServletContext</code>
  305.      *
  306.      * @since Servlet API 2.1
  307.      *
  308.      * @param name The name which was used to set the object with
  309.      * <code>setObject</code>
  310.      */
  311.     void removeAttribute(String name);
  312.  
  313.  
  314.     /**
  315.      * Gets a specific servlet by name. The Servlet is guaranteed to accept
  316.      * service requests.
  317.      * @deprecated Always returns null. Since the servlet engine cannot know
  318.      * if a servlet ever gives up the reference to another servlet it could
  319.      * never destroy the servlet after this call.
  320.      * Only the servlet engine should have references to Servlets.
  321.      *
  322.      * @since Servlet API 1.0
  323.      *
  324.      * @param name the name of the wanted servlet
  325.      * @return null, used to return the servlet or null if not loaded.
  326.      * @exception ServletException if a servlet related error occured
  327.      */
  328.     Servlet        getServlet    (String name) throws ServletException;
  329.  
  330.  
  331.     /**
  332.      * Gets all servlets
  333.      * @deprecated Always returns an empty Enumeration.
  334.      * Only the servlet engine should have references to Servlets.
  335.      *
  336.      * @since Servlet API 1.0
  337.      *
  338.      * @return Empty Enumeration, used to return an enumeration containing all
  339.      * loaded servlets including the calling servlet.
  340.      */
  341.     Enumeration    getServlets    ();
  342.  
  343.  
  344.     /**
  345.      * Gets all servlet names
  346.      * @deprecated Always returns an empty Enumeration.
  347.      * Only the servlet engine should have references to Servlets.
  348.      * @since Servlet API 2.0
  349.      *
  350.      * @return Empty Enumeration, used to return an enumeration containing all
  351.      * loaded servlet names including the calling servlet name
  352.      */
  353.     Enumeration    getServletNames    ();
  354. }
  355.