001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    
020    //
021    // This source code implements specifications defined by the Java
022    // Community Process. In order to remain compliant with the specification
023    // DO NOT add / change / or delete method signatures!
024    //
025    
026    package javax.servlet.http;
027    
028    import java.io.IOException;
029    import javax.servlet.ServletResponse;
030    
031    /**
032     * Extends the {@link ServletResponse} interface to provide HTTP-specific
033     * functionality in sending a response.  For example, it has methods
034     * to access HTTP headers and cookies.
035     *
036     * <p>The servlet container creates an <code>HttpServletResponse</code> object
037     * and passes it as an argument to the servlet's service methods
038     * (<code>doGet</code>, <code>doPost</code>, etc).
039     *
040     * @see javax.servlet.ServletResponse
041     *
042     * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $
043     */
044    public interface HttpServletResponse extends ServletResponse {
045        /**
046         * Adds the specified cookie to the response.  This method can be called
047         * multiple times to set more than one cookie.
048         *
049         * @param cookie the Cookie to return to the client
050         */
051        public void addCookie(Cookie cookie);
052    
053        /**
054         * Returns a boolean indicating whether the named response header has
055         * already been set.
056         *
057         * @param name the header name
058         * @return <code>true</code> if the named response header has already been
059         * set; <code>false</code> otherwise
060         */
061        public boolean containsHeader(String name);
062    
063        /**
064         * Encodes the specified URL by including the session ID in it,
065         * or, if encoding is not needed, returns the URL unchanged.
066         * The implementation of this method includes the logic to
067         * determine whether the session ID needs to be encoded in the URL.
068         * For example, if the browser supports cookies, or session
069         * tracking is turned off, URL encoding is unnecessary.
070         *
071         * <p>For robust session tracking, all URLs emitted by a servlet
072         * should be run through this
073         * method.  Otherwise, URL rewriting cannot be used with browsers
074         * which do not support cookies.
075         *
076         * @param url the url to be encoded.
077         * @return the encoded URL if encoding is needed; the unchanged URL
078         * otherwise.
079         */
080        public String encodeURL(String url);
081    
082        /**
083         * Encodes the specified URL for use in the
084         * <code>sendRedirect</code> method or, if encoding is not needed,
085         * returns the URL unchanged.  The implementation of this method
086         * includes the logic to determine whether the session ID
087         * needs to be encoded in the URL.  Because the rules for making
088         * this determination can differ from those used to decide whether to
089         * encode a normal link, this method is separete from the
090         * <code>encodeURL</code> method.
091         *
092         * <p>All URLs sent to the <code>HttpServletResponse.sendRedirect</code>
093         * method should be run through this method.  Otherwise, URL
094         * rewriting cannot be used with browsers which do not support
095         * cookies.
096         *
097         * @param url the url to be encoded.
098         * @return the encoded URL if encoding is needed; the unchanged URL
099         * otherwise.
100         *
101         * @see #sendRedirect
102         * @see #encodeUrl
103         */
104        public String encodeRedirectURL(String url);
105    
106        /**
107         * @deprecated As of version 2.1, use encodeURL(String url) instead
108         *
109         * @param url the url to be encoded.
110         * @return the encoded URL if encoding is needed; the unchanged URL
111         * otherwise.
112         */
113        public String encodeUrl(String url);
114    
115        /**
116         * @deprecated As of version 2.1, use encodeRedirectURL(String url) instead
117         *
118         * @param url the url to be encoded.
119         * @return the encoded URL if encoding is needed; the unchanged URL
120         * otherwise.
121         */
122        public String encodeRedirectUrl(String url);
123    
124        /**
125         * Sends an error response to the client using the specified
126         * status.  The server defaults to creating the
127         * response to look like an HTML-formatted server error page
128         * containing the specified message, setting the content type
129         * to "text/html", leaving cookies and other headers unmodified.
130         *
131         * If an error-page declaration has been made for the web application
132         * corresponding to the status code passed in, it will be served back in
133         * preference to the suggested msg parameter.
134         *
135         * <p>If the response has already been committed, this method throws
136         * an IllegalStateException.
137         * After using this method, the response should be considered
138         * to be committed and should not be written to.
139         *
140         * @param sc the error status code
141         * @param msg the descriptive message
142         * @exception IOException If an input or output exception occurs
143         * @exception IllegalStateException If the response was committed
144         */
145        public void sendError(int sc, String msg) throws IOException;
146    
147        /**
148         * Sends an error response to the client using the specified status
149         * code and clearing the buffer.
150         * <p>If the response has already been committed, this method throws
151         * an IllegalStateException.
152         * After using this method, the response should be considered
153         * to be committed and should not be written to.
154         *
155         * @param sc the error status code
156         * @exception IOException If an input or output exception occurs
157         * @exception IllegalStateException If the response was committed
158         * before this method call
159         */
160        public void sendError(int sc) throws IOException;
161    
162        /**
163         * Sends a temporary redirect response to the client using the
164         * specified redirect location URL.  This method can accept relative URLs;
165         * the servlet container must convert the relative URL to an absolute URL
166         * before sending the response to the client. If the location is relative
167         * without a leading '/' the container interprets it as relative to
168         * the current request URI. If the location is relative with a leading
169         * '/' the container interprets it as relative to the servlet container root.
170         *
171         * <p>If the response has already been committed, this method throws
172         * an IllegalStateException.
173         * After using this method, the response should be considered
174         * to be committed and should not be written to.
175         *
176         * @param location the redirect location URL
177         * @exception IOException If an input or output exception occurs
178         * @exception IllegalStateException If the response was committed or
179         * if a partial URL is given and cannot be converted into a valid URL
180         */
181        public void sendRedirect(String location) throws IOException;
182    
183        /**
184         * Sets a response header with the given name and
185         * date-value.  The date is specified in terms of
186         * milliseconds since the epoch.  If the header had already
187         * been set, the new value overwrites the previous one.  The
188         * <code>containsHeader</code> method can be used to test for the
189         * presence of a header before setting its value.
190         *
191         * @param name the name of the header to set
192         * @param date the assigned date value
193         *
194         * @see #containsHeader
195         * @see #addDateHeader
196         */
197        public void setDateHeader(String name, long date);
198    
199        /**
200         * Adds a response header with the given name and
201         * date-value.  The date is specified in terms of
202         * milliseconds since the epoch.  This method allows response headers
203         * to have multiple values.
204         *
205         * @param name the name of the header to set
206         * @param date the additional date value
207         *
208         * @see #setDateHeader
209         */
210        public void addDateHeader(String name, long date);
211    
212        /**
213         * Sets a response header with the given name and value.
214         * If the header had already been set, the new value overwrites the
215         * previous one.  The <code>containsHeader</code> method can be
216         * used to test for the presence of a header before setting its
217         * value.
218         *
219         * @param name the name of the header
220         * @param value the header value  If it contains octet string,
221         * it should be encoded according to RFC 2047
222         * (http://www.ietf.org/rfc/rfc2047.txt)
223         *
224         * @see #containsHeader
225         * @see #addHeader
226         */
227        public void setHeader(String name, String value);
228    
229        /**
230         * Adds a response header with the given name and value.
231         * This method allows response headers to have multiple values.
232         *
233         * @param name the name of the header
234         * @param value the additional header value If it contains octet string,
235         * it should be encoded according to RFC 2047
236         * (http://www.ietf.org/rfc/rfc2047.txt)
237         *
238         * @see #setHeader
239         */
240        public void addHeader(String name, String value);
241    
242        /**
243         * Sets a response header with the given name and
244         * integer value.  If the header had already been set, the new value
245         * overwrites the previous one.  The <code>containsHeader</code>
246         * method can be used to test for the presence of a header before
247         * setting its value.
248         *
249         * @param name the name of the header
250         * @param value the assigned integer value
251         *
252         * @see #containsHeader
253         * @see #addIntHeader
254         */
255        public void setIntHeader(String name, int value);
256    
257        /**
258         * Adds a response header with the given name and
259         * integer value.  This method allows response headers to have multiple
260         * values.
261         *
262         * @param name the name of the header
263         * @param value the assigned integer value
264         *
265         * @see #setIntHeader
266         */
267        public void addIntHeader(String name, int value);
268    
269        /**
270         * Sets the status code for this response.  This method is used to
271         * set the return status code when there is no error (for example,
272         * for the status codes SC_OK or SC_MOVED_TEMPORARILY).  If there
273         * is an error, and the caller wishes to invoke an error-page defined
274         * in the web applicaion, the <code>sendError</code> method should be used
275         * instead.
276         * <p> The container clears the buffer and sets the Location header, preserving
277         * cookies and other headers.
278         *
279         * @param sc the status code
280         *
281         * @see #sendError
282         */
283        public void setStatus(int sc);
284    
285        /**
286         * @deprecated As of version 2.1, due to ambiguous meaning of the
287         * message parameter. To set a status code
288         * use <code>setStatus(int)</code>, to send an error with a description
289         * use <code>sendError(int, String)</code>.
290         *
291         * Sets the status code and message for this response.
292         *
293         * @param sc the status code
294         * @param sm the status message
295         */
296        public void setStatus(int sc, String sm);
297    
298        //
299        // Server status codes; see RFC 2068.
300        //
301    
302        /**
303         * Status code (100) indicating the client can continue.
304         */
305        public static final int SC_CONTINUE = 100;
306    
307        /**
308         * Status code (101) indicating the server is switching protocols
309         * according to Upgrade header.
310         */
311        public static final int SC_SWITCHING_PROTOCOLS = 101;
312    
313        /**
314         * Status code (200) indicating the request succeeded normally.
315         */
316        public static final int SC_OK = 200;
317    
318        /**
319         * Status code (201) indicating the request succeeded and created
320         * a new resource on the server.
321         */
322        public static final int SC_CREATED = 201;
323    
324        /**
325         * Status code (202) indicating that a request was accepted for
326         * processing, but was not completed.
327         */
328        public static final int SC_ACCEPTED = 202;
329    
330        /**
331         * Status code (203) indicating that the meta information presented
332         * by the client did not originate from the server.
333         */
334        public static final int SC_NON_AUTHORITATIVE_INFORMATION = 203;
335    
336        /**
337         * Status code (204) indicating that the request succeeded but that
338         * there was no new information to return.
339         */
340        public static final int SC_NO_CONTENT = 204;
341    
342        /**
343         * Status code (205) indicating that the agent <em>SHOULD</em> reset
344         * the document view which caused the request to be sent.
345         */
346        public static final int SC_RESET_CONTENT = 205;
347    
348        /**
349         * Status code (206) indicating that the server has fulfilled
350         * the partial GET request for the resource.
351         */
352        public static final int SC_PARTIAL_CONTENT = 206;
353    
354        /**
355         * Status code (300) indicating that the requested resource
356         * corresponds to any one of a set of representations, each with
357         * its own specific location.
358         */
359        public static final int SC_MULTIPLE_CHOICES = 300;
360    
361        /**
362         * Status code (301) indicating that the resource has permanently
363         * moved to a new location, and that future references should use a
364         * new URI with their requests.
365         */
366        public static final int SC_MOVED_PERMANENTLY = 301;
367    
368        /**
369         * Status code (302) indicating that the resource has temporarily
370         * moved to another location, but that future references should
371         * still use the original URI to access the resource.
372         *
373         * This definition is being retained for backwards compatibility.
374         * SC_FOUND is now the preferred definition.
375         */
376        public static final int SC_MOVED_TEMPORARILY = 302;
377    
378        /**
379         * Status code (302) indicating that the resource reside
380         * temporarily under a different URI. Since the redirection might
381         * be altered on occasion, the client should continue to use the
382         * Request-URI for future requests.(HTTP/1.1) To represent the
383         * status code (302), it is recommended to use this variable.
384         */
385        public static final int SC_FOUND = 302;
386    
387        /**
388         * Status code (303) indicating that the response to the request
389         * can be found under a different URI.
390         */
391        public static final int SC_SEE_OTHER = 303;
392    
393        /**
394         * Status code (304) indicating that a conditional GET operation
395         * found that the resource was available and not modified.
396         */
397        public static final int SC_NOT_MODIFIED = 304;
398    
399        /**
400         * Status code (305) indicating that the requested resource
401         * <em>MUST</em> be accessed through the proxy given by the
402         * <code><em>Location</em></code> field.
403         */
404        public static final int SC_USE_PROXY = 305;
405    
406        /**
407         * Status code (307) indicating that the requested resource
408         * resides temporarily under a different URI. The temporary URI
409         * <em>SHOULD</em> be given by the <code><em>Location</em></code>
410         * field in the response.
411         */
412        public static final int SC_TEMPORARY_REDIRECT = 307;
413    
414        /**
415         * Status code (400) indicating the request sent by the client was
416         * syntactically incorrect.
417         */
418        public static final int SC_BAD_REQUEST = 400;
419    
420        /**
421         * Status code (401) indicating that the request requires HTTP
422         * authentication.
423         */
424        public static final int SC_UNAUTHORIZED = 401;
425    
426        /**
427         * Status code (402) reserved for future use.
428         */
429        public static final int SC_PAYMENT_REQUIRED = 402;
430    
431        /**
432         * Status code (403) indicating the server understood the request
433         * but refused to fulfill it.
434         */
435        public static final int SC_FORBIDDEN = 403;
436    
437        /**
438         * Status code (404) indicating that the requested resource is not
439         * available.
440         */
441        public static final int SC_NOT_FOUND = 404;
442    
443        /**
444         * Status code (405) indicating that the method specified in the
445         * <code><em>Request-Line</em></code> is not allowed for the resource
446         * identified by the <code><em>Request-URI</em></code>.
447         */
448        public static final int SC_METHOD_NOT_ALLOWED = 405;
449    
450        /**
451         * Status code (406) indicating that the resource identified by the
452         * request is only capable of generating response entities which have
453         * content characteristics not acceptable according to the accept
454         * headers sent in the request.
455         */
456        public static final int SC_NOT_ACCEPTABLE = 406;
457    
458        /**
459         * Status code (407) indicating that the client <em>MUST</em> first
460         * authenticate itself with the proxy.
461         */
462        public static final int SC_PROXY_AUTHENTICATION_REQUIRED = 407;
463    
464        /**
465         * Status code (408) indicating that the client did not produce a
466         * request within the time that the server was prepared to wait.
467         */
468        public static final int SC_REQUEST_TIMEOUT = 408;
469    
470        /**
471         * Status code (409) indicating that the request could not be
472         * completed due to a conflict with the current state of the
473         * resource.
474         */
475        public static final int SC_CONFLICT = 409;
476    
477        /**
478         * Status code (410) indicating that the resource is no longer
479         * available at the server and no forwarding address is known.
480         * This condition <em>SHOULD</em> be considered permanent.
481         */
482        public static final int SC_GONE = 410;
483    
484        /**
485         * Status code (411) indicating that the request cannot be handled
486         * without a defined <code><em>Content-Length</em></code>.
487         */
488        public static final int SC_LENGTH_REQUIRED = 411;
489    
490        /**
491         * Status code (412) indicating that the precondition given in one
492         * or more of the request-header fields evaluated to false when it
493         * was tested on the server.
494         */
495        public static final int SC_PRECONDITION_FAILED = 412;
496    
497        /**
498         * Status code (413) indicating that the server is refusing to process
499         * the request because the request entity is larger than the server is
500         * willing or able to process.
501         */
502        public static final int SC_REQUEST_ENTITY_TOO_LARGE = 413;
503    
504        /**
505         * Status code (414) indicating that the server is refusing to service
506         * the request because the <code><em>Request-URI</em></code> is longer
507         * than the server is willing to interpret.
508         */
509        public static final int SC_REQUEST_URI_TOO_LONG = 414;
510    
511        /**
512         * Status code (415) indicating that the server is refusing to service
513         * the request because the entity of the request is in a format not
514         * supported by the requested resource for the requested method.
515         */
516        public static final int SC_UNSUPPORTED_MEDIA_TYPE = 415;
517    
518        /**
519         * Status code (416) indicating that the server cannot serve the
520         * requested byte range.
521         */
522        public static final int SC_REQUESTED_RANGE_NOT_SATISFIABLE = 416;
523    
524        /**
525         * Status code (417) indicating that the server could not meet the
526         * expectation given in the Expect request header.
527         */
528        public static final int SC_EXPECTATION_FAILED = 417;
529    
530        /**
531         * Status code (500) indicating an error inside the HTTP server
532         * which prevented it from fulfilling the request.
533         */
534        public static final int SC_INTERNAL_SERVER_ERROR = 500;
535    
536        /**
537         * Status code (501) indicating the HTTP server does not support
538         * the functionality needed to fulfill the request.
539         */
540        public static final int SC_NOT_IMPLEMENTED = 501;
541    
542        /**
543         * Status code (502) indicating that the HTTP server received an
544         * invalid response from a server it consulted when acting as a
545         * proxy or gateway.
546         */
547        public static final int SC_BAD_GATEWAY = 502;
548    
549        /**
550         * Status code (503) indicating that the HTTP server is
551         * temporarily overloaded, and unable to handle the request.
552         */
553        public static final int SC_SERVICE_UNAVAILABLE = 503;
554    
555        /**
556         * Status code (504) indicating that the server did not receive
557         * a timely response from the upstream server while acting as
558         * a gateway or proxy.
559         */
560        public static final int SC_GATEWAY_TIMEOUT = 504;
561    
562        /**
563         * Status code (505) indicating that the server does not support
564         * or refuses to support the HTTP protocol version that was used
565         * in the request message.
566         */
567        public static final int SC_HTTP_VERSION_NOT_SUPPORTED = 505;
568    }