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.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 }