org.ceryle.plink
Class PlinkProcessor

java.lang.Object
  org.ceryle.plink.PlinkProcessor

public class PlinkProcessor
extends Object

Adds purple links (ala Augment from bootstrap.org) to an XHTML document (or potentially any XML, if customized). For more extensive documentation see the plink home page.

Plink Documentation Notes

The entire document by default will be plinked. The starting and ending locations can be specified by metadata within the document (see startingID and endingID for details).

Copyright 2001-2007 Murray Altheim. All Rights Reserved.
See LICENSE included with distribution, or in the source code for this file.

Since:

JDK1.3

Version:

$Id: PlinkProcessor.java,v 3.7 2007-06-15 12:09:28 altheim Exp $

Author:

Murray Altheim

Field Summary

static String	anchorElementName A String containing the element type name of the link anchor (or target, default 'a').
static String	bodyElementName A String containing the element type name of the document body element (default 'body').
protected String	defaultDivision A String containing a whitespace-delimited list of element type names, used as the division elements for the processor (default includes the HTML heading elements).
protected String	defaultEmpty A String containing a whitespace-delimited list of element type names, known to be declared EMPTY for use by the processor.
protected String	defaultSignificant A String containing a whitespace-delimited list of element type names, used as the significant elements for the processor (default includes <p>, <li>, <dt>, and <img> elements).
protected String	defaultWrapper A String containing a whitespace-delimited list of element type names, used as the wrapper elements for the processor.
static String	dPfx The String used as a prefix to all assigned division ID values (default is 'd').
protected String	endingID A String indicating the ID to use as a termination point for adding links.
static String	headElementName A String containing the element type name of the document-level metadata container (default 'head').
static String	hPfx The String used as a prefix to all assigned (hierarchical) SSN values (default 'hid').
static String	idAttrName A String containing the attribute name used for IDs (default 'id').
static String	indicatorAttrName A String containing the attribute name used to indicate plink markup (default 'class').
static String	legacyAttrName A String containing the attribute name used for legacy linking (default 'name').
static String	linkElementName A String containing the element type name of the link used to indicate schema namespaces.
static String	linkHref A String containing the attribute name used for link URI references (default 'href').
static String	metaElementName A String containing the element type name of the metadata container (default 'meta').
static int	MODE_AUGMENT Internal mode setting - augment markup.
static int	MODE_NOOP Internal mode setting - no function (pass through).
static int	MODE_REMOVE Internal mode setting - remove markup.
boolean	padSpace
static String	PFX_plink A String containing the attribute namespace prefix value for plink (default 'plink').
static String	PLINK_PROP The base URI for Plink properties (includes hash character).
static String	plinkEndingIdAttr A String containing the name of the plink ending ID attribute.
static String	plinkRevAttr A String containing the name of the plink revision attribute, also used to determine if a document has been plinked.
static String	plinkSIDCountAttr A String containing the name of the plink SID count attribute, used to avoid reuse of SID numbers (when a document is updated, the next SID created will be this value + 1).
static String	plinkStartingIdAttr A String containing the name of the plink starting ID attribute.
static String	plinkStylesheetAttr A String containing the name of the plink stylesheet attribute.
static String	SIDcDelim The character used as the closing delimiter of a "Worker-Assigned Statement Label" (default is ')').
static String	sidIndicator A String containing the attribute value used to indicate plink SID links (default 'plinks').
static String	SIDoDelim The character used as the opening delimiter of a "Worker-Assigned Statement Label" (default is '(').
static String	sPfx The String used as a prefix to all assigned statement (ie., sequential) ID values (default 'nid').
static String	ssnIndicator A String containing the attribute value used to indicate plink SSN links (default 'plink').
protected String	startingID A String indicating the first ID to use as a starting point for adding links.
boolean	useNbsp
static String	XMLNS_plink A String containing the namespace indicator used to indicate plink, http://www.bootstrap.org/plink.

Constructor Summary

PlinkProcessor()
Default constructor.

Method Summary

