ServletContext


1   /*
2   * Licensed to the Apache Software Foundation (ASF) under one or more
3   * contributor license agreements.  See the NOTICE file distributed with
4   * this work for additional information regarding copyright ownership.
5   * The ASF licenses this file to You under the Apache License, Version 2.0
6   * (the "License"); you may not use this file except in compliance with
7   * the License.  You may obtain a copy of the License at
8   *
9   *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * 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 and
15  * limitations under the License.
16  */
17  package javax.servlet;
18  
19  import java.io.InputStream  ;
20  import java.net.MalformedURLException  ;
21  import java.net.URL  ;
22  import java.util.Enumeration  ;
23  import java.util.Set  ;
24  
25  
26  /**
27   * 
28   * Defines a set of methods that a servlet uses to communicate with its
29   * servlet container, for example, to get the MIME type of a file, dispatch
30   * requests, or write to a log file.
31   *
32   * <p>There is one context per "web application" per Java Virtual Machine.  (A
33   * "web application" is a collection of servlets and content installed under a
34   * 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 web
38   * application marked "distributed" in its deployment descriptor, there will
39   * be one context instance for each virtual machine.  In this situation, the 
40   * context cannot be used as a location to share global information (because
41   * 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 the
46   * servlet when the servlet is initialized.
47   *
48   * @author  Various
49   * @version     $Version$
50   *
51   * @see     Servlet#getServletConfig
52   * @see     ServletConfig#getServletContext
53   *
54   */
55  
56  public interface 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 gain
64       * access to the context for various parts of the server, and as
65       * 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 of
68       * other web applications hosted on this container.
69       * 
70       * <p>In a security conscious environment, the servlet container may
71       * return <code>null</code> for a given URL.
72       *       
73       * @param uripath   a <code>String</code> specifying the context path of
74       *          another web application in the container.
75       * @return      the <code>ServletContext</code> object that
76       *          corresponds to the named URL, or null if either
77              none exists or the container wishes to restrict 
78       *          this access.
79       *
80       * @see         RequestDispatcher
81       *
82       */
83  
84      public ServletContext   getContext(String   uripath);
85      
86  
87      public String   getContextPath();
88  
89  
90      /**
91       * Returns the major version of the Java Servlet API that this
92       * servlet container supports. All implementations that comply
93       * with Version 2.4 must have this method
94       * return the integer 2.
95       *
96       * @return      2
97       *
98       */
99      
100     public int getMajorVersion();
101     
102     
103 
104     /**
105      * Returns the minor version of the Servlet API that this
106      * servlet container supports. All implementations that comply
107      * with Version 2.4 must have this method
108      * return the integer 4.
109      *
110      * @return      4
111      *
112      */
113 
114     public int 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 determined
121      * by the configuration of the servlet container, and may be specified
122      * in a web application deployment descriptor. Common MIME
123      * types are <code>"text/html"</code> and <code>"image/gif"</code>.
124      *
125      *
126      * @param   file    a <code>String</code> specifying the name
127      *          of a file
128      *
129      * @return      a <code>String</code> specifying the file's MIME type
130      *
131      */
132 
133     public String   getMimeType(String   file);
134     
135     /**
136     * Returns a directory-like listing of all the paths to resources within the web application whose longest sub-path
137     * 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 path
158     * begins with the supplied path.
159 
160     * @since Servlet 2.3
161     */
162     
163     public Set   getResourcePaths(String   path);
164     
165     
166 
167     /**
168      * Returns a URL to the resource that is mapped to a specified
169      * path. The path must begin with a "/" and is interpreted
170      * 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 remote
175      * file system, in a database, or in a <code>.war</code> file. 
176      *
177      * <p>The servlet container must implement the URL handlers
178      * and <code>URLConnection</code> objects that are necessary
179      * 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 by
185      * 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 than
193      * <code>java.lang.Class.getResource</code>,
194      * which looks up resources based on a class loader. This
195      * method does not use class loaders.
196      * 
197      * @param path              a <code>String</code> specifying
198      *                      the path to the resource
199      *
200      * @return                  the resource located at the named path,
201      *                      or <code>null</code> if there is no resource
202      *                      at that path
203      *
204      * @exception MalformedURLException     if the pathname is not given in 
205      *                      the correct form
206      *
207      */
208     
209     public URL   getResource(String   path) throws MalformedURLException  ;
210     
211     
212 
213     /**
214      * Returns the resource located at the named path as
215      * 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 according
219      * to the rules given in <code>getResource</code>.
220      * This method returns <code>null</code> if no resource exists at
221      * the specified path. 
222      * 
223      * <p>Meta-information such as content length and content type
224      * 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 handlers
228      * and <code>URLConnection</code> objects necessary to access
229      * 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 available
235      * to a servlet from any location, without using a class loader.
236      * 
237      *
238      * @param path  a <code>String</code> specifying the path
239      *          to the resource
240      *
241      * @return      the <code>InputStream</code> returned to the 
242      *          servlet, or <code>null</code> if no resource
243      *          exists at the specified path 
244      *
245      *
246      */
247 
248     public InputStream   getResourceAsStream(String   path);
249     
250 
251 
252 
253     /**
254      * 
255      * Returns a {@link RequestDispatcher} object that acts
256      * 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 relative
262      * to the current context root.  Use <code>getContext</code> to obtain
263      * 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 pathname
268      *          to the resource
269      *
270      * @return      a <code>RequestDispatcher</code> object
271      *          that acts as a wrapper for the resource
272      *          at the specified path, or <code>null</code> if 
273      *          the <code>ServletContext</code> cannot return
274      *          a <code>RequestDispatcher</code>
275      *
276      * @see         RequestDispatcher
277      * @see         ServletContext#getContext
278      *
279      */
280 
281     public RequestDispatcher   getRequestDispatcher(String   path);
282 
283 
284 
285     /**
286      * Returns a {@link RequestDispatcher} object that acts
287      * 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 name
299      *          of a servlet to wrap
300      *
301      * @return      a <code>RequestDispatcher</code> object
302      *          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         RequestDispatcher
307      * @see         ServletContext#getContext
308      * @see         ServletConfig#getServletName
309      *
310      */
311 
312     public RequestDispatcher   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 servlet
322      * 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 logic
329      * by invoking methods on common non-servlet classes.
330      *
331      */
332 
333     public Servlet   getServlet(String   name) throws ServletException  ;
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 this
346      * version, this method always returns an empty enumeration and
347      * remains only to preserve binary compatibility. This method
348      * will be permanently removed in a future version of the Java
349      * Servlet API.
350      *
351      */
352     
353     public Enumeration   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     public Enumeration   getServletNames();
373     
374   
375   
376     
377     
378     /**
379      *
380      * Writes the specified message to a servlet log file, usually
381      * 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 file
387      *
388      */
389      
390     public void log(String   msg);
391     
392     
393     
394     
395 
396     /**
397      * @deprecated  As of Java Servlet API 2.1, use
398      *          {@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 message
403      * to the servlet log file.
404      *
405      */
406 
407     public void log(Exception   exception, String   msg);
408     
409     
410     
411     
412 
413     /**
414      * Writes an explanatory message and a stack trace
415      * for a given <code>Throwable</code> exception
416      * 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 exception
422      *
423      * @param throwable     the <code>Throwable</code> error 
424      *              or exception
425      *
426      */
427     
428     public void 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 be
438      * 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 form
442      * appropriate to the computer and operating system on
443      * which the servlet container is running, including the
444      * proper path separators. This method returns <code>null</code>
445      * if the servlet container cannot translate the virtual path
446      * to a real path for any reason (such as when the content is
447      * being made available from a <code>.war</code> archive).
448      *
449      *
450      * @param path  a <code>String</code> specifying a virtual path
451      *
452      *
453      * @return      a <code>String</code> specifying the real path,
454      *                  or null if the translation cannot be performed
455      *          
456      *
457      */
458 
459     public String   getRealPath(String   path);
460     
461     
462 
463 
464     /**
465      * Returns the name and version of the servlet container on which
466      * 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 string
471      * <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 number
480      *
481      */
482 
483     public String   getServerInfo();
484     
485     
486 
487 
488     /**
489      * Returns a <code>String</code> containing the value of the named
490      * 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 useful
494      * 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 the
499      *                  parameter whose value is requested
500      * 
501      * @return      a <code>String</code> containing at least the 
502      *          servlet container name and version number
503      *
504      * @see ServletConfig#getInitParameter
505      */
506 
507     public String   getInitParameter(String   name);
508     
509     
510 
511 
512     /**
513      * Returns the names of the context's initialization parameters as an
514      * <code>Enumeration</code> of <code>String</code> objects, or an
515      * empty <code>Enumeration</code> if the context has no initialization
516      * parameters.
517      *
518      * @return      an <code>Enumeration</code> of <code>String</code> 
519      *                  objects containing the names of the context's
520      *                  initialization parameters
521      *
522      * @see ServletConfig#getInitParameter
523      */
524 
525     public Enumeration   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 the
533      * servlet additional information not
534      * already provided by this interface. See your
535      * server documentation for information about its attributes.
536      * A list of supported attributes can be retrieved using
537      * <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 package
542      * names. The Java Servlet API specification reserves names
543      * 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 attribute
549      *
550      * @return      an <code>Object</code> containing the value 
551      *          of the attribute, or <code>null</code>
552      *          if no attribute exists matching the given
553      *          name
554      *
555      * @see         ServletContext#getAttributeNames
556      *
557      */
558   
559     public Object   getAttribute(String   name);
560     
561     
562     
563 
564     /**
565      * Returns an <code>Enumeration</code> containing the 
566      * attribute names available
567      * within this servlet context. Use the
568      * {@link #getAttribute} method with an attribute name
569      * to get the value of an attribute.
570      *
571      * @return      an <code>Enumeration</code> of attribute 
572      *          names
573      *
574      * @see     #getAttribute
575      *
576      */
577 
578     public Enumeration   getAttributeNames();
579     
580     
581     
582     
583     /**
584      *
585      * Binds an object to a given attribute name in this servlet context. If
586      * the name specified is already used for an attribute, this
587      * 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 package
595      * names. The Java Servlet API specification reserves names
596      * matching <code>java.*</code>, <code>javax.*</code>, and
597      * <code>sun.*</code>.
598      *
599      *
600      * @param name  a <code>String</code> specifying the name 
601      *          of the attribute
602      *
603      * @param object    an <code>Object</code> representing the
604      *          attribute to be bound
605      *
606      *
607      *
608      */
609     
610     public void 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 to
619      * {@link #getAttribute} to retrieve the attribute's value
620      * 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 removed
629      *
630      */
631 
632     public void removeAttribute(String   name);
633     
634     /**
635      * Returns the name of this web application corresponding to this ServletContext as specified in the deployment
636      * 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.3
641      */
642     
643     public String   getServletContextName();
644 }
645 
646 
647
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags