javax.faces.context.ResponseWriter Maven / Gradle / Ivy
/*
* $Id: ResponseWriter.java,v 1.18 2006/03/24 19:05:33 edburns Exp $
*/
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the License at
* https://javaserverfaces.dev.java.net/CDDL.html or
* legal/CDDLv1.0.txt.
* See the License for the specific language governing
* permission and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at legal/CDDLv1.0.txt.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* your own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* [Name of File] [ver.__] [Date]
*
* Copyright 2005 Sun Microsystems Inc. All Rights Reserved
*/
package javax.faces.context;
import java.io.IOException;
import java.io.Writer;
import javax.faces.component.UIComponent;
/**
* ResponseWriter is an abstract class describing an
* adapter to an underlying output mechanism for character-based output.
* In addition to the low-level write() methods inherited from
* java.io.Writer, this class provides utility methods
* that are useful in producing elements and attributes for markup languages
* like HTML and XML.
*/
public abstract class ResponseWriter extends Writer {
/**
* Return the content type (such as "text/html") for this {@link
* ResponseWriter}. Note: this must not include the "charset="
* suffix.
*/
public abstract String getContentType();
/**
* Return the character encoding (such as "ISO-8859-1") for this
* {@link ResponseWriter}. Please see the
* IANA for a list of character encodings.
*/
public abstract String getCharacterEncoding();
/**
* Flush any ouput buffered by the output method to the
* underlying Writer or OutputStream. This method
* will not flush the underlying Writer or OutputStream; it
* simply clears any values buffered by this {@link ResponseWriter}.
*/
public abstract void flush() throws IOException;
/**
* Write whatever text should begin a response.
*
* @throws IOException if an input/output error occurs
*/
public abstract void startDocument() throws IOException;
/**
* Write whatever text should end a response. If there is an open
* element that has been created by a call to startElement(),
* that element will be closed first.
*
* @throws IOException if an input/output error occurs
*/
public abstract void endDocument() throws IOException;
/**
* Write the start of an element, up to and including the
* element name. Once this method has been called, clients can
* call the writeAttribute() or
* writeURIAttribute() methods to add attributes and
* corresponding values. The starting element will be closed
* (that is, the trailing '>' character added)
* on any subsequent call to startElement(),
* writeComment(),
* writeText(), endElement(),
* endDocument(), close(),
* flush(), or write().
*
* @param name Name of the element to be started
* @param component The {@link UIComponent} (if any) to which
* this element corresponds
*
* @throws IOException if an input/output error occurs
* @throws NullPointerException if name
* is null
*/
public abstract void startElement(String name, UIComponent component)
throws IOException;
/**
* Write the end of an element, after closing any open element
* created by a call to startElement(). Elements must be
* closed in the inverse order from which they were opened; it is an
* error to do otherwise.
*
* @param name Name of the element to be ended
*
* @throws IOException if an input/output error occurs
* @throws NullPointerException if name
* is null
*/
public abstract void endElement(String name) throws IOException;
/**
* Write an attribute name and corresponding value, after converting
* that text to a String (if necessary), and after performing any escaping
* appropriate for the markup language being rendered.
* This method may only be called after a call to
* startElement(), and before the opened element has been
* closed.
*
* @param name Attribute name to be added
* @param value Attribute value to be added
* @param property Name of the property or attribute (if any) of the
* {@link UIComponent} associated with the containing element,
* to which this generated attribute corresponds
*
* @throws IllegalStateException if this method is called when there
* is no currently open element
* @throws IOException if an input/output error occurs
* @throws NullPointerException if name is
* null
*/
public abstract void writeAttribute(String name, Object value,
String property)
throws IOException;
/**
* Write a URI attribute name and corresponding value, after converting
* that text to a String (if necessary), and after performing any encoding
* appropriate to the markup language being rendered.
* This method may only be called after a call to
* startElement(), and before the opened element has been
* closed.
*
* @param name Attribute name to be added
* @param value Attribute value to be added
* @param property Name of the property or attribute (if any) of the
* {@link UIComponent} associated with the containing element,
* to which this generated attribute corresponds
*
* @throws IllegalStateException if this method is called when there
* is no currently open element
* @throws IOException if an input/output error occurs
* @throws NullPointerException if name is
* null
*/
public abstract void writeURIAttribute(String name, Object value,
String property)
throws IOException;
/**
* Write a comment containing the specified text, after converting
* that text to a String (if necessary), and after performing any escaping
* appropriate for the markup language being rendered. If there is
* an open element that has been created by a call to
* startElement(), that element will be closed first.
*
* @param comment Text content of the comment
*
* @throws IOException if an input/output error occurs
* @throws NullPointerException if comment
* is null
*/
public abstract void writeComment(Object comment) throws IOException;
/**
* Write an object, after converting it to a String (if necessary),
* and after performing any escaping appropriate for the markup language
* being rendered. If there is an open element that has been created
* by a call to startElement(), that element will be closed
* first.
*
* @param text Text to be written
* @param property Name of the property or attribute (if any) of the
* {@link UIComponent} associated with the containing element,
* to which this generated text corresponds
*
* @throws IOException if an input/output error occurs
* @throws NullPointerException if text
* is null
*/
public abstract void writeText(Object text, String property)
throws IOException;
/**
* Write an object, after converting it to a String (if
* necessary), and after performing any escaping appropriate for the
* markup language being rendered. This method is equivalent to
* {@link #writeText(java.lang.Object,java.lang.String)} but adds a
* component property to allow custom
* ResponseWriter implementations to associate a
* component with an arbitrary portion of text.
*
* The default implementation simply ignores the
* component argument and calls through to {@link
* #writeText(java.lang.Object,java.lang.String)}
*
* @param text Text to be written
* @param component The {@link UIComponent} (if any) to which
* this element corresponds
* @param property Name of the property or attribute (if any) of the
* {@link UIComponent} associated with the containing element,
* to which this generated text corresponds
*
* @throws IOException if an input/output error occurs
* @throws NullPointerException if text
* is null
*
* @since 1.2
*/
public void writeText(Object text, UIComponent component, String property)
throws IOException {
writeText(text, property);
}
/**
* Write text from a character array, after any performing any
* escaping appropriate for the markup language being rendered.
* If there is an open element that has been created by a call to
* startElement(), that element will be closed first.
*
* @param text Text to be written
* @param off Starting offset (zero-relative)
* @param len Number of characters to be written
*
* @throws IndexOutOfBoundsException if the calculated starting or
* ending position is outside the bounds of the character array
* @throws IOException if an input/output error occurs
* @throws NullPointerException if text
* is null
*/
public abstract void writeText(char text[], int off, int len)
throws IOException;
/**
* Create and return a new instance of this {@link ResponseWriter},
* using the specified Writer as the output destination.
*
* @param writer The Writer that is the output destination
*/
public abstract ResponseWriter cloneWithWriter(Writer writer);
}