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.
Constructor and Description |
---|
ResponseWriter() |
Modifier and Type | Method and Description |
---|---|
abstract ResponseWriter |
cloneWithWriter(Writer writer)
Create and return a new instance of this
ResponseWriter ,
using the specified Writer as the output destination. |
void |
endCDATA()
Close an XML |
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 to
startElement() . |
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 this
ResponseWriter . |
abstract String |
getContentType()
Return the content type (such as "text/html") for this
ResponseWriter . |
void |
startCDATA()
Open an XML |
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.
|
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.
|
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 |
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.
|
public abstract String getContentType()
Return the content type (such as "text/html") for this ResponseWriter
. Note: this must not include the "charset="
suffix.
public abstract String getCharacterEncoding()
Return the character encoding (such as "ISO-8859-1") for this
ResponseWriter
. Please see the
IANA for a list of character encodings.
public abstract void flush() throws IOException
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
.
flush
in interface Flushable
flush
in class Writer
IOException
public abstract void startDocument() throws IOException
Write whatever text should begin a response.
IOException
- if an input/output error occurspublic abstract void endDocument() 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.
IOException
- if an input/output error occurspublic abstract void startElement(String name, UIComponent component) 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 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.
name
- Name of the element to be startedcomponent
- The UIComponent
(if any) to which this
element corresponds. This component is
inspected for its pass through attributes as
described in the standard HTML_BASIC RenderKit
specification.IOException
- if an input/output error occursNullPointerException
- if name
is null
public abstract void endElement(String name) 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 Renderer.PASSTHROUGH_RENDERER_LOCALNAME_KEY
,
use that as the element name, instead of the value passed as the first
parameter to this method.
name
- Name of the element to be endedIOException
- if an input/output error occursNullPointerException
- if name
is null
public abstract void writeAttribute(String name, Object value, String property) 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.
name
- Attribute name to be addedvalue
- Attribute value to be addedproperty
- Name of the property or attribute (if any) of the
UIComponent
associated with the containing element,
to which this generated attribute correspondsIllegalStateException
- if this method is called when there
is no currently open elementIOException
- if an input/output error occursNullPointerException
- if name
is
null
public abstract void writeURIAttribute(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.
name
- Attribute name to be addedvalue
- Attribute value to be addedproperty
- Name of the property or attribute (if any) of the
UIComponent
associated with the containing element,
to which this generated attribute correspondsIllegalStateException
- if this method is called when there
is no currently open elementIOException
- if an input/output error occursNullPointerException
- if name
is
null
public void startCDATA() 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.
IOException
- if input/output error occurespublic void endCDATA() throws IOException
Close an XML CDATA
block. The default implementation of this method takes no action
when invoked.
IOException
- if input/output error occurespublic abstract void writeComment(Object comment) 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.
comment
- Text content of the commentIOException
- if an input/output error occursNullPointerException
- if comment
is null
public void writePreamble(String preamble) throws IOException
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.
preamble
- Text content of the preambleIOException
- if an input/output error occurspublic void writeDoctype(String doctype) throws IOException
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.
doctype
- Text content of the doctypeIOException
- if an input/output error occurspublic 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. If there is an open element that has been created
by a call to startElement()
, that element will be closed
first.
text
- Text to be writtenproperty
- Name of the property or attribute (if any) of the
UIComponent
associated with the containing element,
to which this generated text correspondsIOException
- if an input/output error occursNullPointerException
- if text
is null
public void writeText(Object text, UIComponent component, 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
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 writeText(java.lang.Object,java.lang.String)
text
- Text to be writtencomponent
- The UIComponent
(if any) to which
this element correspondsproperty
- Name of the property or attribute (if any) of the
UIComponent
associated with the containing element,
to which this generated text correspondsIOException
- if an input/output error occursNullPointerException
- if text
is null
public abstract void writeText(char[] text, int off, int len) throws IOException
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.
text
- Text to be writtenoff
- Starting offset (zero-relative)len
- Number of characters to be writtenIndexOutOfBoundsException
- if the calculated starting or
ending position is outside the bounds of the character arrayIOException
- if an input/output error occursNullPointerException
- if text
is null
public abstract ResponseWriter cloneWithWriter(Writer writer)
Create and return a new instance of this ResponseWriter
,
using the specified Writer
as the output destination.
writer
- The Writer
that is the output destinationResponseWriter
Copyright © 2019 Eclipse Foundation.
Use is subject to license terms.