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