001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/web/tags/sakai_2-4-1/news-api/api/src/java/org/sakaiproject/news/api/NewsService.java $
003: * $Id: NewsService.java 17639 2006-10-31 20:02:37Z wagnermr@iupui.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.news.api;
021:
022: import java.util.List;
023:
024: import org.sakaiproject.javax.Filter;
025: import org.sakaiproject.entity.api.EntityProducer;
026:
027: /**
028: * <p>
029: * NewsService is the interface for retrieving and caching news items from a rss news feed.
030: * </p>
031: */
032: public interface NewsService extends EntityProducer {
033: /** This string can be used to find the service in the service manager. */
034: public static final String SERVICE_NAME = NewsService.class
035: .getName();
036:
037: /** This string starts the references to resources in this service. */
038: public static final String REFERENCE_ROOT = "/news";
039:
040: /**
041: * Retrieves a list of rss feeds that are being used.
042: *
043: * @return A list of NewsChannel objects (possibly empty).
044: */
045: public List getChannels();
046:
047: /**
048: * Retrieves a NewsChannel object indexed by a URL.
049: *
050: * @param source
051: * The url for the channel.
052: * @return A NewsChannel object (possibly null).
053: * @throws NewsConnectionException
054: * @throws NewsFormatException
055: */
056: public NewsChannel getChannel(String source)
057: throws NewsConnectionException, NewsFormatException;
058:
059: /**
060: * Retrieves a list of rss feeds that are being used.
061: *
062: * @return A list of NewsChannel objects (possibly empty).
063: * @throws ?
064: * if param channel is not a valid url.
065: */
066: public void removeChannel(String channel);
067:
068: /**
069: * Retrieves a list of items from an rss feed.
070: *
071: * @param channel
072: * The url for the feed.
073: * @return A list of NewsItem objects retrieved from the feed.
074: * @throws ?
075: * if param feed is not a valid url.
076: */
077: public List getNewsitems(String channel)
078: throws NewsConnectionException, NewsFormatException;
079:
080: /**
081: * Retrieves a list of items from an rss feed.
082: *
083: * @param channel
084: * The url for the feed.
085: * @param filter
086: * A filtering object to accept NewsItems, or null if no filtering is desired.
087: * @return A list of NewsItem objects retrieved from the feed.
088: * @throws ?
089: * if param feed is not a valid url.
090: */
091: public List getNewsitems(String channel, Filter filter)
092: throws NewsConnectionException, NewsFormatException;
093:
094: /**
095: * Checks whether an update is available for the rss news feed.
096: *
097: * @param feed
098: * The url for the feed.
099: * @return true if update is available, false otherwise
100: * @throws ?
101: * if param feed is not a valid url.
102: */
103: public boolean isUpdateAvailable(String channel);
104: }
|