All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.faces.context.ResponseWriter Maven / Gradle / Ivy

Go to download

This is the master POM file for Oracle's Implementation of the JSF 2.2 Specification.

There is a newer version: 2.2.20
Show newest version
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

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.

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

* *
* *

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




© 2015 - 2024 Weber Informatics LLC | Privacy Policy