Response


1   /*
2    * Copyright 1999-2004 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.util.Locale  ;
19  
20  /**
21   * Defines an interface to provide client response information .
22   *
23   * @author <a HREF="mailto:dims@yahoo.com">Davanum Srinivas</a>
24   * @author <a HREF="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
25   * @version CVS $Id: Response.java 30932 2004-07-29 17:35:38Z vgritsenko $
26   *
27   */
28  
29  public interface Response {
30  
31      /**
32       * Returns the name of the charset used for
33       * the MIME body sent in this response.
34       *
35       * <p>If no charset has been assigned, it is implicitly
36       * set to <code>ISO-8859-1</code> (<code>Latin-1</code>).
37       *
38       * <p>See RFC 2047 (http://ds.internic.net/rfc/rfc2045.txt)
39       * for more information about character encoding and MIME.
40       *
41       * @return                a <code>String</code> specifying the
42       *                        name of the charset, for
43       *                        example, <code>ISO-8859-1</code>
44       *
45       */
46  
47      String   getCharacterEncoding();
48  
49      /**
50       * Sets the locale of the response, setting the headers (including the
51       * Content-Type's charset) as appropriate.  By default, the response locale
52       * is the default locale for the server.
53       *
54       * @param loc  the locale of the response
55       *
56       * @see                 #getLocale()
57       *
58       */
59  
60      void setLocale(Locale   loc);
61  
62      /**
63       * Returns the locale assigned to the response.
64       *
65       *
66       * @see                 #setLocale(Locale)
67       *
68       */
69  
70      Locale   getLocale();
71  
72      /**
73       * Constructs a cookie with a specified name and value.
74       *
75       * <p>The name must conform to RFC 2109. That means it can contain
76       * only ASCII alphanumeric characters and cannot contain commas,
77       * semicolons, or white space or begin with a $ character. The cookie's
78       * name cannot be changed after creation.
79       *
80       * <p>The value can be anything the server chooses to send. Its
81       * value is probably of interest only to the server. The cookie's
82       * value can be changed after creation with the
83       * <code>setValue</code> method.
84       *
85       * <p>By default, cookies are created according to the Netscape
86       * cookie specification. The version can be changed with the
87       * <code>setVersion</code> method.
88       *
89       *
90       * @param name                         a <code>String</code> specifying the name of the cookie
91       *
92       * @param value                        a <code>String</code> specifying the value of the cookie
93       *
94       * @throws IllegalArgumentException        if the cookie name contains illegal characters
95       *                                        (for example, a comma, space, or semicolon)
96       *                                        or it is one of the tokens reserved for use
97       *                                        by the cookie protocol
98       *
99       */
100     Cookie createCookie(String   name, String   value);
101 
102     /**
103      * Adds the specified cookie to the response.  This method can be called
104      * multiple times to set more than one cookie.
105      *
106      * @param cookie the Cookie to return to the client
107      *
108      */
109 
110     void addCookie(Cookie cookie);
111 
112     /**
113      * Returns a boolean indicating whether the named response header
114      * has already been set.
115      *
116      * @param        name        the header name
117      * @return                <code>true</code> if the named response header
118      *                        has already been set;
119      *                         <code>false</code> otherwise
120      */
121 
122     boolean containsHeader(String   name);
123 
124     /**
125      * Encodes the specified URL by including the session ID in it,
126      * or, if encoding is not needed, returns the URL unchanged.
127      * The implementation of this method includes the logic to
128      * determine whether the session ID needs to be encoded in the URL.
129      * For example, if the browser supports cookies, or session
130      * tracking is turned off, URL encoding is unnecessary.
131      *
132      * <p>For robust session tracking, all URLs emitted by a servlet
133      * should be run through this
134      * method.  Otherwise, URL rewriting cannot be used with browsers
135      * which do not support cookies.
136      *
137      * @param        url        the url to be encoded.
138      * @return                the encoded URL if encoding is needed;
139      *                         the unchanged URL otherwise.
140      */
141 
142     String   encodeURL(String   url);
143 
144     /**
145      *
146      * Sets a response header with the given name and
147      * date-value.  The date is specified in terms of
148      * milliseconds since the epoch.  If the header had already
149      * been set, the new value overwrites the previous one.  The
150      * <code>containsHeader</code> method can be used to test for the
151      * presence of a header before setting its value.
152      *
153      * @param        name        the name of the header to set
154      * @param        date        the assigned date value
155      *
156      * @see #containsHeader(String)
157      * @see #addDateHeader(String, long)
158      */
159 
160     void setDateHeader(String   name, long date);
161 
162     /**
163      *
164      * Adds a response header with the given name and
165      * date-value.  The date is specified in terms of
166      * milliseconds since the epoch.  This method allows response headers
167      * to have multiple values.
168      *
169      * @param        name        the name of the header to set
170      * @param        date        the additional date value
171      *
172      * @see #setDateHeader(String, long)
173      */
174 
175     void addDateHeader(String   name, long date);
176 
177     /**
178      *
179      * Sets a response header with the given name and value.
180      * If the header had already been set, the new value overwrites the
181      * previous one.  The <code>containsHeader</code> method can be
182      * used to test for the presence of a header before setting its
183      * value.
184      *
185      * @param        name        the name of the header
186      * @param        value        the header value
187      *
188      * @see #containsHeader(String)
189      * @see #addHeader(String, String)
190      */
191 
192     void setHeader(String   name, String   value);
193 
194     /**
195      * Adds a response header with the given name and value.
196      * This method allows response headers to have multiple values.
197      *
198      * @param        name        the name of the header
199      * @param        value        the additional header value
200      *
201      * @see #setHeader(String, String)
202      */
203 
204     void addHeader(String   name, String   value);
205 
206     /**
207      * Sets a response header with the given name and
208      * int value. If the header had already
209      * been set, the new value overwrites the previous one.  The
210      * <code>containsHeader</code> method can be used to test for the
211      * presence of a header before setting its value.
212      *
213      * @param        name        the name of the header to set
214      * @param        value       the assigned int value
215      *
216      * @see #containsHeader(String)
217      * @see #addIntHeader(String, int)
218      */
219 
220     void setIntHeader(String   name, int value);
221 
222     /**
223      * Adds a response header with the given name and
224      * int value. This method allows response headers
225      * to have multiple values.
226      *
227      * @param        name        the name of the header to set
228      * @param        value       the additional int value
229      *
230      * @see #setIntHeader(String, int)
231      */
232 
233     void addIntHeader(String   name, int value);
234 }
235
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags