org.apache.fop.fo

Class FONode

Implemented Interfaces:
Cloneable
Known Direct Subclasses:
AbstractAFPExtensionObject, AbstractMetadataElement, AbstractPSExtensionElement, AbstractPSExtensionObject, Destination, FObj, FOText, XMLObj

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

Base class for nodes in the XML tree

Nested Class Summary

static interface
FONode.FONodeIterator
Base iterator interface over a FO's children

Field Summary

protected static String
FOX_URI
FOP's proprietary extension namespace URI
protected static String
FO_URI
the XSL-FO namespace URI
protected Locator
locator
Marks location of this object from the input FO Call locator.getSystemId(), getLineNumber(), getColumnNumber() for file, line, column information
protected static Log
log
Logger for fo-tree related messages *
protected FONode
parent
Parent FO node
protected FONode[]
siblings
pointer to the sibling nodes

Constructor Summary

FONode(FONode parent)
Main constructor.

Method Summary

protected void
addCharacters(char[] data, int start, int end, PropertyList pList, Locator locator)
Adds characters (does nothing here)
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.
protected void
attributeError(String problem)
Helper function to standardize property error exceptions (e.g., not specifying either an internal- or an external-destination property for an FO:link)
void
attributeWarning(String problem)
Helper function to standardize attribute warnings (e.g., currently unsupported properties)
void
bind(PropertyList propertyList)
Bind the given PropertyList to this node Does nothing by default.
protected boolean
canHaveMarkers()
CharIterator
charIterator()
protected Object
clone()
Perform a shallow cloning operation
FONode
clone(FONode cloneparent, boolean removeChildren)
Perform a shallow cloning operation, set its parent, and optionally clean the list of child nodes
protected PropertyList
createPropertyList(PropertyList pList, FOEventHandler foEventHandler)
Create a property list for this node.
static String
decorateWithContextInfo(String text, FONode node)
Decorates a log or warning message with context information on the given node.
protected 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 String
errorText(Locator loc)
Helper function to return "Error(line#/column#)" string for above exception messages
protected String
gatherContextInfo()
Gathers context information for the getContextInfo() method.
FONode.FONodeIterator
getChildNodes()
Return an iterator over all the child nodes of this FObj.
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.
String
getContextInfo()
Returns a String containing as much context information as possible 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.
abstract String
getLocalName()
Returns the local name (i.e.
Locator
getLocator()
static String
getLocatorString(Locator loc)
Helper function to format a Locator instance.
Log
getLogger()
Returns the logger for the node.
String
getName()
Returns the fully qualified name of the node
String
getName(String prefix)
Returns the fully qualified name of the node
int
getNameId()
Returns the Constants class integer value of this node
String
getNamespaceURI()
static String
getNodeString(String namespaceURI, String localName)
Helper function to standardize the names of all namespace URI - local name pairs in text messages.
abstract String
getNormalNamespacePrefix()
FONode
getParent()
Root
getRoot()
Returns the root node of this tree
FOUserAgent
getUserAgent()
Returns the user agent for the node.
protected boolean
inMarker()
protected void
invalidChildError(Locator loc, String nsURI, String lName)
Helper function to return "invalid child" exceptions (e.g., fo:block appearing immediately under fo:root)
protected void
invalidChildError(Locator loc, String nsURI, String lName, String ruleViolated)
Helper function to return "invalid child" exceptions with more complex validation rules (i.e., needing more explanation of the problem)
protected void
missingChildElementError(String contentModel)
Helper function to throw an error caused by missing mandatory child elements.
protected void
missingPropertyError(String propertyName)
Helper function to throw an error caused by missing mandatory properties
protected void
nodesOutOfOrderError(Locator loc, String tooLateNode, String tooEarlyNode)
Helper function to standardize "out of order" exceptions (e.g., fo:layout-master-set appearing after fo:page-sequence)
void
processNode(String elementName, Locator locator, 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(Locator locator)
Set the location information for this element
protected void
startOfNode()
Called after processNode() is called.
protected void
tooManyNodesError(Locator loc, String offendingNode)
Helper function to standardize "too many" error exceptions (e.g., two fo:declarations within fo:root) This overrloaded method helps make the caller code better self-documenting
protected void
tooManyNodesError(Locator loc, String nsURI, String lName)
Helper function to standardize "too many" error exceptions (e.g., two fo:declarations within fo:root)
protected void
validateChildNode(Locator loc, String namespaceURI, String localName)
Checks to make sure, during SAX processing of input document, that the incoming node is valid for the 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 void
validateChildNode(FONode fo, Locator loc, String namespaceURI, 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 static String
warningText(Locator loc)
Helper function to return "Warning(line#/column#)" string for warning messages

Field Details

FOX_URI

protected static final String FOX_URI
FOP's proprietary extension namespace URI

FO_URI

protected static final String FO_URI
the XSL-FO namespace URI

locator

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

log

protected static Log log
Logger for fo-tree related messages *

parent

protected FONode parent
Parent FO node

siblings

protected FONode[] siblings
pointer to the sibling nodes

Constructor Details

FONode

protected FONode(FONode parent)
Main constructor.
Parameters:
parent - parent of this node

Method Details

addCharacters

protected void addCharacters(char[] data,
                             int start,
                             int end,
                             PropertyList pList,
                             Locator locator)
            throws FOPException
Adds characters (does nothing here)
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 fo source file.
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

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

attributeError

protected void attributeError(String problem)
            throws ValidationException
Helper function to standardize property error exceptions (e.g., not specifying either an internal- or an external-destination property for an FO:link)
Parameters:
problem - text to display that indicates the problem
Throws:
ValidationException - the validation error provoked by the method call

attributeWarning

public void attributeWarning(String problem)
Helper function to standardize attribute warnings (e.g., currently unsupported properties)
Parameters:
problem - text to display that indicates the problem

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

canHaveMarkers

protected boolean canHaveMarkers()
Returns:
true if markers are valid children

charIterator

public CharIterator charIterator()
Returns:
an iterator for the characters in this node

clone

protected Object clone()
Perform a shallow cloning operation
Returns:
the cloned object

clone

public FONode clone(FONode cloneparent,
                    boolean removeChildren)
            throws FOPException
Perform a shallow cloning operation, set its parent, and optionally clean 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

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

decorateWithContextInfo

public static String decorateWithContextInfo(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

endOfNode

protected 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.
Throws:
FOPException - if there's a problem during processing

errorText

protected static String errorText(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

gatherContextInfo

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

getChildNodes

public FONode.FONodeIterator getChildNodes()
Return an iterator over all the child nodes of this FObj.
Returns:
A ListIterator.

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:
A ListIterator or null if child node isn't a child of this FObj.

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

getContextInfo

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

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.

getFOEventHandler

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

getLocalName

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

getLocator

public Locator getLocator()
Returns:
the location information for this element or null, if not available

getLocatorString

public static String getLocatorString(Locator loc)
Helper function to format a Locator instance.
Parameters:
loc - org.xml.sax.Locator object
Returns:
String the formatted text

getLogger

public Log getLogger()
Returns the logger for the node.
Returns:
the logger

getName

public String getName()
Returns the fully qualified name of the node
Returns:
the fully qualified name of this node

getName

public String getName(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

getNameId

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

getNamespaceURI

public String getNamespaceURI()
Returns:
the namespace URI for this node

getNodeString

public static String getNodeString(String namespaceURI,
                                   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.

getNormalNamespacePrefix

public abstract String getNormalNamespacePrefix()
Returns:
the normally ussed namespace prefix for this kind of node (ex. "fo" for XSL-FO)

getParent

public FONode getParent()
Returns:
the parent node of this node

getRoot

public Root getRoot()
Returns the root node of this tree
Returns:
the root node

getUserAgent

public FOUserAgent getUserAgent()
Returns the user agent for the node.
Returns:
FOUserAgent

inMarker

protected boolean inMarker()

invalidChildError

protected void invalidChildError(Locator loc,
                                 String nsURI,
                                 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(Locator loc,
                                 String nsURI,
                                 String lName,
                                 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)
nsURI - namespace URI of incoming invalid node
lName - local name (i.e., no prefix) of incoming node
ruleViolated - text explanation of problem
Throws:
ValidationException - the validation error provoked by the method call

missingChildElementError

protected void missingChildElementError(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 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

missingPropertyError

protected void missingPropertyError(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

nodesOutOfOrderError

protected void nodesOutOfOrderError(Locator loc,
                                    String tooLateNode,
                                    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

processNode

public void processNode(String elementName,
                        Locator locator,
                        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

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

setLocator

public void setLocator(Locator locator)
Set the location information for this element
Parameters:
locator - the org.xml.sax.Locator object

startOfNode

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

tooManyNodesError

protected void tooManyNodesError(Locator loc,
                                 String offendingNode)
            throws ValidationException
Helper function to standardize "too many" error exceptions (e.g., two fo:declarations within fo:root) This overrloaded 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

tooManyNodesError

protected void tooManyNodesError(Locator loc,
                                 String nsURI,
                                 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

validateChildNode

protected void validateChildNode(Locator loc,
                                 String namespaceURI,
                                 String localName)
            throws ValidationException
Checks to make sure, during SAX processing of input document, that the incoming node is valid for the 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,
                                        Locator loc,
                                        String namespaceURI,
                                        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

warningText

protected static String warningText(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

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