org.newsml.toolkit
Interface BaseNode

All Known Subinterfaces:

AdministrativeMetadata, AssignedFormalName, AssignedOriginText, AssignedText, BasisForChoice, Catalog, Characteristics, Comment, ContentItem, Copyright, DataContent, DefaultVocabularyFor, Delta, Description, DescriptiveMetadata, Encoding, EquivalentNode, FormalName, FormalNameDecl, Identification, IdText, Instruction, Label, Metadata, NewsComponent, NewsEnvelope, NewsIdentifier, NewsItem, NewsItemId, NewsItemRef, NewsLine, NewsLines, NewsManagement, NewsML, OfInterestTo, Origin, OriginNode, OriginText, Party, PartyList, Property, ProviderId, Resource, RevisionHistory, RevisionId, RevisionStatus, RightsMetadata, SourceList, StatusWillChange, SubjectCode, Text, Topic, TopicOccurrence, TopicSet, TopicSetRef, TopicUse, TransmissionId, Update, UsageRights

public interface BaseNode

Base interface for all NewsML objects.

The base interface provides basic services for navigation, modification, and serialization, as well as access to the NewsMLSession, which allows the client application to execute queries against the NewsML object tree. All NewsML nodes implement this interface, directly or indirectly.

For navigation, the primitive methods are getChildCount(), getChild(int), getParent(), and getAttr(String). For modification, the primitive methods are insertChild(int,BaseNode), replaceChild(int,BaseNode), removeChild(int), setAttr(Text), and unsetAttr(Text). There are also many derived methods for convenience.

Version:

2.0

Author:

Reuters PLC

Method Summary

Text	getAttr(String xmlName) Get an attribute-based node by name.
BaseNode[]	getChild() Get an array of child nodes.
BaseNode	getChild(int index) Get a child of the node by position.
BaseNode[]	getChild(String xmlName) Get an array of child nodes with the specified XML name.
BaseNode	getChild(String xmlName, int index) Get a child of the node by name and position.
int	getChildCount() Count the children for this node.
int	getChildCount(String xmlName) Count the children with the specified name.
BaseNode	getParent() Get the parent of the node in the NewsML content tree.
BaseNode[]	getPath() Get the path from the root node to this node.
NewsMLSession	getSession() Get the NewsML session associated with the package.
String	getXMLName() Get the XML element name associated with the node.
String	getXPath() Get the XPath from the document root to this node.
BaseNode	insertAfter(String xmlName, BaseNode child) Insert a new child after an existing named child.
BaseNode[]	insertAfter(String xmlName, BaseNode[] children) Insert new child nodes after the last existing named child.
BaseNode	insertAfter(String xmlName, int index, BaseNode child) Insert a new child after an existing named child.
BaseNode[]	insertAfter(String xmlName, int index, BaseNode[] children) Insert an array of child nodes after a named node.
BaseNode	insertAfterDuid(String duid, BaseNode child) Insert a new child after one with a specific Duid.
BaseNode[]	insertAfterDuid(String duid, BaseNode[] children) Insert new child nodes after one with a specific Duid.
BaseNode	insertBefore(String xmlName, BaseNode child) Insert a new child before the first existing named child.
BaseNode[]	insertBefore(String xmlName, BaseNode[] children) Insert an array of child nodes before the first named node.
BaseNode	insertBefore(String xmlName, int index, BaseNode child) Insert a new child before an existing named child.
BaseNode[]	insertBefore(String xmlName, int index, BaseNode[] children) Insert an array of child nodes before a named node.
BaseNode	insertBeforeDuid(String duid, BaseNode child) Insert a new child before one with a specific Duid.
BaseNode[]	insertBeforeDuid(String duid, BaseNode[] children) Insert new child nodes before one with a specific Duid.
BaseNode	insertChild(int index, BaseNode child) Insert a new child into the node.
BaseNode[]	insertChild(int index, BaseNode[] children) Insert an array of new children into the node.
BaseNode	insertFirst(BaseNode child) Insert a new child before all existing children (prepend).
BaseNode[]	insertFirst(BaseNode[] children) Insert new child nodes before all existing children (prepend).
BaseNode	insertLast(BaseNode child) Insert a new child after all existing children (append).
BaseNode[]	insertLast(BaseNode[] children) Insert new child nodes after all existing children (append).
BaseNode	removeChild(int index) Remove a child of this node.
BaseNode	removeChild(String xmlName, int index) Remove an existing child node.
void	removeSelf() Remove this node from the NewsML tree.
BaseNode	replaceChild(int index, BaseNode child) Replace an existing child with another node.
BaseNode	replaceChild(int index, BaseNode[] children) Replace an existing child with an array of nodes.
BaseNode	replaceChild(String xmlName, BaseNode child) Replace the first named child node.
BaseNode	replaceChild(String xmlName, BaseNode[] children) Replace the first named child node with an array of nodes.
BaseNode	replaceChild(String xmlName, int index, BaseNode child) Replace a named child node.
BaseNode	replaceChild(String xmlName, int index, BaseNode[] children) Replace a named child node with an array of nodes.
Text	setAttr(String name, String value) Set an attribute value directly from a string.
Text	setAttr(Text attr) Set an attribute-based node, replacing any existing value.
String	toXML(boolean isDocument) Get an XML rendition of this node.
String	toXML(String encoding, String internalSubset) Get an XML document rendition of this node.
Text	unsetAttr(String name) Remove an attribute by name.
Text	unsetAttr(Text attr) Unset an attribute-based node.
void	writeXML(Writer output, boolean isDocument) Serialize this node as XML.
void	writeXML(Writer output, String encoding, String internalSubset) Serialize a node as an XML document.

