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, TopicSet, TopicSetRef, TopicUse, TransmissionId, UsageRights

public interface BaseNode

Base interface for all NewsML objects.

The base interface provides basic services for navigation and serialization, as well as access to the NewsMLSession, which allows the client application to execute queries against the NewsML object tree.

Version:
1.1beta
Author:
Reuters PLC

Method Summary
 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.
 void removeSelf()
          Remove this node from the NewsML tree.
 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.
 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; in that case, the element will be counted, but invoking this method (or any other getChild method) will return null. Currently, the following XML elements do not map directly to a NewsML Toolkit interface: Delete, InsertAfter, InsertBefore, SizeInBytes (the toolkit treats it as an int), and Update.

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

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.

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.