org.newsml.toolkit
Interface NewsComponent

All Superinterfaces:
BaseNode, CatalogNode, CommentNode, IdNode, LanguageNode, PrimaryNode

public interface NewsComponent
extends BaseNode, CatalogNode, CommentNode, IdNode, LanguageNode, PrimaryNode

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 isEquivalentsList() 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:
1.0
Author:
Reuters PLC

Fields inherited from interface org.newsml.toolkit.PrimaryNode
CONTENT_ITEM, NEWS_COMPONENT, NEWS_ITEM, NEWS_ITEM_REF, NEWSML
 
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.
 PrimaryNode[] getMember()
          Get all Member children in an array.
 PrimaryNode 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.
 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.
 boolean isEquivalentsList()
          Test whether the members of this component are equivalents.
 boolean isEssential()
          Test whether the provider has flagged this component as essential.
 
Methods inherited from interface org.newsml.toolkit.BaseNode
getSession, getXMLName
 
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.IdNode
getDuid, getEuid
 
Methods inherited from interface org.newsml.toolkit.LanguageNode
getLang
 
Methods inherited from interface org.newsml.toolkit.PrimaryNode
asContentItem, asNewsComponent, asNewsItem, asNewsItemRef, asNewsML, getChild, getChild, getChildCount, getNodePath, getParent, getType
 

Method Detail

isEssential

public boolean isEssential()
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.
Returns:
true if this component is flagged as essential, false otherwise.

isEquivalentsList

public boolean isEquivalentsList()
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:
true if the members of this component are equivalent versions of the same information, false otherwise.
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:
isEquivalentsList()

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:
isEquivalentsList(), getMember(int)

getBasisForChoice

public BasisForChoice[] getBasisForChoice()
Get all BasisForChoice children in an array.
Returns:
A (possibly-empty) array of BasisForChoice children.

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 PrimaryNode 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 PrimaryNode[] getMember()
Get all Member children in an array.
Returns:
A (possibly-empty) array of Member children.