All Downloads are FREE. Search and download functionalities are using the official Maven repository.

chameleon.rss.Channel Maven / Gradle / Ivy

The newest version!
/*
 * Copyright (c) 2008, Christophe Delory
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *   * Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY CHRISTOPHE DELORY ``AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL CHRISTOPHE DELORY BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package chameleon.rss;

import java.net.URI;
import java.net.URISyntaxException;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

import chameleon.rss.media.BaseMedia;

/**
 * Contains information about the channel (metadata) and its contents.
 * @author Christophe Delory
 * @version $Revision: 92 $
 * @castor.class xml="channel"
 */
public class Channel extends BaseMedia // I don't want regular RSS item to directly extend the group element (Group), as they do not share the same namespace.
{
    /**
     * The name of the channel.
     */
    private String _title = null;

    /**
     * The URL to the HTML website corresponding to the channel.
     */
    private URI _link = null;

    /**
     * Phrase or sentence describing the channel.
     */
    private String _description = null;

    /**
     * The language the channel is written in.
     */
    private String _language = null;

    /**
     * Copyright notice for content in the channel.
     */
    private String _copyright = null;

    /**
     * Email address for person responsible for editorial content.
     */
    private String _managingEditor = null;

    /**
     * Email address for person responsible for technical issues relating to channel.
     */
    private String _webMaster = null;

    /**
     * The publication date for the content in the channel.
     */
    private Date _pubDate = null;

    /**
     * The last time the content of the channel changed.
     */
    private Date _lastBuildDate = null;

    /**
     * Specify one or more categories that the channel belongs to.
     */
    private final List _categories = new ArrayList();

    /**
     * A string indicating the program used to generate the channel.
     */
    private String _generator = null;

    /**
     * An URL that points to the documentation for the format used in the RSS file.
     */
    private String _docs = "http://blogs.law.harvard.edu/tech/rss";

    /**
     * Allows processes to register with a cloud to be notified of updates to the channel, implementing a lightweight publish-subscribe protocol for RSS feeds.
     */
    private Cloud _cloud = null;

    /**
     * It's a number of minutes that indicates how long a channel can be cached before refreshing from the source.
     */
    private Integer _ttl = null;

    /**
     * Specifies a GIF, JPEG or PNG image that can be displayed with the channel.
     */
    private Image _image = null;

    /**
     * The PICS rating for the channel.
     */
    private String _rating = null;

    /**
     * Specifies a text input box that can be displayed with the channel.
     */
    private TextInput _textInput = null;

    /**
     * A hint for aggregators telling them which hours they can skip.
     */
    private final List _skipHours = new ArrayList();

    /**
     * A hint for aggregators telling them which days they can skip.
     */
    private final List _skipDays = new ArrayList();

    /**
     * A channel may contain any number of {@link Item items}.
     */
    private final List _items = new ArrayList();

    /**
     * A reference to the top-level RSS document.
     */
    private transient RSS _rss = null;

    /**
     * Returns the name of the channel.
     * It's how people refer to your service.
     * If you have an HTML website that contains the same information as your RSS file,
     * the title of your channel should be the same as the title of your website.
     * Example: "GoUpstate.com News Headlines".
     * No default value.
     * @return the channel's title. May be null if not yet initialized.
     * @see #setTitle
     * @castor.field
     *  get-method="getTitle"
     *  set-method="setTitle"
     *  required="true"
     * @castor.field-xml
     *  name="title"
     *  node="element"
     */
    public String getTitle()
    {
        return _title;
    }

    /**
     * Initializes the name of the channel.
     * @param title the channel's title. Shall not be null.
     * @throws NullPointerException if title is null.
     * @see #getTitle
     */
    public void setTitle(final String title)
    {
        _title = title.trim(); // Throws NullPointerException if title is null.
    }

    /**
     * Initializes the URL to the HTML website corresponding to the channel.
     * @param link an URL as a string. Shall not be null.
     * @throws NullPointerException if link is null.
     * @throws URISyntaxException if the given string violates RFC 2396, as augmented by the {@link URI} deviations.
     * @see #getLinkString
     * @see #setLink
     */
    public void setLinkString(final String link) throws URISyntaxException
    {
        _link = new URI(link); // May throw NullPointerException, URISyntaxException.
    }

