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 feed description.
203      * <p>
204      * @return the feed description, <b>null</b> if none.
205      *
206      */
207     String getDescription();
208 
209     /***
210      * Sets the feed description.
211      * <p>
212      * @param description the feed description to set, <b>null</b> if none.
213      *
214      */
215     void setDescription(String description);
216 
217     /***
218      * Returns the feed published date.
219      * <p>
220      * This method is a convenience method, it maps to the Dublin Core module date.
221      * <p>
222      * @return the feed published date, <b>null</b> if none.
223      *
224      */
225     Date getPublishedDate();
226 
227     /***
228      * Sets the feed published date.
229      * <p>
230      * This method is a convenience method, it maps to the Dublin Core module date.
231      * <p>
232      * @param publishedDate the feed published date to set, <b>null</b> if none.
233      *
234      */
235     void setPublishedDate(Date publishedDate);
236 
237     /***
238      * Returns the feed author.
239      * <p>
240      * This method is a convenience method, it maps to the Dublin Core module creator.
241      * <p>
242      * @return the feed author, <b>null</b> if none.
243      *
244      */
245     String getAuthor();
246 
247     /***
248      * Sets the feed author.
249      * <p>
250      * This method is a convenience method, it maps to the Dublin Core module creator.
251      * <p>
252      * @param author the feed author to set, <b>null</b> if none.
253      *
254      */
255     void setAuthor(String author);
256 
257     /***
258      * Returns the feed copyright.
259      * <p>
260      * This method is a convenience method, it maps to the Dublin Core module rights.
261      * <p>
262      * @return the feed copyright, <b>null</b> if none.
263      *
264      */
265     String getCopyright();
266 
267     /***
268      * Sets the feed copyright.
269      * <p>
270      * This method is a convenience method, it maps to the Dublin Core module rights.
271      * <p>
272      * @param copyright the feed copyright to set, <b>null</b> if none.
273      *
274      */
275     void setCopyright(String copyright);
276 
277     /***
278      * Returns the feed image.
279      * <p>
280      * @return the feed image, <b>null</b> if none.
281      *
282      */
283     SyndImage getImage();
284 
285     /***
286      * Sets the feed image.
287      * <p>
288      * @param image the feed image to set, <b>null</b> if none.
289      *
290      */
291     void setImage(SyndImage image);
292 
293     /***
294      * Returns the feed categories.
295      * <p>
296      * This method is a convenience method, it maps to the Dublin Core module subjects.
297      * <p>
298      * @return a list of SyndCategoryImpl elements with the feed categories,
299      *         an empty list if none.
300      *
301      */
302     List getCategories();
303 
304     /***
305      * Sets the feed categories.
306      * <p>
307      * This method is a convenience method, it maps to the Dublin Core module subjects.
308      * <p>
309      * @param categories the list of SyndCategoryImpl elements with the feed categories to set,
310      *        an empty list or <b>null</b> if none.
311      *
312      */
313     void setCategories(List categories);
314 
315     /***
316      * Returns the feed entries.
317      * <p>
318      * @return a list of SyndEntryImpl elements with the feed entries,
319      *         an empty list if none.
320      *
321      */
322     List getEntries();
323 
324     /***
325      * Sets the feed entries.
326      * <p>
327      * @param entries the list of SyndEntryImpl elements with the feed entries to set,
328      *        an empty list or <b>null</b> if none.
329      *
330      */
331     void setEntries(List entries);
332 
333     /***
334      * Returns the feed language.
335      * <p>
336      * This method is a convenience method, it maps to the Dublin Core module language.
337      * <p>
338      * @return the feed language, <b>null</b> if none.
339      *
340      */
341     String getLanguage();
342 
343     /***
344      * Sets the feed language.
345      * <p>
346      * This method is a convenience method, it maps to the Dublin Core module language.
347      * <p>
348      * @param language the feed language to set, <b>null</b> if none.
349      *
350      */
351     void setLanguage(String language);
352 
353     /***
354      * Returns the module identified by a given URI.
355      * <p>
356      * @param uri the URI of the ModuleImpl.
357      * @return The module with the given URI, <b>null</b> if none.
358      */
359     public Module getModule(String uri);
360 
361     /***
362      * Returns the feed modules.
363      * <p>
364      * @return a list of ModuleImpl elements with the feed modules,
365      *         an empty list if none.
366      *
367      */
368     List getModules();
369 
370     /***
371      * Sets the feed modules.
372      * <p>
373      * @param modules the list of ModuleImpl elements with the feed modules to set,
374      *        an empty list or <b>null</b> if none.
375      *
376      */
377     void setModules(List modules);
378 
379     /***
380      * Creates a deep clone of the object.
381      * <p>
382      * @return a clone of the object.
383      * @throws CloneNotSupportedException thrown if an element of the object cannot be cloned.
384      *
385      */
386     public Object clone() throws CloneNotSupportedException;
387 
388 }