Java > Open Source Codes > com > go > teaservlet > HttpContext


1 /* ====================================================================
2  * TeaServlet - Copyright (c) 1999-2000 Walt Disney Internet Group
3  * ====================================================================
4  * The Tea Software License, Version 1.1
5  *
6  * Copyright (c) 2000 Walt Disney Internet Group. All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Walt Disney Internet Group (http://opensource.go.com/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Tea", "TeaServlet", "Kettle", "Trove" and "BeanDoc" must
28  * not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact opensource@dig.com.
31  *
32  * 5. Products derived from this software may not be called "Tea",
33  * "TeaServlet", "Kettle" or "Trove", nor may "Tea", "TeaServlet",
34  * "Kettle", "Trove" or "BeanDoc" appear in their name, without prior
35  * written permission of the Walt Disney Internet Group.
36  *
37  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40  * DISCLAIMED. IN NO EVENT SHALL THE WALT DISNEY INTERNET GROUP OR ITS
41  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
42  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
43  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
44  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
45  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
46  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
47  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
48  * ====================================================================
49  *
50  * For more information about Tea, please see http://opensource.go.com/.
51  */
52
53 package com.go.teaservlet;
54
55 import java.io.IOException ;
56 import java.io.UnsupportedEncodingException ;
57 import java.util.Date ;
58 import java.util.List ;
59 import java.util.ArrayList ;
60 import java.util.Iterator ;
61
62 import javax.servlet.ServletException ;
63 import javax.servlet.http.Cookie ;
64
65 /******************************************************************************
66  * The context that is used by the template to return its data. This class
67  * provides some additional HTTP-specific template functions.
68  *
69  * @author Reece Wilton, Brian S O'Neill
70  * @version
71  * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
72  */
73 public interface HttpContext extends com.go.tea.runtime.UtilityContext {
74
75     /**
76      * Gets an object that contains all the request information from the
77      * client.
78      */
79     public Request getRequest();
80
81     /**
82      * Gets an object that contains all the request information from the
83      * client and all the parameters are converted using the specified
84      * character encoding.
85      *
86      * @param encoding the character encoding
87      */
88     public Request getRequest(String encoding);
89
90     /**
91      * Sets the response's HTTP status code, like 200 for OK or 404 for not
92      * found.
93      *
94      * @param code the status code int
95      */
96     public void setStatus(int code);
97
98     /**
99      * Causes an error page to be generated using the given status code.
100      * Further template processing is aborted and any output already
101      * provided by the template is not sent.
102      *
103      * @param code the error code int
104      */
105     public void sendError(int code)
106     throws AbortTemplateException, IOException ;
107
108     /**
109      * Causes an error page to be generated using the given status code and
110      * message. Further template processing is aborted and any output already
111      * provided by the template is not sent.
112      *
113      * @param code the error code int
114      * @param message the error message
115      */
116     public void sendError(int code, String message)
117     throws AbortTemplateException, IOException ;
118
119     /**
120      * Creates a response that forces the client to redirect to the given URL.
121      * Further template processing is aborted and any output already provided
122      * by the template is not sent.
123      *
124      * @param url the url to redirect to
125      */
126     public void sendRedirect(String url)
127     throws AbortTemplateException, IOException ;
128
129     /**
130      * Sets the MIME type of the page, like "text/html" or "text/plain". If
131      * another character encoding is desired, for internationalization, append
132      * charset property like this: "text/html; charset=iso-8859-1".
133      *
134      * @param type the MIME type of the page
135      */
136     public void setContentType(String type)
137     throws UnsupportedEncodingException , IOException ;
138
139     /**
140      * An advanced function that sets the string value of an
141      * arbitrary HTTP response header.
142      *
143      * @param name the name of the header
144      * @param value the string value of the header
145      *
146      * @expert
147      */
148     public void setHeader(String name, String value);
149
150     /**
151      * An advanced function that sets the integer value of an
152      * arbitrary HTTP response header.
153      *
154      * @param name the name of the header
155      * @param value the int value of the header
156      *
157      * @expert
158      */
159     public void setHeader(String name, int value);
160
161     /**
162      * An advanced function that sets the date value of an
163      * arbitrary HTTP response header.
164      *
165      * @param name the name of the header
166      * @param value the date value of the header
167      *
168      * @expert
169      */
170     public void setHeader(String name, Date value);
171
172     /**
173      * Encodes the given string so that it can be safely used in a URL. For
174      * example, '?' is encoded to '%3f'.
175      *
176      * @param str the string to encode
177      */
178     public String encodeParameter(String str);
179
180     /**
181      * Tests if a file at the given path exists. If the servlet that is running
182      * the template has a root directory, it is used to determine the physical
183      * file path. If the servlet does not have a root directory set, it is
184      * assumed to be the root of the file system. If the path given to this
185      * function does not lead with a slash, the path is relative to the
186      * pathInfo variable from the request.
187      *
188      * @param path the name of the file to test
189      */
190     public boolean fileExists(String path) throws IOException ;
191
192     /**
193      * Inserts the contents of the given file into the page output or not at
194      * all if the file does not exist or cannot be read. This function inserts
195      * the raw bytes from the file - no character conversion is applied.
196      * Consider using {@link readFile} in order to use character conversion.
197      * <p>
198      * If the servlet that is running the template has a root directory, it is
199      * used to determine the physical file path. If the servlet does not have
200      * a root directory set, it is assumed to be the root of the file system.
201      * If the path given to this function does not lead with a slash, the path
202      * is relative to the pathInfo variable from the request.
203      *
204      * @param path the name of the file to insert
205      */
206     public void insertFile(String path) throws IOException ;
207
208     /**
209      * Reads and returns the contents of the given file. If the file does not
210      * exist or cannot be read, an empty string is returned. This function
211      * differs from {@link insertFile} in that the character conversion is
212      * applied and the file's contents are returned.
213      * <p>
214      * If the servlet that is running the template has a root directory, it is
215      * used to determine the physical file path. If the servlet does not have
216      * a root directory set, it is assumed to be the root of the file system.
217      * If the path given to this function does not lead with a slash, the path
218      * is relative to the pathInfo variable from the request.
219      *
220      * @param path the name of the file to insert
221      */
222     public String readFile(String path) throws IOException ;
223
224     /**
225      * Reads and returns the contents of the given file. If the file does not
226      * exist or cannot be read, an empty string is returned. This function
227      * differs from {@link insertFile} in that the character conversion is
228      * applied and the file's contents are returned.
229      * <p>
230      * If the servlet that is running the template has a root directory, it is
231      * used to determine the physical file path. If the servlet does not have
232      * a root directory set, it is assumed to be the root of the file system.
233      * If the path given to this function does not lead with a slash, the path
234      * is relative to the pathInfo variable from the request.
235      *
236      * @param path the name of the file to insert
237      * @param encoding character encoding
238      */
239     public String readFile(String path, String encoding) throws IOException ;
240
241     /**
242      * Tests if a resource at the given URL exists. If the URL has no protocol
243      * specified, then a relative lookup is performed. If the relative URL
244      * begins with a slash, the lookup is performed with an absolute path on
245      * the this server. If the relative URL does not begin with a slash, then
246      * the lookup is performed with a relative path.
247      *
248      * @param url the resource URL
249      */
250     public boolean URLExists(String URL) throws IOException ;
251
252     /**
253      * Inserts the contents of the resource at the given URL into the page
254      * output. If the resource does not exist or cannot be read, nothing is
255      * inserted. The given URL can be absolute or relative. This function
256      * inserts the raw bytes from the URL - no character conversion is applied.
257      * Consider using {@link readURL} in order to use character conversion.
258      *
259      * @param url the resource URL
260      */
261     public void insertURL(String URL) throws IOException ;
262
263     /**
264      * Reads and returns the contents of the given URL. If the URL does not
265      * exist or cannot be read, an empty string is returned. This function
266      * differs from {@link insertURL} in that the character conversion is
267      * applied and the resource's contents are returned.
268      *
269      * @param path the name of the file to insert
270      */
271     public String readURL(String URL) throws IOException ;
272
273     /**
274      * Reads and returns the contents of the given URL. If the URL does not
275      * exist or cannot be read, an empty string is returned. This function
276      * differs from {@link insertURL} in that the character conversion is
277      * applied and the resource's contents are returned.
278      *
279      * @param path the name of the file to insert
280      * @param encoding character encoding
281      */
282     public String readURL(String URL, String encoding) throws IOException ;
283
284     /**
285      * Requests to check, insert, or read URLs will timeout if the remote
286      * hosts doesn't respond in time. Call this function to explicitly set
287      * the timeout value.
288      *
289      * @param timeout max time to wait for URL operation to complete, in
290      * milliseconds
291      */
292     public void setURLTimeout(long timeout);
293
294     /**************************************************************************
295      * The Request interface provides access to the data that is passed to an
296      * HTTP servlet.
297      *
298      * @author Reece Wilton
299      * @version
300      * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
301      */
302     public interface Request {
303
304         /**
305          * Returns the name and version of the protocol the request uses in
306          * the form protocol/majorVersion.minorVersion, for example,
307          * HTTP/1.1.
308          */
309         public String getProtocol();
310
311         /**
312          * Returns the name of the scheme used to make this request, for
313          * example, http, https, or ftp.
314          */
315         public String getScheme();
316
317         /**
318          * Returns the host name of the server that received the request.
319          */
320         public String getServerName();
321
322         /**
323          * Returns the port number on which this request was received.
324          */
325         public int getServerPort();
326
327         /**
328          * Returns the Internet Protocol (IP) address of the client that
329          * sent the request.
330          */
331         public String getRemoteAddr();
332
333         /**
334          * Returns the fully qualified name of the client that sent the
335          * request.
336          */
337         public String getRemoteHost();
338
339         /**
340          * Returns the name of the authentication scheme the server uses,
341          * for example, "BASIC" or "SSL," or null if the server does not
342          * have an authentication scheme.
343          */
344         public String getAuthType();
345
346         /**
347          * Returns the name of the HTTP method with which this request was
348          * made, for example, GET, POST, or PUT. The returned String is the
349          * same as the value of the CGI variable REQUEST_METHOD.
350          */
351         public String getMethod();
352
353         /**
354          * Returns the part of this request's URL from the protocol
355          * name up to the query string in the first line of the HTTP request.
356          * For example:
357          *
358          * <blockquote>
359          * <table>
360          * <tr align=left><th>First line of HTTP request<th>
361          * <th>Returned Value
362          * <tr><td>POST /some/path.html HTTP/1.1<td><td>/some/path.html
363          * <tr><td>GET http://foo.bar/a.html HTTP/1.0
364          * <td><td>http://foo.bar/a.html
365          * <tr><td>HEAD /xyz?a=b HTTP/1.1<td><td>/xyz
366          * </table>
367          * </blockquote>
368          */
369         public String getRequestURI();
370
371         /**
372          * Returns the portion of the request URI that indicates the context
373          * of the request. The context path always comes first in a request
374          * URI. The path starts with a "/" character but does not end with a
375          * "/" character.
376          */
377         public String getContextPath();
378
379         /**
380          * Returns the part of this request's URL that calls the servlet.
381          * This includes either the servlet name or a path to the servlet,
382          * but does not include any extra path information or a query string.
383          */
384         public String getServletPath();
385
386         /**
387          * Returns any extra path information associated with the URL the
388          * client sent when it made this request. The extra path information
389          * follows the servlet path but precedes the query string.
390          * Returns null if there was no extra path information.
391          */
392         public String getPathInfo();
393
394         /**
395          * Returns the query string that is contained in the request URL
396          * after the path. Returns null if the URL does not
397          * have a query string.
398          */
399         public String getQueryString();
400         
401
402         /**
403          * Returns the login of the user making this request, if the user has
404          * been authenticated, or null if the user has not been authenticated.
405          * Whether the user name is sent with each subsequent request depends
406          * on the browser and type of authentication.
407          */
408         public String getRemoteUser();
409
410         /**
411          * Returns the session ID specified by the client. This may not be
412          * the same as the ID of the actual session in use. For example, if
413          * the request specified an old (expired) session ID and the server
414          * has started a new session, this method gets a new session with a
415          * new ID. If the request did not specify a session ID, this method
416          * returns null.
417          */
418         public String getRequestedSessionId();
419
420         /**
421          * Checks whether the requested session ID is still valid.
422          */
423         public boolean isRequestedSessionIdValid();
424
425         /**
426          * Returns a Parameters object containing the request parameters.
427          */
428         public Parameters getParameters();
429
430         /**
431          * Returns a Headers object containing the request headers.
432          */
433         public Headers getHeaders();
434
435         /**
436          * Returns a Cookies object containing the request cookies.
437          */
438         public Cookies getCookies();
439
440         /**
441          * Returns an Attributes object containing the request attributes.
442          */
443         public Attributes getAttributes();
444     }
445
446     /**************************************************************************
447      * The Parameters interface provides access to the request parameters.
448      *
449      * @author Reece Wilton
450      * @version
451      * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
452      */
453     public interface Parameters {
454
455         /**
456          * Returns a ParameterValues object containing all of the values for
457          * the named parameter.
458          *
459          * @param name the name of the parameter
460          */
461         public ParameterValues get(String name);
462         
463         /**
464          * Returns a StringArrayList containing the names of the parameters
465          * contained in the request.
466          */
467         public StringArrayList getNames();
468     }
469
470     /**************************************************************************
471      * The ParameterValues interface provides access to the request parameter
472      * values.
473      *
474      * @author Reece Wilton
475      * @version
476      * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
477      */
478     public interface ParameterValues extends List {
479
480         /** The element type for this List is Parameter.class */
481         public static final Class ELEMENT_TYPE = Parameter.class;
482
483         /**
484          * Returns the parameter value as an Integer.
485          */
486         public Integer getAsInteger();
487
488         /**
489          * Returns the parameter value as a String.
490          */
491         public String getAsString();
492
493         public String toString();
494     }
495
496     /**************************************************************************
497      * The Parameter interface provides access to a request parameter
498      * value.
499      *
500      * @author Reece Wilton
501      * @version
502      * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
503      */
504     public interface Parameter {
505
506         /**
507          * Returns the parameter value as an Integer.
508          */
509         public Integer getAsInteger();
510
511         /**
512          * Returns the parameter value as a String.
513          */
514         public String getAsString();
515
516         public String toString();
517     }
518
519     /**************************************************************************
520      * The Headers interface provides access to the request headers.
521      *
522      * @author Reece Wilton
523      * @version
524      * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
525      */
526     public interface Headers {
527
528         /**
529          * Returns a Header object containing the value of
530          * the named Header.
531          *
532          * @param name the name of the header
533          */
534         public Header get(String name);
535         
536         /**
537          * Returns a StringArrayList containing the names of the headers
538          * contained in the request.
539          */
540         public StringArrayList getNames();
541     }
542
543     /**************************************************************************
544      * The Header interface provides access to a request header
545      * value.
546      *
547      * @author Reece Wilton
548      * @version
549      * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
550      */
551     public interface Header {
552
553         /**
554          * Returns the parameter value as an Integer.
555          */
556         public Integer getAsInteger();
557
558         /**
559          * Returns the parameter value as a String.
560          */
561         public String getAsString();
562
563         /**
564          * Returns the parameter value as a Date.
565          */
566         public Date getAsDate();
567
568         public String toString();
569     }
570
571     /**************************************************************************
572      * The Cookies interface provides access to the request cookies.
573      *
574      * @author Reece Wilton
575      * @version
576      * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
577      */
578     public interface Cookies {
579
580         /**
581          * Returns a javax.servlet.http.Cookie object containing the value of
582          * the named Cookie.
583          *
584          * @param name the name of the cookie
585          */
586         public Cookie get(String name);
587
588         /**
589          * Returns an array of javax.servlet.http.Cookie representing all
590          * of the request's cookies.
591          */
592         public Cookie [] getAll();
593     }
594
595     /**************************************************************************
596      * The Attributes interface provides access to the request attributes.
597      *
598      * @author Reece Wilton
599      * @version
600      * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
601      */
602     public interface Attributes {
603
604         /**
605          * Returns the value of the named attribute.
606          *
607          * @param name the name of the attribute
608          */
609         public Object get(String name);
610
611         /**
612          * Returns a StringArrayList containing the names of the attributes
613          * contained in the request.
614          */
615         public StringArrayList getNames();
616     }
617
618     /**************************************************************************
619      * An ArrayList of Strings.
620      *
621      * @author Reece Wilton
622      * @version
623      * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 00/12/12 <!-- $-->
624      */
625     public static class StringArrayList extends ArrayList {
626
627         /** The element type is String */
628         public static final Class ELEMENT_TYPE = String .class;
629         
630         StringArrayList() {
631         }
632     }
633 }
634

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags