org.modeshape.graph.xml
Class XmlHandler

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      org.xml.sax.ext.DefaultHandler2
          org.modeshape.graph.xml.XmlHandler

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler, DeclHandler, EntityResolver2, LexicalHandler

@NotThreadSafe
public class XmlHandler
extends DefaultHandler2

A DefaultHandler2 specialization that responds to XML content events by creating the corresponding content in the supplied graph. This implementation ignores DTD entities, XML contents, and other XML processing instructions. If other behavior is required, the appropriate methods can be overridden. (Which is why this class extends DefaultHandler2, which has support for processing all the different parts of XML.

This class can be passed to the SAXParser's parse(..,DefaultHandler) methods.

Nested Class Summary

static class	XmlHandler.AttributeScoping The choices for how attributes that have no namespace prefix should be assigned a namespace.
protected static class	XmlHandler.ElementEntryState Possible states for an ElementEntry instance.

Field Summary

protected Path	currentPath The path for the node representing the current element.
protected TextDecoder	decoder The TextDecoder that is used to decode the names.
static XmlHandler.AttributeScoping	DEFAULT_ATTRIBUTE_SCOPING The default XmlHandler.AttributeScoping.
static TextDecoder	DEFAULT_DECODER Decoder for XML names, to turn '_xHHHH_' sequences in the XML element and attribute names into the corresponding UTF-16 characters.
protected Destination	destination The destination where the content should be sent.
protected Name	nameAttribute The name of the XML attribute whose value should be used for the name of the node.
protected NameFactory	nameFactory The cached reference to the graph's name factory.
protected NamespaceRegistry	namespaceRegistry The cached reference to the graph's namespace registry.
protected PathFactory	pathFactory The cached reference to the graph's path factory.
protected List<Property>	properties A temporary list used to store the properties for a single node.
protected PropertyFactory	propertyFactory The cached reference to the graph's property factory.
protected Object[]	propertyValues A working array that contains a single value object that is used to create Property objects (without having to create an array of values for each property).
protected boolean	skipFirstElement Flag the records whether the first element should be skipped.
protected Name	typeAttribute The name of the property that is to be set with the type of the XML element.
protected Name	typeAttributeValue The value of the node type property, if the node's name is set with the nameAttribute.

Constructor Summary

XmlHandler(Destination destination, boolean skipRootElement, Path parent, TextDecoder textDecoder, Name nameAttribute, Name typeAttribute, Name typeAttributeValue, XmlHandler.AttributeScoping scoping)
Create a handler that creates content in the supplied graph

Method Summary

void	characters(char[] ch, int start, int length)
protected Property	createProperty(Name propertyName, Collection<Object> values) Create a property with the given name and values, obtained from an attribute name and value in the XML content.
protected Property	createProperty(Name propertyName, Object value) Create a property with the given name and value, obtained from an attribute name and value in the XML content.
void	endDocument()
void	endElement(String uri, String localName, String name)
void	endPrefixMapping(String prefix)
void	startElement(String uri, String localName, String name, Attributes attributes)
void	startPrefixMapping(String prefix, String uri) This method ensures that the namespace is registered with the registry, using the supplied prefix to register the namespace if required.

Methods inherited from class org.xml.sax.ext.DefaultHandler2

attributeDecl, comment, elementDecl, endCDATA, endDTD, endEntity, externalEntityDecl, getExternalSubset, internalEntityDecl, resolveEntity, resolveEntity, startCDATA, startDTD, startEntity

Methods inherited from class org.xml.sax.helpers.DefaultHandler

error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, setDocumentLocator, skippedEntity, startDocument, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_DECODER

public static TextDecoder DEFAULT_DECODER

Decoder for XML names, to turn '_xHHHH_' sequences in the XML element and attribute names into the corresponding UTF-16 characters.

DEFAULT_ATTRIBUTE_SCOPING

public static XmlHandler.AttributeScoping DEFAULT_ATTRIBUTE_SCOPING

The default XmlHandler.AttributeScoping.

destination

protected final Destination destination

The destination where the content should be sent.

nameAttribute

protected final Name nameAttribute

The name of the XML attribute whose value should be used for the name of the node. For example, "jcr:name".

typeAttribute

protected final Name typeAttribute

The name of the property that is to be set with the type of the XML element. For example, "jcr:name".

typeAttributeValue

protected final Name typeAttributeValue

The value of the node type property, if the node's name is set with the nameAttribute.

pathFactory

protected final PathFactory pathFactory

The cached reference to the graph's path factory.

nameFactory

protected final NameFactory nameFactory

The cached reference to the graph's name factory.

propertyFactory

protected final PropertyFactory propertyFactory

The cached reference to the graph's property factory.

namespaceRegistry

protected final NamespaceRegistry namespaceRegistry

The cached reference to the graph's namespace registry.

decoder

protected final TextDecoder decoder

The TextDecoder that is used to decode the names.

currentPath

protected Path currentPath

The path for the node representing the current element. This starts out as the path supplied by the constructor, and never is shorter than that initial path.

skipFirstElement

protected boolean skipFirstElement

Flag the records whether the first element should be skipped.

properties

protected final List<Property> properties

A temporary list used to store the properties for a single node. This is cleared, populated, then used to create the node.

propertyValues

protected final Object[] propertyValues

A working array that contains a single value object that is used to create Property objects (without having to create an array of values for each property).

Constructor Detail

XmlHandler

public XmlHandler(Destination destination,
                  boolean skipRootElement,
                  Path parent,
                  TextDecoder textDecoder,
                  Name nameAttribute,
                  Name typeAttribute,
                  Name typeAttributeValue,
                  XmlHandler.AttributeScoping scoping)

Create a handler that creates content in the supplied graph

Parameters:

destination - the destination where the content should be sent.graph in which the content should be placed

skipRootElement - true if the root element of the document should be skipped, or false if the root element should be converted to the top-level node of the content

parent - the path to the node in the graph under which the content should be placed; if null, the root node is assumed

textDecoder - the text decoder that should be used to decode the XML element names and XML attribute names, prior to using those values to create names; or null if the default encoder should be used

nameAttribute - the name of the property whose value should be used for the names of the nodes (typically, this is "jcr:name" or something equivalent); or null if the XML element name should always be used as the node name

typeAttribute - the name of the property that should be set with the type of the XML element, or null if there is no such property

typeAttributeValue - the value of the type property that should be used if the node has no nameAttribute, or null if the value should be set to the type of the XML element

scoping - defines how to choose the namespace of attributes that do not have a namespace prefix; if null, the DEFAULT_ATTRIBUTE_SCOPING value is used

Throws:

IllegalArgumentException - if the destination reference is null

Method Detail

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)