    /**
     * Returns the URL to the HTML website corresponding to the channel.
     * Example: "http://www.goupstate.com/".
     * No default value.
     * @return an URL as a string. Shall not be null.
     * @throws NullPointerException if no URL has been defined for this channel.
     * @see #setLinkString
     * @see #getLink
     * @castor.field
     *  get-method="getLinkString"
     *  set-method="setLinkString"
     *  required="true"
     * @castor.field-xml
     *  name="link"
     *  node="element"
     */
    public String getLinkString()
    {
        return _link.toString(); // Throws NullPointerException if _link is null.
    }

    /**
     * Initializes the URL to the HTML website corresponding to the channel.
     * @param link an URL. Shall not be null.
     * @throws NullPointerException if link is null.
     * @see #getLink
     * @see #setLinkString
     */
    public void setLink(final URI link)
    {
        if (link == null)
        {
            throw new NullPointerException("No link");
        }

        _link = link;
    }

    /**
     * Returns the URL to the HTML website corresponding to the channel.
     * @return an URL. May be null if not yet initialized.
     * @see #setLink
     * @see #getLinkString
     */
    public URI getLink()
    {
        return _link;
    }

    /**
     * Returns the phrase or sentence describing the channel.
     * Example: "The latest news from GoUpstate.com, a Spartanburg Herald-Journal Web site".
     * No default value.
     * @return the channel's description. May be null if not yet initialized.
     * @see #setDescription
     * @castor.field
     *  get-method="getDescription"
     *  set-method="setDescription"
     *  required="true"
     * @castor.field-xml
     *  name="description"
     *  node="element"
     */
    public String getDescription()
    {
        return _description;
    }

    /**
     * Initializes the phrase or sentence describing the channel.
     * @param description the channel's description. Shall not be null.
     * @throws NullPointerException if description is null.
     * @see #getDescription
     */
    public void setDescription(final String description)
    {
        _description = description.trim(); // Throws NullPointerException if description is null.
    }

    /**
     * Returns the language the channel is written in.
     * This allows aggregators to group all Italian language sites, for example, on a single page.
     * A list of allowable values for this element, as provided by Netscape, is here.
     * You may also use values defined by the W3C.
     * In 0.91, the language element is required.
     * In 0.92 it is optional.
     * Why? If a channel is formed from various input sources there's no way to know that it's going to only contain a single language.
     * Example: "en-us".
     * No default value.
     * @return a language. May be null.
     * @see #setLanguage
     * @castor.field
     *  get-method="getLanguage"
     *  set-method="setLanguage"
     * @castor.field-xml
     *  name="language"
     *  node="element"
     */
    public String getLanguage()
    {
        return _language;
    }

    /**
     * Initializes the language the channel is written in.
     * @param language a language. May be null.
     * @see #getLanguage
     */
    public void setLanguage(final String language)
    {
        _language = language;
    }

    /**
     * Returns the copyright notice for content in the channel.
     * Example: "Copyright 2002, Spartanburg Herald-Journal".
     * No default value.
     * @return a copyright notice. May be null.
     * @see #setCopyright
     * @castor.field
     *  get-method="getCopyright"
     *  set-method="setCopyright"
     * @castor.field-xml
     *  name="copyright"
     *  node="element"
     */
    public String getCopyright()
    {
        return _copyright;
    }

    /**
     * Initializes the copyright notice for content in the channel.
     * @param copyright a copyright notice. May be null.
     * @see #getCopyright
     */
    public void setCopyright(final String copyright)
    {
        _copyright = copyright;
    }

    /**
     * Returns the email address for person responsible for editorial content.
     * Example: "[email protected] (George Matesky)".
     * No default value.
     * @return the managing editor email. May be null.
     * @see #setManagingEditor
     * @castor.field
     *  get-method="getManagingEditor"
     *  set-method="setManagingEditor"
     * @castor.field-xml
     *  name="managingEditor"
     *  node="element"
     */
    public String getManagingEditor()
    {
        return _managingEditor;
    }

    /**
     * Initializes the email address for person responsible for editorial content.
     * @param managingEditor the managing editor email. May be null.
     * @see #getManagingEditor
     */
    public void setManagingEditor(final String managingEditor)
    {
        _managingEditor = managingEditor;
    }

    /**
     * Returns the email address for person responsible for technical issues relating to channel.
     * Example: "[email protected] (Betty Guernsey)".
     * No default value.
     * @return the Web master email. May be null.
     * @see #setWebMaster
     * @castor.field
     *  get-method="getWebMaster"
     *  set-method="setWebMaster"
     * @castor.field-xml
     *  name="webMaster"
     *  node="element"
     */
    public String getWebMaster()
    {
        return _webMaster;
    }

