org.restlet.ext.xml

Class XmlRepresentation

java.lang.Object

org.restlet.representation.Variant

org.restlet.representation.RepresentationInfo

org.restlet.representation.Representation

org.restlet.representation.CharacterRepresentation

org.restlet.representation.WriterRepresentation

org.restlet.ext.xml.XmlRepresentation

Direct Known Subclasses:

DomRepresentation, SaxRepresentation

public abstract class XmlRepresentation
extends WriterRepresentation

Representation based on an XML document. It knows how to evaluate XPath expressions and how to manage a namespace context. This class also offers convenient methods to validate the document against a specified XML scheme.

SECURITY WARNING: Using XML parsers configured to not prevent nor limit document type definition (DTD) entity resolution can expose the parser to an XML Entity Expansion injection attack.

Author:

Jerome Louvel

See Also:

XML Entity Expansion injection attack

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	XML_EXPANDING_ENTITY_REFS True for expanding entity references when parsing XML representations; default value provided by system property "org.restlet.ext.xml.expandingEntityRefs", false by default.
static boolean	XML_VALIDATING_DTD True for validating DTD documents when parsing XML representations; default value provided by system property "org.restlet.ext.xml.validatingDtd", false by default.

Fields inherited from class org.restlet.representation.Representation

UNKNOWN_SIZE

Constructor Summary

Constructors

Constructor and Description
XmlRepresentation(MediaType mediaType) Constructor.
XmlRepresentation(MediaType mediaType, long expectedSize) Constructor.

Method Summary

Modifier and Type	Method and Description
protected org.w3c.dom.Document	getDocument() Returns the XML representation as a DOM document.
protected javax.xml.parsers.DocumentBuilder	getDocumentBuilder() Returns a document builder properly configured.
org.xml.sax.EntityResolver	getEntityResolver() Return the possibly null current SAX EntityResolver.
org.xml.sax.ErrorHandler	getErrorHandler() Return the possibly null current SAX ErrorHandler.
abstract org.xml.sax.InputSource	getInputSource() Returns the XML representation as a SAX input source.
java.util.Map<java.lang.String,java.lang.String>	getNamespaces() Returns the map of namespaces.
java.lang.String	getNamespaceURI(java.lang.String prefix)
java.lang.String	getPrefix(java.lang.String namespaceURI)
java.util.Iterator<java.lang.String>	getPrefixes(java.lang.String namespaceURI)
static java.lang.String	getTextContent(org.w3c.dom.Node node) Returns the text content of a given node and its descendants.
boolean	isCoalescing() Indicates if the parser should be coalescing text.
boolean	isExpandingEntityRefs() Indicates if the parser will expand entity reference nodes.
boolean	isIgnoringComments() Indicates if the parser will ignore comments.
boolean	isIgnoringExtraWhitespaces() Indicates if the parser will ignore extra white spaces in element content.
boolean	isNamespaceAware() Indicates if processing is namespace aware.
boolean	isValidatingDtd() Indicates the desire for validating this type of XML representations against an XML schema if one is referenced within the contents.
boolean	isXIncludeAware() Indicates the desire for processing XInclude if found in this type of XML representations.
void	release() Releases the namespaces map.
void	setCoalescing(boolean coalescing) Indicates if the parser should be coalescing text.
void	setEntityResolver(org.xml.sax.EntityResolver entityResolver) Set the EntityResolver to use when resolving external entity references encountered in this type of XML representations.
void	setErrorHandler(org.xml.sax.ErrorHandler errorHandler) Set the ErrorHandler to use when signaling SAX event exceptions.
void	setExpandingEntityRefs(boolean expandEntityRefs) Indicates if the parser will expand entity reference nodes.
void	setIgnoringComments(boolean ignoringComments) Indicates if the parser will ignore comments.
void	setIgnoringExtraWhitespaces(boolean ignoringExtraWhitespaces) Indicates if the parser will ignore extra white spaces in element content.
void	setNamespaceAware(boolean namespaceAware) Indicates if processing is namespace aware.
void	setNamespaces(java.util.Map<java.lang.String,java.lang.String> namespaces) Sets the map of namespaces.
void	setValidatingDtd(boolean validating) Indicates the desire for validating this type of XML representations against an XML schema if one is referenced within the contents.
void	setXIncludeAware(boolean includeAware) Indicates the desire for processing XInclude if found in this type of XML representations.

