Class ResponseWriter
- All Implemented Interfaces:
Closeable
,Flushable
,Appendable
,AutoCloseable
- Direct Known Subclasses:
HtmlResponseWriter
,ResponseWriterWrapper
public abstract class ResponseWriter extends 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.
-
Field Summary
-
Constructor Summary
Constructors Constructor Description ResponseWriter()
-
Method Summary
Modifier and Type Method Description abstract ResponseWriter
cloneWithWriter(Writer writer)
Create and return a new instance of thisResponseWriter
, using the specifiedWriter
as the output destination.void
endCDATA()
Close an XMLCDATA
block.abstract void
endDocument()
Write whatever text should end a response.abstract void
endElement(String name)
Write the end of an element, after closing any open element created by a call tostartElement()
.abstract void
flush()
Flush any ouput buffered by the output method to the underlying Writer or OutputStream.abstract String
getCharacterEncoding()
Return the character encoding (such as "ISO-8859-1") for thisResponseWriter
.abstract String
getContentType()
Return the content type (such as "text/html") for thisResponseWriter
.void
startCDATA()
Open an XMLCDATA
block.abstract void
startDocument()
Write whatever text should begin a response.abstract void
startElement(String name, UIComponent component)
Write the start of an element, up to and including the element name.abstract void
writeAttribute(String name, Object value, String property)
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.abstract void
writeComment(Object comment)
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.void
writeDoctype(String doctype)
Write a string containing the markup specific doctype.void
writePreamble(String preamble)
Write a string containing the markup specific preamble.abstract void
writeText(char[] text, int off, int len)
Write text from a character array, after any performing any escaping appropriate for the markup language being rendered.void
writeText(Object text, UIComponent component, String property)
Write an object, after converting it to a String (if necessary), and after performing any escaping appropriate for the markup language being rendered.abstract void
writeText(Object text, String property)
Write an object, after converting it to a String (if necessary), and after performing any escaping appropriate for the markup language being rendered.abstract void
writeURIAttribute(String name, Object value, String property)
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.
-
Constructor Details
-
ResponseWriter
public ResponseWriter()
-
-
Method Details
-
getContentType
Return the content type (such as "text/html") for this
ResponseWriter
. Note: this must not include the "charset=" suffix.- Returns:
- the content type
-
getCharacterEncoding
Return the character encoding (such as "ISO-8859-1") for this
ResponseWriter
. Please see the IANA for a list of character encodings.- Returns:
- the character encoding
-
flush
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
ResponseWriter
.- Specified by:
flush
in interfaceFlushable
- Specified by:
flush
in classWriter
- Throws:
IOException
-
startDocument
Write whatever text should begin a response.
- Throws:
IOException
- if an input/output error occurs
-
endDocument
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
-
startElement
Write the start of an element, up to and including the element name. Once this method has been called, clients can call the
writeAttribute()
orwriteURIAttribute()
methods to add attributes and corresponding values. The starting element will be closed (that is, the trailing '>' character added) on any subsequent call tostartElement()
,writeComment()
,writeText()
,endElement()
,endDocument()
,close()
,flush()
, orwrite()
.If the argument component's pass through attributes includes an attribute of the name given by the value of the symbolic constant
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.- Parameters:
name
- Name of the element to be startedcomponent
- TheUIComponent
(if any) to which this element corresponds. This component is inspected for its pass through attributes as described in the standard HTML_BASICRenderKit
specification.- Throws:
IOException
- if an input/output error occursNullPointerException
- ifname
isnull
-
endElement
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
Renderer.PASSTHROUGH_RENDERER_LOCALNAME_KEY
, use that as the element name, instead of the value passed as the first parameter to this method.- Parameters:
name
- Name of the element to be ended- Throws:
IOException
- if an input/output error occursNullPointerException
- ifname
isnull
-
writeAttribute
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.- Parameters:
name
- Attribute name to be addedvalue
- Attribute value to be addedproperty
- Name of the property or attribute (if any) of theUIComponent
associated with the containing element, to which this generated attribute corresponds- Throws:
IllegalStateException
- if this method is called when there is no currently open elementIOException
- if an input/output error occursNullPointerException
- ifname
isnull
-
writeURIAttribute
public abstract void writeURIAttribute(String name, Object value, String property) throws IOExceptionWrite 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.- Parameters:
name
- Attribute name to be addedvalue
- Attribute value to be addedproperty
- Name of the property or attribute (if any) of theUIComponent
associated with the containing element, to which this generated attribute corresponds- Throws:
IllegalStateException
- if this method is called when there is no currently open elementIOException
- if an input/output error occursNullPointerException
- ifname
isnull
-
startCDATA
Open an XML
CDATA
block. Note that XML does not allow nestedCDATA
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
-
endCDATA
Close an XML
CDATA
block. The default implementation of this method takes no action when invoked.- Throws:
IOException
- if input/output error occures
-
writeComment
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.- Parameters:
comment
- Text content of the comment- Throws:
IOException
- if an input/output error occursNullPointerException
- ifcomment
isnull
-
writePreamble
Write a string containing the markup specific preamble. No escaping is performed. The default implementation simply calls through to
Writer.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.
- Parameters:
preamble
- Text content of the preamble- Throws:
IOException
- if an input/output error occurs- Since:
- 2.2
-
writeDoctype
Write a string containing the markup specific doctype. No escaping is performed. The default implementation simply calls through to
Writer.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.
- Parameters:
doctype
- Text content of the doctype- Throws:
IOException
- if an input/output error occurs- Since:
- 2.2
-
writeText
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.- Parameters:
text
- Text to be writtenproperty
- Name of the property or attribute (if any) of theUIComponent
associated with the containing element, to which this generated text corresponds- Throws:
IOException
- if an input/output error occursNullPointerException
- iftext
isnull
-
writeText
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
writeText(java.lang.Object,java.lang.String)
but adds acomponent
property to allow customResponseWriter
implementations to associate a component with an arbitrary portion of text.The default implementation simply ignores the
component
argument and calls through towriteText(java.lang.Object,java.lang.String)
- Parameters:
text
- Text to be writtencomponent
- TheUIComponent
(if any) to which this element correspondsproperty
- Name of the property or attribute (if any) of theUIComponent
associated with the containing element, to which this generated text corresponds- Throws:
IOException
- if an input/output error occursNullPointerException
- iftext
isnull
- Since:
- 1.2
-
writeText
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.- Parameters:
text
- Text to be writtenoff
- Starting offset (zero-relative)len
- Number of characters to be written- Throws:
IndexOutOfBoundsException
- if the calculated starting or ending position is outside the bounds of the character arrayIOException
- if an input/output error occursNullPointerException
- iftext
isnull
-
cloneWithWriter
Create and return a new instance of this
ResponseWriter
, using the specifiedWriter
as the output destination.- Parameters:
writer
- TheWriter
that is the output destination- Returns:
- the new
ResponseWriter
-