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.util.Locale;
020:
021: /**
022: * Defines an interface to provide client response information .
023: *
024: * @author <a href="mailto:dims@yahoo.com">Davanum Srinivas</a>
025: * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
026: * @version CVS $Id: Response.java 433543 2006-08-22 06:22:54Z crossley $
027: *
028: */
029:
030: public interface Response {
031:
032: /**
033: * Returns the name of the charset used for
034: * the MIME body sent in this response.
035: *
036: * <p>If no charset has been assigned, it is implicitly
037: * set to <code>ISO-8859-1</code> (<code>Latin-1</code>).
038: *
039: * <p>See RFC 2047 (http://ds.internic.net/rfc/rfc2045.txt)
040: * for more information about character encoding and MIME.
041: *
042: * @return a <code>String</code> specifying the
043: * name of the charset, for
044: * example, <code>ISO-8859-1</code>
045: *
046: */
047:
048: String getCharacterEncoding();
049:
050: /**
051: * Sets the locale of the response, setting the headers (including the
052: * Content-Type's charset) as appropriate. By default, the response locale
053: * is the default locale for the server.
054: *
055: * @param loc the locale of the response
056: *
057: * @see #getLocale()
058: *
059: */
060:
061: void setLocale(Locale loc);
062:
063: /**
064: * Returns the locale assigned to the response.
065: *
066: *
067: * @see #setLocale(Locale)
068: *
069: */
070:
071: Locale getLocale();
072:
073: /**
074: * Constructs a cookie with a specified name and value.
075: *
076: * <p>The name must conform to RFC 2109. That means it can contain
077: * only ASCII alphanumeric characters and cannot contain commas,
078: * semicolons, or white space or begin with a $ character. The cookie's
079: * name cannot be changed after creation.
080: *
081: * <p>The value can be anything the server chooses to send. Its
082: * value is probably of interest only to the server. The cookie's
083: * value can be changed after creation with the
084: * <code>setValue</code> method.
085: *
086: * <p>By default, cookies are created according to the Netscape
087: * cookie specification. The version can be changed with the
088: * <code>setVersion</code> method.
089: *
090: *
091: * @param name a <code>String</code> specifying the name of the cookie
092: *
093: * @param value a <code>String</code> specifying the value of the cookie
094: *
095: * @throws IllegalArgumentException if the cookie name contains illegal characters
096: * (for example, a comma, space, or semicolon)
097: * or it is one of the tokens reserved for use
098: * by the cookie protocol
099: *
100: */
101: Cookie createCookie(String name, String value);
102:
103: /**
104: * Adds the specified cookie to the response. This method can be called
105: * multiple times to set more than one cookie.
106: *
107: * @param cookie the Cookie to return to the client
108: *
109: */
110:
111: void addCookie(Cookie cookie);
112:
113: /**
114: * Returns a boolean indicating whether the named response header
115: * has already been set.
116: *
117: * @param name the header name
118: * @return <code>true</code> if the named response header
119: * has already been set;
120: * <code>false</code> otherwise
121: */
122:
123: boolean containsHeader(String name);
124:
125: /**
126: * Encodes the specified URL by including the session ID in it,
127: * or, if encoding is not needed, returns the URL unchanged.
128: * The implementation of this method includes the logic to
129: * determine whether the session ID needs to be encoded in the URL.
130: * For example, if the browser supports cookies, or session
131: * tracking is turned off, URL encoding is unnecessary.
132: *
133: * <p>For robust session tracking, all URLs emitted by a servlet
134: * should be run through this
135: * method. Otherwise, URL rewriting cannot be used with browsers
136: * which do not support cookies.
137: *
138: * @param url the url to be encoded.
139: * @return the encoded URL if encoding is needed;
140: * the unchanged URL otherwise.
141: */
142:
143: String encodeURL(String url);
144:
145: /**
146: *
147: * Sets a response header with the given name and
148: * date-value. The date is specified in terms of
149: * milliseconds since the epoch. If the header had already
150: * been set, the new value overwrites the previous one. The
151: * <code>containsHeader</code> method can be used to test for the
152: * presence of a header before setting its value.
153: *
154: * @param name the name of the header to set
155: * @param date the assigned date value
156: *
157: * @see #containsHeader(String)
158: * @see #addDateHeader(String, long)
159: */
160:
161: void setDateHeader(String name, long date);
162:
163: /**
164: *
165: * Adds a response header with the given name and
166: * date-value. The date is specified in terms of
167: * milliseconds since the epoch. This method allows response headers
168: * to have multiple values.
169: *
170: * @param name the name of the header to set
171: * @param date the additional date value
172: *
173: * @see #setDateHeader(String, long)
174: */
175:
176: void addDateHeader(String name, long date);
177:
178: /**
179: *
180: * Sets a response header with the given name and value.
181: * If the header had already been set, the new value overwrites the
182: * previous one. The <code>containsHeader</code> method can be
183: * used to test for the presence of a header before setting its
184: * value.
185: *
186: * @param name the name of the header
187: * @param value the header value
188: *
189: * @see #containsHeader(String)
190: * @see #addHeader(String, String)
191: */
192:
193: void setHeader(String name, String value);
194:
195: /**
196: * Adds a response header with the given name and value.
197: * This method allows response headers to have multiple values.
198: *
199: * @param name the name of the header
200: * @param value the additional header value
201: *
202: * @see #setHeader(String, String)
203: */
204:
205: void addHeader(String name, String value);
206:
207: /**
208: * Sets a response header with the given name and
209: * int value. If the header had already
210: * been set, the new value overwrites the previous one. The
211: * <code>containsHeader</code> method can be used to test for the
212: * presence of a header before setting its value.
213: *
214: * @param name the name of the header to set
215: * @param value the assigned int value
216: *
217: * @see #containsHeader(String)
218: * @see #addIntHeader(String, int)
219: */
220:
221: void setIntHeader(String name, int value);
222:
223: /**
224: * Adds a response header with the given name and
225: * int value. This method allows response headers
226: * to have multiple values.
227: *
228: * @param name the name of the header to set
229: * @param value the additional int value
230: *
231: * @see #setIntHeader(String, int)
232: */
233:
234: void addIntHeader(String name, int value);
235: }
|