Method Detail

getXMLName

public String getXMLName()

Get the XML element name associated with the node.

Returns:

The XML element name associated with the node, or null if there is none.

getXPath

public String getXPath()

Get the XPath from the document root to this node.

Returns:

an XPath to this node.

getSession

public NewsMLSession getSession()

Get the NewsML session associated with the package.

Returns:

The session (not null).

getParent

public BaseNode getParent()

Get the parent of the node in the NewsML content tree.

Returns:

The parent node, or null if this is the root.

See Also:

getChild(int)

getChildCount

public int getChildCount()

Count the children for this node.

See getChild(int) for information on what is and is not counted as a child here.

Returns:

The number of children.

See Also:

getChildCount(String)

getChildCount

public int getChildCount(String xmlName)

Count the children with the specified name.

See getChild(int) for information on what is and is not counted as a child here.

Parameters:

xmlName - The XML name of the children to count.

Returns:

The number of children with the XML name specified.

See Also:

getXMLName(), getChildCount()

getChild

public BaseNode getChild(int index)

Get a child of the node by position.

This method uses the XML notion of parent/child, not the NewsML notion. That difference can matter quite a bit; for example, while the get* methods for information in subelements and information in attributes are indistinguishable in the NewsML Toolkit API, this method will deal only with the element children.

Some elements in the XML are not represented directly in the NewsML toolkit, such as the content of the DataContent element; in that case, the element will not be counted as a child.

Since the result of invoking this method can be unpredictable in so many ways, it is recommend to use the named getChild(String, int) method whenever possible.

Parameters:

index - The index of the child, zero-based, numbered sequentially, or -1 for the last child.

Returns:

The node representing the specified child, or null if none is available at the index provided.

See Also:

getParent(), getChild(String,int)

getChild

public BaseNode getChild(String xmlName,
                         int index)

Get a child of the node by name and position.

See getChild(int) for information on what is and is not counted as a child here.

Parameters:

xmlName - The XML name of the children to use.

index - The index of the child, zero-based, numbered sequentially, counting only children with the given XML name, or -1 for the last child with the name specified.

Returns:

The node representing the specified child, or null if none is available at the XML name and index provided.

See Also:

getChild(int)

getChild

public BaseNode[] getChild()

Get an array of child nodes.

See getChild(int) for information on what is and is not counted as a child here.

Returns:

A (possibly-empty) array of primary child nodes.

getChild

public BaseNode[] getChild(String xmlName)

Get an array of child nodes with the specified XML name.

See getChild(int) for information on what is and is not counted as a child here.

Parameters:

xmlName - The XML name of the child nodes to return.

Returns:

A (possibly-empty) array of primary child nodes.

insertChild

public BaseNode insertChild(int index,
                            BaseNode child)

Insert a new child into the node.

This method works only for NewsML nodes based on XML elements.

