com.ctc.wstx.sr
Class InputElementStack

java.lang.Object
  extended by com.ctc.wstx.sr.InputElementStack
All Implemented Interfaces:
javax.xml.namespace.NamespaceContext, AttributeInfo, ValidationContext
Direct Known Subclasses:
NonNsInputElementStack, NsInputElementStack

public abstract class InputElementStack
extends java.lang.Object
implements AttributeInfo, javax.xml.namespace.NamespaceContext, ValidationContext

Shared base class that defines API stream reader uses to communicate with the element stack implementation, independent of whether it's operating in namespace-aware or non-namespace modes. Element stack class is used for storing nesting information about open elements, and for namespace-aware mode, also information about namespaces active (including default namespace), during parsing of XML input.

This class also implements NamespaceContext, since it has all the information necessary, so parser can just return element stack instance as necesary.


Field Summary
protected  ReaderConfig mConfig
           
protected  int mIdAttrIndex
          Index of the attribute with type of ID, if known (most likely due to Xml:id support); -1 if not available, or no ID attribute for current element.
protected  InputProblemReporter mReporter
           
protected  XMLValidator mValidator
          Optional validator object that will get called if set, and that can validate xml content.
 
Constructor Summary
protected InputElementStack(ReaderConfig cfg)
           
 
Method Summary
abstract  int addDefaultAttribute(java.lang.String localName, java.lang.String uri, java.lang.String prefix, java.lang.String value)
          Method called by actual validator instances when attributes with default values have no explicit values for the element; if so, default value needs to be added as if it was parsed from the element.
abstract  void addNsBinding(java.lang.String prefix, java.lang.String uri)
           
protected  XMLValidator addValidator(XMLValidator vld)
           
protected  void connectReporter(InputProblemReporter rep)
           
abstract  BaseNsContext createNonTransientNsContext(javax.xml.stream.Location loc)
          Method called to construct a non-transient NamespaceContext instance; generally needed when creating events to return from event-based iterators.
abstract  int findAttributeIndex(java.lang.String nsURI, java.lang.String localName)
           
protected abstract  AttributeCollector getAttrCollector()
          Method called by BasicStreamReader, to retrieve the attribute collector it needs for some direct access.
abstract  int getAttributeCount()
          This method returns number of attributes accessible from within currently active start element.
 java.lang.String getAttributeLocalName(int index)
           
 java.lang.String getAttributeNamespace(int index)
           
 java.lang.String getAttributePrefix(int index)
           
 java.lang.String getAttributeType(int index)
           
 java.lang.String getAttributeValue(int index)
           
 java.lang.String getAttributeValue(java.lang.String nsURI, java.lang.String localName)
           
 java.lang.String getBaseUri()
           
abstract  javax.xml.namespace.QName getCurrentElementName()
          Method that can be used to access name information of the innermost (top) element in the element stack.
abstract  int getCurrentNsCount()
           
abstract  java.lang.String getDefaultNsURI()
           
abstract  int getDepth()
           
 int getIdAttributeIndex()
          Default implementation just indicates it does not know of such attributes; this because that requires DTD information that only some implementations have.
abstract  java.lang.String getLocalName()
           
abstract  java.lang.String getLocalNsPrefix(int index)
           
abstract  java.lang.String getLocalNsURI(int index)
           
abstract  java.lang.String getNamespaceURI(java.lang.String prefix)
          Method that can be called by the validator to resolve a namespace prefix of the currently active top-level element.
 int getNotationAttributeIndex()
          Default implementation just indicates it does not know of such attributes; this because that requires DTD information that only some implementations have.
abstract  java.lang.String getNsURI()
           
abstract  java.lang.String getPrefix()
           
abstract  java.lang.String getPrefix(java.lang.String nsURI)
           
abstract  java.util.Iterator getPrefixes(java.lang.String nsURI)
           
abstract  java.lang.String getTopElementDesc()
           
abstract  int getTotalNsCount()
           
 javax.xml.stream.Location getValidationLocation()
          Method that will return the location that best represents current location within document to be validated, if such information is available.
 java.lang.String getXmlVersion()
          Method that validator can call to figure out which xml version document being validated declared (if none, "1.0" is assumed as per xml specifications 1.0 and 1.1).
abstract  boolean isEmpty()
           
abstract  boolean isNamespaceAware()
           
 boolean isNotationDeclared(java.lang.String name)
           
abstract  boolean isPrefixLocallyDeclared(java.lang.String internedPrefix)
           
 boolean isUnparsedEntityDeclared(java.lang.String name)
           
