javax.faces.context.ResponseWriter Maven / Gradle / Ivy
Show all versions of javaee-web-api Show documentation
/*
* 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.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.
*
* @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);
}