001: /*
002: * Copyright 2004 Sun Microsystems, Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: *
016: */
017: package com.sun.syndication.feed.synd;
018:
019: import com.sun.syndication.feed.CopyFrom;
020: import com.sun.syndication.feed.WireFeed;
021: import com.sun.syndication.feed.module.Extendable;
022: import com.sun.syndication.feed.module.Module;
023:
024: import java.util.Date;
025: import java.util.List;
026:
027: /**
028: * Bean interface for all types of feeds.
029: * <p>
030: * It handles all RSS versions and Atom 0.3, it normalizes all info, it may lose information.
031: * <p>
032: * @author Alejandro Abdelnur
033: *
034: */
035: public interface SyndFeed extends Cloneable, CopyFrom, Extendable {
036:
037: /**
038: * Returns the real feed types the SyndFeedImpl supports when converting from and to.
039: * <p>
040: * @return the real feed type supported.
041: */
042: List getSupportedFeedTypes();
043:
044: /**
045: * Creates a real feed containing the information of the SyndFeedImpl.
046: * <p>
047: * The feed type of the created WireFeed is taken from the SyndFeedImpl feedType property.
048: * <p>
049: * @return the real feed.
050: *
051: */
052: WireFeed createWireFeed();
053:
054: /**
055: * Creates a real feed containing the information of the SyndFeedImpl.
056: * <p>
057: * @param feedType the feed type for the WireFeed to be created.
058: * @return the real feed.
059: *
060: */
061: WireFeed createWireFeed(String feedType);
062:
063: /**
064: * Returns the wire feed type the feed had/will-have when coverted from/to a WireFeed.
065: * <p>
066: * @return the feed type, <b>null</b> if none.
067: *
068: */
069: String getFeedType();
070:
071: /**
072: * Sets the wire feed type the feed will-have when coverted to a WireFeed.
073: * <p>
074: * @param feedType the feed type to set, <b>null</b> if none.
075: *
076: */
077: void setFeedType(String feedType);
078:
079: /**
080: * Returns the charset encoding of a the feed. This is not set by Rome parsers.
081: * <p>
082: * @return the charset encoding of the feed.
083: *
084: */
085: public String getEncoding();
086:
087: /**
088: * Sets the charset encoding of a the feed. This is not set by Rome parsers.
089: * <p>
090: * @param encoding the charset encoding of the feed.
091: *
092: */
093: public void setEncoding(String encoding);
094:
095: /**
096: * Returns the feed URI.
097: * <p>
098: * How the feed URI maps to a concrete feed type (RSS or Atom) depends on
099: * 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 title.
163: * <p>
164: * @return the feed title, <b>null</b> if none.
165: *
166: */
167: SyndContent getTitleEx();
168:
169: /**
170: * Sets the feed title.
171: * <p>
172: * @param title the feed title to set, <b>null</b> if none.
173: *
174: */
175: void setTitleEx(SyndContent title);
176:
177: /**
178: * Returns the feed link.
179: * <p>
180: * Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
181: * the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
182: * is the URL that the item is accessible under, the URI is the
183: * permanent identifier which the aggregator should use to reference
184: * this item. Often the URI will use some standardized identifier scheme
185: * such as DOI's so that items can be identified even if they appear in
186: * multiple feeds with different "links" (they might be on different
187: * hosting platforms but be the same item). Also, though rare, there
188: * could be multiple items with the same link but a different URI and
189: * associated metadata which need to be treated as distinct entities.
190: * In the RSS 1.0 case the URI must be a valid RDF URI reference.
191: * <p>
192: * @return the feed link, <b>null</b> if none.
193: *
194: */
195: String getLink();
196:
197: /**
198: * Sets the feed link.
199: * <p>
200: * Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
201: * the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
202: * is the URL that the item is accessible under, the URI is the
203: * permanent identifier which the aggregator should use to reference
204: * this item. Often the URI will use some standardized identifier scheme
205: * such as DOI's so that items can be identified even if they appear in
206: * multiple feeds with different "links" (they might be on different
207: * hosting platforms but be the same item). Also, though rare, there
208: * could be multiple items with the same link but a different URI and
209: * associated metadata which need to be treated as distinct entities.
210: * In the RSS 1.0 case the URI must be a valid RDF URI reference.
211: * <p>
212: * @param link the feed link to set, <b>null</b> if none.
213: *
214: */
215: void setLink(String link);
216:
217: /**
218: * Returns the entry links
219: * <p>
220: * @return the entry links, <b>null</b> if none.
221: *
222: */
223: List getLinks();
224:
225: /**
226: * Sets the entry links.
227: * <p>
228: * @param links the entry links to set, <b>null</b> if none.
229: *
230: */
231: void setLinks(List links);
232:
233: /**
234: * Returns the feed description.
235: * <p>
236: * @return the feed description, <b>null</b> if none.
237: *
238: */
239: String getDescription();
240:
241: /**
242: * Sets the feed description.
243: * <p>
244: * @param description the feed description to set, <b>null</b> if none.
245: *
246: */
247: void setDescription(String description);
248:
249: /**
250: * Returns the feed description as a text construct.
251: * <p>
252: * @return the feed description, <b>null</b> if none.
253: *
254: */
255: SyndContent getDescriptionEx();
256:
257: /**
258: * Sets the feed description as a text construct.
259: * <p>
260: * @param description the feed description to set, <b>null</b> if none.
261: *
262: */
263: void setDescriptionEx(SyndContent description);
264:
265: /**
266: * Returns the feed published date.
267: * <p>
268: * This method is a convenience method, it maps to the Dublin Core module date.
269: * <p>
270: * @return the feed published date, <b>null</b> if none.
271: *
272: */
273: Date getPublishedDate();
274:
275: /**
276: * Sets the feed published date.
277: * <p>
278: * This method is a convenience method, it maps to the Dublin Core module date.
279: * <p>
280: * @param publishedDate the feed published date to set, <b>null</b> if none.
281: *
282: */
283: void setPublishedDate(Date publishedDate);
284:
285: /**
286: * Returns the feed authors.
287: * <p>
288: * For Atom feeds, this returns the authors as a list of SyndPerson objects,
289: * for RSS feeds this method is a convenience method, it maps to the
290: * Dublin Core module creator.
291: * <p>
292: * @return the feed author, <b>null</b> if none.
293: *
294: */
295: List getAuthors();
296:
297: /**
298: * Sets the feed author.
299: * <p>
300: * For Atom feeds, this sets the authors as a list of SyndPerson
301: * objects, for RSS feeds this method is a convenience method, it maps
302: * to the Dublin Core module creator.
303: * <p>
304: * @param author the feed author to set, <b>null</b> if none.
305: *
306: */
307: void setAuthors(List authors);
308:
309: /**
310: * Returns the name of the first feed author in the collection of authors.
311: * <p>
312: * For Atom feeds, this returns the authors as a list of SyndPerson objects,
313: * for RSS feeds this method is a convenience method, it maps to the
314: * Dublin Core module creator.
315: * <p>
316: * @return the feed author, <b>null</b> if none.
317: *
318: */
319: String getAuthor();
320:
321: /**
322: * Sets the feed author.
323: * <p>
324: * For Atom feeds, this sets the feed author's name, for RSS feeds
325: * this method is a convenience method, it maps to the Dublin Core
326: * module creator.
327: * <p>
328: * @param author the feed author to set, <b>null</b> if none.
329: *
330: */
331: void setAuthor(String author);
332:
333: /**
334: * Returns the feed author.
335: * <p>
336: * For Atom feeds, this returns the contributors as a list of
337: * SyndPerson objects
338: * <p>
339: * @return the feed author, <b>null</b> if none.
340: *
341: */
342: public List getContributors();
343:
344: /**
345: * Sets the feed author.
346: * <p>
347: * Returns contributors as a list of SyndPerson objects.
348: * <p>
349: * @param author the feed author to set, <b>null</b> if none.
350: *
351: */
352: void setContributors(List contributors);
353:
354: /**
355: * Returns the feed copyright.
356: * <p>
357: * This method is a convenience method, it maps to the Dublin Core module rights.
358: * <p>
359: * @return the feed copyright, <b>null</b> if none.
360: *
361: */
362: String getCopyright();
363:
364: /**
365: * Sets the feed copyright.
366: * <p>
367: * This method is a convenience method, it maps to the Dublin Core module rights.
368: * <p>
369: * @param copyright the feed copyright to set, <b>null</b> if none.
370: *
371: */
372: void setCopyright(String copyright);
373:
374: /**
375: * Returns the feed image.
376: * <p>
377: * @return the feed image, <b>null</b> if none.
378: *
379: */
380: SyndImage getImage();
381:
382: /**
383: * Sets the feed image.
384: * <p>
385: * @param image the feed image to set, <b>null</b> if none.
386: *
387: */
388: void setImage(SyndImage image);
389:
390: /**
391: * Returns the feed categories.
392: * <p>
393: * This method is a convenience method, it maps to the Dublin Core module subjects.
394: * <p>
395: * @return a list of SyndCategoryImpl elements with the feed categories,
396: * an empty list if none.
397: *
398: */
399: List getCategories();
400:
401: /**
402: * Sets the feed categories.
403: * <p>
404: * This method is a convenience method, it maps to the Dublin Core module subjects.
405: * <p>
406: * @param categories the list of SyndCategoryImpl elements with the feed categories to set,
407: * an empty list or <b>null</b> if none.
408: *
409: */
410: void setCategories(List categories);
411:
412: /**
413: * Returns the feed entries.
414: * <p>
415: * @return a list of SyndEntryImpl elements with the feed entries,
416: * an empty list if none.
417: *
418: */
419: List getEntries();
420:
421: /**
422: * Sets the feed entries.
423: * <p>
424: * @param entries the list of SyndEntryImpl elements with the feed entries to set,
425: * an empty list or <b>null</b> if none.
426: *
427: */
428: void setEntries(List entries);
429:
430: /**
431: * Returns the feed language.
432: * <p>
433: * This method is a convenience method, it maps to the Dublin Core module language.
434: * <p>
435: * @return the feed language, <b>null</b> if none.
436: *
437: */
438: String getLanguage();
439:
440: /**
441: * Sets the feed language.
442: * <p>
443: * This method is a convenience method, it maps to the Dublin Core module language.
444: * <p>
445: * @param language the feed language to set, <b>null</b> if none.
446: *
447: */
448: void setLanguage(String language);
449:
450: /**
451: * Returns the module identified by a given URI.
452: * <p>
453: * @param uri the URI of the ModuleImpl.
454: * @return The module with the given URI, <b>null</b> if none.
455: */
456: public Module getModule(String uri);
457:
458: /**
459: * Returns the feed modules.
460: * <p>
461: * @return a list of ModuleImpl elements with the feed modules,
462: * an empty list if none.
463: *
464: */
465: List getModules();
466:
467: /**
468: * Sets the feed modules.
469: * <p>
470: * @param modules the list of ModuleImpl elements with the feed modules to set,
471: * an empty list or <b>null</b> if none.
472: *
473: */
474: void setModules(List modules);
475:
476: /**
477: * Returns foreign markup found at channel level.
478: * <p>
479: * @return Opaque object to discourage use
480: *
481: */
482: public Object getForeignMarkup();
483:
484: /**
485: * Sets foreign markup found at channel level.
486: * <p>
487: * @param foreignMarkup Opaque object to discourage use
488: *
489: */
490: public void setForeignMarkup(Object foreignMarkup);
491:
492: /**
493: * Creates a deep clone of the object.
494: * <p>
495: * @return a clone of the object.
496: * @throws CloneNotSupportedException thrown if an element of the object cannot be cloned.
497: *
498: */
499: public Object clone() throws CloneNotSupportedException;
500:
501: }
|