001 /** 002 * 003 * Copyright 2003-2004 The Apache Software Foundation 004 * 005 * Licensed under the Apache License, Version 2.0 (the "License"); 006 * you may not use this file except in compliance with the License. 007 * You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018 // 019 // This source code implements specifications defined by the Java 020 // Community Process. In order to remain compliant with the specification 021 // DO NOT add / change / or delete method signatures! 022 // 023 024 package javax.servlet; 025 026 import java.io.InputStream; 027 import java.net.MalformedURLException; 028 import java.net.URL; 029 import java.util.Enumeration; 030 import java.util.Set; 031 032 /** 033 * Defines a set of methods that a servlet uses to communicate with its 034 * servlet container, for example, to get the MIME type of a file, dispatch 035 * requests, or write to a log file. 036 * 037 * <p>There is one context per "web application" per Java Virtual Machine. (A 038 * "web application" is a collection of servlets and content installed under a 039 * specific subset of the server's URL namespace such as <code>/catalog</code> 040 * and possibly installed via a <code>.war</code> file.) 041 * 042 * <p>In the case of a web 043 * application marked "distributed" in its deployment descriptor, there will 044 * be one context instance for each virtual machine. In this situation, the 045 * context cannot be used as a location to share global information (because 046 * the information won't be truly global). Use an external resource like 047 * a database instead. 048 * 049 * <p>The <code>ServletContext</code> object is contained within 050 * the {@link ServletConfig} object, which the Web server provides the 051 * servlet when the servlet is initialized. 052 * 053 * @see Servlet#getServletConfig 054 * @see ServletConfig#getServletContext 055 * 056 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $ 057 */ 058 public interface ServletContext { 059 /** 060 * Returns a <code>ServletContext</code> object that 061 * corresponds to a specified URL on the server. 062 * 063 * <p>This method allows servlets to gain 064 * access to the context for various parts of the server, and as 065 * needed obtain {@link RequestDispatcher} objects from the context. 066 * The given path must be begin with "/", is interpreted relative 067 * to the server's document root and is matched against the context roots of 068 * other web applications hosted on this container. 069 * 070 * <p>In a security conscious environment, the servlet container may 071 * return <code>null</code> for a given URL. 072 * 073 * @param uripath a <code>String</code> specifying the context path of 074 * another web application in the container. 075 * @return the <code>ServletContext</code> object that 076 * corresponds to the named URL, or null if either none exists or the 077 * container wishes to restrict this access. 078 * 079 * @see RequestDispatcher 080 */ 081 public ServletContext getContext(String uripath); 082 083 /** 084 * Returns the major version of the Java Servlet API that this 085 * servlet container supports. All implementations that comply 086 * with Version 2.4 must have this method 087 * return the integer 2. 088 * 089 * @return 2 090 */ 091 public int getMajorVersion(); 092 093 /** 094 * Returns the minor version of the Servlet API that this 095 * servlet container supports. All implementations that comply 096 * with Version 2.4 must have this method 097 * return the integer 4. 098 * 099 * @return 4 100 */ 101 public int getMinorVersion(); 102 103 /** 104 * Returns the MIME type of the specified file, or <code>null</code> if 105 * the MIME type is not known. The MIME type is determined 106 * by the configuration of the servlet container, and may be specified 107 * in a web application deployment descriptor. Common MIME 108 * types are <code>"text/html"</code> and <code>"image/gif"</code>. 109 * 110 * @param file a <code>String</code> specifying the name 111 * of a file 112 * 113 * @return a <code>String</code> specifying the file's MIME type 114 */ 115 public String getMimeType(String file); 116 117 /** 118 * Returns a directory-like listing of all the paths to resources within 119 * the web application whose longest sub-path matches the supplied path 120 * argument. Paths indicating subdirectory paths end with a '/'. The 121 * returned paths are all relative to the root of the web application and 122 * have a leading '/'. For example, for a web application containing<br> 123 * <br> 124 * /welcome.html<br> 125 * /catalog/index.html<br> 126 * /catalog/products.html<br> 127 * /catalog/offers/books.html<br> 128 * /catalog/offers/music.html<br> 129 * /customer/login.jsp<br> 130 * /WEB-INF/web.xml<br> 131 * /WEB-INF/classes/com.acme.OrderServlet.class,<br><br> 132 * 133 * getResourcePaths("/") returns {"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}<br> 134 * getResourcePaths("/catalog/") returns {"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}.<br> 135 * 136 * @param path the partial path used to match the resources, 137 * which must start with a / 138 * @return a Set containing the directory listing, or null if there are no 139 * resources in the web application whose path begins with the supplied path. 140 * 141 * @since Servlet 2.3 142 */ 143 public Set getResourcePaths(String path); 144 145 /** 146 * Returns a URL to the resource that is mapped to a specified 147 * path. The path must begin with a "/" and is interpreted 148 * as relative to the current context root. 149 * 150 * <p>This method allows the servlet container to make a resource 151 * available to servlets from any source. Resources 152 * can be located on a local or remote 153 * file system, in a database, or in a <code>.war</code> file. 154 * 155 * <p>The servlet container must implement the URL handlers 156 * and <code>URLConnection</code> objects that are necessary 157 * to access the resource. 158 * 159 * <p>This method returns <code>null</code> 160 * if no resource is mapped to the pathname. 161 * 162 * <p>Some containers may allow writing to the URL returned by 163 * this method using the methods of the URL class. 164 * 165 * <p>The resource content is returned directly, so be aware that 166 * requesting a <code>.jsp</code> page returns the JSP source code. 167 * Use a <code>RequestDispatcher</code> instead to include results of 168 * an execution. 169 * 170 * <p>This method has a different purpose than 171 * <code>java.lang.Class.getResource</code>, 172 * which looks up resources based on a class loader. This 173 * method does not use class loaders. 174 * 175 * @param path a <code>String</code> specifying the path to the resource 176 * 177 * @return the resource located at the named path, or <code>null</code> 178 * if there is no resource at that path 179 * 180 * @exception MalformedURLException if the pathname is not given in 181 * the correct form 182 */ 183 public URL getResource(String path) throws MalformedURLException; 184 185 /** 186 * Returns the resource located at the named path as 187 * an <code>InputStream</code> object. 188 * 189 * <p>The data in the <code>InputStream</code> can be 190 * of any type or length. The path must be specified according 191 * to the rules given in <code>getResource</code>. 192 * This method returns <code>null</code> if no resource exists at 193 * the specified path. 194 * 195 * <p>Meta-information such as content length and content type 196 * that is available via <code>getResource</code> 197 * method is lost when using this method. 198 * 199 * <p>The servlet container must implement the URL handlers 200 * and <code>URLConnection</code> objects necessary to access 201 * the resource. 202 * 203 * <p>This method is different from 204 * <code>java.lang.Class.getResourceAsStream</code>, 205 * which uses a class loader. This method allows servlet containers 206 * to make a resource available 207 * to a servlet from any location, without using a class loader. 208 * 209 * @param path a <code>String</code> specifying the path 210 * to the resource 211 * 212 * @return the <code>InputStream</code> returned to the 213 * servlet, or <code>null</code> if no resource exists at the 214 * specified path 215 */ 216 public InputStream getResourceAsStream(String path); 217 218 /** 219 * Returns a {@link RequestDispatcher} object that acts 220 * as a wrapper for the resource located at the given path. 221 * A <code>RequestDispatcher</code> object can be used to forward 222 * a request to the resource or to include the resource in a response. 223 * The resource can be dynamic or static. 224 * 225 * <p>The pathname must begin with a "/" and is interpreted as relative 226 * to the current context root. Use <code>getContext</code> to obtain 227 * a <code>RequestDispatcher</code> for resources in foreign contexts. 228 * This method returns <code>null</code> if the <code>ServletContext</code> 229 * cannot return a <code>RequestDispatcher</code>. 230 * 231 * @param path a <code>String</code> specifying the pathname 232 * to the resource 233 * 234 * @return a <code>RequestDispatcher</code> object that acts as a wrapper 235 * for the resource at the specified path, or <code>null</code> if the 236 * <code>ServletContext</code> cannot return a <code>RequestDispatcher</code> 237 * 238 * @see RequestDispatcher 239 * @see ServletContext#getContext 240 */ 241 public RequestDispatcher getRequestDispatcher(String path); 242 243 /** 244 * Returns a {@link RequestDispatcher} object that acts 245 * as a wrapper for the named servlet. 246 * 247 * <p>Servlets (and JSP pages also) may be given names via server 248 * administration or via a web application deployment descriptor. 249 * A servlet instance can determine its name using 250 * {@link ServletConfig#getServletName}. 251 * 252 * <p>This method returns <code>null</code> if the 253 * <code>ServletContext</code> 254 * cannot return a <code>RequestDispatcher</code> for any reason. 255 * 256 * @param name a <code>String</code> specifying the name 257 * of a servlet to wrap 258 * 259 * @return a <code>RequestDispatcher</code> object 260 * that acts as a wrapper for the named servlet, 261 * or <code>null</code> if the <code>ServletContext</code> 262 * cannot return a <code>RequestDispatcher</code> 263 * 264 * @see RequestDispatcher 265 * @see ServletContext#getContext 266 * @see ServletConfig#getServletName 267 */ 268 public RequestDispatcher getNamedDispatcher(String name); 269 270 /** 271 * @deprecated As of Java Servlet API 2.1, with no direct replacement. 272 * 273 * <p>This method was originally defined to retrieve a servlet 274 * from a <code>ServletContext</code>. In this version, this method 275 * always returns <code>null</code> and remains only to preserve 276 * binary compatibility. This method will be permanently removed 277 * in a future version of the Java Servlet API. 278 * 279 * <p>In lieu of this method, servlets can share information using the 280 * <code>ServletContext</code> class and can perform shared business logic 281 * by invoking methods on common non-servlet classes. 282 */ 283 public Servlet getServlet(String name) throws ServletException; 284 285 /** 286 * @deprecated As of Java Servlet API 2.0, with no replacement. 287 * 288 * <p>This method was originally defined to return an <code>Enumeration</code> 289 * of all the servlets known to this servlet context. In this 290 * version, this method always returns an empty enumeration and 291 * remains only to preserve binary compatibility. This method 292 * will be permanently removed in a future version of the Java 293 * Servlet API. 294 */ 295 public Enumeration getServlets(); 296 297 /** 298 * @deprecated As of Java Servlet API 2.1, with no replacement. 299 * 300 * <p>This method was originally defined to return an 301 * <code>Enumeration</code> 302 * of all the servlet names known to this context. In this version, 303 * this method always returns an empty <code>Enumeration</code> and 304 * remains only to preserve binary compatibility. This method will 305 * be permanently removed in a future version of the Java Servlet API. 306 */ 307 public Enumeration getServletNames(); 308 309 /** 310 * Writes the specified message to a servlet log file, usually 311 * an event log. The name and type of the servlet log file is 312 * specific to the servlet container. 313 * 314 * @param msg a <code>String</code> specifying the 315 * message to be written to the log file 316 */ 317 public void log(String msg); 318 319 /** 320 * @deprecated As of Java Servlet API 2.1, use 321 * {@link #log(String message, Throwable throwable)} 322 * instead. 323 * 324 * <p>This method was originally defined to write an 325 * exception's stack trace and an explanatory error message 326 * to the servlet log file. 327 */ 328 public void log(Exception exception, String msg); 329 330 /** 331 * Writes an explanatory message and a stack trace 332 * for a given <code>Throwable</code> exception 333 * to the servlet log file. The name and type of the servlet log 334 * file is specific to the servlet container, usually an event log. 335 * 336 * @param message a <code>String</code> that 337 * describes the error or exception 338 * 339 * @param throwable the <code>Throwable</code> error 340 * or exception 341 */ 342 public void log(String message, Throwable throwable); 343 344 /** 345 * Returns a <code>String</code> containing the real path 346 * for a given virtual path. For example, the path "/index.html" 347 * returns the absolute file path on the server's filesystem would be 348 * served by a request for "http://host/contextPath/index.html", 349 * where contextPath is the context path of this ServletContext.. 350 * 351 * <p>The real path returned will be in a form 352 * appropriate to the computer and operating system on 353 * which the servlet container is running, including the 354 * proper path separators. This method returns <code>null</code> 355 * if the servlet container cannot translate the virtual path 356 * to a real path for any reason (such as when the content is 357 * being made available from a <code>.war</code> archive). 358 * 359 * @param path a <code>String</code> specifying a virtual path 360 * 361 * @return a <code>String</code> specifying the real path, 362 * or null if the translation cannot be performed 363 */ 364 public String getRealPath(String path); 365 366 /** 367 * Returns the name and version of the servlet container on which 368 * the servlet is running. 369 * 370 * <p>The form of the returned string is 371 * <i>servername</i>/<i>versionnumber</i>. 372 * For example, the JavaServer Web Development Kit may return the string 373 * <code>JavaServer Web Dev Kit/1.0</code>. 374 * 375 * <p>The servlet container may return other optional information 376 * after the primary string in parentheses, for example, 377 * <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>. 378 * 379 * @return a <code>String</code> containing at least the 380 * servlet container name and version number 381 */ 382 public String getServerInfo(); 383 384 /** 385 * Returns a <code>String</code> containing the value of the named 386 * context-wide initialization parameter, or <code>null</code> if the 387 * parameter does not exist. 388 * 389 * <p>This method can make available configuration information useful 390 * to an entire "web application". For example, it can provide a 391 * webmaster's email address or the name of a system that holds 392 * critical data. 393 * 394 * @param name a <code>String</code> containing the name of the 395 * parameter whose value is requested 396 * 397 * @return a <code>String</code> containing at least the 398 * servlet container name and version number 399 * 400 * @see ServletConfig#getInitParameter 401 */ 402 public String getInitParameter(String name); 403 404 /** 405 * Returns the names of the context's initialization parameters as an 406 * <code>Enumeration</code> of <code>String</code> objects, or an 407 * empty <code>Enumeration</code> if the context has no initialization 408 * parameters. 409 * 410 * @return an <code>Enumeration</code> of <code>String</code> 411 * objects containing the names of the context's initialization parameters 412 * 413 * @see ServletConfig#getInitParameter 414 */ 415 public Enumeration getInitParameterNames(); 416 417 418 /** 419 * Returns the servlet container attribute with the given name, 420 * or <code>null</code> if there is no attribute by that name. 421 * An attribute allows a servlet container to give the 422 * servlet additional information not 423 * already provided by this interface. See your 424 * server documentation for information about its attributes. 425 * A list of supported attributes can be retrieved using 426 * <code>getAttributeNames</code>. 427 * 428 * <p>The attribute is returned as a <code>java.lang.Object</code> 429 * or some subclass. 430 * Attribute names should follow the same convention as package 431 * names. The Java Servlet API specification reserves names 432 * matching <code>java.*</code>, <code>javax.*</code>, 433 * and <code>sun.*</code>. 434 * 435 * @param name a <code>String</code> specifying the name 436 * of the attribute 437 * 438 * @return an <code>Object</code> containing the value 439 * of the attribute, or <code>null</code> if no attribute 440 * exists matching the given name 441 * 442 * @see ServletContext#getAttributeNames 443 */ 444 public Object getAttribute(String name); 445 446 /** 447 * Returns an <code>Enumeration</code> containing the 448 * attribute names available 449 * within this servlet context. Use the 450 * {@link #getAttribute} method with an attribute name 451 * to get the value of an attribute. 452 * 453 * @return an <code>Enumeration</code> of attribute names 454 * 455 * @see #getAttribute 456 */ 457 public Enumeration getAttributeNames(); 458 459 /** 460 * Binds an object to a given attribute name in this servlet context. If 461 * the name specified is already used for an attribute, this 462 * method will replace the attribute with the new to the new attribute. 463 * <p>If listeners are configured on the <code>ServletContext</code> the 464 * container notifies them accordingly. 465 * <p> 466 * If a null value is passed, the effect is the same as calling 467 * <code>removeAttribute()</code>. 468 * 469 * <p>Attribute names should follow the same convention as package 470 * names. The Java Servlet API specification reserves names 471 * matching <code>java.*</code>, <code>javax.*</code>, and 472 * <code>sun.*</code>. 473 * 474 * @param name a <code>String</code> specifying the name 475 * of the attribute 476 * 477 * @param object an <code>Object</code> representing the 478 * attribute to be bound 479 */ 480 public void setAttribute(String name, Object object); 481 482 /** 483 * Removes the attribute with the given name from 484 * the servlet context. After removal, subsequent calls to 485 * {@link #getAttribute} to retrieve the attribute's value 486 * will return <code>null</code>. 487 * 488 * <p>If listeners are configured on the <code>ServletContext</code> the 489 * container notifies them accordingly. 490 * 491 * @param name a <code>String</code> specifying the name 492 * of the attribute to be removed 493 */ 494 public void removeAttribute(String name); 495 496 /** 497 * Returns the name of this web application correponding to this ServletContext as specified in the deployment 498 * descriptor for this web application by the display-name element. 499 * 500 * @return The name of the web application or null if no name has been declared in the deployment descriptor. 501 * @since Servlet 2.3 502 */ 503 public String getServletContextName(); 504 }