christophedelory.rss
Class Item

java.lang.Object
  christophedelory.rss.media.BaseMedia
      christophedelory.rss.Item

public class Item
extends BaseMedia

An item may represent a "story" -- much like a story in a newspaper or magazine; if so its description is a synopsis of the story, and the link points to the full story. An item may also be complete in itself, if so, the description contains the text (entity-encoded HTML is allowed), and the link and title may be omitted. All elements of an item are optional, however at least one of title or description must be present.
RSS Media note:
While both media contents and media groups have no limitations on the number of times they can appear, the general nature of RSS should be preserved: an item represents a "story". Simply stated, this is similar to the blog style of syndication. However, if one is using this module to strictly publish media, there should be one item element for each media object/group. This is to allow for proper attribution for the origination of the media content through the link element. It also allows the full benefit of the other RSS elements to be realized.

Version:

$Revision: 92 $

Author:

Christophe Delory

Constructor Summary

Item()

Method Summary

void	addCategory(Category category) Includes the item in a category.
void	addMediaContent(Content mediaContent) Adds a media content.
void	addMediaGroup(Group mediaGroup) Adds a media group.
String	getAuthor() Returns the email address of the author of the item.
List<Category>	getCategories() Returns a list of one or more item's categories.
Channel	getChannel() Returns the parent channel, if any.
String	getComments() Returns an URL of a page for comments relating to the item.
String	getDescription() Returns the item synopsis. 0.92 allows entity-encoded HTML in the description of an item, to reflect actual practice by bloggers, who are often proficient HTML coders.
Enclosure	getEnclosure() Describes a media object that is attached to the item.
GUID	getGuid() Returns a string that uniquely identifies the item.
URI	getLink() Returns the URL of the item.
String	getLinkString() Returns the URL of the item.
List<Content>	getMediaContents() Returns the list of media contents.
List<Group>	getMediaGroups() Returns the list of media groups.
Date	getPubDate() Indicates when the item was published.
String	getPubDateString() Indicates when the item was published.
Source	getSource() Returns the RSS channel that the item came from.
String	getTitle() Returns the title of the item.
void	setAuthor(String author) Initializes the email address of the author of the item.
(package private) void	setChannel(Channel channel) Initializes the parent channel.
void	setComments(String comments) Initializes an URL of a page for comments relating to the item.
void	setDescription(String description) Initializes the item synopsis.
void	setEnclosure(Enclosure enclosure) Describes a media object that is attached to the item.
void	setGuid(GUID guid) Initializes a string that uniquely identifies the item.
void	setLink(URI link) Initializes the URL of the item.
void	setLinkString(String link) Initializes the URL of the item.
void	setPubDate(Date pubDate) Indicates when the item was published.
void	setPubDateString(String pubDate) Indicates when the item was published.
void	setSource(Source source) Initializes the RSS channel that the item came from.
void	setTitle(String title) Initializes the title of the item.

Methods inherited from class christophedelory.rss.media.BaseMedia

addMediaCategory, addMediaCredit, addMediaHash, addMediaRating, addMediaRestriction, addMediaText, addMediaThumbnail, getMediaAdult, getMediaCategories, getMediaCopyright, getMediaCredits, getMediaDescription, getMediaHashes, getMediaKeywords, getMediaPlayer, getMediaRatings, getMediaRestrictions, getMediaTexts, getMediaThumbnails, getMediaTitle, isMediaAdult, setMediaAdult, setMediaAdult, setMediaCopyright, setMediaDescription, setMediaKeywords, setMediaPlayer, setMediaTitle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Item

public Item()

Method Detail

getTitle

public String getTitle()

Returns the title of the item. In 0.91, title is a required sub-element of item. In 0.92, all sub-elements of item are optional. Why? When a RSS file reflects the content of a weblog or "blog" site, the structure required by previous versions of RSS was often impossible to synthesize. For example, there is no actual limit on the number of links a weblog item can have. Example: "Venice Film Festival Tries to Quit Sinking". No default value.

Returns:

the item's title. May be null.

See Also:

setTitle(java.lang.String)

setTitle

public void setTitle(String title)

Initializes the title of the item.

Parameters:

title - the item's title. May be null.

See Also:

getTitle()

setLinkString

public void setLinkString(String link)
                   throws URISyntaxException

Initializes the URL of the item.

Parameters:

link - an URL as a string. Shall not be null.

Throws:

NullPointerException - if link is null.

URISyntaxException - if the given string violates RFC 2396, as augmented by the URI deviations.

See Also:

getLinkString(), setLink(java.net.URI)

getLinkString

public String getLinkString()

Returns the URL of the item.

Returns:

an URL as a string. May be null.

See Also:

setLinkString(java.lang.String), getLink()

setLink

public void setLink(URI link)

Initializes the URL of the item.

Parameters:

link - an URL. May be null.

See Also:

getLink(), setLinkString(java.lang.String)

getLink

public URI getLink()

Returns the URL of the item. In 0.91, link is a required sub-element of item. In 0.92, all sub-elements of item are optional. Why? When a RSS file reflects the content of a weblog or "blog" site, the structure required by previous versions of RSS was often impossible to synthesize. For example, there is no actual limit on the number of links a weblog item can have. Example: "http://nytimes.com/2004/12/07FEST.html". No default value.

Returns:

an URL. May be null.

See Also:

setLink(java.net.URI), getLinkString()

getDescription

public String getDescription()

Returns the item synopsis. 0.92 allows entity-encoded HTML in the description of an item, to reflect actual practice by bloggers, who are often proficient HTML coders. Example: "Some of the most heated chatter at the Venice Film Festival this week was about the way that the arrival of the stars at the Palazzo del Cinema was being staged.". No default value.

