Your browser does not support JavaScript and this site utilizes JavaScript to build content and provide links to additional information. You should either enable JavaScript in your browser settings or use a browser that supports JavaScript in order to take full advantage of this site.

1 /*2 * Licensed to the Apache Software Foundation (ASF) under one or more3 * contributor license agreements. See the NOTICE file distributed with4 * this work for additional information regarding copyright ownership.5 * The ASF licenses this file to You under the Apache License, Version 2.06 * (the "License"); you may not use this file except in compliance with7 * the License. You may obtain a copy of the License at8 *9 * http://www.apache.org/licenses/LICENSE-2.010 *11 * Unless required by applicable law or agreed to in writing, software12 * distributed under the License is distributed on an "AS IS" BASIS,13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.14 * See the License for the specific language governing permissions and15 * limitations under the License.16 */17 package javax.servlet;18 19 importjava.io.InputStream;20 importjava.net.MalformedURLException;21 importjava.net.URL;22 importjava.util.Enumeration;23 importjava.util.Set;24 25 26 /**27 * 28 * Defines a set of methods that a servlet uses to communicate with its29 * servlet container, for example, to get the MIME type of a file, dispatch30 * requests, or write to a log file.31 *32 * <p>There is one context per "web application" per Java Virtual Machine. (A33 * "web application" is a collection of servlets and content installed under a34 * specific subset of the server's URL namespace such as <code>/catalog</code>35 * and possibly installed via a <code>.war</code> file.) 36 *37 * <p>In the case of a web38 * application marked "distributed" in its deployment descriptor, there will39 * be one context instance for each virtual machine. In this situation, the 40 * context cannot be used as a location to share global information (because41 * the information won't be truly global). Use an external resource like 42 * a database instead.43 *44 * <p>The <code>ServletContext</code> object is contained within 45 * the {@link ServletConfig} object, which the Web server provides the46 * servlet when the servlet is initialized.47 *48 * @author Various49 * @version $Version$50 *51 * @see Servlet#getServletConfig52 * @see ServletConfig#getServletContext53 *54 */55 56 publicinterface ServletContext {57 58 59 /**60 * Returns a <code>ServletContext</code> object that 61 * corresponds to a specified URL on the server.62 *63 * <p>This method allows servlets to gain64 * access to the context for various parts of the server, and as65 * needed obtain {@link RequestDispatcher} objects from the context.66 * The given path must be begin with "/", is interpreted relative 67 * to the server's document root and is matched against the context roots of68 * other web applications hosted on this container.69 * 70 * <p>In a security conscious environment, the servlet container may71 * return <code>null</code> for a given URL.72 * 73 * @param uripath a <code>String</code> specifying the context path of74 * another web application in the container.75 * @return the <code>ServletContext</code> object that76 * corresponds to the named URL, or null if either77 none exists or the container wishes to restrict 78 * this access.79 *80 * @see RequestDispatcher81 *82 */83 84 publicServletContext getContext(String uripath);85 86 87 publicString getContextPath();88 89 90 /**91 * Returns the major version of the Java Servlet API that this92 * servlet container supports. All implementations that comply93 * with Version 2.4 must have this method94 * return the integer 2.95 *96 * @return 297 *98 */99 100 publicint getMajorVersion();101 102 103 104 /**105 * Returns the minor version of the Servlet API that this106 * servlet container supports. All implementations that comply107 * with Version 2.4 must have this method108 * return the integer 4.109 *110 * @return 4111 *112 */113 114 publicint getMinorVersion();115 116 117 118 /**119 * Returns the MIME type of the specified file, or <code>null</code> if 120 * the MIME type is not known. The MIME type is determined121 * by the configuration of the servlet container, and may be specified122 * in a web application deployment descriptor. Common MIME123 * types are <code>"text/html"</code> and <code>"image/gif"</code>.124 *125 *126 * @param file a <code>String</code> specifying the name127 * of a file128 *129 * @return a <code>String</code> specifying the file's MIME type130 *131 */132 133 publicString getMimeType(String file);134 135 /**136 * Returns a directory-like listing of all the paths to resources within the web application whose longest sub-path137 * matches the supplied path argument. Paths indicating subdirectory paths end with a '/'. The returned paths are all 138 * relative to the root of the web application and have a leading '/'. For example, for a web application 139 * containing<br><br>140 141 * /welcome.html<br>142 * /catalog/index.html<br>143 * /catalog/products.html<br>144 * /catalog/offers/books.html<br>145 * /catalog/offers/music.html<br>146 * /customer/login.jsp<br>147 * /WEB-INF/web.xml<br>148 * /WEB-INF/classes/com.acme.OrderServlet.class,<br><br>149 *150 * getResourcePaths("/") returns {"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}<br>151 * getResourcePaths("/catalog/") returns {"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}.<br>152 153 154 155 *@param path the partial path used to match the resources,156 * which must start with a /157 *@return a Set containing the directory listing, or null if there are no resources in the web application whose path158 * begins with the supplied path.159 160 * @since Servlet 2.3161 */162 163 publicSet getResourcePaths(String path);164 165 166 167 /**168 * Returns a URL to the resource that is mapped to a specified169 * path. The path must begin with a "/" and is interpreted170 * as relative to the current context root.171 *172 * <p>This method allows the servlet container to make a resource 173 * available to servlets from any source. Resources 174 * can be located on a local or remote175 * file system, in a database, or in a <code>.war</code> file. 176 *177 * <p>The servlet container must implement the URL handlers178 * and <code>URLConnection</code> objects that are necessary179 * to access the resource.180 *181 * <p>This method returns <code>null</code>182 * if no resource is mapped to the pathname.183 *184 * <p>Some containers may allow writing to the URL returned by185 * this method using the methods of the URL class.186 *187 * <p>The resource content is returned directly, so be aware that 188 * requesting a <code>.jsp</code> page returns the JSP source code.189 * Use a <code>RequestDispatcher</code> instead to include results of 190 * an execution.191 *192 * <p>This method has a different purpose than193 * <code>java.lang.Class.getResource</code>,194 * which looks up resources based on a class loader. This195 * method does not use class loaders.196 * 197 * @param path a <code>String</code> specifying198 * the path to the resource199 *200 * @return the resource located at the named path,201 * or <code>null</code> if there is no resource202 * at that path203 *204 * @exception MalformedURLException if the pathname is not given in 205 * the correct form206 *207 */208 209 publicURL getResource(String path) throwsMalformedURLException;210 211 212 213 /**214 * Returns the resource located at the named path as215 * an <code>InputStream</code> object.216 *217 * <p>The data in the <code>InputStream</code> can be 218 * of any type or length. The path must be specified according219 * to the rules given in <code>getResource</code>.220 * This method returns <code>null</code> if no resource exists at221 * the specified path. 222 * 223 * <p>Meta-information such as content length and content type224 * that is available via <code>getResource</code>225 * method is lost when using this method.226 *227 * <p>The servlet container must implement the URL handlers228 * and <code>URLConnection</code> objects necessary to access229 * the resource.230 *231 * <p>This method is different from 232 * <code>java.lang.Class.getResourceAsStream</code>,233 * which uses a class loader. This method allows servlet containers 234 * to make a resource available235 * to a servlet from any location, without using a class loader.236 * 237 *238 * @param path a <code>String</code> specifying the path239 * to the resource240 *241 * @return the <code>InputStream</code> returned to the 242 * servlet, or <code>null</code> if no resource243 * exists at the specified path 244 *245 *246 */247 248 publicInputStream getResourceAsStream(String path);249 250 251 252 253 /**254 * 255 * Returns a {@link RequestDispatcher} object that acts256 * as a wrapper for the resource located at the given path.257 * A <code>RequestDispatcher</code> object can be used to forward 258 * a request to the resource or to include the resource in a response.259 * The resource can be dynamic or static.260 *261 * <p>The pathname must begin with a "/" and is interpreted as relative262 * to the current context root. Use <code>getContext</code> to obtain263 * a <code>RequestDispatcher</code> for resources in foreign contexts.264 * This method returns <code>null</code> if the <code>ServletContext</code>265 * cannot return a <code>RequestDispatcher</code>.266 *267 * @param path a <code>String</code> specifying the pathname268 * to the resource269 *270 * @return a <code>RequestDispatcher</code> object271 * that acts as a wrapper for the resource272 * at the specified path, or <code>null</code> if 273 * the <code>ServletContext</code> cannot return274 * a <code>RequestDispatcher</code>275 *276 * @see RequestDispatcher277 * @see ServletContext#getContext278 *279 */280 281 publicRequestDispatcher getRequestDispatcher(String path);282 283 284 285 /**286 * Returns a {@link RequestDispatcher} object that acts287 * as a wrapper for the named servlet.288 *289 * <p>Servlets (and JSP pages also) may be given names via server 290 * administration or via a web application deployment descriptor.291 * A servlet instance can determine its name using 292 * {@link ServletConfig#getServletName}.293 *294 * <p>This method returns <code>null</code> if the 295 * <code>ServletContext</code>296 * cannot return a <code>RequestDispatcher</code> for any reason.297 *298 * @param name a <code>String</code> specifying the name299 * of a servlet to wrap300 *301 * @return a <code>RequestDispatcher</code> object302 * that acts as a wrapper for the named servlet,303 * or <code>null</code> if the <code>ServletContext</code>304 * cannot return a <code>RequestDispatcher</code>305 *306 * @see RequestDispatcher307 * @see ServletContext#getContext308 * @see ServletConfig#getServletName309 *310 */311 312 publicRequestDispatcher getNamedDispatcher(String name);313 314 315 316 317 /**318 *319 * @deprecated As of Java Servlet API 2.1, with no direct replacement.320 *321 * <p>This method was originally defined to retrieve a servlet322 * from a <code>ServletContext</code>. In this version, this method 323 * always returns <code>null</code> and remains only to preserve 324 * binary compatibility. This method will be permanently removed 325 * in a future version of the Java Servlet API.326 *327 * <p>In lieu of this method, servlets can share information using the 328 * <code>ServletContext</code> class and can perform shared business logic329 * by invoking methods on common non-servlet classes.330 *331 */332 333 publicServlet getServlet(String name) throwsServletException;334 335 336 337 338 339 340 /**341 *342 * @deprecated As of Java Servlet API 2.0, with no replacement.343 *344 * <p>This method was originally defined to return an <code>Enumeration</code>345 * of all the servlets known to this servlet context. In this346 * version, this method always returns an empty enumeration and347 * remains only to preserve binary compatibility. This method348 * will be permanently removed in a future version of the Java349 * Servlet API.350 *351 */352 353 publicEnumeration getServlets();354 355 356 357 358 359 360 /**361 * @deprecated As of Java Servlet API 2.1, with no replacement.362 *363 * <p>This method was originally defined to return an 364 * <code>Enumeration</code>365 * of all the servlet names known to this context. In this version,366 * this method always returns an empty <code>Enumeration</code> and 367 * remains only to preserve binary compatibility. This method will 368 * be permanently removed in a future version of the Java Servlet API.369 *370 */371 372 publicEnumeration getServletNames();373 374 375 376 377 378 /**379 *380 * Writes the specified message to a servlet log file, usually381 * an event log. The name and type of the servlet log file is 382 * specific to the servlet container.383 *384 *385 * @param msg a <code>String</code> specifying the 386 * message to be written to the log file387 *388 */389 390 publicvoid log(String msg);391 392 393 394 395 396 /**397 * @deprecated As of Java Servlet API 2.1, use398 * {@link #log(String message, Throwable throwable)} 399 * instead.400 *401 * <p>This method was originally defined to write an 402 * exception's stack trace and an explanatory error message403 * to the servlet log file.404 *405 */406 407 publicvoid log(Exception exception, String msg);408 409 410 411 412 413 /**414 * Writes an explanatory message and a stack trace415 * for a given <code>Throwable</code> exception416 * to the servlet log file. The name and type of the servlet log 417 * file is specific to the servlet container, usually an event log.418 *419 *420 * @param message a <code>String</code> that 421 * describes the error or exception422 *423 * @param throwable the <code>Throwable</code> error 424 * or exception425 *426 */427 428 publicvoid log(String message, Throwable throwable);429 430 431 432 433 434 /**435 * Returns a <code>String</code> containing the real path 436 * for a given virtual path. For example, the path "/index.html"437 * returns the absolute file path on the server's filesystem would be438 * served by a request for "http://host/contextPath/index.html",439 * where contextPath is the context path of this ServletContext..440 *441 * <p>The real path returned will be in a form442 * appropriate to the computer and operating system on443 * which the servlet container is running, including the444 * proper path separators. This method returns <code>null</code>445 * if the servlet container cannot translate the virtual path446 * to a real path for any reason (such as when the content is447 * being made available from a <code>.war</code> archive).448 *449 *450 * @param path a <code>String</code> specifying a virtual path451 *452 *453 * @return a <code>String</code> specifying the real path,454 * or null if the translation cannot be performed455 * 456 *457 */458 459 publicString getRealPath(String path);460 461 462 463 464 /**465 * Returns the name and version of the servlet container on which466 * the servlet is running. 467 *468 * <p>The form of the returned string is 469 * <i>servername</i>/<i>versionnumber</i>.470 * For example, the JavaServer Web Development Kit may return the string471 * <code>JavaServer Web Dev Kit/1.0</code>.472 *473 * <p>The servlet container may return other optional information 474 * after the primary string in parentheses, for example,475 * <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>.476 *477 *478 * @return a <code>String</code> containing at least the 479 * servlet container name and version number480 *481 */482 483 publicString getServerInfo();484 485 486 487 488 /**489 * Returns a <code>String</code> containing the value of the named490 * context-wide initialization parameter, or <code>null</code> if the 491 * parameter does not exist.492 *493 * <p>This method can make available configuration information useful494 * to an entire "web application". For example, it can provide a 495 * webmaster's email address or the name of a system that holds 496 * critical data.497 *498 * @param name a <code>String</code> containing the name of the499 * parameter whose value is requested500 * 501 * @return a <code>String</code> containing at least the 502 * servlet container name and version number503 *504 * @see ServletConfig#getInitParameter505 */506 507 publicString getInitParameter(String name);508 509 510 511 512 /**513 * Returns the names of the context's initialization parameters as an514 * <code>Enumeration</code> of <code>String</code> objects, or an515 * empty <code>Enumeration</code> if the context has no initialization516 * parameters.517 *518 * @return an <code>Enumeration</code> of <code>String</code> 519 * objects containing the names of the context's520 * initialization parameters521 *522 * @see ServletConfig#getInitParameter523 */524 525 publicEnumeration getInitParameterNames();526 527 528 529 /**530 * Returns the servlet container attribute with the given name, 531 * or <code>null</code> if there is no attribute by that name.532 * An attribute allows a servlet container to give the533 * servlet additional information not534 * already provided by this interface. See your535 * server documentation for information about its attributes.536 * A list of supported attributes can be retrieved using537 * <code>getAttributeNames</code>.538 *539 * <p>The attribute is returned as a <code>java.lang.Object</code>540 * or some subclass.541 * Attribute names should follow the same convention as package542 * names. The Java Servlet API specification reserves names543 * matching <code>java.*</code>, <code>javax.*</code>,544 * and <code>sun.*</code>.545 *546 *547 * @param name a <code>String</code> specifying the name 548 * of the attribute549 *550 * @return an <code>Object</code> containing the value 551 * of the attribute, or <code>null</code>552 * if no attribute exists matching the given553 * name554 *555 * @see ServletContext#getAttributeNames556 *557 */558 559 publicObject getAttribute(String name);560 561 562 563 564 /**565 * Returns an <code>Enumeration</code> containing the 566 * attribute names available567 * within this servlet context. Use the568 * {@link #getAttribute} method with an attribute name569 * to get the value of an attribute.570 *571 * @return an <code>Enumeration</code> of attribute 572 * names573 *574 * @see #getAttribute575 *576 */577 578 publicEnumeration getAttributeNames();579 580 581 582 583 /**584 *585 * Binds an object to a given attribute name in this servlet context. If586 * the name specified is already used for an attribute, this587 * method will replace the attribute with the new to the new attribute.588 * <p>If listeners are configured on the <code>ServletContext</code> the 589 * container notifies them accordingly.590 * <p>591 * If a null value is passed, the effect is the same as calling 592 * <code>removeAttribute()</code>.593 * 594 * <p>Attribute names should follow the same convention as package595 * names. The Java Servlet API specification reserves names596 * matching <code>java.*</code>, <code>javax.*</code>, and597 * <code>sun.*</code>.598 *599 *600 * @param name a <code>String</code> specifying the name 601 * of the attribute602 *603 * @param object an <code>Object</code> representing the604 * attribute to be bound605 *606 *607 *608 */609 610 publicvoid setAttribute(String name, Object object);611 612 613 614 615 616 /**617 * Removes the attribute with the given name from 618 * the servlet context. After removal, subsequent calls to619 * {@link #getAttribute} to retrieve the attribute's value620 * will return <code>null</code>.621 622 * <p>If listeners are configured on the <code>ServletContext</code> the 623 * container notifies them accordingly.624 625 *626 *627 * @param name a <code>String</code> specifying the name 628 * of the attribute to be removed629 *630 */631 632 publicvoid removeAttribute(String name);633 634 /**635 * Returns the name of this web application corresponding to this ServletContext as specified in the deployment636 * descriptor for this web application by the display-name element.637 *638 *639 * @return The name of the web application or null if no name has been declared in the deployment descriptor.640 * @since Servlet 2.3641 */642 643 publicString getServletContextName();644 }645 646 647