Package org.restlet.ext.xml

Class XmlRepresentation

  • All Implemented Interfaces:
    javax.xml.namespace.NamespaceContext
    Direct Known Subclasses:
    DomRepresentation, SaxRepresentation
    public abstract class XmlRepresentation
extends WriterRepresentation
implements javax.xml.namespace.NamespaceContext
    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.
    See Also:
    XML Entity Expansion injection attack

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private boolean coalescing
      Specifies that the parser will convert CDATA nodes to text nodes and append it to the adjacent (if any) text node.
      private org.xml.sax.EntityResolver entityResolver
      A SAX EntityResolver to use when resolving external entity references while parsing this type of XML representations.
      private org.xml.sax.ErrorHandler errorHandler
      A SAX ErrorHandler to use for signaling SAX exceptions while parsing this type of XML representations.
      private boolean expandingEntityRefs
      Specifies that the parser will expand entity reference nodes.
      private boolean ignoringComments
      Indicates if the parser will ignore comments.
      private boolean ignoringExtraWhitespaces
      Indicates if the parser will ignore extra white spaces in element content.
      private boolean namespaceAware
      Indicates if processing is namespace aware.
      private java.util.Map<java.lang.String,​java.lang.String> namespaces
      Internal map of namespaces.
      private javax.xml.validation.Schema schema
      A (compiled) Schema to use when validating this type of XML representations.
      private boolean validatingDtd
      Indicates the desire for validating this type of XML representations against a DTD.
      private boolean xIncludeAware
      Indicates the desire for processing XInclude if found in this type of XML representations.
      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.

    • 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.

      • coalescing

        private volatile boolean coalescing
        Specifies that 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.

      • entityResolver

        private volatile org.xml.sax.EntityResolver entityResolver
        A SAX EntityResolver to use when resolving external entity references while parsing this type of XML representations.
        See Also:
        DocumentBuilder.setEntityResolver(EntityResolver)

      • errorHandler

        private volatile org.xml.sax.ErrorHandler errorHandler
        A SAX ErrorHandler to use for signaling SAX exceptions while parsing this type of XML representations.
        See Also:
        DocumentBuilder.setErrorHandler(ErrorHandler)

      • expandingEntityRefs

        private volatile boolean expandingEntityRefs
        Specifies that the parser will expand entity reference nodes. By default the value of this is set to true.

      • ignoringComments

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

      • ignoringExtraWhitespaces

        private volatile boolean ignoringExtraWhitespaces
        Indicates if the parser will ignore extra white spaces in element content. By default the value of this is set to false.

      • namespaceAware

        private volatile boolean namespaceAware
        Indicates if processing is namespace aware.

      • namespaces

        private volatile java.util.Map<java.lang.String,​java.lang.String> namespaces
        Internal map of namespaces.

      • schema

        private volatile javax.xml.validation.Schema schema
        A (compiled) Schema to use when validating this type of XML representations.
        See Also:
        DocumentBuilderFactory.setSchema(javax.xml.validation.Schema)

      • validatingDtd

        private volatile boolean validatingDtd
        Indicates the desire for validating this type of XML representations against a DTD. Note that for XML schema or Relax NG validation, use the "schema" property instead.
        See Also:
        DocumentBuilderFactory.setValidating(boolean)

      • xIncludeAware

        private volatile boolean xIncludeAware
        Indicates the desire for processing XInclude if found in this type of XML representations. By default the value of this is set to false.
        See Also:
        DocumentBuilderFactory.setXIncludeAware(boolean)

    • 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

      • appendTextContent

        private static void appendTextContent​(org.w3c.dom.Node node,
                                      java.lang.StringBuilder sb)
        Appends the text content of a given node and its descendants to the given buffer.
        Parameters:
        node - The node.
        sb - The buffer.

      • getSaxSource

        public static javax.xml.transform.sax.SAXSource getSaxSource​(Representation xmlRepresentation)
                                                      throws java.io.IOException
        Returns a SAX source.
        Parameters:
        xmlRepresentation - The XML representation to wrap.
        Returns:
        A SAX source.
        Throws:
        java.io.IOException

      • getSchema

        private static javax.xml.validation.Schema getSchema​(Representation schemaRepresentation)
                                              throws java.lang.Exception
        Returns the wrapped schema.
        Returns:
        The wrapped schema.
        Throws:
        java.io.IOException
        java.lang.Exception

      • getSchemaLanguageUri

        private static java.lang.String getSchemaLanguageUri​(Representation schemaRepresentation)
        Returns the schema URI for the current schema media type.
        Returns:
        The schema URI.

      • 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.

      • getBoolean

        public java.lang.Boolean getBoolean​(java.lang.String expression)
        Evaluates an XPath expression as a boolean. If the evaluation fails, null will be returned.
        Returns:
        The evaluation result.

      • 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

      • getDomSource

        public javax.xml.transform.dom.DOMSource getDomSource()
                                               throws java.io.IOException
        Returns a DOM source.
        Returns:
        A DOM source.
        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)
        {@inheritDoc javax.xml.namespace.NamespaceContext#getNamespaceURI(java.lang.String}
        Specified by:
        getNamespaceURI in interface javax.xml.namespace.NamespaceContext

      • getNode

        public org.w3c.dom.Node getNode​(java.lang.String expression)
        Evaluates an XPath expression as a DOM Node. If the evaluation fails, null will be returned.
        Returns:
        The evaluation result.

      • getNodes

        public NodeList getNodes​(java.lang.String expression)
        Evaluates an XPath expression as a DOM NodeList. If the evaluation fails, null will be returned.
        Returns:
        The evaluation result.

      • getNumber

        public java.lang.Double getNumber​(java.lang.String expression)
        Evaluates an XPath expression as a number. If the evaluation fails, null will be returned.
        Returns:
        The evaluation result.

      • getPrefix

        public java.lang.String getPrefix​(java.lang.String namespaceURI)
        {@inheritDoc javax.xml.namespace.NamespaceContext#getPrefix(java.lang.String}
        Specified by:
        getPrefix in interface javax.xml.namespace.NamespaceContext

      • getPrefixes

        public java.util.Iterator<java.lang.String> getPrefixes​(java.lang.String namespaceURI)
        {@inheritDoc javax.xml.namespace.NamespaceContext#getPrefixes(java.lang.String}
        Specified by:
        getPrefixes in interface javax.xml.namespace.NamespaceContext

      • getSaxSource

        public javax.xml.transform.sax.SAXSource getSaxSource()
                                               throws java.io.IOException
        Returns a SAX source.
        Returns:
        A SAX source.
        Throws:
        java.io.IOException

      • getSchema

        public javax.xml.validation.Schema getSchema()
        Return the possibly null Schema to use for this type of XML representations.
        Returns:
        the Schema object of this type of XML representations.

      • getStreamSource

        public javax.xml.transform.stream.StreamSource getStreamSource()
                                                        throws java.io.IOException
        Returns a stream of XML markup.
        Returns:
        A stream of XML markup.
        Throws:
        java.io.IOException

      • getText

        public java.lang.String getText​(java.lang.String expression)
        Evaluates an XPath expression as a string.
        Returns:
        The evaluation result.

      • internalEval

        private java.lang.Object internalEval​(java.lang.String expression,
                                      javax.xml.namespace.QName returnType)
        Evaluates an XPath expression and returns the result as in the given return type.
        Parameters:
        returnType - The qualified name of the return type.
        Returns:
        The evaluation result.

      • 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.

      • setSchema

        public void setSchema​(javax.xml.validation.Schema schema)
        Set a (compiled) Schema to use when parsing and validating this type of XML representations.
        Parameters:
        schema - The (compiled) Schema object to set.

      • setSchema

        public void setSchema​(Representation schemaRepresentation)
        Set a schema representation to be compiled and used when parsing and validating this type of XML representations.
        Parameters:
        schemaRepresentation - The schema representation to set.

      • 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.

      • validate

        public void validate​(javax.xml.validation.Schema schema)
              throws java.lang.Exception
        Validates the XML representation against a given schema.
        Parameters:
        schema - The XML schema to use.
        Throws:
        java.lang.Exception

      • validate

        public void validate​(javax.xml.validation.Schema schema,
                     javax.xml.transform.Result result)
              throws java.lang.Exception
        Validates the XML representation against a given schema.
        Parameters:
        schema - The XML schema to use.
        result - The Result object that receives (possibly augmented) XML.
        Throws:
        java.lang.Exception

      • validate

        public void validate​(Representation schemaRepresentation)
              throws java.lang.Exception
        Validates the XML representation against a given schema.
        Parameters:
        schemaRepresentation - The XML schema representation to use.
        Throws:
        java.lang.Exception

      • validate

        public void validate​(Representation schemaRepresentation,
                     javax.xml.transform.Result result)
              throws java.lang.Exception
        Validates the XML representation against a given schema.
        Parameters:
        schemaRepresentation - The XML schema representation to use.
        result - The Result object that receives (possibly augmented) XML.
        Throws:
        java.lang.Exception