001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.environment;
018:
019: import java.security.Principal;
020: import java.util.Enumeration;
021: import java.util.Locale;
022: import java.util.Map;
023:
024: /**
025: * Defines an interface to provide client request information .
026: *
027: * @author <a href="mailto:dims@yahoo.com">Davanum Srinivas</a>
028: * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
029: * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
030: * @version $Id: Request.java 433543 2006-08-22 06:22:54Z crossley $
031: */
032: public interface Request {
033:
034: /**
035: *
036: * Returns the value of the named attribute as an <code>Object</code>,
037: * or <code>null</code> if no attribute of the given name exists.
038: *
039: * @param name a <code>String</code> specifying the name of
040: * the attribute
041: *
042: * @return an <code>Object</code> containing the value
043: * of the attribute, or <code>null</code> if
044: * the attribute does not exist
045: *
046: */
047:
048: Object get(String name);
049:
050: /**
051: *
052: * Returns the value of the named attribute as an <code>Object</code>,
053: * or <code>null</code> if no attribute of the given name exists.
054: *
055: * @param name a <code>String</code> specifying the name of
056: * the attribute
057: *
058: * @return an <code>Object</code> containing the value
059: * of the attribute, or <code>null</code> if
060: * the attribute does not exist
061: *
062: */
063:
064: Object getAttribute(String name);
065:
066: /**
067: * Returns an <code>Enumeration</code> containing the
068: * names of the attributes available to this request.
069: * This method returns an empty <code>Enumeration</code>
070: * if the request has no attributes available to it.
071: *
072: *
073: * @return an <code>Enumeration</code> of strings
074: * containing the names
075: * of the request's attributes
076: *
077: */
078:
079: Enumeration getAttributeNames();
080:
081: /**
082: *
083: * Stores an attribute in this request.
084: * Attributes are reset between requests.
085: *
086: * <p>Attribute names should follow the same conventions as
087: * package names. Names beginning with <code>java.*</code>,
088: * <code>javax.*</code>, and <code>com.sun.*</code>, are
089: * reserved for use by Sun Microsystems.
090: *
091: *
092: * @param name a <code>String</code> specifying
093: * the name of the attribute
094: *
095: * @param o the <code>Object</code> to be stored
096: *
097: */
098:
099: void setAttribute(String name, Object o);
100:
101: /**
102: *
103: * Removes an attribute from this request. This method is not
104: * generally needed as attributes only persist as long as the request
105: * is being handled.
106: *
107: * <p>Attribute names should follow the same conventions as
108: * package names. Names beginning with <code>java.*</code>,
109: * <code>javax.*</code>, and <code>com.sun.*</code>, are
110: * reserved for use by Sun Microsystems.
111: *
112: *
113: * @param name a <code>String</code> specifying
114: * the name of the attribute to remove
115: *
116: */
117:
118: void removeAttribute(String name);
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)
155: throws java.io.UnsupportedEncodingException;
156:
157: /**
158: * Returns the length, in bytes, of the request body
159: *
160: * @return an integer containing the length of the
161: * request body or -1 if the length is not known
162: *
163: */
164:
165: int getContentLength();
166:
167: /**
168: * Returns the MIME type of the body of the request
169: *
170: * @return a <code>String</code> containing the name
171: * of the MIME type of
172: * the request, or -1 if the type is not known
173: *
174: */
175:
176: String getContentType();
177:
178: /**
179: * Returns the value of a request parameter as a <code>String</code>,
180: *
181: * @param name a <code>String</code> specifying the
182: * name of the parameter
183: *
184: * @return a <code>String</code> representing the
185: * single value of the parameter
186: *
187: * @see #getParameterValues(String)
188: *
189: */
190:
191: String getParameter(String name);
192:
193: /**
194: *
195: * Returns an <code>Enumeration</code> of <code>String</code>
196: * objects containing the names of the parameters contained
197: * in this request. If the request has
198: * no parameters, the method returns an
199: * empty <code>Enumeration</code>.
200: *
201: * @return an <code>Enumeration</code> of <code>String</code>
202: * objects, each <code>String</code> containing
203: * the name of a request parameter; or an
204: * empty <code>Enumeration</code> if the
205: * request has no parameters
206: *
207: */
208:
209: Enumeration getParameterNames();
210:
211: /**
212: * Returns an array of <code>String</code> objects containing
213: * all of the values the given request parameter has, or
214: * <code>null</code> if the parameter does not exist.
215: *
216: * <p>If the parameter has a single value, the array has a length
217: * of 1.
218: *
219: * @param name a <code>String</code> containing the name of
220: * the parameter whose value is requested
221: *
222: * @return an array of <code>String</code> objects
223: * containing the parameter's values
224: *
225: * @see #getParameter(String)
226: *
227: */
228:
229: String[] getParameterValues(String name);
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: }
|