This method ensures that the namespace is registered with the registry, using the supplied prefix to register the namespace if required. Note that because this class does not really use the namespace prefixes to create Name objects, no attempt is made to match the XML namespace prefixes.

Specified by:

startPrefixMapping in interface ContentHandler

Overrides:

startPrefixMapping in class DefaultHandler

See Also:

DefaultHandler.startPrefixMapping(java.lang.String, java.lang.String)

endPrefixMapping

public void endPrefixMapping(String prefix)

Specified by:

endPrefixMapping in interface ContentHandler

Overrides:

endPrefixMapping in class DefaultHandler

See Also:

DefaultHandler.endPrefixMapping(java.lang.String)

startElement

public void startElement(String uri,
                         String localName,
                         String name,
                         Attributes attributes)

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class DefaultHandler

See Also:

DefaultHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endElement

public void endElement(String uri,
                       String localName,
                       String name)

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class DefaultHandler

See Also:

DefaultHandler.endElement(java.lang.String, java.lang.String, java.lang.String)

characters

public void characters(char[] ch,
                       int start,
                       int length)

Specified by:

characters in interface ContentHandler

Overrides:

characters in class DefaultHandler

See Also:

DefaultHandler.characters(char[], int, int)

endDocument

public void endDocument()

Specified by:

endDocument in interface ContentHandler

Overrides:

endDocument in class DefaultHandler

See Also:

DefaultHandler.endDocument()

createProperty

protected Property createProperty(Name propertyName,
                                  Object value)

Create a property with the given name and value, obtained from an attribute name and value in the XML content.

By default, this method creates a property by directly using the value as the sole value of the property.

Parameters:

propertyName - the name of the property; never null

value - the attribute value

Returns:

the property; may not be null

createProperty

protected Property createProperty(Name propertyName,
                                  Collection<Object> values)

Create a property with the given name and values, obtained from an attribute name and value in the XML content.

By default, this method creates a property by directly using the values as the values of the property.

Parameters:

propertyName - the name of the property; never null

values - the attribute values

Returns:

the property; may not be null