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