Returns:

the item's description. May be null.

See Also:

setDescription(java.lang.String)

setDescription

public void setDescription(String description)

Initializes the item synopsis.

Parameters:

description - the item's description. May be null.

See Also:

getDescription()

getAuthor

public String getAuthor()

Returns the email address of the author of the item. For newspapers and magazines syndicating via RSS, the author is the person who wrote the article that the item describes. For collaborative weblogs, the author of the item might be different from the managing editor or webmaster. For a weblog authored by a single individual it would make sense to omit the element. Example: "lawyer@boyer.net (Lawyer Boyer)". No default value.

Returns:

the author's email. May be null.

Since:

2.0

See Also:

setAuthor(java.lang.String)

setAuthor

public void setAuthor(String author)

Initializes the email address of the author of the item.

Parameters:

author - the author's email. May be null.

Since:

2.0

See Also:

getAuthor()

getCategories

public List<Category> getCategories()

Returns a list of one or more item's categories. You may include as many category elements as you need to, for different domains, and to have an item cross-referenced in different parts of the same domain. The list is initially empty.

Returns:

a list of categories. May be empty but not null.

Since:

0.92

See Also:

addCategory(christophedelory.rss.Category)

addCategory

public void addCategory(Category category)

Includes the item in a category.

Parameters:

category - an item's category. Shall not be null.

Throws:

NullPointerException - if category is null.

Since:

0.92

See Also:

getCategories()

getComments

public String getComments()

Returns an URL of a page for comments relating to the item. If present, it is the url of the comments page for the item. Example: "http://ekzemplo.com/entry/4403/comments". More about comments here. No default value.

Returns:

an URL as a string. May be null.

Since:

2.0

See Also:

setComments(java.lang.String)

setComments

public void setComments(String comments)

Initializes an URL of a page for comments relating to the item.

Parameters:

comments - an URL as a string. May be null.

Since:

2.0

See Also:

getComments()

getEnclosure

public Enclosure getEnclosure()

Describes a media object that is attached to the item. No default value.

Returns:

a media descriptor. May be null.

Since:

0.92

See Also:

setEnclosure(christophedelory.rss.Enclosure)

setEnclosure

public void setEnclosure(Enclosure enclosure)

Describes a media object that is attached to the item.

Parameters:

enclosure - a media descriptor. May be null.

Since:

0.92

See Also:

getEnclosure()

getGuid

public GUID getGuid()

Returns a string that uniquely identifies the item. A frequently asked question about guids is how do they compare to links. Aren't they the same thing? Yes, in some content systems, and no in others. In some systems, link is a permalink to a weblog item. However, in other systems, each item is a synopsis of a longer article, link points to the article, and guid is the permalink to the weblog entry. In all cases, it's recommended that you provide the guid, and if possible make it a permalink. This enables aggregators to not repeat items, even if there have been editing changes. No default value.

Returns:

a GUID. May be null.

Since:

2.0

See Also:

setGuid(christophedelory.rss.GUID)

setGuid

public void setGuid(GUID guid)

Initializes a string that uniquely identifies the item.

Parameters:

guid - a GUID. May be null.

Since:

2.0

See Also:

getGuid()

setPubDateString

public void setPubDateString(String pubDate)

Indicates when the item was published.

Parameters:

pubDate - a date as a string. Shall not be null.

Throws:

NullPointerException - if pubDate is null.

Since:

2.0

See Also:

getPubDateString(), setPubDate(java.util.Date)

getPubDateString

public String getPubDateString()

Indicates when the item was published.

Returns:

a date as a string. May be null.

Since:

2.0

See Also:

setPubDateString(java.lang.String), getPubDate()

getPubDate

public Date getPubDate()

Indicates when the item was published. Its value is a date, indicating when the item was published. If it's a date in the future, aggregators may choose to not display the item until that date. Example: "Sun, 19 May 2002 15:21:36 GMT". No default value.

Returns:

a date. May be null.

Since:

2.0

See Also:

setPubDate(java.util.Date), getPubDateString()

setPubDate

public void setPubDate(Date pubDate)

Indicates when the item was published.

Parameters:

pubDate - a date. May be null.

Since:

2.0

See Also:

getPubDate(), setPubDateString(java.lang.String)

getSource

public Source getSource()

Returns the RSS channel that the item came from. No default value.

Returns:

the item's source. May be null.

Since:

0.92

See Also:

setSource(christophedelory.rss.Source)

setSource

public void setSource(Source source)

Initializes the RSS channel that the item came from.

Parameters:

source - the item's source. May be null.

Since:

0.92

See Also:

getSource()

addMediaContent

public void addMediaContent(Content mediaContent)

Adds a media content.

Parameters:

mediaContent - a media content. Shall not be null.

Throws:

NullPointerException - if mediaContent is null.

See Also:

getMediaContents()

getMediaContents

public List<Content> getMediaContents()

Returns the list of media contents.

Returns:

a list of media contents. May be empty but not null.

See Also:

addMediaContent(christophedelory.rss.media.Content)

getMediaGroups

public List<Group> getMediaGroups()

Returns the list of media groups.

Returns:

a list of media groups. May be empty but not null.

See Also:

addMediaGroup(christophedelory.rss.media.Group)

addMediaGroup

public void addMediaGroup(Group mediaGroup)

Adds a media group.

Parameters:

mediaGroup - a media group. Shall not be null.

Throws:

NullPointerException - if mediaGroup is null.

See Also:

getMediaGroups()

setChannel

void setChannel(Channel channel)

Initializes the parent channel.

Parameters:

channel - the parent channel. May be null.

See Also:

getChannel()

getChannel

public Channel getChannel()

Returns the parent channel, if any.

Returns:

the parent channel. May be null.