Parameters:

index - If 0 or greater, the position at which to insert the new child (increasing the index of all subsequent children); if -1, insert the child at the end of the existing children.

child - The new node to add.

Returns:

The child that has been inserted.

See Also:

insertChild(int,BaseNode[])

insertChild

public BaseNode[] insertChild(int index,
                              BaseNode[] children)

Insert an array of new children into the node.

This method works only for NewsML nodes based on XML elements.

Parameters:

index - If 0 or greater, the position at which to insert the new children (increasing the index of all subsequent children); if -1, insert the child at the end of the existing children.

children - An array of new nodes to add.

Returns:

The array of child nodes that have been inserted.

See Also:

insertChild(int,BaseNode)

insertFirst

public BaseNode insertFirst(BaseNode child)

Insert a new child before all existing children (prepend).

Parameters:

child - The new child to insert in the first position.

Returns:

The new child inserted.

insertFirst

public BaseNode[] insertFirst(BaseNode[] children)

Insert new child nodes before all existing children (prepend).

Parameters:

children - The new child nodes to insert in the first position.

Returns:

The new children inserted.

insertLast

public BaseNode insertLast(BaseNode child)

Insert a new child after all existing children (append).

Parameters:

child - The new child to insert in the last position.

Returns:

The new child inserted.

insertLast

public BaseNode[] insertLast(BaseNode[] children)

Insert new child nodes after all existing children (append).

Parameters:

children - The new child nodes to insert in the last position.

Returns:

The new children inserted.

insertBefore

public BaseNode insertBefore(String xmlName,
                             int index,
                             BaseNode child)

Insert a new child before an existing named child.

Parameters:

xmlName - The XML name of the existing child.

index - The index of the existing child relative to others with the same name, or -1 for the last one.

child - The new child to insert before the existing one.

Returns:

The new child inserted, or null if no existing child could be found.

insertBefore

public BaseNode insertBefore(String xmlName,
                             BaseNode child)

Insert a new child before the first existing named child.

Parameters:

xmlName - The XML name of the existing child.

child - The new child to insert before the existing one.

Returns:

The new child inserted, or null if no existing child could be found.

insertBefore

public BaseNode[] insertBefore(String xmlName,
                               int index,
                               BaseNode[] children)

Insert an array of child nodes before a named node.

Parameters:

xmlName - The name of the existing node.

index - The index of the existing node, relative to other nodes with the same name, or -1 for the last one.

children - The array of child nodes to insert before the existing one.

Returns:

The array of child nodes inserted, or null if the existing node could not be found.

insertBefore

public BaseNode[] insertBefore(String xmlName,
                               BaseNode[] children)

Insert an array of child nodes before the first named node.

Parameters:

xmlName - The name of the existing node.

children - The array of child nodes to insert before the existing one.

Returns:

The array of child nodes inserted, or null if the existing node could not be found.

insertBeforeDuid

public BaseNode insertBeforeDuid(String duid,
                                 BaseNode child)

Insert a new child before one with a specific Duid.

Note that this method works only on the immediate children of a node; it does not search the entire document for the Duid required (see NewsMLSession.getNodeByDuid(String)).

Parameters:

Duid - the Duid of the existing child.

child - The new child to insert before the existing one.

Returns:

The new child inserted, or null if no child was found with the Duid specified.

insertBeforeDuid

public BaseNode[] insertBeforeDuid(String duid,
                                   BaseNode[] children)

Insert new child nodes before one with a specific Duid.

Note that this method works only on the immediate children of a node; it does not search the entire document for the Duid required (see NewsMLSession.getNodeByDuid(String)).

Parameters:

Duid - the Duid of the existing child.

children - The new child nodes to insert before the existing one.

Returns:

The new children inserted, or null if no child was found with the Duid specified.

insertAfter

public BaseNode insertAfter(String xmlName,
                            int index,
                            BaseNode child)

Insert a new child after an existing named child.

Parameters:

xmlName - The XML name of the existing child.

index - The index of the existing child relative to others with the same name, or -1 for the last one.

child - The new child to insert after the existing one.

Returns:

The new child inserted, or null if no existing child could be found.

insertAfter

public BaseNode insertAfter(String xmlName,
                            BaseNode child)

Insert a new child after an existing named child.

