Java > Open Source Codes > org > apache > cocoon > environment > Request


1 /*
2  * Copyright 1999-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.cocoon.environment;
17
18 import java.security.Principal ;
19 import java.util.Enumeration ;
20 import java.util.Locale ;
21 import java.util.Map ;
22
23 /**
24  * Defines an interface to provide client request information .
25  *
26  * @author <a HREF="mailto:dims@yahoo.com">Davanum Srinivas</a>
27  * @author <a HREF="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
28  * @author <a HREF="mailto:bloritsch@apache.org">Berin Loritsch</a>
29  * @version $Id: Request.java 202262 2005-06-28 18:02:55Z vgritsenko $
30  */
31 public interface Request {
32
33     /**
34      *
35      * Returns the value of the named attribute as an <code>Object</code>,
36      * or <code>null</code> if no attribute of the given name exists.
37      *
38      * @param name a <code>String</code> specifying the name of
39      * the attribute
40      *
41      * @return an <code>Object</code> containing the value
42      * of the attribute, or <code>null</code> if
43      * the attribute does not exist
44      *
45      */
46
47     Object get(String name);
48
49     /**
50      *
51      * Returns the value of the named attribute as an <code>Object</code>,
52      * or <code>null</code> if no attribute of the given name exists.
53      *
54      * @param name a <code>String</code> specifying the name of
55      * the attribute
56      *
57      * @return an <code>Object</code> containing the value
58      * of the attribute, or <code>null</code> if
59      * the attribute does not exist
60      *
61      */
62
63     Object getAttribute(String name);
64
65     /**
66      * Returns an <code>Enumeration</code> containing the
67      * names of the attributes available to this request.
68      * This method returns an empty <code>Enumeration</code>
69      * if the request has no attributes available to it.
70      *
71      *
72      * @return an <code>Enumeration</code> of strings
73      * containing the names
74      * of the request's attributes
75      *
76      */
77
78     Enumeration getAttributeNames();
79
80     /**
81      *
82      * Stores an attribute in this request.
83      * Attributes are reset between requests.
84      *
85      * <p>Attribute names should follow the same conventions as
86      * package names. Names beginning with <code>java.*</code>,
87      * <code>javax.*</code>, and <code>com.sun.*</code>, are
88      * reserved for use by Sun Microsystems.
89      *
90      *
91      * @param name a <code>String</code> specifying
92      * the name of the attribute
93      *
94      * @param o the <code>Object</code> to be stored
95      *
96      */
97
98     void setAttribute(String name, Object o);
99
100     /**
101      *
102      * Removes an attribute from this request. This method is not
103      * generally needed as attributes only persist as long as the request
104      * is being handled.
105      *
106      * <p>Attribute names should follow the same conventions as
107      * package names. Names beginning with <code>java.*</code>,
108      * <code>javax.*</code>, and <code>com.sun.*</code>, are
109      * reserved for use by Sun Microsystems.
110      *
111      *
112      * @param name a <code>String</code> specifying
113      * the name of the attribute to remove
114      *
115      */
116
117     void removeAttribute(String name);
118
119
120     /**
121      *
122      * Returns the name of the authentication scheme used to protect
123      * the servlet, for example, "BASIC" or "SSL," or null if the servlet was
124      * not protected
125      *
126      * @return The name of the authentication scheme used to
127      * protect the servlet, or null if the servlet was
128      * not protected
129      */
130
131     String getAuthType();
132
133     /**
134      * Returns the name of the character encoding used in the body of this
135      * request. This method returns <code>null</code> if the request
136      * does not specify a character encoding
137      *
138      *
139      * @return a <code>String</code> containing the name of
140      * the chararacter encoding, or <code>null</code>
141      * if the request does not specify a character encoding
142      *
143      */
144
145     String getCharacterEncoding();
146
147     /**
148      * Overrides the charactor encoding of parameters.
149      *
150      * @throws java.io.UnsupportedEncodingException if this is not a valid encoding.
151      *
152      */
153
154     void setCharacterEncoding(String enc) throws java.io.UnsupportedEncodingException ;
155
156     /**
157      * Returns the length, in bytes, of the request body
158      *
159      * @return an integer containing the length of the
160      * request body or -1 if the length is not known
161      *
162      */
163
164     int getContentLength();
165
166     /**
167      * Returns the MIME type of the body of the request
168      *
169      * @return a <code>String</code> containing the name
170      * of the MIME type of
171      * the request, or -1 if the type is not known
172      *
173      */
174
175     String getContentType();
176
177     /**
178      * Returns the value of a request parameter as a <code>String</code>,
179      *
180      * @param name a <code>String</code> specifying the
181      * name of the parameter
182      *
183      * @return a <code>String</code> representing the
184      * single value of the parameter
185      *
186      * @see #getParameterValues(String)
187      *
188      */
189
190     String getParameter(String name);
191
192     /**
193      *
194      * Returns an <code>Enumeration</code> of <code>String</code>
195      * objects containing the names of the parameters contained
196      * in this request. If the request has
197      * no parameters, the method returns an
198      * empty <code>Enumeration</code>.
199      *
200      * @return an <code>Enumeration</code> of <code>String</code>
201      * objects, each <code>String</code> containing
202      * the name of a request parameter; or an
203      * empty <code>Enumeration</code> if the
204      * request has no parameters
205      *
206      */
207
208     Enumeration getParameterNames();
209
210     /**
211      * Returns an array of <code>String</code> objects containing
212      * all of the values the given request parameter has, or
213      * <code>null</code> if the parameter does not exist.
214      *
215      * <p>If the parameter has a single value, the array has a length
216      * of 1.
217      *
218      * @param name a <code>String</code> containing the name of
219      * the parameter whose value is requested
220      *
221      * @return an array of <code>String</code> objects
222      * containing the parameter's values
223      *
224      * @see #getParameter(String)
225      *
226      */
227
228     String [] getParameterValues(String name);
229
230
231     /**
232      * Returns the name and version of the protocol the request uses
233      * in the form <i>protocol/majorVersion.minorVersion</i>, for
234      * example, HTTP/1.1. For HTTP servlets, the value
235      * returned is the same as the value of the CGI variable
236      * <code>SERVER_PROTOCOL</code>.
237      *
238      * @return a <code>String</code> containing the protocol
239      * name and version number
240      *
241      */
242
243     String getProtocol();
244
245     /**
246      * Returns the name of the scheme used to make this request,
247      * for example,
248      * <code>http</code>, <code>https</code>, or <code>ftp</code>.
249      * Different schemes have different rules for constructing URLs,
250      * as noted in RFC 1738.
251      *
252      * @return a <code>String</code> containing the name
253      * of the scheme used to make this request
254      *
255      */
256
257     String getScheme();
258
259     /**
260      * Returns the host name of the server that received the request.
261      * For HTTP servlets, same as the value of the CGI variable
262      * <code>SERVER_NAME</code>.
263      *
264      * @return a <code>String</code> containing the name
265      * of the server to which the request was sent
266      */
267
268     String getServerName();
269
270     /**
271      * Returns the port number on which this request was received.
272      * For HTTP servlets, same as the value of the CGI variable
273      * <code>SERVER_PORT</code>.
274      *
275      * @return an integer specifying the port number
276      *
277      */
278
279     int getServerPort();
280
281     /**
282      * Returns the Internet Protocol (IP) address of the client
283      * that sent the request. For HTTP servlets, same as the value of the
284      * CGI variable <code>REMOTE_ADDR</code>.
285      *
286      * @return a <code>String</code> containing the
287      * IP address of the client that sent the request
288      *
289      */
290
291     String getRemoteAddr();
292
293     /**
294      * Returns the fully qualified name of the client that sent the
295      * request, or the IP address of the client if the name cannot be
296      * determined. For HTTP servlets, same as the value of the CGI variable
297      * <code>REMOTE_HOST</code>.
298      *
299      * @return a <code>String</code> containing the fully qualified name
300      * of the client
301      *
302      */
303
304     String getRemoteHost();
305
306     /**
307      *
308      * Returns the preferred <code>Locale</code> that the client will
309      * accept content in, based on the Accept-Language header.
310      * If the client request doesn't provide an Accept-Language header,
311      * this method returns the default locale for the server.
312      *
313      *
314      * @return the preferred <code>Locale</code> for the client
315      *
316      */
317
318     Locale getLocale();
319
320     /**
321      *
322      * Returns an <code>Enumeration</code> of <code>Locale</code> objects
323      * indicating, in decreasing order starting with the preferred locale, the
324      * locales that are acceptable to the client based on the Accept-Language
325      * header.
326      * If the client request doesn't provide an Accept-Language header,
327      * this method returns an <code>Enumeration</code> containing one
328      * <code>Locale</code>, the default locale for the server.
329      *
330      *
331      * @return an <code>Enumeration</code> of preferred
332      * <code>Locale</code> objects for the client
333      *
334      */
335
336     Enumeration getLocales();
337
338     /**
339      *
340      * Returns a boolean indicating whether this request was made using a
341      * secure channel, such as HTTPS.
342      *
343      *
344      * @return a boolean indicating if the request was made using a
345      * secure channel
346      *
347      */
348
349     boolean isSecure();
350
351     /**
352      *
353      * Returns an array containing all of the <code>Cookie</code>
354      * objects the client sent with this request.
355      * This method returns <code>null</code> if no cookies were sent.
356      *
357      * @return an array of all the <code>Cookies</code>
358      * included with this request, or <code>null</code>
359      * if the request has no cookies
360      *
361      *
362      */
363
364     Cookie[] getCookies();
365
366     /**
367      * Returns a map of the <code>Cookie</code> objects the client sent
368      * with this request, indexed by name. This method returns an empty
369      * map if no cookies were sent.
370      *
371      * @return a Map of <code>Cookie</code> objects
372      */
373     Map getCookieMap();
374
375     /**
376      *
377      * Returns the value of the specified request header
378      * as a <code>long</code> value that represents a
379      * <code>Date</code> object. Use this method with
380      * headers that contain dates, such as
381      * <code>If-Modified-Since</code>.
382      *
383      * <p>The date is returned as
384      * the number of milliseconds since January 1, 1970 GMT.
385      * The header name is case insensitive.
386      *
387      * <p>If the request did not have a header of the
388      * specified name, this method returns -1. If the header
389      * can't be converted to a date, the method throws
390      * an <code>IllegalArgumentException</code>.
391      *
392      * @param name a <code>String</code> specifying the
393      * name of the header
394      *
395      * @return a <code>long</code> value
396      * representing the date specified
397      * in the header expressed as
398      * the number of milliseconds
399      * since January 1, 1970 GMT,
400      * or -1 if the named header
401      * was not included with the
402      * reqest
403      *
404      * @exception IllegalArgumentException If the header value
405      * can't be converted
406      * to a date
407      *
408      */
409
410     long getDateHeader(String name);
411
412     /**
413      *
414      * Returns the value of the specified request header
415      * as a <code>String</code>. If the request did not include a header
416      * of the specified name, this method returns <code>null</code>.
417      * The header name is case insensitive. You can use
418      * this method with any request header.
419      *
420      * @param name a <code>String</code> specifying the
421      * header name
422      *
423      * @return a <code>String</code> containing the
424      * value of the requested
425      * header, or <code>null</code>
426      * if the request does not
427      * have a header of that name
428      *
429      */
430
431     String getHeader(String name);
432
433     /**
434      *
435      * Returns all the values of the specified request header
436      * as an <code>Enumeration</code> of <code>String</code> objects.
437      *
438      * <p>Some headers, such as <code>Accept-Language</code> can be sent
439      * by clients as several headers each with a different value rather than
440      * sending the header as a comma separated list.
441      *
442      * <p>If the request did not include any headers
443      * of the specified name, this method returns an empty
444      * <code>Enumeration</code>.
445      * The header name is case insensitive. You can use
446      * this method with any request header.
447      *
448      * @param name a <code>String</code> specifying the
449      * header name
450      *
451      * @return a <code>Enumeration</code> containing the
452      * values of the requested
453      * header, or <code>null</code>
454      * if the request does not
455      * have any headers of that name
456      *
457      */
458
459     Enumeration getHeaders(String name);
460
461     /**
462      *
463      * Returns an enumeration of all the header names
464      * this request contains. If the request has no
465      * headers, this method returns an empty enumeration.
466      *
467      * <p>Some servlet containers do not allow do not allow
468      * servlets to access headers using this method, in
469      * which case this method returns <code>null</code>
470      *
471      * @return an enumeration of all the
472      * header names sent with this
473      * request; if the request has
474      * no headers, an empty enumeration;
475      * if the servlet container does not
476      * allow servlets to use this method,
477      * <code>null</code>
478      *
479      */
480
481     Enumeration getHeaderNames();
482
483     /**
484      *
485      * Returns the name of the HTTP method with which this
486      * request was made, for example, GET, POST, or PUT.
487      * Same as the value of the CGI variable REQUEST_METHOD.
488      *
489      * @return a <code>String</code>
490      * specifying the name
491      * of the method with which
492      * this request was made
493      *
494      */
495
496     String getMethod();
497
498     /**
499      *
500      * Returns any extra path information associated with
501      * the URL the client sent when it made this request.
502      * The extra path information follows the servlet path
503      * but precedes the query string.
504      * This method returns <code>null</code> if there
505      * was no extra path information.
506      *
507      * <p>Same as the value of the CGI variable PATH_INFO.
508      *
509      *
510      * @return a <code>String</code> specifying
511      * extra path information that comes
512      * after the servlet path but before
513      * the query string in the request URL;
514      * or <code>null</code> if the URL does not have
515      * any extra path information
516      *
517      */
518
519     String getPathInfo();
520
521     /**
522      *
523      * Returns any extra path information after the servlet name
524      * but before the query string, and translates it to a real
525      * path. Same as the value of the CGI variable PATH_TRANSLATED.
526      *
527      * <p>If the URL does not have any extra path information,
528      * this method returns <code>null</code>.
529      *
530      *
531      * @return a <code>String</code> specifying the
532      * real path, or <code>null</code> if
533      * the URL does not have any extra path
534      * information
535      *
536      *
537      */
538
539     String getPathTranslated();
540
541     /**
542      *
543      * Returns the portion of the request URI that indicates the context
544      * of the request. The context path always comes first in a request
545      * URI. The path starts with a "/" character but does not end with a "/"
546      * character. For servlets in the default (root) context, this method
547      * returns "".
548      *
549      *
550      * @return a <code>String</code> specifying the
551      * portion of the request URI that indicates the context
552      * of the request
553      *
554      *
555      */
556
557     String getContextPath();
558
559     /**
560      *
561      * Returns the query string that is contained in the request
562      * URL after the path. This method returns <code>null</code>
563      * if the URL does not have a query string. Same as the value
564      * of the CGI variable QUERY_STRING.
565      *
566      * @return a <code>String</code> containing the query
567      * string or <code>null</code> if the URL
568      * contains no query string
569      *
570      */
571
572     String getQueryString();
573
574     /**
575      *
576      * Returns the login of the user making this request, if the
577      * user has been authenticated, or <code>null</code> if the user
578      * has not been authenticated.
579      * Whether the user name is sent with each subsequent request
580      * depends on the browser and type of authentication. Same as the
581      * value of the CGI variable REMOTE_USER.
582      *
583      * @return a <code>String</code> specifying the login
584      * of the user making this request, or <code>null</code
585      * if the user login is not known
586      *
587      */
588
589     String getRemoteUser();
590
591     /**
592      *
593      * Returns the login of the user making this request, if the
594      * user has been authenticated, or <code>null</code> if the user
595      * has not been authenticated.
596      * Whether the user name is sent with each subsequent request
597      * depends on the browser and type of authentication. Same as the
598      * value of the CGI variable REMOTE_USER.
599      *
600      * @return a <code>String</code> specifying the login
601      * of the user making this request, or <code>null</code
602      * if the user login is not known
603      *
604      */
605
606     Principal getUserPrincipal();
607
608     /**
609      *
610      * Checks whether the currently logged in user is in a specified role.
611      *
612      * @return <code>true</code> if the user is
613      * authenticated and in the role;
614      * otherwise, <code>false</code>
615      *
616      *
617      * @see #getRemoteUser()
618      *
619      */
620
621     boolean isUserInRole(String role);
622
623     /**
624      *
625      * Returns the session ID specified by the client. This may
626      * not be the same as the ID of the actual session in use.
627      * For example, if the request specified an old (expired)
628      * session ID and the server has started a new session, this
629      * method gets a new session with a new ID. If the request
630      * did not specify a session ID, this method returns
631      * <code>null</code>.
632      *
633      *
634      * @return a <code>String</code> specifying the session
635      * ID, or <code>null</code> if the request did
636      * not specify a session ID
637      *
638      * @see #isRequestedSessionIdValid()
639      *
640      */
641
642     String getRequestedSessionId();
643
644     /**
645      *
646      * Returns the part of this request's URL from the protocol
647      * name up to the query string in the first line of the HTTP request.
648      * For example:
649      *
650      * <blockquote>
651      * <table>
652      * <tr align=left><th>First line of HTTP request<th>
653      * <th>Returned Value
654      * <tr><td>POST /some/path.html HTTP/1.1<td><td>/some/path.html
655      * <tr><td>GET http://foo.bar/a.html HTTP/1.0
656      * <td><td>http://foo.bar/a.html
657      * <tr><td>HEAD /xyz?a=b HTTP/1.1<td><td>/xyz
658      * </table>
659      * </blockquote>
660      *
661      * @return a <code>String</code> containing
662      * the part of the URL from the
663      * protocol name up to the query string
664      *
665      *
666      */
667
668     String getRequestURI();
669
670     /**
671      * <p>
672      * Returns the URI of the requested resource as interpreted by the sitemap.
673      * For example, if your webapp is mounted at "/webapp" and the HTTP request
674      * is for "/webapp/foo", this method returns "foo". Consequently, if the
675      * request is for "/webapp", this method returns an empty string.
676      * </p>
677      * <p>
678      * Note that if the request is mapped to a pipeline that contains
679      * aggregated content, and if this method is called in the context of
680      * one of the aggregated parts (e.g. a server page), this method will
681      * return the URI of the aggregated part, not the original requested URI.
682      * </p>
683      *
684      * @return a <code>String</code> containing the URL as mangled by the
685      * sitemap
686      */
687     String getSitemapURI();
688
689     /**
690      * <p>
691      * Returns the URI Prefix of the requested resource where the sitemap is mounted.
692      * For example, if your webapp is mounted at "/webapp" and the HTTP request
693      * is for "/webapp/foo", this method returns "webapp/".
694      * </p>
695      *
696      * @return a <code>String</code> containing the URI prefix as mangled by the
697      * sitemap
698      */
699     String getSitemapURIPrefix();
700
701     /**
702      *
703      * Returns the part of this request's URL that calls
704      * the servlet. This includes either the servlet name or
705      * a path to the servlet, but does not include any extra
706      * path information or a query string. Same as the value
707      * of the CGI variable SCRIPT_NAME.
708      *
709      *
710      * @return a <code>String</code> containing
711      * the name or path of the servlet being
712      * called, as specified in the request URL
713      *
714      *
715      */
716
717     String getServletPath();
718
719     /**
720      *
721      * Returns the current <code>Session</code>
722      * associated with this request or, if if there is no
723      * current session and <code>create</code> is true, returns
724      * a new session.
725      *
726      * <p>If <code>create</code> is <code>false</code>
727      * and the request has no valid <code>Session</code>,
728      * this method returns <code>null</code>.
729      *
730      * <p>To make sure the session is properly maintained,
731      * you must call this method before
732      * the response is committed.
733      *
734      *
735      *
736      *
737      * @param create <code>true</code> to create
738      * a new session for this request if necessary;
739      * <code>false</code> to return <code>null</code>
740      * if there's no current session
741      *
742      *
743      * @return the <code>Session</code> associated
744      * with this request or <code>null</code> if
745      * <code>create</code> is <code>false</code>
746      * and the request has no valid session
747      *
748      * @see #getSession()
749      *
750      *
751      */
752
753     Session getSession(boolean create);
754
755     /**
756      *
757      * Returns the current session associated with this request,
758      * or if the request does not have a session, creates one.
759      *
760      * @return the <code>Session</code> associated
761      * with this request
762      *
763      * @see #getSession(boolean)
764      *
765      */
766
767      Session getSession();
768
769     /**
770      *
771      * Checks whether the requested session ID is still valid.
772      *
773      * @return <code>true</code> if this
774      * request has an id for a valid session
775      * in the current session context;
776      * <code>false</code> otherwise
777      *
778      * @see #getRequestedSessionId()
779      * @see #getSession()
780      *
781      */
782
783     boolean isRequestedSessionIdValid();
784
785     /**
786      *
787      * Checks whether the requested session ID came in as a cookie.
788      *
789      * @return <code>true</code> if the session ID
790      * came in as a
791      * cookie; otherwise, <code>false</code>
792      *
793      *
794      * @see #getSession()
795      *
796      */
797
798     boolean isRequestedSessionIdFromCookie();
799
800     /**
801      *
802      * Checks whether the requested session ID came in as part of the
803      * request URL.
804      *
805      * @return <code>true</code> if the session ID
806      * came in as part of a URL; otherwise,
807      * <code>false</code>
808      *
809      *
810      * @see #getSession()
811      *
812      */
813
814     boolean isRequestedSessionIdFromURL();
815 }
816

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags