1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 }