Parameters:

xmlName - The XML name of the existing child.

child - The new child to insert after the existing one.

Returns:

The new child inserted, or null if no existing child could be found.

insertAfter

public BaseNode[] insertAfter(String xmlName,
                              int index,
                              BaseNode[] children)

Insert an array of child nodes after a named node.

Parameters:

xmlName - The name of the existing node.

index - The index of the existing node, relative to other nodes with the same name, or -1 for the last one.

children - The array of child nodes to insert after the existing one.

Returns:

The array of child nodes inserted, or null if the existing node could not be found.

insertAfter

public BaseNode[] insertAfter(String xmlName,
                              BaseNode[] children)

Insert new child nodes after the last existing named child.

Parameters:

xmlName - The XML name of the existing child.

children - The new child nodes to insert before the existing one.

Returns:

The new child nodes inserted, or null if no existing child could be found.

insertAfterDuid

public BaseNode insertAfterDuid(String duid,
                                BaseNode child)

Insert a new child after one with a specific Duid.

Note that this method works only on the immediate children of a node; it does not search the entire document for the Duid required (see NewsMLSession.getNodeByDuid(String)).

Parameters:

Duid - the Duid of the existing child.

child - The new child to insert after the existing one.

Returns:

The new child inserted, or null if no child was found with the Duid specified.

insertAfterDuid

public BaseNode[] insertAfterDuid(String duid,
                                  BaseNode[] children)

Insert new child nodes after one with a specific Duid.

Note that this method works only on the immediate children of a node; it does not search the entire document for the Duid required (see NewsMLSession.getNodeByDuid(String)).

Parameters:

Duid - the Duid of the existing child.

children - The new child nodes to insert after the existing one.

Returns:

The new child nodes inserted, or null if no child was found with the Duid specified.

replaceChild

public BaseNode replaceChild(int index,
                             BaseNode child)

Replace an existing child with another node.

This method works only for NewsML nodes based on XML elements.

Parameters:

index - The position of the child to replace, or -1 for the last child.

child - The new child to be inserted.

Returns:

The child that has been replaced.

replaceChild

public BaseNode replaceChild(int index,
                             BaseNode[] children)

Replace an existing child with an array of nodes.

This method works only for NewsML nodes based on XML elements.

Parameters:

index - The position of the child to replace, or -1 for the last child.

children - The new child nodes to be inserted.

Returns:

The child that has been replaced.

replaceChild

public BaseNode replaceChild(String xmlName,
                             int index,
                             BaseNode child)

Replace a named child node.

Parameters:

xmlName - The name of the child node to replace.

index - The index of the existing child node relative to others with the same name, or -1 for the last one.

child - The new replacement child.

Returns:

The old child replaced, or null if none was found.

See Also:

replaceChild(int,BaseNode)

replaceChild

public BaseNode replaceChild(String xmlName,
                             BaseNode child)

Replace the first named child node.

Parameters:

xmlName - The name of the child node to replace.

child - The new replacement child.

Returns:

The old child replaced, or null if none was found.

See Also:

replaceChild(int,BaseNode)

replaceChild

public BaseNode replaceChild(String xmlName,
                             int index,
                             BaseNode[] children)

Replace a named child node with an array of nodes.

Parameters:

xmlName - The name of the child node to replace.

index - The index of the existing child node relative to others with the same name, or -1 for the last one.

children - An array of nodes to replace the node.

Returns:

The old child replaced, or null if none was found.

See Also:

replaceChild(int,BaseNode)

replaceChild

public BaseNode replaceChild(String xmlName,
                             BaseNode[] children)

Replace the first named child node with an array of nodes.

Parameters:

xmlName - The name of the child node to replace.

children - An array of nodes to replace the node.

Returns:

The old child replaced, or null if none was found.

See Also:

replaceChild(int,BaseNode)

removeChild

public BaseNode removeChild(int index)

Remove a child of this node.

This method works only for NewsML nodes based on XML elements.

Parameters:

index - The index of the child to remove, or -1 for the last child.

Returns:

The child that has been removed, or null if no such child was present.

removeChild

public BaseNode removeChild(String xmlName,
                            int index)

Remove an existing child node.

Parameters:

xmlName - The name of the child node to remove.

index - The index of the child node to remove releative to others with the same name, or -1 for the last one.

