org.apache.fop.fo

## Class FONode

- java.lang.Object
- - org.apache.fop.fo.FONode

- All Implemented Interfaces:
    java.lang.Cloneable
  Direct Known Subclasses:
    AbstractAFPExtensionObject, AbstractMetadataElement, AbstractPDFExtensionElement, AbstractPSExtensionElement, AbstractPSExtensionObject, Destination, FObj, FOText, XMLObj

      public abstract class FONode
      extends java.lang.Object
      implements java.lang.Cloneable

  Base class for nodes in the XML tree

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `FONode.FONodeIterator` Base iterator interface over a FO's children, offering three methods on top of the base interface methods.
    `static class` | `FONode.GatherContextInfoFunction` Function for AdvancedMessageFormat to retrieve context info from an FONode.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static java.lang.String` | `FO_URI` the XSL-FO namespace URI
    `protected static java.lang.String` | `FOX_URI` FOP's proprietary extension namespace URI
    `protected org.xml.sax.Locator` | `locator` Marks the location of this object from the input FO Call `locator.getSystemId()`, `getLineNumber()`, `getColumnNumber()` for file, line, column information
    `protected static org.apache.commons.logging.Log` | `log` Logger for fo-tree related messages
    `protected java.util.List<ChangeBar>` | `nodeChangeBarList` The list of active change bars for the given node
    `protected FONode` | `parent` Parent FO node
    `protected FONode[]` | `siblings` pointer to the sibling nodes
    `protected java.util.List<ChangeBar>` | `startOfNodeChangeBarList` The list of active change bars for the start of the given node

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `FONode(FONode parent)` Base constructor

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addCharacters(char[] data, int start, int end, PropertyList pList, org.xml.sax.Locator locator)` Deprecated. Please override `characters(char[], int, int, PropertyList, Locator)` instead!
    `protected void` | `addChildNode(FONode child)` Adds a node as a child of this node.
    `protected static void` | `attachSiblings(FONode precedingSibling, FONode followingSibling)` This method is used when adding child nodes to a FO that already contains at least one child.
    `void` | `bind(PropertyList propertyList)` Bind the given `PropertyList` to this node Does nothing by default.
    `protected boolean` | `canHaveMarkers()` Returns `true` if `fo:marker` is allowed as a child node.
    `protected void` | `characters(char[] data, int start, int length, PropertyList pList, org.xml.sax.Locator locator)` Adds characters.
    `CharIterator` | `charIterator()` Return a `CharIterator` over all characters in this node
    `protected java.lang.Object` | `clone()`
    `FONode` | `clone(FONode cloneparent, boolean removeChildren)` Performs a shallow cloning operation, sets the clone's parent, and optionally cleans the list of child nodes
    `java.util.Stack<DelimitedTextRange>` | `collectDelimitedTextRanges(java.util.Stack<DelimitedTextRange> ranges)` Collect the sequence of delimited text ranges, where each new range is pushed onto RANGES.
    `protected java.util.Stack<DelimitedTextRange>` | `collectDelimitedTextRanges(java.util.Stack<DelimitedTextRange> ranges, DelimitedTextRange currentRange)` Collect the sequence of delimited text ranges, where each new range is pushed onto RANGES, where default implementation collects ranges of child nodes.
    `protected PropertyList` | `createPropertyList(PropertyList pList, FOEventHandler foEventHandler)` Create a property list for this node.
    `static java.lang.String` | `decorateWithContextInfo(java.lang.String text, FONode node)` Decorates a log or warning message with context information on the given node.
    `void` | `endOfNode()` Primarily used for making final content model validation checks and/or informing the `FOEventHandler` that the end of this FO has been reached.
    `protected static java.lang.String` | `errorText(org.xml.sax.Locator loc)` Helper function to return "Error(line#/column#)" string for above exception messages
    `void` | `finalizeNode()` Finalize this node.
    `protected java.lang.String` | `gatherContextInfo()` Gathers context information for the getContextInfo() method.
    `FOTreeBuilderContext` | `getBuilderContext()` Returns the context class providing information used during FO tree building.
    `java.util.List<ChangeBar>` | `getChangeBarList()` Returns the list of active change bars.
    `FONode.FONodeIterator` | `getChildNodes()` Return an iterator over all the child nodes of this node.
    `FONode.FONodeIterator` | `getChildNodes(FONode childNode)` Return an iterator over the object's child nodes starting at the passed node.
    `ContentHandlerFactory` | `getContentHandlerFactory()` This method is overridden by extension elements and allows the extension element to return a `ContentHandlerFactory`.
    `java.lang.String` | `getContextInfo()` Returns a String containing as much context information as possible about a node.
    `protected java.lang.String` | `getContextInfoAlt()` Returns a String containing as some context information about a node.
    `ExtensionAttachment` | `getExtensionAttachment()` This method is overridden by extension elements and allows the extension element to return a pass-through attachment which the parent formatting objects should simply carry with them but otherwise ignore.
    `FOEventHandler` | `getFOEventHandler()` Recursively goes up the FOTree hierarchy until the `fo:root` is found, which returns the parent `FOEventHandler`.
    `protected FOValidationEventProducer` | `getFOValidationEventProducer()` Returns an instance of the FOValidationEventProducer.
    `abstract java.lang.String` | `getLocalName()` Returns the local name (i.e.
    `org.xml.sax.Locator` | `getLocator()` Returns the `Locator` containing the location information for this element, or `null` if not available
    `static java.lang.String` | `getLocatorString(org.xml.sax.Locator loc)` Helper function to format a Locator instance.
    `org.apache.commons.logging.Log` | `getLogger()` Returns the logger for the node.
    `java.lang.String` | `getName()` Returns the fully qualified name of the node
    `java.lang.String` | `getName(java.lang.String prefix)` Returns the fully qualified name of the node
    `int` | `getNameId()` Returns the `Constants` class integer value of this node
    `java.lang.String` | `getNamespaceURI()` Returns the namespace URI for this node
    `static java.lang.String` | `getNodePrefix(java.lang.String namespaceURI)` Helper function to obtain standard usage prefix for FOP related namespace URIs.
    `static java.lang.String` | `getNodeString(java.lang.String namespaceURI, java.lang.String localName)` Helper function to standardize the names of all namespace URI - local name pairs in text messages.
    `abstract java.lang.String` | `getNormalNamespacePrefix()` Returns the normally used namespace prefix for this node
    `FONode` | `getParent()` Return the parent node of this node
    `Root` | `getRoot()` Returns the root node of this tree
    `StructureTreeElement` | `getStructureTreeElement()` Returns the structure tree element associated to this object.
    `FOUserAgent` | `getUserAgent()` Returns the user agent that is associated with the tree's `FOEventHandler`.
    `protected boolean` | `inMarker()` Indicates whether this node is a child of an fo:marker.
    `protected void` | `invalidChildError(org.xml.sax.Locator loc, java.lang.String nsURI, java.lang.String lName)` Helper function to return "invalid child" exceptions (e.g., `fo:block` appearing immediately under `fo:root`)
    `protected void` | `invalidChildError(org.xml.sax.Locator loc, java.lang.String parentName, java.lang.String nsURI, java.lang.String lName, java.lang.String ruleViolated)` Helper function to return "invalid child" exceptions with more complex validation rules (i.e., needing more explanation of the problem)
    `protected void` | `invalidPropertyValueError(java.lang.String propertyName, java.lang.String propertyValue, java.lang.Exception e)` Helper function to throw an error caused by an invalid property
    `boolean` | `isBidiRangeBlockItem()` Determine if this node is a new bidi RANGE block item.
    `boolean` | `isChangeBarElement(java.lang.String namespaceURI, java.lang.String localName)` Tests if the given element is a change bar element.
    `boolean` | `isDelimitedTextRangeBoundary(int boundary)` Determine if node has a delimited text range boundary.
    `protected void` | `missingChildElementError(java.lang.String contentModel)` Helper function to throw an error caused by missing mandatory child elements.
    `protected void` | `missingChildElementError(java.lang.String contentModel, boolean canRecover)` Helper function to throw an error caused by missing mandatory child elements.
    `protected void` | `missingPropertyError(java.lang.String propertyName)` Helper function to throw an error caused by missing mandatory properties
    `protected void` | `nodesOutOfOrderError(org.xml.sax.Locator loc, java.lang.String tooLateNode, java.lang.String tooEarlyNode)` Helper function to standardize "out of order" exceptions (e.g., `fo:layout-master-set` appearing after `fo:page-sequence`)
    `protected void` | `nodesOutOfOrderError(org.xml.sax.Locator loc, java.lang.String tooLateNode, java.lang.String tooEarlyNode, boolean canRecover)` Helper function to standardize "out of order" exceptions (e.g., fo:layout-master-set appearing after fo:page-sequence)
    `protected void` | `notSupportedChildError(org.xml.sax.Locator loc, java.lang.String nsURI, java.lang.String lName)` Helper function to return "not supported child" exceptions.
    `void` | `processNode(java.lang.String elementName, org.xml.sax.Locator locator, org.xml.sax.Attributes attlist, PropertyList pList)` Initialize the node with its name, location information, and attributes The attributes must be used immediately as the sax attributes will be altered for the next element.
    `void` | `removeChild(FONode child)` Removes a child node.
    `void` | `setLocator(org.xml.sax.Locator locator)` Set the location information for this element
    `void` | `setStructureTreeElement(StructureTreeElement structureTreeElement)` Sets the structure tree element.
    `void` | `startOfNode()` Called after processNode() is called.
    `protected void` | `tooManyNodesError(org.xml.sax.Locator loc, org.apache.xmlgraphics.util.QName offendingNode)` Helper function to standardize "too many" error exceptions (e.g., two `fo:declarations` within `fo:root`)
    `protected void` | `tooManyNodesError(org.xml.sax.Locator loc, java.lang.String offendingNode)` Helper function to standardize "too many" error exceptions (e.g., two fo:declarations within fo:root) This overloaded method helps make the caller code better self-documenting
    `protected void` | `tooManyNodesError(org.xml.sax.Locator loc, java.lang.String nsURI, java.lang.String lName)` Helper function to standardize "too many" error exceptions (e.g., two fo:declarations within fo:root)
    `protected static void` | `validateChildNode(FONode fo, org.xml.sax.Locator loc, java.lang.String namespaceURI, java.lang.String localName)` Static version of `validateChildNode(Locator, String, String)` that can be used by subclasses that need to validate children against a different node (for example: `fo:wrapper` needs to check if the incoming node is a valid child to its parent)
    `protected void` | `validateChildNode(org.xml.sax.Locator loc, java.lang.String namespaceURI, java.lang.String localName)` Checks to make sure, during SAX processing of input document, that the incoming node is valid for this (parent) node (e.g., checking to see that `fo:table` is not an immediate child of `fo:root`) called from `FOTreeBuilder.startElement(String, String, String, Attributes)` before constructing the child `FObj`.
    `protected static java.lang.String` | `warningText(org.xml.sax.Locator loc)` Helper function to return "Warning(line#/column#)" string for warning messages

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### FO_URI

          protected static final java.lang.String FO_URI

      the XSL-FO namespace URI
      See Also:
        Constant Field Values

    - #### FOX_URI

          protected static final java.lang.String FOX_URI

      FOP's proprietary extension namespace URI
      See Also:
        Constant Field Values

    - #### parent

          protected FONode parent

      Parent FO node

    - #### siblings

          protected FONode[] siblings

      pointer to the sibling nodes

    - #### nodeChangeBarList

          protected java.util.List<ChangeBar> nodeChangeBarList

      The list of active change bars for the given node

    - #### startOfNodeChangeBarList

          protected java.util.List<ChangeBar> startOfNodeChangeBarList

      The list of active change bars for the start of the given node

    - #### locator

          protected org.xml.sax.Locator locator

      Marks the location of this object from the input FO
      Call `locator.getSystemId()`, `getLineNumber()`, `getColumnNumber()` for file, line, column information

    - #### log

          protected static final org.apache.commons.logging.Log log

      Logger for fo-tree related messages

  - ### Constructor Detail

    - #### FONode

          protected FONode(FONode parent)

      Base constructor
      Parameters:
        `parent` - parent of this node

  - ### Method Detail

    - #### clone

          public FONode clone(FONode cloneparent,
                     boolean removeChildren)
                       throws FOPException

      Performs a shallow cloning operation, sets the clone's parent, and optionally cleans the list of child nodes
      Parameters:
        `cloneparent` - the intended parent of the clone
        `removeChildren` - if true, clean the list of child nodes
      Returns:
        the cloned FO node
      Throws:
        `FOPException` - if there's a problem while cloning the node

    - #### clone

          protected java.lang.Object clone()

      Overrides:
        `clone` in class `java.lang.Object`

    - #### bind

          public void bind(PropertyList propertyList)
                    throws FOPException

      Bind the given `PropertyList` to this node Does nothing by default. Subclasses should override this method in case they want to use the properties available on the `PropertyList`.
      Parameters:
        `propertyList` - the `PropertyList`
      Throws:
        `FOPException` - if there was an error when processing the `PropertyList`

    - #### setLocator

          public void setLocator(org.xml.sax.Locator locator)

      Set the location information for this element
      Parameters:
        `locator` - the org.xml.sax.Locator object

    - #### getLocator

          public org.xml.sax.Locator getLocator()

      Returns the `Locator` containing the location information for this element, or `null` if not available
      Returns:
        the location information for this element or `null`, if not available

    - #### getFOEventHandler

          public FOEventHandler getFOEventHandler()

      Recursively goes up the FOTree hierarchy until the `fo:root` is found, which returns the parent `FOEventHandler`.
      (see also: `Root.getFOEventHandler()`)
      Returns:
        the FOEventHandler object that is the parent of the FO Tree

    - #### getBuilderContext

          public FOTreeBuilderContext getBuilderContext()

      Returns the context class providing information used during FO tree building.
      Returns:
        the builder context

    - #### inMarker

          protected boolean inMarker()

      Indicates whether this node is a child of an fo:marker.
      Returns:
        true if this node is a child of an fo:marker

    - #### isChangeBarElement

          public boolean isChangeBarElement(java.lang.String namespaceURI,
                                   java.lang.String localName)

      Tests if the given element is a change bar element.
      Parameters:
        `namespaceURI` - The name space of the element
        `localName` - The local name of the element
      Returns:
        A boolean value true if the given element is a change bar element

    - #### getUserAgent

          public FOUserAgent getUserAgent()

      Returns the user agent that is associated with the tree's `FOEventHandler`.
      Returns:
        the user agent

    - #### getLogger

          public org.apache.commons.logging.Log getLogger()

      Returns the logger for the node.
      Returns:
        the logger

    - #### processNode

          public void processNode(java.lang.String elementName,
                         org.xml.sax.Locator locator,
                         org.xml.sax.Attributes attlist,
                         PropertyList pList)
                           throws FOPException

      Initialize the node with its name, location information, and attributes The attributes must be used immediately as the sax attributes will be altered for the next element.
      Parameters:
        `elementName` - element name (e.g., "fo:block")
        `locator` - Locator object (ignored by default)
        `attlist` - Collection of attributes passed to us from the parser.
        `pList` - the property list of the parent node
      Throws:
        `FOPException` - for errors or inconsistencies in the attributes

    - #### createPropertyList

          protected PropertyList createPropertyList(PropertyList pList,
                                        FOEventHandler foEventHandler)
                                             throws FOPException

      Create a property list for this node. Return null if the node does not need a property list.
      Parameters:
        `pList` - the closest parent propertylist.
        `foEventHandler` - The FOEventHandler where the PropertyListMaker instance can be found.
      Returns:
        A new property list.
      Throws:
        `FOPException` - if there's a problem during processing

    - #### validateChildNode

          protected void validateChildNode(org.xml.sax.Locator loc,
                               java.lang.String namespaceURI,
                               java.lang.String localName)
                                    throws ValidationException

      Checks to make sure, during SAX processing of input document, that the incoming node is valid for this (parent) node (e.g., checking to see that `fo:table` is not an immediate child of `fo:root`) called from `FOTreeBuilder.startElement(String, String, String, Attributes)` before constructing the child `FObj`.
      Parameters:
        `loc` - location in the FO source file
        `namespaceURI` - namespace of incoming node
        `localName` - name of the incoming node (without namespace prefix)
      Throws:
        `ValidationException` - if incoming node not valid for parent

    - #### validateChildNode

          protected static void validateChildNode(FONode fo,
                               org.xml.sax.Locator loc,
                               java.lang.String namespaceURI,
                               java.lang.String localName)
                                           throws ValidationException

      Static version of `validateChildNode(Locator, String, String)` that can be used by subclasses that need to validate children against a different node (for example: `fo:wrapper` needs to check if the incoming node is a valid child to its parent)
      Parameters:
        `fo` - the `FONode` to validate against
        `loc` - location in the source file
        `namespaceURI` - namespace of the incoming node
        `localName` - name of the incoming node (without namespace prefix)
      Throws:
        `ValidationException` - if the incoming node is not a valid child for the given FO

    - #### addCharacters

          protected void addCharacters(char[] data,
                           int start,
                           int end,
                           PropertyList pList,
                           org.xml.sax.Locator locator)
                                throws FOPException

      Deprecated. Please override `characters(char[], int, int, PropertyList, Locator)` instead!
      Adds characters. Does nothing by default. To be overridden in subclasses that allow `#PCDATA` content.
      Parameters:
        `data` - array of characters containing text to be added
        `start` - starting array element to add
        `end` - ending array element to add
        `pList` - currently applicable PropertyList
        `locator` - location in the XSL-FO source file.
      Throws:
        `FOPException` - if there's a problem during processing

    - #### characters

          protected void characters(char[] data,
                        int start,
                        int length,
                        PropertyList pList,
                        org.xml.sax.Locator locator)
                             throws FOPException

      Adds characters. Does nothing by default. To be overridden in subclasses that allow `#PCDATA` content.
      Parameters:
        `data` - array of characters containing text to be added
        `start` - starting array element to add
        `length` - number of elements to add
        `pList` - currently applicable PropertyList
        `locator` - location in the XSL-FO source file.
      Throws:
        `FOPException` - if there's a problem during processing

    - #### startOfNode

          public void startOfNode()
                           throws FOPException

      Called after processNode() is called. Subclasses can do additional processing.
      Throws:
        `FOPException` - if there's a problem during processing

    - #### endOfNode

          public void endOfNode()
                         throws FOPException

      Primarily used for making final content model validation checks and/or informing the `FOEventHandler` that the end of this FO has been reached. The default implementation simply calls `finalizeNode()`, without sending any event to the `FOEventHandler`.

      Note: the recommended way to override this method in subclasses is

      `super.endOfNode(); // invoke finalizeNode()`

      `getFOEventHandler().endXXX(); // send endOfNode() notification`

      Throws:
        `FOPException` - if there's a problem during processing

    - #### addChildNode

          protected void addChildNode(FONode child)
                               throws FOPException

      Adds a node as a child of this node. The default implementation of this method just ignores any child node being added.
      Parameters:
        `child` - child node to be added to the childNodes of this node
      Throws:
        `FOPException` - if there's a problem during processing

    - #### removeChild

          public void removeChild(FONode child)

      Removes a child node. Used by the child nodes to remove themselves, for example table-body if it has no children.
      Parameters:
        `child` - child node to be removed

    - #### finalizeNode

          public void finalizeNode()
                            throws FOPException

      Finalize this node. This method can be overridden by subclasses to perform finishing tasks (cleanup, validation checks, ...) without triggering endXXX() events in the `FOEventHandler`. The method is called by the default `endOfNode()` implementation.
      Throws:
        `FOPException` - in case there was an error

    - #### getParent

          public FONode getParent()

      Return the parent node of this node
      Returns:
        the parent node of this node

    - #### getChildNodes

          public FONode.FONodeIterator getChildNodes()

      Return an iterator over all the child nodes of this node.
      Returns:
        the iterator over the FO's childnodes

    - #### getChildNodes

          public FONode.FONodeIterator getChildNodes(FONode childNode)

      Return an iterator over the object's child nodes starting at the passed node.
      Parameters:
        `childNode` - First node in the iterator
      Returns:
        the iterator, or `null` if the given node is not a child of this node.

    - #### charIterator

          public CharIterator charIterator()

      Return a `CharIterator` over all characters in this node
      Returns:
        an iterator for the characters in this node

    - #### getNodePrefix

          public static java.lang.String getNodePrefix(java.lang.String namespaceURI)

      Helper function to obtain standard usage prefix for FOP related namespace URIs.
      Parameters:
        `namespaceURI` - URI of node found (e.g., "http://www.w3.org/1999/XSL/Format")
      Returns:
        the prefix or null if none

    - #### getNodeString

          public static java.lang.String getNodeString(java.lang.String namespaceURI,
                                       java.lang.String localName)

      Helper function to standardize the names of all namespace URI - local name pairs in text messages. For readability, using fo:, fox:, svg:, for those namespaces even though that prefix may not have been chosen in the document.
      Parameters:
        `namespaceURI` - URI of node found (e.g., "http://www.w3.org/1999/XSL/Format")
        `localName` - local name of node, (e.g., "root" for "fo:root")
      Returns:
        the prefix:localname, if fo/fox/svg, or a longer representation with the unabbreviated URI otherwise.

    - #### getFOValidationEventProducer

          protected FOValidationEventProducer getFOValidationEventProducer()

      Returns an instance of the FOValidationEventProducer.
      Returns:
        an event producer for FO validation

    - #### tooManyNodesError

          protected void tooManyNodesError(org.xml.sax.Locator loc,
                               java.lang.String nsURI,
                               java.lang.String lName)
                                    throws ValidationException

      Helper function to standardize "too many" error exceptions (e.g., two fo:declarations within fo:root)
      Parameters:
        `loc` - org.xml.sax.Locator object of the error (*not* parent node)
        `nsURI` - namespace URI of incoming invalid node
        `lName` - local name (i.e., no prefix) of incoming node
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### tooManyNodesError

          protected void tooManyNodesError(org.xml.sax.Locator loc,
                               org.apache.xmlgraphics.util.QName offendingNode)
                                    throws ValidationException

      Helper function to standardize "too many" error exceptions (e.g., two `fo:declarations` within `fo:root`)
      Parameters:
        `loc` - org.xml.sax.Locator object of the error (*not* parent node)
        `offendingNode` - the qualified name of the offending node
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### tooManyNodesError

          protected void tooManyNodesError(org.xml.sax.Locator loc,
                               java.lang.String offendingNode)
                                    throws ValidationException

      Helper function to standardize "too many" error exceptions (e.g., two fo:declarations within fo:root) This overloaded method helps make the caller code better self-documenting
      Parameters:
        `loc` - org.xml.sax.Locator object of the error (*not* parent node)
        `offendingNode` - incoming node that would cause a duplication.
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### nodesOutOfOrderError

          protected void nodesOutOfOrderError(org.xml.sax.Locator loc,
                                  java.lang.String tooLateNode,
                                  java.lang.String tooEarlyNode)
                                       throws ValidationException

      Helper function to standardize "out of order" exceptions (e.g., `fo:layout-master-set` appearing after `fo:page-sequence`)
      Parameters:
        `loc` - org.xml.sax.Locator object of the error (*not* parent node)
        `tooLateNode` - string name of node that should be earlier in document
        `tooEarlyNode` - string name of node that should be later in document
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### nodesOutOfOrderError

          protected void nodesOutOfOrderError(org.xml.sax.Locator loc,
                                  java.lang.String tooLateNode,
                                  java.lang.String tooEarlyNode,
                                  boolean canRecover)
                                       throws ValidationException

      Helper function to standardize "out of order" exceptions (e.g., fo:layout-master-set appearing after fo:page-sequence)
      Parameters:
        `loc` - org.xml.sax.Locator object of the error (*not* parent node)
        `tooLateNode` - string name of node that should be earlier in document
        `tooEarlyNode` - string name of node that should be later in document
        `canRecover` - indicates whether FOP can recover from this problem and continue working
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### invalidChildError

          protected void invalidChildError(org.xml.sax.Locator loc,
                               java.lang.String nsURI,
                               java.lang.String lName)
                                    throws ValidationException

      Helper function to return "invalid child" exceptions (e.g., `fo:block` appearing immediately under `fo:root`)
      Parameters:
        `loc` - org.xml.sax.Locator object of the error (*not* parent node)
        `nsURI` - namespace URI of incoming invalid node
        `lName` - local name (i.e., no prefix) of incoming node
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### invalidChildError

          protected void invalidChildError(org.xml.sax.Locator loc,
                               java.lang.String parentName,
                               java.lang.String nsURI,
                               java.lang.String lName,
                               java.lang.String ruleViolated)
                                    throws ValidationException

      Helper function to return "invalid child" exceptions with more complex validation rules (i.e., needing more explanation of the problem)
      Parameters:
        `loc` - org.xml.sax.Locator object of the error (*not* parent node)
        `parentName` - the name of the parent element
        `nsURI` - namespace URI of incoming offending node
        `lName` - local name (i.e., no prefix) of incoming offending node
        `ruleViolated` - name of the rule violated (used to lookup a resource in a bundle)
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### notSupportedChildError

          protected void notSupportedChildError(org.xml.sax.Locator loc,
                                    java.lang.String nsURI,
                                    java.lang.String lName)
                                         throws ValidationException

      Helper function to return "not supported child" exceptions. Note that the child is valid, just not supported yet by FOP.
      Parameters:
        `loc` - org.xml.sax.Locator object of the error (*not* parent node)
        `nsURI` - namespace URI of incoming invalid node
        `lName` - local name (i.e., no prefix) of incoming node
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### missingChildElementError

          protected void missingChildElementError(java.lang.String contentModel)
                                           throws ValidationException

      Helper function to throw an error caused by missing mandatory child elements. (e.g., `fo:layout-master-set` not having any `fo:page-master` child element.
      Parameters:
        `contentModel` - The XSL Content Model for the fo: object or a similar description indicating the necessary child elements.
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### missingChildElementError

          protected void missingChildElementError(java.lang.String contentModel,
                                      boolean canRecover)
                                           throws ValidationException

      Helper function to throw an error caused by missing mandatory child elements. E.g., fo:layout-master-set not having any page-master child element.
      Parameters:
        `contentModel` - The XSL Content Model for the fo: object or a similar description indicating the necessary child elements.
        `canRecover` - indicates whether FOP can recover from this problem and continue working
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### missingPropertyError

          protected void missingPropertyError(java.lang.String propertyName)
                                       throws ValidationException

      Helper function to throw an error caused by missing mandatory properties
      Parameters:
        `propertyName` - the name of the missing property.
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### invalidPropertyValueError

          protected void invalidPropertyValueError(java.lang.String propertyName,
                                       java.lang.String propertyValue,
                                       java.lang.Exception e)
                                            throws ValidationException

      Helper function to throw an error caused by an invalid property
      Parameters:
        `propertyName` - the name of the property.
        `propertyValue` - the value of the property.
        `e` - optional property parsing exception.
      Throws:
        `ValidationException` - the validation error provoked by the method call

    - #### errorText

          protected static java.lang.String errorText(org.xml.sax.Locator loc)

      Helper function to return "Error(line#/column#)" string for above exception messages
      Parameters:
        `loc` - org.xml.sax.Locator object
      Returns:
        String opening error text

    - #### warningText

          protected static java.lang.String warningText(org.xml.sax.Locator loc)

      Helper function to return "Warning(line#/column#)" string for warning messages
      Parameters:
        `loc` - org.xml.sax.Locator object
      Returns:
        String opening warning text

    - #### getLocatorString

          public static java.lang.String getLocatorString(org.xml.sax.Locator loc)

      Helper function to format a Locator instance.
      Parameters:
        `loc` - org.xml.sax.Locator object
      Returns:
        String the formatted text

    - #### decorateWithContextInfo

          public static java.lang.String decorateWithContextInfo(java.lang.String text,
                                                 FONode node)

      Decorates a log or warning message with context information on the given node.
      Parameters:
        `text` - the original message
        `node` - the context node
      Returns:
        the decorated text

    - #### getContextInfo

          public java.lang.String getContextInfo()

      Returns a String containing as much context information as possible about a node. Call this method only in exceptional conditions because this method may perform quite extensive information gathering inside the FO tree.
      Returns:
        a String containing context information

    - #### getContextInfoAlt

          protected java.lang.String getContextInfoAlt()

      Returns a String containing as some context information about a node. It does not take the locator into consideration and returns null if no useful context information can be found. Call this method only in exceptional conditions because this method may perform quite extensive information gathering inside the FO tree. All text returned by this method that is not extracted from document content needs to be locale-independent.
      Returns:
        a String containing context information

    - #### gatherContextInfo

          protected java.lang.String gatherContextInfo()

      Gathers context information for the getContextInfo() method.
      Returns:
        the collected context information or null, if none is available

    - #### getRoot

          public Root getRoot()

      Returns the root node of this tree
      Returns:
        the root node

    - #### getName

          public java.lang.String getName()

      Returns the fully qualified name of the node
      Returns:
        the fully qualified name of this node

    - #### getName

          public java.lang.String getName(java.lang.String prefix)

      Returns the fully qualified name of the node
      Parameters:
        `prefix` - the namespace prefix to build the name with (may be null)
      Returns:
        the fully qualified name of this node

    - #### getLocalName

          public abstract java.lang.String getLocalName()

      Returns the local name (i.e. without namespace prefix) of the node
      Returns:
        the local name of this node

    - #### getNormalNamespacePrefix

          public abstract java.lang.String getNormalNamespacePrefix()

      Returns the normally used namespace prefix for this node
      Returns:
        the normally used namespace prefix for this kind of node (ex. "fo" for XSL-FO)

    - #### getNamespaceURI

          public java.lang.String getNamespaceURI()

      Returns the namespace URI for this node
      Returns:
        the namespace URI for this node

    - #### getNameId

          public int getNameId()

      Returns the `Constants` class integer value of this node
      Returns:
        the integer enumeration of this FO (e.g. `Constants.FO_ROOT`) if a formatting object, `Constants.FO_UNKNOWN_NODE` otherwise

    - #### getExtensionAttachment

          public ExtensionAttachment getExtensionAttachment()

      This method is overridden by extension elements and allows the extension element to return a pass-through attachment which the parent formatting objects should simply carry with them but otherwise ignore. This mechanism is used to pass non-standard information from the FO tree through to the layout engine and the renderers.
      Returns:
        the extension attachment if one is created by the extension element, null otherwise.

    - #### getContentHandlerFactory

          public ContentHandlerFactory getContentHandlerFactory()

      This method is overridden by extension elements and allows the extension element to return a `ContentHandlerFactory`. This factory can create ContentHandler implementations that handle foreign XML content by either building up a specific DOM, a Java object or something else.
      Returns:
        the `ContentHandlerFactory` or `null` if not applicable

    - #### canHaveMarkers

          protected boolean canHaveMarkers()

      Returns `true` if `fo:marker` is allowed as a child node.
      To be overridden only in extension nodes that need it.
      Returns:
        true if markers are valid children

    - #### attachSiblings

          protected static void attachSiblings(FONode precedingSibling,
                            FONode followingSibling)

      This method is used when adding child nodes to a FO that already contains at least one child. In this case, the new child becomes a sibling to the previous one
      Parameters:
        `precedingSibling` - the previous child
        `followingSibling` - the new child

    - #### isDelimitedTextRangeBoundary

          public boolean isDelimitedTextRangeBoundary(int boundary)

      Determine if node has a delimited text range boundary. N.B. that we report this to be true by default, while specific subclasses override this method to report false.
      Parameters:
        `boundary` - one of {EN_BEFORE, EN_AFTER, or EN_BOTH} enumeration constants
      Returns:
        true if indicated boundary (or boundaries) constitute a delimited text range boundary.

    - #### collectDelimitedTextRanges

          public java.util.Stack<DelimitedTextRange> collectDelimitedTextRanges(java.util.Stack<DelimitedTextRange> ranges)

      Collect the sequence of delimited text ranges, where each new range is pushed onto RANGES.
      Parameters:
        `ranges` - a stack of delimited text ranges
      Returns:
        the (possibly) updated stack of delimited text ranges

    - #### collectDelimitedTextRanges

          protected java.util.Stack<DelimitedTextRange> collectDelimitedTextRanges(java.util.Stack<DelimitedTextRange> ranges,
                                                                       DelimitedTextRange currentRange)

      Collect the sequence of delimited text ranges, where each new range is pushed onto RANGES, where default implementation collects ranges of child nodes.
      Parameters:
        `ranges` - a stack of delimited text ranges
        `currentRange` - the current range or null (if none)
      Returns:
        the (possibly) updated stack of delimited text ranges

    - #### isBidiRangeBlockItem

          public boolean isBidiRangeBlockItem()

      Determine if this node is a new bidi RANGE block item.
      Returns:
        true if this node is a new bidi RANGE block item

    - #### getChangeBarList

          public java.util.List<ChangeBar> getChangeBarList()

      Returns the list of active change bars.
      Returns:
        The list of active change bars

    - #### setStructureTreeElement

          public void setStructureTreeElement(StructureTreeElement structureTreeElement)

      Sets the structure tree element.
      Parameters:
        `structureTreeElement` - set.

    - #### getStructureTreeElement

          public StructureTreeElement getStructureTreeElement()

      Returns the structure tree element associated to this object.
      Returns:
        the structure tree element

Copyright 1999-2019 The Apache Software Foundation. All Rights Reserved.