org.newsml.toolkit
Interface NewsComponent

All Superinterfaces:

BaseNode, CatalogNode, CommentNode, EquivalentNode, IdNode, LanguageNode

public interface NewsComponent

extends BaseNode, CatalogNode, CommentNode, EquivalentNode, IdNode, LanguageNode

Container for specifying role information and metadata for news objects.

A news component is a branch in the NewsML content tree. A news component may contain zero or more members, and the members may function as complements or equivalents (see the getEquivalentsList() method).

A member of a NewsComponent may be a NewsItem, a reference to a NewsItem, another NewsComponent, or a ContentItem. If a news component has more than one member and they are flagged as equivalents, then the getBasisForChoice(int) method specifies the criteria for choosing among the alternatives. It is also possible to have a NewsComponent with no members (say, to transmit NewsLines alone).

Version:

2.0

Author:

Reuters PLC

Method Summary

AdministrativeMetadata	getAdministrativeMetadata() Get administrative information for the news component.
BasisForChoice[]	getBasisForChoice() Get all BasisForChoice children in an array.
BasisForChoice	getBasisForChoice(int index) Get the basis for choosing among equivalent members.
int	getBasisForChoiceCount() Get the number of bases for choice.
DescriptiveMetadata	getDescriptiveMetadata() Get descriptive information about the news component.
Text	getEquivalentsList() Test whether the members of this component are equivalents.
Text	getEssential() Test whether the provider has flagged this component as essential.
EquivalentNode[]	getMember() Get all Member children in an array.
EquivalentNode	getMember(int index) Return one of the members of this news component.
int	getMemberCount() Get the number of members in this news component.
Metadata[]	getMetadata() Get all Metadata children in an array.
Metadata	getMetadata(int index) Get generic metadata about the news component.
int	getMetadataCount() Get the number of generic metadata objects present.
NewsLines	getNewsLines() Get a news component's headline, byline, etc.
BasisForChoice[]	getRankedBasisForChoice() Get all BasisForChoice children, sorted by rank.
RightsMetadata	getRightsMetadata() Get rights information for the news component.
FormalName	getRole() Get the role of this component in a parent component.
TopicSet[]	getTopicSet() Get all TopicSet children in an array.
TopicSet	getTopicSet(int index) Get a topic set attached to this component.
int	getTopicSetCount() Get the number of topic sets.

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

getCatalog

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

Methods inherited from interface org.newsml.toolkit.LanguageNode

getLang

Method Detail

getEssential

public Text getEssential()

Test whether the provider has flagged this component as essential.

An essential flag indicates that the provider considers this component necessary to the understanding of the story; otherwise, the component may safely be omitted.

To test this property as a boolean, use the Text.toBoolean() method in the Text object returned.

Returns:

Text containing the word 'yes' if this node is essential, or 'no' otherwise (or null if unspecified, which means default to 'no').

getEquivalentsList

public Text getEquivalentsList()

Test whether the members of this component are equivalents. If the members are equivalent, then the user should choose among them using the criteria specified by getBasisForChoice(int).

Returns:

Text containing the word 'yes' if the members of this component are equivalent versions of the same information, or 'no' otherwise (or null if unspecified, which means default to 'no').

See Also:

getMember(int), getBasisForChoice(int)

getTopicSetCount

public int getTopicSetCount()

Get the number of topic sets.

Returns:

The number of topic sets present.

getTopicSet

public TopicSet getTopicSet(int index)

Get a topic set attached to this component.

Parameters:

index - The index of the topic set, zero-based, numbered sequentially in document order.

Returns:

The topic set, or null if none was provided at the specified index.

getTopicSet

public TopicSet[] getTopicSet()

Get all TopicSet children in an array.

Returns:

A (possibly-empty) array of TopicSet children.

getRole

public FormalName getRole()

Get the role of this component in a parent component. When a news component contains one or more subcomponents that are not equivalent, the role property specifies how they should be used together.

Returns:

A formal name representing the component's role, or null if none was specified.

See Also:

getEquivalentsList()

getBasisForChoiceCount

public int getBasisForChoiceCount()

Get the number of bases for choice.

Returns:

The number of bases for choice.

getBasisForChoice

public BasisForChoice getBasisForChoice(int index)

Get the basis for choosing among equivalent members. If the news component contains more than one equivalent member, this method specifies what information an application should examine for choosing among the members. The return value is an XPath expression, which may be tricky for applications to use; it may be advisable to obtain a fixed list of XPath expressions from your news provider and treat them as enumerated values.

Parameters:

index - The index of the basis for choice, zero-based, in sequential order.

Returns:

An XPath expression representing the basis for choice, or null if none was specified with the current index.

See Also:

getEquivalentsList(), getMember(int)

getBasisForChoice

public BasisForChoice[] getBasisForChoice()

Get all BasisForChoice children in an array.

Returns:

A (possibly-empty) array of BasisForChoice children.

getRankedBasisForChoice

public BasisForChoice[] getRankedBasisForChoice()

Get all BasisForChoice children, sorted by rank.

The entries will be arranged first by the value of the BasisForChoice 'rank' attribute (treating no value as the lowest possible rank), and then, in document order.

Returns:

An array of all BasisForChoice children, sorted by rank from least to most important.

getNewsLines

public NewsLines getNewsLines()

Get a news component's headline, byline, etc. The news lines represent human-readable information about the content, including the headline and subheadline, dateline, byline, rights line, and other information.

Returns:

An object containing the news lines for the component, or null if none was specified.

getAdministrativeMetadata

public AdministrativeMetadata getAdministrativeMetadata()

Get administrative information for the news component. Administrative information includes the providers, creators, sources, and contributors, among other information.

Returns:

An object containing the administrative metadata for the component, or null if none was provided.

See Also:

getRightsMetadata(), getDescriptiveMetadata(), getMetadata(int)

getRightsMetadata

public RightsMetadata getRightsMetadata()

Get rights information for the news component. Rights information includes copyright and usage rights.

Returns:

An object containing the rights metadata for the component, or null if none was provided.

See Also:

getAdministrativeMetadata(), getDescriptiveMetadata(), getMetadata(int)

getDescriptiveMetadata

public DescriptiveMetadata getDescriptiveMetadata()

Get descriptive information about the news component. Descriptive information includes the language, genre, and subject codes, among other information.

Returns:

An object containing the descriptive metadata for the component, or null if none was provided.

See Also:

getAdministrativeMetadata(), getRightsMetadata(), getMetadata(int)

getMetadataCount

public int getMetadataCount()

Get the number of generic metadata objects present.

Returns:

The number of generic metadata objects present.

getMetadata

public Metadata getMetadata(int index)

Get generic metadata about the news component. This information includes metadata not classified as administrative, rights-related, or descriptive. There may be multiple generic metadata sections, each containing a related group of information.

Parameters:

index - The index of the generic metadata, zero-based, numbered sequentially.

Returns:

An object containing the generic metadata, or null if none was provided at the specified index.

getMetadata

public Metadata[] getMetadata()

Get all Metadata children in an array.

Returns:

A (possibly-empty) array of Metadata children.

getMemberCount

public int getMemberCount()

Get the number of members in this news component.

Returns:

The number of members.

getMember

public EquivalentNode getMember(int index)

Return one of the members of this news component. The members of the component will be all news components, all content items, or a mixture of news items and references to news items.

Parameters:

index - The index of the member, zero-based, numbered sequentially.

Returns:

The member or null if no member was provided at the specified index.

getMember

public EquivalentNode[] getMember()

Get all Member children in an array.

Returns:

A (possibly-empty) array of Member children.