    /**
     * Initializes the email address for person responsible for technical issues relating to channel.
     * @param webMaster the Web master email. May be null.
     * @see #getWebMaster
     */
    public void setWebMaster(final String webMaster)
    {
        _webMaster = webMaster;
    }

    /**
     * Initializes the publication date for the content in the channel.
     * @param pubDate a date as a string. Shall not be null.
     * @throws NullPointerException if pubDate is null.
     * @see #getPubDateString
     * @see #setPubDate
     */
    public void setPubDateString(final String pubDate)
    {
        _pubDate = RFC822.valueOf(pubDate); // Throws NullPointerException if pubDate is null.
    }

    /**
     * Returns the publication date for the content in the channel.
     * @return a date as a string. May be null.
     * @see #setPubDateString
     * @see #getPubDate
     * @castor.field
     *  get-method="getPubDateString"
     *  set-method="setPubDateString"
     * @castor.field-xml
     *  name="pubDate"
     *  node="element"
     */
    public String getPubDateString()
    {
        String ret = null;

        if (_pubDate != null)
        {
            ret = RFC822.toString(_pubDate);
        }

        return ret;
    }

    /**
     * Initializes the publication date for the content in the channel.
     * @param pubDate a date. May be null.
     * @see #getPubDate
     * @see #setPubDateString
     */
    public void setPubDate(final Date pubDate)
    {
        _pubDate = pubDate;
    }

    /**
     * Returns the publication date for the content in the channel.
     * For example, the New York Times publishes on a daily basis, the publication date flips once every 24 hours.
     * That's when the pubDate of the channel changes.
     * All date-times in RSS conform to the Date and Time Specification of RFC 822,
     * with the exception that the year may be expressed with two characters or four characters (four preferred).
     * Example: "Sat, 07 Sep 2002 00:00:01 GMT".
     * No default value.
     * @return a date. May be null.
     * @see #setPubDate
     * @see #getPubDateString
     */
    public Date getPubDate()
    {
        return _pubDate;
    }

    /**
     * Initializes the last time the content of the channel changed.
     * @param lastBuildDate a date as a string. Shall not be null.
     * @throws NullPointerException if lastBuildDate is null.
     * @see #getLastBuildDateString
     * @see #setLastBuildDate
     */
    public void setLastBuildDateString(final String lastBuildDate)
    {
        _lastBuildDate = RFC822.valueOf(lastBuildDate); // Throws NullPointerException if lastBuildDate is null.
    }

    /**
     * Returns the last time the content of the channel changed.
     * @return a date as a string. May be null.
     * @see #setLastBuildDateString
     * @see #getLastBuildDate
     * @castor.field
     *  get-method="getLastBuildDateString"
     *  set-method="setLastBuildDateString"
     * @castor.field-xml
     *  name="lastBuildDate"
     *  node="element"
     */
    public String getLastBuildDateString()
    {
        String ret = null;

        if (_lastBuildDate != null)
        {
            ret = RFC822.toString(_lastBuildDate);
        }

        return ret;
    }

    /**
     * Initializes the last time the content of the channel changed.
     * @param lastBuildDate a date. May be null.
     * @see #getLastBuildDate
     * @see #setLastBuildDateString
     */
    public void setLastBuildDate(final Date lastBuildDate)
    {
        _lastBuildDate = lastBuildDate;
    }

    /**
     * Returns the last time the content of the channel changed.
     * Example: "Sat, 07 Sep 2002 09:42:31 GMT".
     * No default value.
     * @return a date. May be null.
     * @see #setLastBuildDate
     * @see #getLastBuildDateString
     */
    public Date getLastBuildDate()
    {
        return _lastBuildDate;
    }

    /**
     * Returns a list of one or more categories that the channel belongs to.
     * In RSS 2.0, a provision is made for linking a channel to its identifier in a cataloging system, using the category feature.
     * For example, to link a channel to its Syndic8 identifier,
     * include a category element as a sub-element of {@link Channel}, with domain "Syndic8",
     * and value the identifier for your channel in the Syndic8 database.
     * The appropriate category element for Scripting News would be <category domain="Syndic8">1765</category>.
     * Example: "Newspapers".
     * The list is initially empty.
     * @return a list of categories. May be empty but not null.
     * @see #addCategory
     * @since 0.92
     * @castor.field
     *  get-method="getCategories"
     *  set-method="addCategory"
     *  type="chameleon.rss.Category"
     *  collection="arraylist"
     * @castor.field-xml
     *  name="category"
     *  node="element"
     */
    public List getCategories()
    {
        return _categories;
    }