abstract  boolean matches(java.lang.String prefix, java.lang.String localName)
           
protected  void normalizeXmlIdAttr(AttributeCollector ac, int ix)
          Method called to normalize value of an ID attribute, specified using name xml:id, when support for Xml:id specification enabled.
abstract  int pop()
          Method called by the stream reader to remove the topmost (start) element from the stack; called when an end element is encountered during parsing.
abstract  void push(java.lang.String fullName)
          Method called by the stream reader to add new (start) element into the stack in non-namespace mode; called when a start element is encountered during parsing, but only in non-namespace mode.
abstract  void push(java.lang.String prefix, java.lang.String localName)
          Method called by the stream reader to add new (start) element into the stack in namespace-aware mode; called when a start element is encountered during parsing, but only in ns-aware mode.
protected  boolean reallyValidating()
          This is a method called by the reader to ensure that we have at least one 'real' validator.
 void reportProblem(XMLValidationProblem problem)
          Method called by the validator, upon encountering a validation problem.
abstract  int resolveAndValidateElement()
          Method called to resolve element and attribute namespaces (in namespace-aware mode), and do optional validation using pluggable validator object.
protected abstract  void setAutomaticDTDValidator(XMLValidator validator, NsDefaultProvider nsDefs)
          Method called to connect the automatically handled DTD validator (one detected from DOCTYPE, loaded and completely handled by the stream reader without application calling validation methods).
 XMLValidator stopValidatingAgainst(XMLValidationSchema schema)
           
 XMLValidator stopValidatingAgainst(XMLValidator validator)
           
 XMLValidator validateAgainst(XMLValidationSchema schema)
           
 void validateText(TextBuffer tb, boolean lastTextSegment)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mConfig

protected final ReaderConfig mConfig

mReporter

protected InputProblemReporter mReporter

mValidator

protected XMLValidator mValidator
Optional validator object that will get called if set, and that can validate xml content. Note that it is possible that this is set to a proxy object that calls multiple validators in sequence.


mIdAttrIndex

protected int mIdAttrIndex
Index of the attribute with type of ID, if known (most likely due to Xml:id support); -1 if not available, or no ID attribute for current element.

Constructor Detail

InputElementStack

protected InputElementStack(ReaderConfig cfg)
Method Detail

connectReporter

protected void connectReporter(InputProblemReporter rep)

addValidator

protected XMLValidator addValidator(XMLValidator vld)

setAutomaticDTDValidator

protected abstract void setAutomaticDTDValidator(XMLValidator validator,
                                                 NsDefaultProvider nsDefs)
Method called to connect the automatically handled DTD validator (one detected from DOCTYPE, loaded and completely handled by the stream reader without application calling validation methods). Handled separately, since its behaviour is potentially different from that of explicitly added validators.


validateAgainst

public XMLValidator validateAgainst(XMLValidationSchema schema)
                             throws javax.xml.stream.XMLStreamException
Throws:
javax.xml.stream.XMLStreamException

stopValidatingAgainst

public XMLValidator stopValidatingAgainst(XMLValidationSchema schema)
                                   throws javax.xml.stream.XMLStreamException
Throws:
javax.xml.stream.XMLStreamException

stopValidatingAgainst

public XMLValidator stopValidatingAgainst(XMLValidator validator)
                                   throws javax.xml.stream.XMLStreamException
Throws:
javax.xml.stream.XMLStreamException

reallyValidating

protected boolean reallyValidating()
This is a method called by the reader to ensure that we have at least one 'real' validator. This is only needed to ensure that validation problems that the reader can detect (illegal textual content) can be reported as validity errors. Since the validator API does not have a good way to cleanly deal with such a possibility, the check is rather fragile, but should work for now: essentially we need at least one validator object that either is not a sub-class of DTDValidatorBase or returns true for reallyValidating.

!!! TODO: remove need for this method (and method itself) with Woodstox 4.0, by adding necessary support in Stax2 XMLValidator interface.


getAttrCollector

protected abstract AttributeCollector getAttrCollector()
Method called by BasicStreamReader, to retrieve the attribute collector it needs for some direct access.


createNonTransientNsContext

public abstract BaseNsContext createNonTransientNsContext(javax.xml.stream.Location loc)
Method called to construct a non-transient NamespaceContext instance; generally needed when creating events to return from event-based iterators.


push

public abstract void push(java.lang.String prefix,
                          java.lang.String localName)
Method called by the stream reader to add new (start) element into the stack in namespace-aware mode; called when a start element is encountered during parsing, but only in ns-aware mode.