Methods inherited from class org.restlet.representation.WriterRepresentation

getReader

Methods inherited from class org.restlet.representation.CharacterRepresentation

getChannel, getStream, write, write

Methods inherited from class org.restlet.representation.Representation

append, exhaust, getAvailableSize, getDigest, getDisposition, getExpirationDate, getRange, getRegistration, getSize, getText, hasKnownSize, isAvailable, isEmpty, isSelectable, isTransient, setAvailable, setDigest, setDisposition, setExpirationDate, setListener, setRange, setSize, setTransient, write

Methods inherited from class org.restlet.representation.RepresentationInfo

getModificationDate, getTag, setModificationDate, setTag

Methods inherited from class org.restlet.representation.Variant

createClientInfo, equals, getCharacterSet, getEncodings, getLanguages, getLocationRef, getMediaType, hashCode, includes, isCompatible, setCharacterSet, setEncodings, setLanguages, setLocationRef, setLocationRef, setMediaType, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

XML_EXPANDING_ENTITY_REFS

public static final boolean XML_EXPANDING_ENTITY_REFS

True for expanding entity references when parsing XML representations; default value provided by system property "org.restlet.ext.xml.expandingEntityRefs", false by default.

XML_VALIDATING_DTD

public static final boolean XML_VALIDATING_DTD

True for validating DTD documents when parsing XML representations; default value provided by system property "org.restlet.ext.xml.validatingDtd", false by default.

Constructor Detail

XmlRepresentation

public XmlRepresentation(MediaType mediaType)

Constructor.

Parameters:

mediaType - The representation's mediaType.

XmlRepresentation

public XmlRepresentation(MediaType mediaType,
                         long expectedSize)

Constructor.

Parameters:

mediaType - The representation's mediaType.

expectedSize - The expected input stream size.

Method Detail

getTextContent

public static java.lang.String getTextContent(org.w3c.dom.Node node)

Returns the text content of a given node and its descendants.

Parameters:

node - The node.

Returns:

The text content of a given node.

getDocument

protected org.w3c.dom.Document getDocument()
                                    throws java.lang.Exception

Returns the XML representation as a DOM document.

Returns:

The DOM document.

Throws:

java.lang.Exception

getDocumentBuilder

protected javax.xml.parsers.DocumentBuilder getDocumentBuilder()
                                                        throws java.io.IOException

Returns a document builder properly configured.

Returns:

A document builder properly configured.

Throws:

java.io.IOException

getEntityResolver

public org.xml.sax.EntityResolver getEntityResolver()

Return the possibly null current SAX EntityResolver.

Returns:

The possibly null current SAX EntityResolver.

getErrorHandler

public org.xml.sax.ErrorHandler getErrorHandler()

Return the possibly null current SAX ErrorHandler.

Returns:

The possibly null current SAX ErrorHandler.

getInputSource

public abstract org.xml.sax.InputSource getInputSource()
                                                throws java.io.IOException

Returns the XML representation as a SAX input source.

Returns:

The SAX input source.

Throws:

java.io.IOException

getNamespaces

public java.util.Map<java.lang.String,java.lang.String> getNamespaces()

Returns the map of namespaces. Namespace prefixes are keys and URI references are values.

Returns:

The map of namespaces.

getNamespaceURI

public java.lang.String getNamespaceURI(java.lang.String prefix)

getPrefix

public java.lang.String getPrefix(java.lang.String namespaceURI)

getPrefixes

public java.util.Iterator<java.lang.String> getPrefixes(java.lang.String namespaceURI)