void	deplink(Document doc) Processes the XmlDocument xmldoc to remove all plink markup.
void	generateID(Element element) Checks for the existence of an id attribute, and if missing or empty generates and adds it to the Element element.
HashSet	getDeclaredEmpty() Returns the HashSet containing the list of elements declared EMPTY, as according to a parse of the DTD or a preset.
String	getEndingID() Returns the ID of the element whose presence signals the ending of plink processing, null if this has not been set.
Document	getIndex() Returns the Document populated with the index of links created.
String	getStartingID() Returns the ID of the element whose presence signals the beginning of plink processing, null if this has not been set.
static int	parseMode(String arg) Parses the String arg for either "augment" or "remove", returning a Plink mode MODE_AUGMENT or MODE_REMOVE, throwing a PlinkException if the string is null or not recognized.
void	plink(Document doc) Processes the XmlDocument xmldoc to produce a plink markup.
void	registerID(String id, Element element) Registers the value id for the Element element with the plink registry.
void	registerIDs(Document doc) Obtains the existing ID list when in validation mode (since the processor only knows which attributes are IDs in this mode), otherwise scans all of Elements in the Document (assuming this is XHTML) for id attributes to obtain this list.
void	removePlink(Element element, String indicator) Removes the plink-created link direct children of Element element having an indicator attribute value starting with the String indicator (whose default is "plink").
void	setBodyElementName(String name) Sets the element type name expected to be the document body element.
void	setDivisionElements(String s) Provided an or-group String of element types s (eg., 'h1|h2|h3'), sets them as the set of division elements to be used by this processor.
void	setEmptyElements(String s) Provided an or-group String of element types s (eg., 'br|img|meta|link'), sets them as the set of empty elements (ie., those declared EMPTY) to be used by this processor.
void	setEndingID(String id) Sets the ID of the element whose presence signals the ending of plink processing.
void	setHeadElementName(String name) Sets the element type name expected to be the document head element.
void	setIDAttributeName(String name) Sets the attribute name of the IDs created by the processor.
void	setIndex(String documentName) Creates a new indexDocument as the Document to be populated with the index of links created, with name documentName.
void	setIndicatorAttributeName(String name) Sets the attribute name of the plink indicator attributes created by the processor.
void	setLinkName(String name, String attrName) Sets the element type and attribute names of the links created by the processor.
void	setSignificantElements(String s) Provided an or-group String of element types s (eg., 'p|blockquote|li'), sets them as the set of significant elements to be used by this processor.
void	setStartingID(String id) Sets the ID of the element whose presence signals the beginning of plink processing.
void	setWrapperElements(String s) Provided an or-group String of element types s (eg., 'div|ul|ol|dl'), sets them as the set of wrapper elements to be used by this processor.
void	updatePreviousPlink(Document doc) After it has been determined that the provided document has already been processed, this will update the plink revision date attribute (defaulting to the contents of an plink.revision-date attribute on <meta> element).
static boolean	wasPlinked(Document doc) Returns true if the provided document has already been processed, e.g., to avoid double-processing.

Methods inherited from class java.lang.Object

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

Field Detail

PLINK_PROP

public static final String PLINK_PROP

The base URI for Plink properties (includes hash character).

See Also:

Constant Field Values

MODE_NOOP

public static final int MODE_NOOP

Internal mode setting - no function (pass through).

See Also:

Constant Field Values

MODE_AUGMENT

public static final int MODE_AUGMENT

Internal mode setting - augment markup.

See Also:

Constant Field Values

MODE_REMOVE

public static final int MODE_REMOVE

Internal mode setting - remove markup.

See Also:

Constant Field Values

XMLNS_plink

public static String XMLNS_plink

A String containing the namespace indicator used to indicate plink, http://www.bootstrap.org/plink.

PFX_plink

public static String PFX_plink

A String containing the attribute namespace prefix value for plink (default 'plink').

plinkRevAttr

public static String plinkRevAttr

A String containing the name of the plink revision attribute, also used to determine if a document has been plinked.

plinkSIDCountAttr

public static String plinkSIDCountAttr

A String containing the name of the plink SID count attribute, used to avoid reuse of SID numbers (when a document is updated, the next SID created will be this value + 1).

plinkStylesheetAttr

public static String plinkStylesheetAttr

A String containing the name of the plink stylesheet attribute.

ssnIndicator

public static String ssnIndicator

A String containing the attribute value used to indicate plink SSN links (default 'plink').

sidIndicator

public static String sidIndicator

A String containing the attribute value used to indicate plink SID links (default 'plinks').

hPfx

public static String hPfx

The String used as a prefix to all assigned (hierarchical) SSN values (default 'hid').

dPfx

public static String dPfx

The String used as a prefix to all assigned division ID values (default is 'd').

sPfx

public static String sPfx

