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