View Javadoc

1   /*
2    * Copyright 2004 Sun Microsystems, Inc.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   *
16   */
17  package com.sun.syndication.feed.synd;
18  
19  import com.sun.syndication.feed.CopyFrom;
20  import com.sun.syndication.feed.WireFeed;
21  import com.sun.syndication.feed.module.Module;
22  
23  import java.util.Date;
24  import java.util.List;
25  
26  /***
27   * Bean interface for all types of feeds.
28   * <p>
29   * It handles all RSS versions and Atom 0.3, it normalizes all info, it may lose information.
30   * <p>
31   * @author Alejandro Abdelnur
32   *
33   */
34  public interface SyndFeed extends Cloneable,CopyFrom {
35  
36      /***
37       * Returns the real feed types the SyndFeedImpl supports when converting from and to.
38       * <p>
39       * @return the real feed type supported.
40       */
41      List getSupportedFeedTypes();
42  
43      /***
44       * Creates a real feed containing the information of the SyndFeedImpl.
45       * <p>
46       * The feed type of the created WireFeed is taken from the SyndFeedImpl feedType property.
47       * <p>
48       * @return the real feed.
49       *
50       */
51      WireFeed createWireFeed();
52  
53      /***
54       * Creates a real feed containing the information of the SyndFeedImpl.
55       * <p>
56       * @param feedType the feed type for the WireFeed to be created.
57       * @return the real feed.
58       *
59       */
60      WireFeed createWireFeed(String feedType);
61  
62  
63      /***
64       * Returns the wire feed type the feed had/will-have when coverted from/to a WireFeed.
65       * <p>
66       * @return the feed type, <b>null</b> if none.
67       *
68       */
69      String getFeedType();
70  
71      /***
72       * Sets the wire feed type the feed will-have when coverted to a WireFeed.
73       * <p>
74       * @param feedType the feed type to set, <b>null</b> if none.
75       *
76       */
77      void setFeedType(String feedType);
78  
79      /***
80       * Returns the charset encoding of a the feed. This is not set by Rome parsers.
81       * <p>
82       * @return the charset encoding of the feed.
83       *
84       */
85      public String getEncoding();
86  
87      /***
88       * Sets the charset encoding of a the feed. This is not set by Rome parsers.
89       * <p>
90       * @param encoding the charset encoding of the feed.
91       *
92       */
93      public void setEncoding(String encoding);
94  
95      /***
96       * Returns the feed URI.
97       * <p>
98       * How the feed URI maps to a concrete feed type (RSS or Atom) depends on
99       * the concrete feed type. This is explained in detail in Rome documentation,
100      * <a href="http://wiki.java.net/bin/edit/Javawsxml/Rome04URIMapping">Feed and entry URI mapping</a>.
101      * <p>
102      * The returned URI is a normalized URI as specified in RFC 2396bis.
103      * <p>
104      * Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
105      * the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
106      * is the URL that the item is accessible under, the URI is the
107      * permanent identifier which the aggregator should use to reference
108      * this item. Often the URI will use some standardized identifier scheme
109      * such as DOI's so that items can be identified even if they appear in
110      * multiple feeds with different "links" (they might be on different
111      * hosting platforms but be the same item). Also, though rare, there
112      * could be multiple items with the same link but a different URI and
113      * associated metadata which need to be treated as distinct entities.
114      * In the RSS 1.0 case the URI must be a valid RDF URI reference.
115      * <p>
116      * @return the feed URI, <b>null</b> if none.
117      *
118      */
119     String getUri();
120 
121     /***
122      * Sets the feed URI.
123      * <p>
124      * How the feed URI maps to a concrete feed type (RSS or Atom) depends on
125      * the concrete feed type. This is explained in detail in Rome documentation,
126      * <a href="http://wiki.java.net/bin/edit/Javawsxml/Rome04URIMapping">Feed and entry URI mapping</a>.
127      * <p>
128      * Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
129      * the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
130      * is the URL that the item is accessible under, the URI is the
131      * permanent identifier which the aggregator should use to reference
132      * this item. Often the URI will use some standardized identifier scheme
133      * such as DOI's so that items can be identified even if they appear in
134      * multiple feeds with different "links" (they might be on different
135      * hosting platforms but be the same item). Also, though rare, there
136      * could be multiple items with the same link but a different URI and
137      * associated metadata which need to be treated as distinct entities.
138      * In the RSS 1.0 case the URI must be a valid RDF URI reference.
139      * <p>
140      * @param uri the feed URI to set, <b>null</b> if none.
141      *
142      */
143     void setUri(String uri);
144 
145     /***
146      * Returns the feed title.
147      * <p>
148      * @return the feed title, <b>null</b> if none.
149      *
150      */
151     String getTitle();
152 
153     /***
154      * Sets the feed title.
155      * <p>
156      * @param title the feed title to set, <b>null</b> if none.
157      *
158      */
159     void setTitle(String title);
160 
161     /***
162      * Returns the feed link.
163      * <p>
164      * Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
165      * the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
166      * is the URL that the item is accessible under, the URI is the
167      * permanent identifier which the aggregator should use to reference
168      * this item. Often the URI will use some standardized identifier scheme
169      * such as DOI's so that items can be identified even if they appear in
170      * multiple feeds with different "links" (they might be on different
171      * hosting platforms but be the same item). Also, though rare, there
172      * could be multiple items with the same link but a different URI and
173      * associated metadata which need to be treated as distinct entities.
174      * In the RSS 1.0 case the URI must be a valid RDF URI reference.
175      * <p>
176      * @return the feed link, <b>null</b> if none.
177      *
178      */
179     String getLink();
180 
181     /***
182      * Sets the feed link.
183      * <p>
184      * Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
185      * the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
186      * is the URL that the item is accessible under, the URI is the
187      * permanent identifier which the aggregator should use to reference
188      * this item. Often the URI will use some standardized identifier scheme
189      * such as DOI's so that items can be identified even if they appear in
190      * multiple feeds with different "links" (they might be on different
191      * hosting platforms but be the same item). Also, though rare, there
192      * could be multiple items with the same link but a different URI and
193      * associated metadata which need to be treated as distinct entities.
194      * In the RSS 1.0 case the URI must be a valid RDF URI reference.
195      * <p>
196      * @param link the feed link to set, <b>null</b> if none.
197      *
198      */
199     void setLink(String link);
200 
201     /***
202      * Returns the entry links
203      * <p>
204      * @return the entry links, <b>null</b> if none.
205      *
206      */
207     List getLinks();
208 
209     /***
210      * Sets the entry links.
211      * <p>
212      * @param links the entry links to set, <b>null</b> if none.
213      *
214      */
215     void setLinks(List links);
216 
217     /***
218      * Returns the feed description.
219      * <p>
220      * @return the feed description, <b>null</b> if none.
221      *
222      */
223     String getDescription();
224 
225     /***
226      * Sets the feed description.
227      * <p>
228      * @param description the feed description to set, <b>null</b> if none.
229      *
230      */
231     void setDescription(String description);
232 
233     /***
234      * Returns the feed published date.
235      * <p>
236      * This method is a convenience method, it maps to the Dublin Core module date.
237      * <p>
238      * @return the feed published date, <b>null</b> if none.
239      *
240      */
241     Date getPublishedDate();
242 
243     /***
244      * Sets the feed published date.
245      * <p>
246      * This method is a convenience method, it maps to the Dublin Core module date.
247      * <p>
248      * @param publishedDate the feed published date to set, <b>null</b> if none.
249      *
250      */
251     void setPublishedDate(Date publishedDate);
252 
253     /***
254      * Returns the feed authors.
255      * <p>
256      * For Atom feeds, this returns the authors as a list of SyndPerson objects,
257      * for RSS feeds this method is a convenience method, it maps to the
258      * Dublin Core module creator.
259      * <p>
260      * @return the feed author, <b>null</b> if none.
261      *
262      */
263     List getAuthors();
264 
265     /***
266      * Sets the feed author.
267      * <p>
268      * For Atom feeds, this sets the authors as a list of SyndPerson
269      * objects, for RSS feeds this method is a convenience method, it maps
270      * to the Dublin Core module creator.
271      * <p>
272      * @param author the feed author to set, <b>null</b> if none.
273      *
274      */
275     void setAuthors(List authors);
276 
277     /***
278      * Returns the name of the first feed author in the collection of authors.
279      * <p>
280      * For Atom feeds, this returns the authors as a list of SyndPerson objects,
281      * for RSS feeds this method is a convenience method, it maps to the
282      * Dublin Core module creator.
283      * <p>
284      * @return the feed author, <b>null</b> if none.
285      *
286      */
287     String getAuthor();
288 
289     /***
290      * Sets the feed author.
291      * <p>
292      * For Atom feeds, this sets the feed author's name, for RSS feeds
293      * this method is a convenience method, it maps to the Dublin Core
294      * module creator.
295      * <p>
296      * @param author the feed author to set, <b>null</b> if none.
297      *
298      */
299     void setAuthor(String author);
300 
301     /***
302      * Returns the feed author.
303      * <p>
304      * For Atom feeds, this returns the contributors as a list of
305      * SyndPerson objects
306      * <p>
307      * @return the feed author, <b>null</b> if none.
308      *
309      */
310     public List getContributors();
311 
312     /***
313      * Sets the feed author.
314      * <p>
315      * Returns contributors as a list of SyndPerson objects.
316      * <p>
317      * @param author the feed author to set, <b>null</b> if none.
318      *
319      */
320     void setContributors(List contributors);
321 
322     /***
323      * Returns the feed copyright.
324      * <p>
325      * This method is a convenience method, it maps to the Dublin Core module rights.
326      * <p>
327      * @return the feed copyright, <b>null</b> if none.
328      *
329      */
330     String getCopyright();
331 
332     /***
333      * Sets the feed copyright.
334      * <p>
335      * This method is a convenience method, it maps to the Dublin Core module rights.
336      * <p>
337      * @param copyright the feed copyright to set, <b>null</b> if none.
338      *
339      */
340     void setCopyright(String copyright);
341 
342     /***
343      * Returns the feed image.
344      * <p>
345      * @return the feed image, <b>null</b> if none.
346      *
347      */
348     SyndImage getImage();
349 
350     /***
351      * Sets the feed image.
352      * <p>
353      * @param image the feed image to set, <b>null</b> if none.
354      *
355      */
356     void setImage(SyndImage image);
357 
358     /***
359      * Returns the feed categories.
360      * <p>
361      * This method is a convenience method, it maps to the Dublin Core module subjects.
362      * <p>
363      * @return a list of SyndCategoryImpl elements with the feed categories,
364      *         an empty list if none.
365      *
366      */
367     List getCategories();
368 
369     /***
370      * Sets the feed categories.
371      * <p>
372      * This method is a convenience method, it maps to the Dublin Core module subjects.
373      * <p>
374      * @param categories the list of SyndCategoryImpl elements with the feed categories to set,
375      *        an empty list or <b>null</b> if none.
376      *
377      */
378     void setCategories(List categories);
379 
380     /***
381      * Returns the feed entries.
382      * <p>
383      * @return a list of SyndEntryImpl elements with the feed entries,
384      *         an empty list if none.
385      *
386      */
387     List getEntries();
388 
389     /***
390      * Sets the feed entries.
391      * <p>
392      * @param entries the list of SyndEntryImpl elements with the feed entries to set,
393      *        an empty list or <b>null</b> if none.
394      *
395      */
396     void setEntries(List entries);
397 
398     /***
399      * Returns the feed language.
400      * <p>
401      * This method is a convenience method, it maps to the Dublin Core module language.
402      * <p>
403      * @return the feed language, <b>null</b> if none.
404      *
405      */
406     String getLanguage();
407 
408     /***
409      * Sets the feed language.
410      * <p>
411      * This method is a convenience method, it maps to the Dublin Core module language.
412      * <p>
413      * @param language the feed language to set, <b>null</b> if none.
414      *
415      */
416     void setLanguage(String language);
417 
418     /***
419      * Returns the module identified by a given URI.
420      * <p>
421      * @param uri the URI of the ModuleImpl.
422      * @return The module with the given URI, <b>null</b> if none.
423      */
424     public Module getModule(String uri);
425 
426     /***
427      * Returns the feed modules.
428      * <p>
429      * @return a list of ModuleImpl elements with the feed modules,
430      *         an empty list if none.
431      *
432      */
433     List getModules();
434 
435     /***
436      * Sets the feed modules.
437      * <p>
438      * @param modules the list of ModuleImpl elements with the feed modules to set,
439      *        an empty list or <b>null</b> if none.
440      *
441      */
442     void setModules(List modules);
443 
444     /***
445      * Creates a deep clone of the object.
446      * <p>
447      * @return a clone of the object.
448      * @throws CloneNotSupportedException thrown if an element of the object cannot be cloned.
449      *
450      */
451     public Object clone() throws CloneNotSupportedException;
452 
453 }