The String used as a prefix to all assigned statement (ie., sequential) ID values (default 'nid').

SIDoDelim

public static String SIDoDelim

The character used as the opening delimiter of a "Worker-Assigned Statement Label" (default is '(').

SIDcDelim

public static String SIDcDelim

The character used as the closing delimiter of a "Worker-Assigned Statement Label" (default is ')').

linkElementName

public static String linkElementName

A String containing the element type name of the link used to indicate schema namespaces.

anchorElementName

public static String anchorElementName

A String containing the element type name of the link anchor (or target, default 'a').

linkHref

public static String linkHref

A String containing the attribute name used for link URI references (default 'href').

idAttrName

public static String idAttrName

A String containing the attribute name used for IDs (default 'id').

legacyAttrName

public static String legacyAttrName

A String containing the attribute name used for legacy linking (default 'name').

indicatorAttrName

public static String indicatorAttrName

A String containing the attribute name used to indicate plink markup (default 'class').

headElementName

public static String headElementName

A String containing the element type name of the document-level metadata container (default 'head').

metaElementName

public static String metaElementName

A String containing the element type name of the metadata container (default 'meta').

bodyElementName

public static String bodyElementName

A String containing the element type name of the document body element (default 'body').

plinkStartingIdAttr

public static String plinkStartingIdAttr

A String containing the name of the plink starting ID attribute.

startingID

protected String startingID

A String indicating the first ID to use as a starting point for adding links. This can be set by the presence of a metadata element, e.g., <meta name="plink.starting-id" content="myStartID" />.

plinkEndingIdAttr

public static String plinkEndingIdAttr

A String containing the name of the plink ending ID attribute.

endingID

protected String endingID

A String indicating the ID to use as a termination point for adding links. This can be set by the presence of a metadata element, e.g., <meta name="plink.ending-id" content="myEndID" />.

defaultDivision

protected String defaultDivision

A String containing a whitespace-delimited list of element type names, used as the division elements for the processor (default includes the HTML heading elements).

defaultSignificant

protected String defaultSignificant

A String containing a whitespace-delimited list of element type names, used as the significant elements for the processor (default includes <p>, <li>, <dt>, and <img> elements).

defaultWrapper

protected String defaultWrapper

A String containing a whitespace-delimited list of element type names, used as the wrapper elements for the processor. These are typically significant wrapper elements that should not receive links (default includes <blockquote>, <div>, <ul>, <ol>, and <dl> elements).

defaultEmpty

protected String defaultEmpty

A String containing a whitespace-delimited list of element type names, known to be declared EMPTY for use by the processor. In XHTML this list (which is the default) includes <area>, <base>, <basefont>, <br>, <col>, <frame>, <hr>, <img>, <input>, <isindexXXX>, <link>, <meta>, and <param> elements).

useNbsp

public boolean useNbsp

padSpace

public boolean padSpace

Constructor Detail

PlinkProcessor

public PlinkProcessor()
               throws ProcessException

Default constructor. This will initialize the processor with the provided settings, using default values.

Throws:

ProcessException

Method Detail

plink

public void plink(Document doc)
           throws PlinkException

Processes the XmlDocument xmldoc to produce a plink markup. This is generally used only for XHTML source documents. The mode is set to PlinkProcessor.MODE_AUGMENT.

Throws:

PlinkException

deplink

public void deplink(Document doc)
             throws PlinkException

Processes the XmlDocument xmldoc to remove all plink markup. This is generally used only for XHTML source documents. The mode is set to PlinkProcessor.MODE_REMOVE.

Throws:

PlinkException

parseMode

public static int parseMode(String arg)
                     throws PlinkException

Parses the String arg for either "augment" or "remove", returning a Plink mode MODE_AUGMENT or MODE_REMOVE, throwing a PlinkException if the string is null or not recognized. Used for parsing command line arguments.

Throws:

PlinkException

setDivisionElements

public void setDivisionElements(String s)
                         throws PlinkException

Provided an or-group String of element types s (eg., 'h1|h2|h3'), sets them as the set of division elements to be used by this processor.

Throws:

PlinkException

setSignificantElements

public void setSignificantElements(String s)
                            throws PlinkException

Provided an or-group String of element types s (eg., 'p|blockquote|li'), sets them as the set of significant elements to be used by this processor.

Note that this method checks to be sure that none of the elements considered significant are also division elements, so this method should always be called after setDivisionElements.

Throws:

PlinkException

setWrapperElements

public void setWrapperElements(String s)
                        throws PlinkException

Provided an or-group String of element types s (eg., 'div|ul|ol|dl'), sets them as the set of wrapper elements to be used by this processor.

Note that this method checks to be sure that none of the elements considered wrapper are also significant or division elements, so this method should always be called after setDivisionElements. Note that these are not checked against the significant set.

Throws:

PlinkException

setEmptyElements

public void setEmptyElements(String s)
                      throws PlinkException

Provided an or-group String of element types s (eg., 'br|img|meta|link'), sets them as the set of empty elements (ie., those declared EMPTY) to be used by this processor.

Throws:

PlinkException

getDeclaredEmpty

public HashSet getDeclaredEmpty()

Returns the HashSet containing the list of elements declared EMPTY, as according to a parse of the DTD or a preset.

setStartingID

public void setStartingID(String id)
                   throws PlinkException

Sets the ID of the element whose presence signals the beginning of plink processing.

Throws:

PlinkException

getStartingID

public String getStartingID()

Returns the ID of the element whose presence signals the beginning of plink processing, null if this has not been set.

setEndingID

public void setEndingID(String id)
                 throws PlinkException

Sets the ID of the element whose presence signals the ending of plink processing.

Throws:

PlinkException

getEndingID

public String getEndingID()

Returns the ID of the element whose presence signals the ending of plink processing, null if this has not been set.

setLinkName

public void setLinkName(String name,
                        String attrName)
                 throws PlinkException

Sets the element type and attribute names of the links created by the processor. Default values are 'a' and 'href', respectively. This also sets these values for the IndexProcessor if it has been established.

Throws:

PlinkException

setIDAttributeName

public void setIDAttributeName(String name)
                        throws PlinkException

Sets the attribute name of the IDs created by the processor. Default value is 'id'.

Throws:

PlinkException

setIndicatorAttributeName

public void setIndicatorAttributeName(String name)
                               throws PlinkException

Sets the attribute name of the plink indicator attributes created by the processor. Default value is 'class'.

Throws:

PlinkException

setBodyElementName

public void setBodyElementName(String name)
                        throws PlinkException

Sets the element type name expected to be the document body element. Default value is 'body'.

Throws:

PlinkException

setHeadElementName

public void setHeadElementName(String name)
                        throws PlinkException

Sets the element type name expected to be the document head element. Default value is 'head'.

Throws:

PlinkException

setIndex

public void setIndex(String documentName)
              throws PlinkException

Creates a new indexDocument as the Document to be populated with the index of links created, with name documentName. If not set, this feature is ignored.

Throws:

PlinkException

getIndex

public Document getIndex()

Returns the Document populated with the index of links created. If never set, null is returned.

registerIDs

public void registerIDs(Document doc)

Obtains the existing ID list when in validation mode (since the processor only knows which attributes are IDs in this mode), otherwise scans all of Elements in the Document (assuming this is XHTML) for id attributes to obtain this list. This is rather time-consuming, so users are encouraged to parse in validation mode if the generateIDs feature is being used.

Note: the current implementation works only for XHTML, using the 'id' attribute value as an ID. Previous implementations relied upon Xerces' DocumentImpl, which provided access to the Document IDs.

registerID

public void registerID(String id,
                       Element element)

Registers the value id for the Element element with the plink registry.

generateID

public void generateID(Element element)

Checks for the existence of an id attribute, and if missing or empty generates and adds it to the Element element.

wasPlinked

public static boolean wasPlinked(Document doc)

Returns true if the provided document has already been processed, e.g., to avoid double-processing. This checks to see if the Document contains a <link> element containing the reference to the plink schema.

updatePreviousPlink

public void updatePreviousPlink(Document doc)
                         throws PlinkException

After it has been determined that the provided document has already been processed, this will update the plink revision date attribute (defaulting to the contents of an plink.revision-date attribute on <meta> element). This will also scan the gamut of existing SID links and set the initial count for new SID links to the next number in sequence, to avoid creating an SID link management conflict with earlier document revisions.

Throws:

PlinkException

removePlink

public void removePlink(Element element,
                        String indicator)

Removes the plink-created link direct children of Element element having an indicator attribute value starting with the String indicator (whose default is "plink"). If indicator is "*", it will remove any element matching either the SID or SSN indicator. The plink linking elements are directly preceded by &nbsp; character entities, which are also removed.