com.xmlmind.xml.xinclude

Class XInclude

java.lang.Object

com.xmlmind.xml.xinclude.XInclude

All Implemented Interfaces:

Inclusion, SimpleInclusion, XInclusion

public final class XInclude
extends Object
implements SimpleInclusion

Represents an xi:include element. Supports both XInclude v1.0 and v1.1 (upward-compatible with v1.0).

See Also:

XIncludeScheme, XInclude 1.0, XInclude 1.1

Field Summary

Fields

Modifier and Type	Field and Description
String	absoluteHref String representation of href, the above URL.
Attribute[]	attributes Other attributes of the xi:include element.
Element	fallback The xi:fallback element if any.
String	fragid The string representation of the fragment identifier.
URL	href The URL of the document containing the nodes to be included (AKA the target document).
boolean	parseText true if the target document is to be included as text; false otherwise.
String	textEncoding The encoding of the target document.
String	xpointer The string representation of the XPointer.

Constructor Summary

Constructors

Constructor and Description
XInclude(String clipboardForm) Constructs an XInclude initialized using specified clipboard form.
XInclude(URL href, String absoluteHref, String xpointer, String fragid, boolean parseText, String textEncoding, Attribute[] attributes, Element fallback)

Method Summary

Modifier and Type	Method and Description
Node[]	copySourceNodes(Node firstNode, Node lastNode) Returns nodes to be included, which are copies, as is (XInclude 1.0) or modified (DITA Conref, XInclude 1.1), of specified source nodes.
static XInclude	fromElement(Element element) Creates an XInclude object representing specified xi:include element.
String	getSchemeName() Returns the name of the XInclusion scheme which has created this XInclusion.
Node[]	getSourceNodes(Document sourceDocument, Node inclusionHolder) Returns the original nodes.
URL	getSourceURL(Node inclusionHolder) Returns the URL of document from which the nodes have been included.
boolean	hasSimpleXPointer() Returns true if this XInclude object has no xpointer or has a xpointer using the element() scheme and containing an ID (id or element(id)) or pointing to the root element of the document (element(/1)).
Node[]	include(Node firstNode, Node lastNode, boolean updating, XInclusionContext context) Creates and returns the included nodes corresponding to this XInclusion.
boolean	isMarkedForUpdate() Returns true if this XInclusion has been marked for update using XInclusion.setMarkedForUpdate(boolean); false otherwise This method is exclusively for use by the XIncluder.
void	setMarkedForUpdate(boolean mark) Mark this inclusion for update.
String	toClipboardForm() Returns a parseable string representation of this inclusion.
static String	toHref(NodeIterator nodeIter)
String	toString()
Node[]	uninclude(Node firstIncludedNode, Node lastIncludedNode) Creates and returns one or more nodes acting as the inclusion directive which allows to obtain specified nodes.

Methods inherited from class java.lang.Object

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

Field Detail

href

public final URL href

The URL of the document containing the nodes to be included (AKA the target document). Never null.

absoluteHref

public final String absoluteHref

String representation of href, the above URL. null if the above URL was specified as a relative URL.

This string representation is needed because it may make use of XML catalog trick (Example: foo:bar/gee.xml, where foo: is resolved using an XML catalog).

xpointer

public final String xpointer

The string representation of the XPointer. May be null.

fragid

public final String fragid

The string representation of the fragment identifier. May be null.

parseText

public final boolean parseText

true if the target document is to be included as text; false otherwise.

textEncoding

public final String textEncoding

The encoding of the target document. Ignored unless parseText is true. May be null.

attributes

public final Attribute[] attributes

Other attributes of the xi:include element. May be null.

These attributes are used to implement the Attribute Copying feature of XInclude 1.1. Example: set-xml-id.

fallback

public final Element fallback

The xi:fallback element if any. May be null.

Constructor Detail

XInclude

public XInclude(URL href,
                String absoluteHref,
                String xpointer,
                String fragid,
                boolean parseText,
                String textEncoding,
                Attribute[] attributes,
                Element fallback)
         throws InclusionException

Throws:

InclusionException

XInclude

public XInclude(String clipboardForm)
         throws InclusionException

Constructs an XInclude initialized using specified clipboard form.

Throws:

InclusionException

See Also:

toClipboardForm()

Method Detail

getSchemeName

public String getSchemeName()

Description copied from interface: XInclusion

Returns the name of the XInclusion scheme which has created this XInclusion. This name must be the same as the one returned by XInclusionScheme.getSchemeName().

Specified by:

getSchemeName in interface XInclusion

fromElement

public static XInclude fromElement(Element element)
                            throws InclusionException

Creates an XInclude object representing specified xi:include element.

Parameters:

element - The xi:include element to be converted.

Returns:

An XInclude object representing specified xi:include element.

Throws:

InclusionException - if, for any reason, specified element cannot be converted to an an XInclude object.

hasSimpleXPointer

public boolean hasSimpleXPointer()