isCoalescing

public boolean isCoalescing()

Indicates if the parser should be coalescing text. If true the parser will convert CDATA nodes to text nodes and append it to the adjacent (if any) text node. By default the value of this is set to false.

Returns:

True if parser should be coalescing text.

isExpandingEntityRefs

public boolean isExpandingEntityRefs()

Indicates if the parser will expand entity reference nodes. By default the value of this is set to true.

Returns:

True if the parser will expand entity reference nodes.

isIgnoringComments

public boolean isIgnoringComments()

Indicates if the parser will ignore comments. By default the value of this is set to false.

Returns:

True if the parser will ignore comments.

isIgnoringExtraWhitespaces

public boolean isIgnoringExtraWhitespaces()

Indicates if the parser will ignore extra white spaces in element content. Note that the isValidatingDtd() must be true when this property is 'true' as validation is needed for it to work. By default the value of this is set to false.

Returns:

True if the parser will ignore extra white spaces.

isNamespaceAware

public boolean isNamespaceAware()

Indicates if processing is namespace aware.

Returns:

True if processing is namespace aware.

isValidatingDtd

public boolean isValidatingDtd()

Indicates the desire for validating this type of XML representations against an XML schema if one is referenced within the contents.

Returns:

True if the schema-based validation is enabled.

isXIncludeAware

public boolean isXIncludeAware()

Indicates the desire for processing XInclude if found in this type of XML representations. By default the value of this is set to false.

Returns:

The current value of the xIncludeAware flag.

release

public void release()

Releases the namespaces map.

Overrides:

release in class Representation

setCoalescing

public void setCoalescing(boolean coalescing)

Indicates if the parser should be coalescing text. If true the parser will convert CDATA nodes to text nodes and append it to the adjacent (if any) text node. By default the value of this is set to false.

Parameters:

coalescing - True if parser should be coalescing text.

setEntityResolver

public void setEntityResolver(org.xml.sax.EntityResolver entityResolver)

Set the EntityResolver to use when resolving external entity references encountered in this type of XML representations.

Parameters:

entityResolver - the EntityResolver to set.

setErrorHandler

public void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)

Set the ErrorHandler to use when signaling SAX event exceptions.

Parameters:

errorHandler - the ErrorHandler to set.

setExpandingEntityRefs

public void setExpandingEntityRefs(boolean expandEntityRefs)

Indicates if the parser will expand entity reference nodes. By default the value of this is set to true.

Parameters:

expandEntityRefs - True if the parser will expand entity reference nodes.

setIgnoringComments

public void setIgnoringComments(boolean ignoringComments)

Indicates if the parser will ignore comments. By default the value of this is set to false.

Parameters:

ignoringComments - True if the parser will ignore comments.

setIgnoringExtraWhitespaces

public void setIgnoringExtraWhitespaces(boolean ignoringExtraWhitespaces)

Indicates if the parser will ignore extra white spaces in element content. Note that the setValidatingDtd(boolean) will be invoked with 'true' if setting this property to 'true' as validation is needed for it to work.

Parameters:

ignoringExtraWhitespaces - True if the parser will ignore extra white spaces in element content.

setNamespaceAware

public void setNamespaceAware(boolean namespaceAware)

Indicates if processing is namespace aware.

Parameters:

namespaceAware - Indicates if processing is namespace aware.

setNamespaces

public void setNamespaces(java.util.Map<java.lang.String,java.lang.String> namespaces)

Sets the map of namespaces.

Parameters:

namespaces - The map of namespaces.

setValidatingDtd

public void setValidatingDtd(boolean validating)

Indicates the desire for validating this type of XML representations against an XML schema if one is referenced within the contents.

Parameters:

validating - The new validation flag to set.

setXIncludeAware

public void setXIncludeAware(boolean includeAware)

Indicates the desire for processing XInclude if found in this type of XML representations. By default the value of this is set to false.

Parameters:

includeAware - The new value of the xIncludeAware flag.