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.module.Extendable;
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 entries of SyndFeedImpl feeds.
28   * <p>
29   * @author Alejandro Abdelnur
30   *
31   */
32  public interface SyndEntry extends Cloneable, CopyFrom, Extendable {
33  
34      /***
35       * Returns the entry URI.
36       * <p>
37       * How the entry URI maps to a concrete feed type (RSS or Atom) depends on
38       * the concrete feed type. This is explained in detail in Rome documentation,
39       * <a href="http://wiki.java.net/bin/edit/Javawsxml/Rome04URIMapping">Feed and entry URI mapping</a>.
40       * <p>
41       * The returned URI is a normalized URI as specified in RFC 2396bis.
42       * <p>
43       * @return the entry URI, <b>null</b> if none.
44       *
45       */
46      String getUri();
47  
48      /***
49       * Sets the entry URI.
50       * <p>
51       * How the entry URI maps to a concrete feed type (RSS or Atom) depends on
52       * the concrete feed type. This is explained in detail in Rome documentation,
53       * <a href="http://wiki.java.net/bin/edit/Javawsxml/Rome04URIMapping">Feed and entry URI mapping</a>.
54       * <p>
55       * @param uri the entry URI to set, <b>null</b> if none.
56       *
57       */
58      void setUri(String uri);
59  
60      /***
61       * Returns the entry title.
62       * <p>
63       * @return the entry title, <b>null</b> if none.
64       *
65       */
66      String getTitle();
67  
68      /***
69       * Sets the entry title.
70       * <p>
71       * @param title the entry title to set, <b>null</b> if none.
72       *
73       */
74      void setTitle(String title);
75  
76      /***
77       * Returns the entry title as a text construct.
78       * <p>
79       * @return the entry title, <b>null</b> if none.
80       *
81       */
82      SyndContent getTitleEx();
83  
84      /***
85       * Sets the entry title as a text construct.
86       * <p>
87       * @param title the entry title to set, <b>null</b> if none.
88       *
89       */
90      void setTitleEx(SyndContent title);
91  
92      /***
93       * Returns the entry link.
94       * <p>
95       * @return the entry link, <b>null</b> if none.
96       *
97       */
98      String getLink();
99  
100     /***
101      * Sets the entry link.
102      * <p>
103      * @param link the entry link to set, <b>null</b> if none.
104      *
105      */
106     void setLink(String link);
107 
108     /***
109      * Returns the entry links
110      * <p>
111      * @return the entry links, <b>null</b> if none.
112      *
113      */
114     List getLinks();
115 
116     /***
117      * Sets the entry links.
118      * <p>
119      * @param links the entry links to set, <b>null</b> if none.
120      *
121      */
122     void setLinks(List links);
123 
124     /***
125      * Returns the entry description.
126      * <p>
127      * @return the entry description, <b>null</b> if none.
128      *
129      */
130     SyndContent getDescription();
131 
132     /***
133      * Sets the entry description.
134      * <p>
135      * @param description the entry description to set, <b>null</b> if none.
136      *
137      */
138     void setDescription(SyndContent description);
139 
140     /***
141      * Returns the entry contents.
142      * <p>
143      * @return a list of SyndContentImpl elements with the entry contents,
144      *         an empty list if none.
145      *
146      */
147     List getContents();
148 
149     /***
150      * Sets the entry contents.
151      * <p>
152      * @param contents the list of SyndContentImpl elements with the entry contents to set,
153      *        an empty list or <b>null</b> if none.
154      *
155      */
156     void setContents(List contents);
157 
158     /***
159      * Returns the entry enclosures.
160      * <p>
161      * @return a list of SyndEnclosure elements with the entry enclosures,
162      *         an empty list if none.
163      *
164      */
165     public List getEnclosures();
166 
167     /***
168      * Sets the entry enclosures.
169      * <p>
170      * @param enclosures the list of SyndEnclosure elements with the entry enclosures to set,
171      *        an empty list or <b>null</b> if none.
172      *
173      */
174     public void setEnclosures(List enclosures);
175 
176     /***
177      * Returns the entry published date.
178      * <p>
179      * This method is a convenience method, it maps to the Dublin Core module date.
180      * <p>
181      * @return the entry published date, <b>null</b> if none.
182      *
183      */
184     Date getPublishedDate();
185 
186     /***
187      * Sets the entry published date.
188      * <p>
189      * This method is a convenience method, it maps to the Dublin Core module date.
190      * <p>
191      * @param publishedDate the entry published date to set, <b>null</b> if none.
192      *
193      */
194     void setPublishedDate(Date publishedDate);
195 
196     /***
197      * Returns the entry updated date.
198      * <p>
199      * @return the entry updated date, <b>null</b> if none.
200      *
201      */
202     Date getUpdatedDate();
203 
204     /***
205      * Sets the entry updated date.
206      * <p>
207      * @param updatedDate the entry updated date to set, <b>null</b> if none.
208      *
209      */
210     void setUpdatedDate(Date updatedDate);
211 
212     /***
213      * Returns the entry authors.
214      * <p>
215      * For Atom feeds, this returns the authors as a list of SyndPerson objects, 
216      * for RSS feeds this method is a convenience method, it maps to the 
217      * Dublin Core module creator.
218      * <p>
219      * @return the feed author, <b>null</b> if none.
220      *
221      */
222     List getAuthors();
223 
224     /***
225      * Sets the entry author.
226      * <p>
227      * For Atom feeds, this sets the authors as a list of SyndPerson 
228      * objects, for RSS feeds this method is a convenience method, it maps 
229      * to the Dublin Core module creator.
230      * <p>
231      * @param authors the feed author to set, <b>null</b> if none.
232      *
233      */
234     void setAuthors(List authors);
235     
236     /***
237      * Returns the name of the first entry author in the collection of authors.
238      * <p>
239      * For Atom feeds, this returns the authors as a list of SyndPerson objects, 
240      * for RSS feeds this method is a convenience method, it maps to the 
241      * Dublin Core module creator.
242      * <p>
243      * @return the feed author, <b>null</b> if none.
244      *
245      */
246     String getAuthor();
247 
248     /***
249      * Sets the entry author.
250      * <p>
251      * For Atom feeds, this sets the feed author's name, for RSS feeds 
252      * this method is a convenience method, it maps to the Dublin Core 
253      * module creator.
254      * <p>
255      * @param author the feed author to set, <b>null</b> if none.
256      */
257     void setAuthor(String author);
258     
259     /***
260      * Returns the feed author.
261      * <p>
262      * For Atom feeds, this returns the contributors as a list of 
263      * SyndPerson objects
264      * <p>
265      * @return the feed author, <b>null</b> if none.
266      *
267      */
268     List getContributors();
269 
270     /***
271      * Sets the feed contributors.
272      * <p>
273      * Returns contributors as a list of SyndPerson objects.
274      * <p>
275      * @param contributors the feed contributors to set, <b>null</b> if none.
276      *
277      */
278     void setContributors(List contributors);
279 
280     /***
281      * Returns the entry categories.
282      * <p>
283      * This method is a convenience method, it maps to the Dublin Core module subjects.
284      * <p>
285      * @return a list of SyndCategoryImpl elements with the entry categories,
286      *         an empty list if none.
287      *
288      */
289     List getCategories();
290 
291     /***
292      * Sets the entry categories.
293      * <p>
294      * This method is a convenience method, it maps to the Dublin Core module subjects.
295      * <p>
296      * @param categories the list of SyndCategoryImpl elements with the entry categories to set,
297      *        an empty list or <b>null</b> if none.
298      *
299      */
300     void setCategories(List categories);
301     
302     /***
303      * Returns the entry source.
304      * <p>
305      * This returns the entry source as a SyndFeed
306      * <p>
307      * @return the SyndFeed to which this entry is attributed
308      * 
309      */
310     SyndFeed getSource();
311     
312     /***
313      * Sets the entry source feed (for use if different from containing feed)
314      * <p>
315      * @param source the original SyndFeed that contained this article
316      * 
317      */
318     void setSource(SyndFeed source);
319 
320     /***
321      * Returns the module identified by a given URI.
322      * <p>
323      * @param uri the URI of the ModuleImpl.
324      * @return The module with the given URI, <b>null</b> if none.
325      */
326     public Module getModule(String uri);
327 
328     /***
329      * Returns the entry modules.
330      * <p>
331      * @return a list of ModuleImpl elements with the entry modules,
332      *         an empty list if none.
333      *
334      */
335     List getModules();
336 
337     /***
338      * Sets the entry modules.
339      * <p>
340      * @param modules the list of ModuleImpl elements with the entry modules to set,
341      *        an empty list or <b>null</b> if none.
342      *
343      */
344     void setModules(List modules);
345 
346     /***
347      * Returns foreign markup found at channel level.
348      * <p>
349      * @return Opaque object to discourage use
350      *
351      */
352     public Object getForeignMarkup();
353 
354     /***
355      * Sets foreign markup found at channel level.
356      * <p>
357      * @param foreignMarkup Opaque object to discourage use
358      *
359      */
360     public void setForeignMarkup(Object foreignMarkup);
361     
362     /***
363      * Creates a deep clone of the object.
364      * <p>
365      * @return a clone of the object.
366      * @throws CloneNotSupportedException thrown if an element of the object cannot be cloned.
367      *
368      */
369     public Object clone() throws CloneNotSupportedException;
370 
371 }