org.restlet.ext.xml
Class XmlRepresentation

java.lang.Object
  extended by org.restlet.representation.Variant
      extended by org.restlet.representation.RepresentationInfo
          extended by org.restlet.representation.Representation
              extended by org.restlet.representation.CharacterRepresentation
                  extended by org.restlet.representation.WriterRepresentation
                      extended by org.restlet.ext.xml.XmlRepresentation
All Implemented Interfaces:
NamespaceContext
Direct Known Subclasses:
DomRepresentation, SaxRepresentation

public abstract class XmlRepresentation
extends WriterRepresentation
implements 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.

Author:
Jerome Louvel

Field Summary
 
Fields inherited from class org.restlet.representation.Representation
UNKNOWN_SIZE
 
Constructor Summary
XmlRepresentation(MediaType mediaType)
          Constructor.
XmlRepresentation(MediaType mediaType, long expectedSize)
          Constructor.
 
Method Summary
 Object evaluate(String expression, QName returnType)
          Deprecated. Use the getBoolean(String), getNumber(String), getText(String), getNode(String) and getNodes(String) methods instead.
 Boolean getBoolean(String expression)
          Evaluates an XPath expression as a boolean.
protected  Document getDocument()
          Returns the XML representation as a DOM document.
protected  DocumentBuilder getDocumentBuilder()
          Returns a document builder properly configured.
 DOMSource getDomSource()
          Returns a DOM source.
 EntityResolver getEntityResolver()
          Return the possibly null current SAX EntityResolver.
 ErrorHandler getErrorHandler()
          Return the possibly null current SAX ErrorHandler.
abstract  InputSource getInputSource()
          Returns the XML representation as a SAX input source.
 Map<String,String> getNamespaces()
          Returns the map of namespaces.
 String getNamespaceURI(String prefix)
          
 Node getNode(String expression)
          Evaluates an XPath expression as a DOM Node.
 NodeList getNodes(String expression)
          Evaluates an XPath expression as a DOM NodeList.
 Double getNumber(String expression)
          Evaluates an XPath expression as a number.
 String getPrefix(String namespaceURI)
          
 Iterator<String> getPrefixes(String namespaceURI)
          
 SAXSource getSaxSource()
          Returns a SAX source.
static SAXSource getSaxSource(Representation xmlRepresentation)
          Returns a SAX source.
 Schema getSchema()
          Return the possibly null Schema to use for this type of XML representations.
 StreamSource getStreamSource()
          Returns a stream of XML markup.
 String getText(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(EntityResolver entityResolver)
          Set the EntityResolver to use when resolving external entity references encountered in this type of XML representations.
 void setErrorHandler(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(Map<String,String> namespaces)
          Sets the map of namespaces.
 void setSchema(Representation schemaRepresentation)
          Set a schema representation to be compiled and used when parsing and validating this type of XML representations.
 void setSchema(Schema schema)
          Set a (compiled) Schema to use 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(Representation schemaRepresentation)
          Validates the XML representation against a given schema.
 void validate(Representation schemaRepresentation, Result result)
          Validates the XML representation against a given schema.
 void validate(Schema schema)
          Validates the XML representation against a given schema.
 void validate(Schema schema, 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, includes, isCompatible, setCharacterSet, setEncodings, setLanguages, setLocationRef, setLocationRef, setMediaType, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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

getSaxSource

public static SAXSource getSaxSource(Representation xmlRepresentation)
                              throws IOException
Returns a SAX source.

Parameters:
xmlRepresentation - The XML representation to wrap.
Returns:
A SAX source.
Throws:
IOException

evaluate

@Deprecated
public Object evaluate(String expression,
                                  QName returnType)
                throws Exception
Deprecated. Use the getBoolean(String), getNumber(String), getText(String), getNode(String) and getNodes(String) methods instead.

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.
Throws:
Exception
See Also:
XPathException, XPathConstants

getBoolean

public Boolean getBoolean(String expression)
Evaluates an XPath expression as a boolean. If the evaluation fails, null will be returned.

Returns:
The evaluation result.

getDocument

protected Document getDocument()
                        throws Exception
Returns the XML representation as a DOM document.

Returns:
The DOM document.
Throws:
Exception

getDocumentBuilder

protected DocumentBuilder getDocumentBuilder()
                                      throws IOException
Returns a document builder properly configured.

Returns:
A document builder properly configured.
Throws:
IOException

getDomSource

public DOMSource getDomSource()
                       throws IOException
Returns a DOM source.

Returns:
A DOM source.
Throws:
IOException

getEntityResolver

public EntityResolver getEntityResolver()
Return the possibly null current SAX EntityResolver.

Returns:
The possibly null current SAX EntityResolver.

getErrorHandler

public ErrorHandler getErrorHandler()
Return the possibly null current SAX ErrorHandler.

Returns:
The possibly null current SAX ErrorHandler.

getInputSource

public abstract InputSource getInputSource()
                                    throws IOException
Returns the XML representation as a SAX input source.

Returns:
The SAX input source.
Throws:
IOException

getNamespaces

public Map<String,String> getNamespaces()
Returns the map of namespaces. Namespace prefixes are keys and URI references are values.

Returns:
The map of namespaces.

getNamespaceURI

public String getNamespaceURI(String prefix)

Specified by:
getNamespaceURI in interface NamespaceContext

getNode

public Node getNode(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(String expression)
Evaluates an XPath expression as a DOM NodeList. If the evaluation fails, null will be returned.

Returns:
The evaluation result.

getNumber

public Double getNumber(String expression)
Evaluates an XPath expression as a number. If the evaluation fails, null will be returned.

Returns:
The evaluation result.

getPrefix

public String getPrefix(String namespaceURI)

Specified by:
getPrefix in interface NamespaceContext

getPrefixes

public Iterator<String> getPrefixes(String namespaceURI)

Specified by:
getPrefixes in interface NamespaceContext

getSaxSource

public SAXSource getSaxSource()
                       throws IOException
Returns a SAX source.

Returns:
A SAX source.
Throws:
IOException

getSchema

public 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 StreamSource getStreamSource()
                             throws IOException
Returns a stream of XML markup.

Returns:
A stream of XML markup.
Throws:
IOException

getText

public String getText(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 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(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(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(Map<String,String> namespaces)
Sets the map of namespaces.

Parameters:
namespaces - The map of namespaces.

setSchema

public void setSchema(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(Schema schema)
              throws Exception
Validates the XML representation against a given schema.

Parameters:
schema - The XML schema to use.
Throws:
Exception

validate

public void validate(Schema schema,
                     Result result)
              throws 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:
Exception

validate

public void validate(Representation schemaRepresentation)
              throws Exception
Validates the XML representation against a given schema.

Parameters:
schemaRepresentation - The XML schema representation to use.
Throws:
Exception

validate

public void validate(Representation schemaRepresentation,
                     Result result)
              throws 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:
Exception


Copyright © 2005-2013 Restlet.