push

public abstract void push(java.lang.String fullName)
Method called by the stream reader to add new (start) element into the stack in non-namespace mode; called when a start element is encountered during parsing, but only in non-namespace mode.


pop

public abstract int pop()
                 throws javax.xml.stream.XMLStreamException
Method called by the stream reader to remove the topmost (start) element from the stack; called when an end element is encountered during parsing.

Returns:
Validation state that should be effective for the parent element state
Throws:
javax.xml.stream.XMLStreamException

resolveAndValidateElement

public abstract int resolveAndValidateElement()
                                       throws javax.xml.stream.XMLStreamException
Method called to resolve element and attribute namespaces (in namespace-aware mode), and do optional validation using pluggable validator object.

Returns:
Text content validation state that should be effective for the fully resolved element context
Throws:
javax.xml.stream.XMLStreamException

getAttributeCount

public abstract int getAttributeCount()
Description copied from interface: ValidationContext
This method returns number of attributes accessible from within currently active start element.

Note: this method is only guaranteed to be callable during execution of XMLValidator methods XMLValidator.validateElementStart(java.lang.String, java.lang.String, java.lang.String), XMLValidator.validateAttribute(java.lang.String, java.lang.String, java.lang.String, java.lang.String) and XMLValidator.validateElementAndAttributes(). At other times implementations may choose to allow it to be called (for example, with information regarding last start element processed), to throw a IllegalArgumentException, or to return 0 to indicate no attribute information is available.

Also note that whether defaulted attributes (attributes for which values are only available via attribute defaulting) are accessible depends on exact time when this method is called, and in general can not be assumed to function reliably.

Specified by:
getAttributeCount in interface AttributeInfo
Specified by:
getAttributeCount in interface ValidationContext
Returns:
Number of all attributes accessible (including ones created from the default values, if any) using this Object.

findAttributeIndex

public abstract int findAttributeIndex(java.lang.String nsURI,
                                       java.lang.String localName)
Specified by:
findAttributeIndex in interface AttributeInfo
Specified by:
findAttributeIndex in interface ValidationContext
Returns:
Index of the specified attribute, if the current element has such an attribute (explicit, or one created via default value expansion); -1 if not.

getIdAttributeIndex

public final int getIdAttributeIndex()
Default implementation just indicates it does not know of such attributes; this because that requires DTD information that only some implementations have.

Specified by:
getIdAttributeIndex in interface AttributeInfo
Returns:
Index of the ID attribute of current element, if the current element has such an attribute defined; -1 if not.

getNotationAttributeIndex

public final int getNotationAttributeIndex()
Default implementation just indicates it does not know of such attributes; this because that requires DTD information that only some implementations have.

Specified by:
getNotationAttributeIndex in interface AttributeInfo
Returns:
Index of the NOTATION attribute of current element, if the current element has such an attribute defined; -1 if not.

getNamespaceURI

public abstract java.lang.String getNamespaceURI(java.lang.String prefix)
Description copied from interface: ValidationContext
Method that can be called by the validator to resolve a namespace prefix of the currently active top-level element. This may be necessary for things like DTD validators (which may need to heuristically guess proper namespace URI of attributes, esp. ones with default values).

Specified by:
getNamespaceURI in interface javax.xml.namespace.NamespaceContext
Specified by:
getNamespaceURI in interface ValidationContext

getPrefix

public abstract java.lang.String getPrefix(java.lang.String nsURI)
Specified by:
getPrefix in interface javax.xml.namespace.NamespaceContext

getPrefixes

public abstract java.util.Iterator getPrefixes(java.lang.String nsURI)
Specified by:
getPrefixes in interface javax.xml.namespace.NamespaceContext

getXmlVersion

public final java.lang.String getXmlVersion()
Description copied from interface: ValidationContext
Method that validator can call to figure out which xml version document being validated declared (if none, "1.0" is assumed as per xml specifications 1.0 and 1.1).

Specified by:
getXmlVersion in interface ValidationContext
Returns:
Xml version of the document: currently has to be either "1.0" or "1.1".

getAttributeLocalName

public java.lang.String getAttributeLocalName(int index)
Specified by:
getAttributeLocalName in interface ValidationContext

getAttributeNamespace

public java.lang.String getAttributeNamespace(int index)
Specified by:
getAttributeNamespace in interface ValidationContext

getAttributePrefix

public java.lang.String getAttributePrefix(int index)
Specified by:
getAttributePrefix in interface ValidationContext

getAttributeValue