Returns:

The child removed, or null if none was found.

See Also:

removeChild(int)

removeSelf

public void removeSelf()
                throws NewsMLException

Remove this node from the NewsML tree.

WARNING: removing a node may result in an invalid NewsML tree. Don't use this method unless you know what you're doing.

This method will work for nodes represented as XML elements, but not for nodes represented as XML attributes. It will also fail for the root node of the NewsML tree (often, but not always "NewsML") and will throw a NewsMLException for all failures.

If the implementation does not support modification, it may also throw an exception.

Throws:

NewsMLException - if the implementation cannot remove this node for any reason.

getAttr

public Text getAttr(String xmlName)

Get an attribute-based node by name.

Parameters:

xmlName - The XML name of the attribute (with the leading '@').

Returns:

The node representing the specified attribute, or null if none is available with the XML name specified.

setAttr

public Text setAttr(Text attr)

Set an attribute-based node, replacing any existing value.

Parameters:

node - A BaseNode based on an XML attribute.

Returns:

The former attribute node with the same XML name, or null if there was none.

setAttr

public Text setAttr(String name,
                    String value)

Set an attribute value directly from a string.

This method invokes the Text.setString(String) method on the Text node associated with the named attribute, creating the Text node first if necessary.

Parameters:

name - The XML name of the attribute, including leading '@'.

value - The string value of the attribute.

Returns:

The Text node representing the attribute (not the former attribute node, as with setAttr(Text).

See Also:

setAttr(Text), unsetAttr(String)

unsetAttr

public Text unsetAttr(Text attr)

Unset an attribute-based node.

Parameters:

node - A BaseNode based on an XML attribute. The value doesn't matter; only the XML name will be used.

Returns:

The node that was removed, or null if the attribute was not already present.

unsetAttr

public Text unsetAttr(String name)

Remove an attribute by name.

This method removes any attribute with the name specified.

Parameters:

name - The name of the attribute to remove.

Returns:

The Text node of the attribute removed, or null if there was none present.

See Also:

unsetAttr(Text), setAttr(String,String)

getPath

public BaseNode[] getPath()

Get the path from the root node to this node.

Returns:

An array of nodes beginning with the root BaseNode and ending with the current BaseNode.

writeXML

public void writeXML(Writer output,
                     boolean isDocument)
              throws IOException

Serialize this node as XML.

This method will create XML markup representing the current node and all of its descendants. It will not reproduct the original XML markup character-for-character, but will create a structurally-equivalent version. The method works on the raw XML level, and has no specialized knowledge of Namespaces (yet).

Parameters:

output - The character stream to which the XML should be written (this method will not close the stream).

isDocument - True if this node is to represent a complete XML document (with DOCTYPE declaration and prolog), false otherwise.

Throws:

IOException - if there is an error writing the document.

See Also:

toXML(boolean)

writeXML

public void writeXML(Writer output,
                     String encoding,
                     String internalSubset)
              throws IOException

Serialize a node as an XML document.

This method serializes a NewsML node like writeXML(Writer,boolean), except that the node is always made into a full XML docuument, and that the provided character encoding and internal DTD subset will be used in place of the defaults.

Parameters:

output - The character stream to which the XML should be written (this method will not close the stream).

encoding - The encoding string to be used in the XML declaration, or null to use the default. Note that this will not affect the encoding actually used by the Writer -- it is the application's responsibility to ensure that the two correspond.

internalSubset - The internal DTD subset to use, the empty string for an empty subset, or null to use the default.

See Also:

toXML(String,String)

toXML

public String toXML(boolean isDocument)

Get an XML rendition of this node.

See writeXML(Writer,boolean) for information on the serialization.

Parameters:

isDocument - True if this node is to represent a complete XML document (with DOCTYPE declaration and prolog), false otherwise.

Returns:

A string containing an XML rendition of the node.

See Also:

writeXML(Writer,boolean)

toXML

public String toXML(String encoding,
                    String internalSubset)

Get an XML document rendition of this node.

See writeXML(Writer,String,String) for details.

Parameters:

encoding - The encoding to include in the XML declaration, or null to use the default.

internalSubset - The internal DTD subset to use, the empty string for an empty subset, or null to use the default.

Returns:

A string containing an XML document.