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, AbstractPSExtensionObject, FObj, FOText, XMLObj

public abstract class FONode

extends java.lang.Object

implements java.lang.Cloneable

Base class for nodes in the XML tree

Field Summary

protected static java.lang.String	FO_URI the XSL-FO namespace URI
protected org.xml.sax.Locator	locator Marks 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 FONode	parent Parent FO node

Constructor Summary

protected

FONode(FONode parent) Main constructor.

Method Summary

protected void	addCharacters(char[] data, int start, int end, PropertyList pList, org.xml.sax.Locator locator) Adds characters (does nothing here)
protected void	addChildNode(FONode child) Adds a node as a child of this node.
protected void	attributeError(java.lang.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)
protected void	attributeWarning(java.lang.String problem) Helper function to standardize attribute warnings (e.g., currently unsupported properties)
protected boolean	canHaveMarkers()
CharIterator	charIterator()
protected java.lang.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 java.lang.String	decorateWithContextInfo(java.lang.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 java.lang.String	errorText(org.xml.sax.Locator loc) Helper function to return "Error(line#/column#)" string for above exception messages
protected java.lang.String	gatherContextInfo() Gathers context information for the getContextInfo() method.
java.util.ListIterator	getChildNodes() Return an iterator over all the child nodes of this FObj.
java.util.ListIterator	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.
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 java.lang.String	getLocalName() Returns the local name (i.e.
org.xml.sax.Locator	getLocator()
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()
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()
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(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 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	missingChildElementError(java.lang.String contentModel) 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)
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
protected void	startOfNode() Called after processNode() is called.
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 overrloaded 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 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 the this (parent) node (e.g., checking to see that fo:table is not an immediate child of fo:root) called within FObj constructor
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

parent

protected FONode parent

Parent FO node

locator

protected org.xml.sax.Locator locator

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

log

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

Logger for fo-tree related messages

Constructor Detail

FONode

protected FONode(FONode parent)

Main constructor.

Parameters:

parent - parent of this node

Method Detail

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

clone

protected java.lang.Object clone()

Perform a shallow cloning operation

Returns:

the cloned object

See Also:

Object.clone()

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 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.

Returns:

the FOEventHandler object that is the parent of the FO Tree

inMarker

protected boolean inMarker()

getUserAgent

public FOUserAgent getUserAgent()

Returns the user agent for the node.

Returns:

FOUserAgent

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 the this (parent) node (e.g., checking to see that fo:table is not an immediate child of fo:root) called within FObj constructor

Parameters:

loc - location in the FO source file

namespaceURI - namespace of incoming node

localName - (e.g. "table" for "fo:table")

Throws:

ValidationException - if incoming node not valid for parent

addCharacters

protected void addCharacters(char[] data,
                             int start,
                             int end,
                             PropertyList pList,
                             org.xml.sax.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

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

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

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

getParent

public FONode getParent()

Returns:

the parent node of this node

getChildNodes

public java.util.ListIterator getChildNodes()

Return an iterator over all the child nodes of this FObj.

Returns:

A ListIterator.

getChildNodes

public java.util.ListIterator 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.

charIterator

public CharIterator charIterator()

Returns:

an iterator for the characters in this node

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.

attributeError

protected void attributeError(java.lang.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

protected void attributeWarning(java.lang.String problem)

Helper function to standardize attribute warnings (e.g., currently unsupported properties)

Parameters:

problem - text to display that indicates the problem

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,
                                 java.lang.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

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

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 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)

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(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 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(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

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 methods only in exceptional conditions because this method may perform quite extensive information gathering inside the FO tree.

Returns:

a String containing

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 ussed 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

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

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 markers are valid children