public java.lang.String getAttributeValue(int index)
Specified by:
getAttributeValue in interface ValidationContext

getAttributeValue

public java.lang.String getAttributeValue(java.lang.String nsURI,
                                          java.lang.String localName)
Specified by:
getAttributeValue in interface ValidationContext

isNotationDeclared

public boolean isNotationDeclared(java.lang.String name)
Specified by:
isNotationDeclared in interface ValidationContext
Returns:
True, if a notation with specified name has been declared in the document being validated; false if not.

isUnparsedEntityDeclared

public boolean isUnparsedEntityDeclared(java.lang.String name)
Specified by:
isUnparsedEntityDeclared in interface ValidationContext
Returns:
True, if an unparsed entity with specified name has been declared in the document being validated; false if not.

getBaseUri

public java.lang.String getBaseUri()
Specified by:
getBaseUri in interface ValidationContext
Returns:
Base URI active in the current location of the document being validated, if known; null to indicate no base URI known.

getCurrentElementName

public abstract javax.xml.namespace.QName getCurrentElementName()
Description copied from interface: ValidationContext
Method that can be used to access name information of the innermost (top) element in the element stack.

Specified by:
getCurrentElementName in interface ValidationContext
Returns:
Name of the element at the top of the current element stack, if any. During validation calls it refers to the element being processed (start or end tag), or its parent (when processing text nodes), or null (in document prolog and epilog).

getValidationLocation

public javax.xml.stream.Location getValidationLocation()
Description copied from interface: ValidationContext
Method that will return the location that best represents current location within document to be validated, if such information is available.

Note: it is likely that even when a location is known, it may not be very accurate; for example, when attributes are validated, it is possible that they all would point to a single location that may point to the start of the element that contains attributes.

Specified by:
getValidationLocation in interface ValidationContext

reportProblem

public void reportProblem(XMLValidationProblem problem)
                   throws XMLValidationException
Description copied from interface: ValidationContext
Method called by the validator, upon encountering a validation problem. Implementations are encouraged to allow an optional ValidationProblemHandler be set by the application, to define handling.

Specified by:
reportProblem in interface ValidationContext
Throws:
XMLValidationException

addDefaultAttribute

public abstract int addDefaultAttribute(java.lang.String localName,
                                        java.lang.String uri,
                                        java.lang.String prefix,
                                        java.lang.String value)
Method called by actual validator instances when attributes with default values have no explicit values for the element; if so, default value needs to be added as if it was parsed from the element.

Specified by:
addDefaultAttribute in interface ValidationContext
Returns:
Index of the newly added attribute, if operation was succesful; -1 if not.

isPrefixLocallyDeclared

public abstract boolean isPrefixLocallyDeclared(java.lang.String internedPrefix)
Returns:
True, if the given prefix ("" for default namespace) was bound/unbound in the current element (one at the top of the stack); false if not.

addNsBinding

public abstract void addNsBinding(java.lang.String prefix,
                                  java.lang.String uri)

validateText

public final void validateText(TextBuffer tb,
                               boolean lastTextSegment)
                        throws XMLValidationException
Throws:
XMLValidationException

isNamespaceAware

public abstract boolean isNamespaceAware()

getDepth

public abstract int getDepth()
Returns:
Number of open elements in the stack; 0 when parser is in prolog/epilog, 1 inside root element and so on.

isEmpty

public abstract boolean isEmpty()

getDefaultNsURI

public abstract java.lang.String getDefaultNsURI()

getNsURI

public abstract java.lang.String getNsURI()

getPrefix

public abstract java.lang.String getPrefix()

getLocalName

public abstract java.lang.String getLocalName()

matches

public abstract boolean matches(java.lang.String prefix,
                                java.lang.String localName)

getTopElementDesc

public abstract java.lang.String getTopElementDesc()

getTotalNsCount

public abstract int getTotalNsCount()

getCurrentNsCount

public abstract int getCurrentNsCount()
Returns:
Number of active prefix/namespace mappings for current scope, NOT including mappings from enclosing elements.

getLocalNsPrefix

public abstract java.lang.String getLocalNsPrefix(int index)

getLocalNsURI

public abstract java.lang.String getLocalNsURI(int index)

getAttributeType

public final java.lang.String getAttributeType(int index)
Returns:
Schema (DTD, RNG, W3C Schema) based type of the attribute in specified index

normalizeXmlIdAttr

protected final void normalizeXmlIdAttr(AttributeCollector ac,
                                        int ix)
Method called to normalize value of an ID attribute, specified using name xml:id, when support for Xml:id specification enabled.