Returns true if this XInclude object has no xpointer or has a xpointer using the element() scheme and containing an ID (id or element(id)) or pointing to the root element of the document (element(/1)). Returns false otherwise.

toString

public String toString()

Overrides:

toString in class Object

setMarkedForUpdate

public void setMarkedForUpdate(boolean mark)

Description copied from interface: XInclusion

Mark this inclusion for update.

Application code does this to signal the XIncluded that the included nodes attached to this XInclusion need to be ``refreshed''.

Specified by:

setMarkedForUpdate in interface XInclusion

isMarkedForUpdate

public boolean isMarkedForUpdate()

Description copied from interface: XInclusion

Returns true if this XInclusion has been marked for update using XInclusion.setMarkedForUpdate(boolean); false otherwise

This method is exclusively for use by the XIncluder.

Specified by:

isMarkedForUpdate in interface XInclusion

include

public Node[] include(Node firstNode,
                      Node lastNode,
                      boolean updating,
                      XInclusionContext context)
               throws InclusionException

Description copied from interface: XInclusion

Creates and returns the included nodes corresponding to this XInclusion.

Specified by:

include in interface XInclusion

Parameters:

firstNode - first node to be replaced by those returned by this method.

lastNode - last node to be replaced by those returned by this method.

firstNode and lastNode specify a node range attached to the document tree.

updating - if true, firstNode and lastNode specify an included node range to be replaced by a more up-to-date included node range. If false, firstNode and lastNode specify an inclusion directive to be replaced by an included node range.

Returns:

a non-empty array containing included nodes.

Included nodes are copies of some ``original nodes''.

These copies are not always clones of the original nodes (e.g. DITA conref).

The returned nodes must each have a Constants.SOURCE_URL_PROPERTY property properly set.

On the other hand, adding the Constants.INCLUSION_PROPERTY and Constants.READ_ONLY_PROPERTY properties to returned nodes is not useful.

Throws:

InclusionException - if this XInclusion fails to locate the original nodes

uninclude

public Node[] uninclude(Node firstIncludedNode,
                        Node lastIncludedNode)

Description copied from interface: XInclusion

Creates and returns one or more nodes acting as the inclusion directive which allows to obtain specified nodes.

For example, if this XInclusion is an XInclude, this method returns an <xi:include> element having the proper attributes.

Specified by:

uninclude in interface XInclusion

Parameters:

firstIncludedNode - first node in the included node range having this XInclusion object as its Constants.INCLUSION_PROPERTY property. This node is attached to the document being processed.

lastIncludedNode - last node in the included node range having this XInclusion object as its Constants.INCLUSION_PROPERTY property This node, a sibling of lastIncludedNode, is also attached to the document being processed.

Returns:

one or more nodes acting as the inclusion directive of this XInclusion object

toClipboardForm

public String toClipboardForm()

Description copied from interface: Inclusion

Returns a parseable string representation of this inclusion.

Specified by:

toClipboardForm in interface Inclusion

getSourceURL

public URL getSourceURL(Node inclusionHolder)

Description copied from interface: SimpleInclusion

Returns the URL of document from which the nodes have been included. May return null (e.g. unresolved DITA conkeyref).

Specified by:

getSourceURL in interface SimpleInclusion

Parameters:

inclusionHolder - one of the included nodes, that is, one of the nodes having an INCLUSION_PROPERTY property pointing to this SimpleInclusion.

Generally this parameter is not used.

getSourceNodes

public Node[] getSourceNodes(Document sourceDocument,
                             Node inclusionHolder)
                      throws InclusionException

Description copied from interface: SimpleInclusion

Returns the original nodes. Included nodes are copies, possibly modified (e.g. DITA conref), of these original nodes.

Specified by:

getSourceNodes in interface SimpleInclusion

Parameters:

sourceDocument - the document containing the original nodes.

The URL of this document is returned by SimpleInclusion.getSourceURL(com.xmlmind.xml.doc.Node).

inclusionHolder - one of the included nodes, that is, one of the nodes having an INCLUSION_PROPERTY property pointing to this SimpleInclusion.

Generally this parameter is not used.

Returns:

a non-empty array containing original nodes.

Throws:

InclusionException - if this SimpleInclusion fails to locate the original nodes

copySourceNodes

public Node[] copySourceNodes(Node firstNode,
                              Node lastNode)

Description copied from interface: SimpleInclusion

Returns nodes to be included, which are copies, as is (XInclude 1.0) or modified (DITA Conref, XInclude 1.1), of specified source nodes.

This method is needed to implement the copyAsInclusion command.

Specified by:

copySourceNodes in interface SimpleInclusion

Parameters:

firstNode - first source node represented by this inclusion object

lastNode - last source node represented by this inclusion object

firstNode and lastNode specify a node range which is attached to the document tree. None of these nodes has already been included.

Returns:

a copy of specified node range

toHref

public static String toHref(NodeIterator nodeIter)