    /**
     * Specifies a category that the channel belongs to.
     * @param category a category. Shall not be null.
     * @throws NullPointerException if category is null.
     * @see #getCategories
     * @since 0.92
     */
    public void addCategory(final Category category)
    {
        if (category == null)
        {
            throw new NullPointerException("no category");
        }

        _categories.add(category);
    }

    /**
     * Initializes the string indicating the program used to generate the channel.
     * @param generator the channel's generator. May be null.
     * @see #getGenerator
     * @since 2.0
     */
    public void setGenerator(final String generator)
    {
        _generator = generator;
    }

    /**
     * Returns a string indicating the program used to generate the channel.
     * Example: "MightyInHouse Content System v2.3".
     * No default value.
     * @return the channel's generator. May be null.
     * @see #setGenerator
     * @since 2.0
     * @castor.field
     *  get-method="getGenerator"
     *  set-method="setGenerator"
     * @castor.field-xml
     *  name="generator"
     *  node="element"
     */
    public String getGenerator()
    {
        return _generator;
    }

    /**
     * Initializes the URL that points to the documentation for the format used in the RSS file.
     * @param docs an URL as a string. May be null.
     * @see #getDocs
     */
    public void setDocs(final String docs)
    {
        _docs = docs;
    }

    /**
     * Returns an URL that points to the documentation for the format used in the RSS file.
     * It's probably a pointer to .
     * It's for people who might stumble across an RSS file on a Web server 25 years from now and wonder what it is.
     * Example: "http://blogs.law.harvard.edu/tech/rss".
     * Defaults to "http://blogs.law.harvard.edu/tech/rss".
     * @return an URL as a string. May be null.
     * @see #setDocs
     * @castor.field
     *  get-method="getDocs"
     *  set-method="setDocs"
     * @castor.field-xml
     *  name="docs"
     *  node="element"
     */
    public String getDocs()
    {
        return _docs;
    }

    /**
     * Initializes the RSS cloud descriptor.
     * @param cloud a cloud descriptor. May be null.
     * @see #getCloud
     * @since 0.92
     */
    public void setCloud(final Cloud cloud)
    {
        _cloud = cloud;
    }

    /**
     * Returns a RSS cloud descriptor.
     * Allows processes to register with a cloud to be notified of updates to the channel, implementing a lightweight publish-subscribe protocol for RSS feeds.
     * No default value.
     * @return a cloud descriptor. May be null.
     * @see #setCloud
     * @since 0.92
     * @castor.field
     *  get-method="getCloud"
     *  set-method="setCloud"
     * @castor.field-xml
     *  name="cloud"
     *  node="element"
     */
    public Cloud getCloud()
    {
        return _cloud;
    }

    /**
     * Initializes the number of minutes that indicates how long a channel can be cached before refreshing from the source.
     * @param ttl the channel's TTL. May be null.
     * @see #getTTL
     * @since 2.0
     */
    public void setTTL(final Integer ttl)
    {
        _ttl = ttl;
    }

    /**
     * Returns a number of minutes that indicates how long a channel can be cached before refreshing from the source.
     * TTL stands for time to live.
     * This makes it possible for RSS sources to be managed by a file-sharing network such as Gnutella.
     * Example: "60".
     * No default value.
     * @return the channel's TTL. May be null.
     * @see #setTTL
     * @since 2.0
     * @castor.field
     *  get-method="getTTL"
     *  set-method="setTTL"
     * @castor.field-xml
     *  name="ttl"
     *  node="element"
     */
    public Integer getTTL()
    {
        return _ttl;
    }

    /**
     * Initializes a GIF, JPEG or PNG image that can be displayed with the channel.
     * @param image an image descriptor. May be null.
     * @see #getImage
     */
    public void setImage(final Image image)
    {
        _image = image;
    }

    /**
     * Returns a GIF, JPEG or PNG image that can be displayed with the channel.
     * No default value.
     * @return an image descriptor. May be null.
     * @see #setImage
     * @castor.field
     *  get-method="getImage"
     *  set-method="setImage"
     * @castor.field-xml
     *  name="image"
     *  node="element"
     */
    public Image getImage()
    {
        return _image;
    }

