org.newsml.toolkit
Interface NewsItemRef

All Superinterfaces:

BaseNode, CommentNode, EquivalentNode, IdNode

public interface NewsItemRef

extends BaseNode, CommentNode, EquivalentNode, IdNode

A reference to a news item located elsewhere.

This class represents a cross-link in the NewsML content tree. Instead of including a NewsItem physically, the content tree may include a pointer to it; the pointer may point to another news item within the same package, or it may point to an external news item using a URL reference.

Version:

2.0

Author:

Reuters PLC

Method Summary

Text	getRef() Get the reference string.
NewsItem	getReferencedNewsItem(boolean useExternal) Get the referenced NewsItem, if possible.

Methods inherited from interface org.newsml.toolkit.BaseNode

getAttr, getChild, getChild, getChild, getChild, getChildCount, getChildCount, getParent, getPath, getSession, getXMLName, getXPath, insertAfter, insertAfter, insertAfter, insertAfter, insertAfterDuid, insertAfterDuid, insertBefore, insertBefore, insertBefore, insertBefore, insertBeforeDuid, insertBeforeDuid, insertChild, insertChild, insertFirst, insertFirst, insertLast, insertLast, removeChild, removeChild, removeSelf, replaceChild, replaceChild, replaceChild, replaceChild, replaceChild, replaceChild, setAttr, setAttr, toXML, toXML, unsetAttr, unsetAttr, writeXML, writeXML

Methods inherited from interface org.newsml.toolkit.CommentNode

getComment, getComment, getCommentCount

Methods inherited from interface org.newsml.toolkit.EquivalentNode

getBasisForChoiceNodes

Methods inherited from interface org.newsml.toolkit.IdNode

getDuid, getEuid

Method Detail

getRef

public Text getRef()

Get the reference string. If this is an internal reference, the reference string will consist of the character '#' followed by the Duid of the news item in the current document; otherwise, the value is either a NewsML URN or a URL referring to an external resource.

Returns:

Text containing the reference string, or null if none was provided.

getReferencedNewsItem

public NewsItem getReferencedNewsItem(boolean useExternal)
                               throws IOException

Get the referenced NewsItem, if possible.

This method will fail for a NewsML URN, but might succeed for an internal reference (beginning with '#') or a URL, depending on whether the target is available.

The URL must point either to a specific NewsItem or to a NewsML package. If the URL points to a complete NewsML package, the first NewsItem in the document will be returned; if that is not what you want, use a fragment identifier to point to the Duid of a different NewsItem.

For any other situations, you can still get a non-URN referenced resource easily using NewsMLSession.findReference(java.lang.String, boolean) in the NewsMLSession (see BaseNode.getSession()).

Parameters:

useExternal - Follow links outside of the current document.

Returns:

A NewsItem, or null if no reference was provided.

Throws:

IOException - If there is an error retrieving the news item.

NewsMLException - If the external document is retrieved successfully but does not have a root element type of NewsML or NewsItem.