jforum example source code file (ResponseContext.java)

This example jforum source code file (ResponseContext.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - jforum tags/keywords

http, io, ioexception, ioexception, printwriter, printwriter, request, response, responsecontext, servlet, servletoutputstream, servletoutputstream, string, string

The jforum ResponseContext.java source code

/*
 * Copyright (c) JForum Team
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms,
 * with or without modification, are permitted provided
 * that the following conditions are met:
 *
 * 1) Redistributions of source code must retain the above
 * copyright notice, this list of conditions and the
 * following  disclaimer.
 * 2)  Redistributions in binary form must reproduce the
 * above copyright notice, this list of conditions and
 * the following disclaimer in the documentation and/or
 * other materials provided with the distribution.
 * 3) Neither the name of "Rafael Steil" nor
 * the names of its contributors may be used to endorse
 * or promote products derived from this software without
 * specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT
 * HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
 * THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 * IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
 *
 * The JForum Project
 * http://www.jforum.net
 */
package net.jforum.context;

import javax.servlet.ServletOutputStream;
import javax.servlet.http.Cookie;
import java.io.IOException;
import java.io.PrintWriter;

/**
 * User: SergeMaslyukov Date: 20.08.2006 Time: 18:48:56 <p/> $Id: WebContextResponse.java,v 1.1
 * 2006/08/20 15:30:30 sergemaslyukov Exp $
 */
public interface ResponseContext
{
	/**
	 * Sets the length of the content body in the response In HTTP servlets, this method sets the
	 * HTTP Content-Length header.
	 * 
	 * @param len an integer specifying the length of the content being returned to the client; 
	 * sets the Content-Length header
	 */
	public void setContentLength(int len);

	/**
	 * Returns a boolean indicating whether the named response header has already been set.
	 * 
	 * @param name the header name
	 * @return <code>true if the named response header has already been set;
	 * <code>false otherwise
	 */
	public boolean containsHeader(String name);

	/**
	 * Sets a response header with the given name and value. If the header had already been set, the
	 * new value overwrites the previous one. The <code>containsHeader method can be used
	 * to test for the presence of a header before setting its value.
	 * 
	 * @param name the name of the header
	 * @param value the header value If it contains octet string, it should be encoded 
	 * according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
	 * 
	 * @see #containsHeader
	 * @see #addHeader
	 */
	public void setHeader(String name, String value);

	/**
	 * Adds the specified cookie to the response. This method can be called multiple times to set
	 * more than one cookie.
	 * 
	 * @param cookie the Cookie to return to the client
	 */
	public void addCookie(Cookie cookie);

	/**
	 * Encodes the specified URL for use in the <code>sendRedirect method or, if encoding
	 * is not needed, returns the URL unchanged. The implementation of this method includes the
	 * logic to determine whether the session ID needs to be encoded in the URL. Because the rules
	 * for making this determination can differ from those used to decide whether to encode a normal
	 * link, this method is separated from the <code>encodeURL method.
	 * 
	 * <p>
	 * All URLs sent to the <code>HttpServletResponse.sendRedirect method should be run
	 * through this method. Otherwise, URL rewriting cannot be used with browsers which do not
	 * support cookies.
	 * 
	 * @param url the url to be encoded.
	 * @return the encoded URL if encoding is needed; the unchanged URL otherwise.
	 * 
	 * @see #sendRedirect
	 * @see #encodeUrl
	 */
	public String encodeRedirectURL(String url);

	/**
	 * Returns the name of the character encoding (MIME charset) used for the body sent in this
	 * response. The character encoding may have been specified explicitly using the
	 * {@link #setCharacterEncoding} or {@link #setContentType} methods, or implicitly using the
	 * {@link #setLocale} method. Explicit specifications take precedence over implicit
	 * specifications. Calls made to these methods after <code>getWriter has been called or
	 * after the response has been committed have no effect on the character encoding. If no
	 * character encoding has been specified, <code>ISO-8859-1 is returned.
	 * <p>
	 * See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information about character
	 * encoding and MIME.
	 * 
	 * @return a <code>String specifying the name of the character encoding, for example,
	 * <code>UTF-8
	 * 
	 */
	public String getCharacterEncoding();

	/**
	 * Sends a temporary redirect response to the client using the specified redirect location URL.
	 * This method can accept relative URLs; the servlet container must convert the relative URL to
	 * an absolute URL before sending the response to the client. If the location is relative
	 * without a leading '/' the container interprets it as relative to the current request URI. If
	 * the location is relative with a leading '/' the container interprets it as relative to the
	 * servlet container root.
	 * 
	 * <p>
	 * If the response has already been committed, this method throws an IllegalStateException.
	 * After using this method, the response should be considered to be committed and should not be
	 * written to.
	 * 
	 * @param location the redirect location URL
	 * @exception IOException If an input or output exception occurs
	 * @exception IllegalStateException If the response was committed or if a partial 
	 * URL is given and cannot be converted into a valid URL
	 */
	public void sendRedirect(String location) throws IOException;

	/**
	 * Returns a {@link javax.servlet.ServletOutputStream} suitable for writing binary data in the
	 * response. The servlet container does not encode the binary data.
	 * 
	 * <p>
	 * Calling flush() on the ServletOutputStream commits the response.
	 * 
	 * Either this method or {@link #getWriter} may be called to write the body, not both.
	 * 
	 * @return a {@link javax.servlet.ServletOutputStream} for writing binary data
	 * @exception IllegalStateException if the <code>getWriter method has 
	 * been called on this response
	 * @exception IOException if an input or output exception occurred
	 * @see #getWriter
	 */

	public ServletOutputStream getOutputStream() throws IOException;

	/**
	 * Returns a <code>PrintWriter object that can send character text to the client. The
	 * <code>PrintWriter uses the character encoding returned by
	 * {@link #getCharacterEncoding}. If the response's character encoding has not been specified
	 * as described in <code>getCharacterEncoding (i.e., the method just returns the
	 * default value <code>ISO-8859-1), getWriter updates it to
	 * <code>ISO-8859-1.
	 * <p>
	 * Calling flush() on the <code>PrintWriter commits the response.
	 * <p>
	 * Either this method or {@link #getOutputStream} may be called to write the body, not both.
	 * 
	 * @return a <code>PrintWriter object that can return character data to the client
	 * 
	 * @exception java.io.UnsupportedEncodingException if the character encoding 
	 * returned by <code>getCharacterEncoding cannot be used
	 * @exception IllegalStateException if the <code>getOutputStream method has 
	 * already been called for this response object
	 * @exception IOException if an input or output exception occurred
	 * 
	 * @see #getOutputStream
	 * @see #setCharacterEncoding
	 * 
	 */
	public PrintWriter getWriter() throws IOException;

	/**
	 * Sets the content type of the response being sent to the client, if the response has not been
	 * committed yet. The given content type may include a character encoding specification, for
	 * example, <code>text/html;charset=UTF-8. The response's character encoding is only
	 * set from the given content type if this method is called before <code>getWriter is
	 * called.
	 * <p>
	 * This method may be called repeatedly to change content type and character encoding. This
	 * method has no effect if called after the response has been committed. It does not set the
	 * response's character encoding if it is called after <code>getWriter has been called
	 * or after the response has been committed.
	 * <p>
	 * Containers must communicate the content type and the character encoding used for the servlet
	 * response's writer to the client if the protocol provides a way for doing so. In the case of
	 * HTTP, the <code>Content-Type header is used.
	 * 
	 * @param type a <code>String specifying the MIME type of the content
	 * 
	 * @see #setLocale
	 * @see #setCharacterEncoding
	 * @see #getOutputStream
	 * @see #getWriter
	 */
	public void setContentType(String type);

	/**
	 * Encodes the specified URL by including the session ID in it, or, if encoding is not needed,
	 * returns the URL unchanged. The implementation of this method includes the logic to determine
	 * whether the session ID needs to be encoded in the URL. For example, if the browser supports
	 * cookies, or session tracking is turned off, URL encoding is unnecessary.
	 * 
	 * <p>
	 * For robust session tracking, all URLs emitted by a servlet should be run through this method.
	 * Otherwise, URL rewriting cannot be used with browsers which do not support cookies.
	 * 
	 * @param url the url to be encoded.
	 * @return the encoded URL if encoding is needed; the unchanged URL otherwise.
	 */
	public String encodeURL(String url);

	/**
	 * Adds a response header with the given name and value. This method allows response headers to
	 * have multiple values.
	 * 
	 * @param name the name of the header
	 * @param value the additional header value If it contains octet string, 
	 * it should be encoded according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
	 */
	public void addHeader(String name, String value);

	/**
	 * Sends an error response to the client using the specified status code and clearing the
	 * buffer.
	 * <p>
	 * If the response has already been committed, this method throws an IllegalStateException.
	 * After using this method, the response should be considered to be committed and should not be
	 * written to.
	 * 
	 * @param sc the error status code
	 * @exception java.io.IOException If an input or output exception occurs
	 * @exception IllegalStateException If the response was committed before this method call
	 */
	public void sendError(int sc) throws IOException;
}