com.ctc.wstx.sr
Class InputElementStack

java.lang.Object
  extended by com.ctc.wstx.sr.InputElementStack
All Implemented Interfaces:
NamespaceContext, AttributeInfo, ValidationContext

public final class InputElementStack
extends Object
implements AttributeInfo, 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  AttributeCollector mAttrCollector
           
protected  ReaderConfig mConfig
           
protected  com.ctc.wstx.sr.Element mCurrElement
          Currently open element, if any; null outside root element.
protected  int mDepth
           
protected  com.ctc.wstx.sr.Element mFreeElement
           
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  String mLastLocalName
           
protected  QName mLastName
           
protected  BaseNsContext mLastNsContext
          Last potentially shareable NamespaceContext created by this stack.
protected  String mLastNsURI
           
protected  String mLastPrefix
           
protected  boolean mMayHaveNsDefaults
           
protected  StringVector mNamespaces
          Vector that contains all currently active namespaces; one String for prefix, another for matching URI.
protected  boolean mNsAware
           
protected  NsDefaultProvider mNsDefaultProvider
          Object that will need to be consulted about namespace bindings, since it has some knowledge about default namespace declarations (has default attribute value expansion).
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, boolean nsAware)
           
 
Method Summary
 int addDefaultAttribute(String localName, String uri, String prefix, 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.
 void addNsBinding(String prefix, String uri)
          Callback method called by the namespace default provider.
protected  XMLValidator addValidator(XMLValidator vld)
           
protected  void connectReporter(InputProblemReporter rep)
           
 BaseNsContext createNonTransientNsContext(Location loc)
          Method called to construct a non-transient NamespaceContext instance; generally needed when creating events to return from event-based iterators.
 int findAttributeIndex(String nsURI, String localName)
           
 AttributeCollector getAttrCollector()
          Method called by BasicStreamReader, to retrieve the attribute collector it needs for some direct access.
 int getAttributeCount()
          This method returns number of attributes accessible from within currently active start element.
 String getAttributeLocalName(int index)
           
 String getAttributeNamespace(int index)
           
 String getAttributePrefix(int index)
           
 String getAttributeType(int index)
           
 String getAttributeValue(int index)
           
 String getAttributeValue(String nsURI, String localName)
           
 String getBaseUri()
           
 QName getCurrentElementName()
          Method that can be used to access name information of the innermost (top) element in the element stack.
 int getCurrentNsCount()
           
 String getDefaultNsURI()
           
 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.
 String getLocalName()
           
 String getLocalNsPrefix(int index)
           
 String getLocalNsURI(int index)
           
 String getNamespaceURI(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.
 String getNsURI()
           
 String getPrefix()
           
 String getPrefix(String nsURI)
           
 Iterator getPrefixes(String nsURI)
           
 String getTopElementDesc()
           
 int getTotalNsCount()
           
 Location getValidationLocation()
          Method that will return the location that best represents current location within document to be validated, if such information is available.
 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).
 boolean isEmpty()
           
 boolean isNamespaceAware()
           
 boolean isNotationDeclared(String name)
           
 boolean isPrefixLocallyDeclared(String internedPrefix)
           
 boolean isUnparsedEntityDeclared(String name)
           
 boolean matches(String prefix, String localName)
           
 boolean 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.
 void push(String prefix, 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.
 int resolveAndValidateElement()
          Method called to resolve element and attribute namespaces (in namespace-aware mode), and do optional validation using pluggable validator object.
protected  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)
           
 int validateEndElement()
          Method called after parsing (but before returning) end element, to allow for pluggable validators to verify correctness of the content model for the closing element.
 void validateText(String contents, boolean lastTextSegment)
           
 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

mNsAware

protected final boolean mNsAware

mAttrCollector

protected final AttributeCollector mAttrCollector

mConfig

protected final ReaderConfig mConfig

mReporter

protected InputProblemReporter mReporter

mNsDefaultProvider

protected NsDefaultProvider mNsDefaultProvider
Object that will need to be consulted about namespace bindings, since it has some knowledge about default namespace declarations (has default attribute value expansion).


mDepth

protected int mDepth

mNamespaces

protected final StringVector mNamespaces
Vector that contains all currently active namespaces; one String for prefix, another for matching URI. Does also include default name spaces (at most one per level).


mCurrElement

protected com.ctc.wstx.sr.Element mCurrElement
Currently open element, if any; null outside root element.


mMayHaveNsDefaults

protected boolean mMayHaveNsDefaults

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.


mLastLocalName

protected String mLastLocalName

mLastPrefix

protected String mLastPrefix

mLastNsURI

protected String mLastNsURI

mLastName

protected QName mLastName

mLastNsContext

protected BaseNsContext mLastNsContext
Last potentially shareable NamespaceContext created by this stack. This reference is cleared each time bindings change (either due to a start element with new bindings, or due to the matching end element that closes scope of such binding(s)).


mFreeElement

protected com.ctc.wstx.sr.Element mFreeElement
Constructor Detail

InputElementStack

protected InputElementStack(ReaderConfig cfg,
                            boolean nsAware)
Method Detail

connectReporter

protected void connectReporter(InputProblemReporter rep)

addValidator

protected XMLValidator addValidator(XMLValidator vld)

setAutomaticDTDValidator

protected 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 XMLStreamException
Throws:
XMLStreamException

stopValidatingAgainst

public XMLValidator stopValidatingAgainst(XMLValidationSchema schema)
                                   throws XMLStreamException
Throws:
XMLStreamException

stopValidatingAgainst

public XMLValidator stopValidatingAgainst(XMLValidator validator)
                                   throws XMLStreamException
Throws:
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

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


createNonTransientNsContext

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


push

public final void push(String prefix,
                       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.


pop

public final boolean pop()
                  throws 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:
True if stack has more elements; false if not (that is, root element closed)
Throws:
XMLStreamException

resolveAndValidateElement

public int resolveAndValidateElement()
                              throws 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:
XMLStreamException

validateEndElement

public int validateEndElement()
                       throws XMLStreamException
Method called after parsing (but before returning) end element, to allow for pluggable validators to verify correctness of the content model for the closing element.

Returns:
Validation state that should be effective for the parent element state
Throws:
XMLStreamException

getAttributeCount

public final 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 final int findAttributeIndex(String nsURI,
                                    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 final String getNamespaceURI(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 NamespaceContext
Specified by:
getNamespaceURI in interface ValidationContext

getPrefix

public final String getPrefix(String nsURI)
Specified by:
getPrefix in interface NamespaceContext

getPrefixes

public final Iterator getPrefixes(String nsURI)
Specified by:
getPrefixes in interface NamespaceContext

getXmlVersion

public final 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 String getAttributeLocalName(int index)
Specified by:
getAttributeLocalName in interface ValidationContext

getAttributeNamespace

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

getAttributePrefix

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

getAttributeValue

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

getAttributeValue

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

isNotationDeclared

public boolean isNotationDeclared(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(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 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 final 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 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 XMLStreamException
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.

Note: Stax2 version 2 only allowed throwing instances of XMLValidationProblem; version 3 allows generic base class to be thrown, to support other interfaces such as basic Stax interface XMLReporter.

Specified by:
reportProblem in interface ValidationContext
Throws:
XMLStreamException

addDefaultAttribute

public int addDefaultAttribute(String localName,
                               String uri,
                               String prefix,
                               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 boolean isPrefixLocallyDeclared(String internedPrefix)

addNsBinding

public void addNsBinding(String prefix,
                         String uri)
Callback method called by the namespace default provider. At this point we can trust it to only call this method with somewhat valid arguments (no dups etc).


validateText

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

validateText

public final void validateText(String contents,
                               boolean lastTextSegment)
                        throws XMLStreamException
Throws:
XMLStreamException

isNamespaceAware

public final boolean isNamespaceAware()

isEmpty

public final boolean isEmpty()

getDepth

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

getDefaultNsURI

public final String getDefaultNsURI()

getNsURI

public final String getNsURI()

getPrefix

public final String getPrefix()

getLocalName

public final String getLocalName()

matches

public final boolean matches(String prefix,
                             String localName)

getTopElementDesc

public final String getTopElementDesc()

getTotalNsCount

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

getCurrentNsCount

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

getLocalNsPrefix

public final String getLocalNsPrefix(int index)

getLocalNsURI

public final String getLocalNsURI(int index)

getAttributeType

public final String getAttributeType(int index)
Specified by:
getAttributeType in interface ValidationContext
Returns:
Schema (DTD, RNG, W3C Schema) based type of the attribute in specified index