Package org.restlet.ext.xml

Class XmlRepresentation

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

    • Field Summary

      Fields 
      Modifier and Type Field 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 Description
      XmlRepresentation​(org.restlet.data.MediaType mediaType)
      Constructor.
      XmlRepresentation​(org.restlet.data.MediaType mediaType, long expectedSize)
      Constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Boolean getBoolean​(java.lang.String expression)
      Evaluates an XPath expression as a boolean.
      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.
      javax.xml.transform.dom.DOMSource getDomSource()
      Returns a DOM source.
      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)
      {@inheritDoc javax.xml.namespace.NamespaceContext#getNamespaceURI(java.lang.String}
      org.w3c.dom.Node getNode​(java.lang.String expression)
      Evaluates an XPath expression as a DOM Node.
      NodeList getNodes​(java.lang.String expression)
      Evaluates an XPath expression as a DOM NodeList.
      java.lang.Double getNumber​(java.lang.String expression)
      Evaluates an XPath expression as a number.
      java.lang.String getPrefix​(java.lang.String namespaceURI)
      {@inheritDoc javax.xml.namespace.NamespaceContext#getPrefix(java.lang.String}
      java.util.Iterator<java.lang.String> getPrefixes​(java.lang.String namespaceURI)
      {@inheritDoc javax.xml.namespace.NamespaceContext#getPrefixes(java.lang.String}
      javax.xml.transform.sax.SAXSource getSaxSource()
      Returns a SAX source.
      static javax.xml.transform.sax.SAXSource getSaxSource​(org.restlet.representation.Representation xmlRepresentation)
      Returns a SAX source.
      javax.xml.validation.Schema getSchema()
      Return the possibly null Schema to use for this type of XML representations.
      javax.xml.transform.stream.StreamSource getStreamSource()
      Returns a stream of XML markup.
      java.lang.String getText​(java.lang.String expression)
      Evaluates an XPath expression as a string.
      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 setSchema​(javax.xml.validation.Schema schema)
      Set a (compiled) Schema to use when parsing and validating this type of XML representations.
      void setSchema​(org.restlet.representation.Representation schemaRepresentation)
      Set a schema representation to be compiled and used when parsing and validating this type of XML representations.
      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.
      void validate​(javax.xml.validation.Schema schema)
      Validates the XML representation against a given schema.
      void validate​(javax.xml.validation.Schema schema, javax.xml.transform.Result result)
      Validates the XML representation against a given schema.
      void validate​(org.restlet.representation.Representation schemaRepresentation)
      Validates the XML representation against a given schema.
      void validate​(org.restlet.representation.Representation schemaRepresentation, javax.xml.transform.Result result)
      Validates the XML representation against a given schema.

      • 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​(org.restlet.data.MediaType mediaType)
        Constructor.
        Parameters:
        mediaType - The representation's mediaType.

      • XmlRepresentation

        public XmlRepresentation​(org.restlet.data.MediaType mediaType,
                         long expectedSize)
        Constructor.
        Parameters:
        mediaType - The representation's mediaType.
        expectedSize - The expected input stream size.

    • Method Detail

      • getSaxSource

        public static javax.xml.transform.sax.SAXSource getSaxSource​(org.restlet.representation.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

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

      • 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 org.restlet.representation.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​(org.restlet.representation.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​(org.restlet.representation.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​(org.restlet.representation.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