/* * Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved. * * This program and the accompanying materials are made available under the * terms of the Eclipse Public License v. 2.0, which is available at * http://www.eclipse.org/legal/epl-2.0. * * This Source Code may also be made available under the following Secondary * Licenses when the conditions for such availability set forth in the * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, * version 2 with the GNU Classpath Exception, which is available at * https://www.gnu.org/software/classpath/license.html. * * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 */ package javax.faces.context; import javax.faces.component.UIComponent; import java.io.IOException; import java.io.Writer; /** *

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.

* * @return the content type */ 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.

* * @return the character encoding */ 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}.

*/ @Override 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().

* *
* *

If the argument component's pass through attributes * includes an attribute of the name given by the value of the symbolic * constant {@link javax.faces.render.Renderer#PASSTHROUGH_RENDERER_LOCALNAME_KEY}, * use that as the element name, instead of the value passed as the first * parameter to this method. Care must be taken so that this value * is not also rendered when any other pass through attributes on this component * are rendered.

* *
* * @param name Name of the element to be started * @param component The {@link UIComponent} (if any) to which this * element corresponds. This component is * inspected for its pass through attributes as * described in the standard HTML_BASIC {@code * RenderKit} specification. * @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.

* *
* *

If the argument component's pass through attributes * includes an attribute of the name given by the value of the symbolic * constant {@link javax.faces.render.Renderer#PASSTHROUGH_RENDERER_LOCALNAME_KEY}, * use that as the element name, instead of the value passed as the first * parameter to this method.

* *
* * @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 or escaping * appropriate to the markup language being rendered. When rendering in a WWW environment, * the escaping conventions established in the W3C URI spec document * <http://www.w3.org/Addressing/URL/uri-spec.html> * must be followed. In particular, spaces ' ' must be encoded as * %20 and not the plus character '+'. 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; /** *

Open an XML CDATA * block. Note that XML does not allow nested CDATA * blocks, though this method does not enforce that constraint. The * default implementation of this method takes no action when * invoked.

* @throws IOException if input/output error occures */ public void startCDATA() throws IOException { } /** *

Close an XML CDATA * block. The default implementation of this method takes no action * when invoked.

* @throws IOException if input/output error occures */ public void endCDATA() throws IOException { throw new UnsupportedOperationException(); } /** *

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 a string containing the markup specific * preamble. * No escaping is performed. The default * implementation simply calls through to {@link #write(java.lang.String)} .

* *
* *

The implementation makes no checks if this is the correct place * in the response to have a preamble, nor does it prevent the preamble * from being written more than once.

* *
* * @since 2.2 * @param preamble Text content of the preamble * @throws IOException if an input/output error occurs */ public void writePreamble(String preamble) throws IOException { write(preamble); } /** *

Write a string containing the markup specific * doctype. * No escaping is performed. The default * implementation simply calls through to {@link #write(java.lang.String)} .

* *
* *

The implementation makes no checks if this is the correct place * in the response to have a doctype, nor does it prevent the doctype * from being written more than once.

* *
* * @since 2.2 * @param doctype Text content of the doctype * @throws IOException if an input/output error occurs */ public void writeDoctype(String doctype) throws IOException { write(doctype); } /** *

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 * * @return the new ResponseWriter */ public abstract ResponseWriter cloneWithWriter(Writer writer); }