    /**
     * Initializes the PICS rating for the channel.
     * @param rating a PICS rating. May be null.
     * @see #getRating
     */
    public void setRating(final String rating)
    {
        _rating = rating;
    }

    /**
     * Returns the PICS rating for the channel.
     * No default value.
     * @return a PICS rating. May be null.
     * @see #setRating
     * @castor.field
     *  get-method="getRating"
     *  set-method="setRating"
     * @castor.field-xml
     *  name="rating"
     *  node="element"
     */
    public String getRating()
    {
        return _rating;
    }

    /**
     * Initializes a text input box that can be displayed with the channel.
     * @param textInput the text input descriptor. May be null.
     * @see #getTextInput
     */
    public void setTextInput(final TextInput textInput)
    {
        _textInput = textInput;
    }

    /**
     * Returns a text input box that can be displayed with the channel.
     * No default value.
     * @return the text input descriptor. May be null.
     * @see #setTextInput
     * @castor.field
     *  get-method="getTextInput"
     *  set-method="setTextInput"
     * @castor.field-xml
     *  name="textInput"
     *  node="element"
     */
    public TextInput getTextInput()
    {
        return _textInput;
    }

    /**
     * Returns a hint for aggregators telling them which hours they can skip.
     * Contains up to 24 "hour" sub-elements whose value is a number between 0 and 23, representing a time in GMT,
     * when aggregators, if they support the feature, may not read the channel on hours listed in the skipHours element.
     * The hour beginning at midnight is hour zero.
     * The list is initially empty.
     * 
* This element came from scriptingNews format, designed in late 1997, and adopted by Netscape in RSS 0.91 in the spring of 1999. * @return a list of "hour" elements. May be empty but not null. * @see #addSkipHour * @castor.field * get-method="getSkipHours" * set-method="addSkipHour" * type="java.lang.Integer" * collection="arraylist" * @castor.field-xml * name="hour" * location="skipHours" * node="element" */ public List getSkipHours() { return _skipHours; } /** * Adds an "hour" sub-element which value is a number between 0 and 23, representing a time in GMT. * @param skipHour an "hour" element. Shall not be null. * @throws NullPointerException if skipHour is null. * @see #getSkipHours */ public void addSkipHour(final Integer skipHour) { if (skipHour == null) { throw new NullPointerException("no skipHour"); } _skipHours.add(skipHour); } /** * Returns a hint for aggregators telling them which days they can skip. * Contains up to seven "day" sub-elements whose value is Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday. * Aggregators may not read the channel during days listed in the skipDays element. * No default value. * The list is initially empty. *
* This element came from scriptingNews format, designed in late 1997, and adopted by Netscape in RSS 0.91 in the spring of 1999. * @return a list of "day" elements. May be empty but not null. * @see #addSkipDay * @castor.field * get-method="getSkipDays" * set-method="addSkipDay" * type="java.lang.String" * collection="arraylist" * @castor.field-xml * name="day" * location="skipDays" * node="element" */ public List getSkipDays() { return _skipDays; } /** * Adds a "day" sub-element which value is Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday. * @param skipDay a "day" element. Shall not be null. * @throws NullPointerException if skipDay is null. * @see #getSkipDays */ public void addSkipDay(final String skipDay) { if (skipDay == null) { throw new NullPointerException("no skipDay"); } _skipDays.add(skipDay); } /** * Returns the list of channel's {@link Item items}. * There can be no more than 15 items in a 0.91 channel (not checked). * There are no XML-level limits in RSS 0.92 and greater. * Processors may impose their own limits, and generators may have preferences that say no more than a certain number of {@link Item items} can appear in a channel. * The list is initially empty. * @return a list of items. May be empty but not null. * @see #addItem * @castor.field * get-method="getItems" * set-method="addItem" * type="chameleon.rss.Item" * collection="arraylist" * @castor.field-xml * name="item" * node="element" */ public List getItems() { return _items; } /** * Adds an {@link Item item} to this channel. * @param item a channel's item. Shall not be null. * @throws NullPointerException if item is null. * @see #getItems */ public void addItem(final Item item) { item.setChannel(this); // Throws NullPointerException if item is null. _items.add(item); } /** * Initializes the parent RSS document. * @param rss the parent RSS element. May be null. * @see #getRSS */ void setRSS(final RSS rss) { _rss = rss; } /** * Returns the parent RSS document, if any. * @return the parent RSS document. May be null. */ public RSS getRSS() { return _rss; } }




© 2015 - 2025 Weber Informatics LLC | Privacy Policy