com.colorfulsoftware.rss

Class RSSDoc

java.lang.Object

com.colorfulsoftware.rss.RSSDoc

All Implemented Interfaces:

Serializable

public final class RSSDoc
extends Object
implements Serializable

This class reads and writes RSS documents to and from xml files, objects or Strings. It contains all of the factory methods for building immutable copies of the object elements.

Here are some examples of how to use the RSSpect library in your application:

• Read a file from disk into an RSS bean.
  RSS myRSS = new RSSDoc().readRSSToBean(new File("/myPath/myRSS.xml");
• Read a file from the web into an RSS bean.
  RSS myRSS = new RSSDoc().readRSSToBean(new URL("http://www.abcdefg.net/myRSS.xml");
• Read an RSS bean into a String.
  String myRssStr = myRSS.toString();
• Read an RSS bean into a formatted String.
  String myRssStr = new RSSDoc().readRSSToString(myRSS, "javanet.staxutils.IndentingXMLStreamWriter");
• Write an RSS bean to disk.
  String myRssStr = new RSSDoc().writeRSSDoc(new File("/somewhere/myRSS.xml"), myRSS, "UTF-8", "1.0");
• Write a formatted RSS bean to disk.
  String myRssStr = new RSSDoc().writeRSSDoc(new javanet.staxutils.IndentingXMLStreamWriter( XMLOutputFactory.newInstance().createXMLStreamWriter( new FileOutputStream("/somewhere/myRSS.xml"), "UTF-8")), myRSS, "UTF-8", "1.0");

Author:

Bill Brown

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
RSSDoc()
RSSDoc(List<com.colorfulsoftware.rss.RSSDoc.ProcessingInstruction> processingInstructions)

Method Summary

Methods

Modifier and Type	Method and Description
Attribute	buildAttribute(String name, String value)
Author	buildAuthor(String author)
Category	buildCategory(Attribute domain, String category)
Channel	buildChannel(Title title, Link link, Description description, Language language, Copyright copyright, ManagingEditor managingEditor, WebMaster webMaster, PubDate pubDate, LastBuildDate lastBuildDate, List<Category> categories, Generator generator, Docs docs, Cloud cloud, TTL ttl, Image image, Rating rating, TextInput textInput, SkipHours skipHours, SkipDays skipDays, List<Extension> extensions, List<Item> items)
Cloud	buildCloud(List<Attribute> attributes)
Comments	buildComments(String comments)
Copyright	buildCopyright(String copyright)
Day	buildDay(String day)
Description	buildDescription(String description)
Docs	buildDocs(String docs)
Enclosure	buildEnclosure(List<Attribute> attributes)
Extension	buildExtension(String elementName, List<Attribute> attributes, String content)
Generator	buildGenerator(String text)
GUID	buildGUID(Attribute isPermaLink, String guid)
Height	buildHeight(String height)
Hour	buildHour(String hour)
Image	buildImage(URL url, Title title, Link link, Width width, Height height, Description description)
Item	buildItem(Title title, Link link, Description description, Author author, List<Category> categories, Comments comments, Enclosure enclosure, GUID guid, PubDate pubDate, Source source, List<Extension> extensions)
Language	buildLanguage(String language)
LastBuildDate	buildLastBuildDate(String lastBuildDate)
Link	buildLink(String link)
ManagingEditor	buildManagingEditor(String managingEditor)
Name	buildName(String name)
PubDate	buildPubDate(String pubDate)
Rating	buildRating(String rating)
RSS	buildRSS(Channel channel, List<Attribute> attributes, List<Extension> extensions)
SkipDays	buildSkipDays(List<Day> skipDays)
SkipHours	buildSkipHours(List<Hour> skipHours)
Source	buildSource(Attribute url, String source)
TextInput	buildTextInput(Title title, Description description, Name name, Link link)
Title	buildTitle(String title)
TTL	buildTTL(String ttl)
URL	buildURL(String url)
WebMaster	buildWebMaster(String webMaster)
Width	buildWidth(String width)
String	getEncoding()
Generator	getLibVersion()
String	getXmlVersion()
RSS	readRSSToBean(File file) This method reads an xml File object into a Feed element.
RSS	readRSSToBean(InputStream inputStream) This method reads an rss file from an input stream into a RSS element.
RSS	readRSSToBean(String xmlString) This method reads an xml string into a Feed element.
RSS	readRSSToBean(URL url) This method reads an rss file from a URL into a Feed element.
String	readRSSToString(RSS rss, String xmlStreamWriter) This method reads in a Feed element and returns the contents as an rss feed string with formatting specified by the fully qualified XMLStreamWriter class name (uses reflection internally).
void	writeRSSDoc(File file, RSS rss, String encoding, String version)
void	writeRSSDoc(OutputStream output, RSS rss, String encoding, String version)
void	writeRSSDoc(XMLStreamWriter output, RSS rss, String encoding, String version) For example: to pass the TXW com.sun.xml.txw2.output.IndentingXMLStreamWriter or the stax-utils javanet.staxutils.IndentingXMLStreamWriter for indented printing do this:

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RSSDoc

public RSSDoc()
       throws Exception

Throws:

Exception - if the rsspect.properties file cant be read.

RSSDoc

public RSSDoc(List<com.colorfulsoftware.rss.RSSDoc.ProcessingInstruction> processingInstructions)
       throws Exception

Parameters:

processingInstructions - xml processing instructions.

Throws:

Exception - if the library version information cannot be loaded from the environment.

Method Detail

getLibVersion

public Generator getLibVersion()

Returns:

the RSSpect library version in the form of a generator element. This element is output for all feeds that are generated by RSSpect.

writeRSSDoc

public void writeRSSDoc(OutputStream output,
               RSS rss,
               String encoding,
               String version)
                 throws Exception

Parameters:

output - the target output stream for the rss document.

rss - the rss object containing the content of the feed

encoding - the file encoding (default is UTF-8)

version - the xml version (default is 1.0)

Throws:

Exception - thrown if the feed cannot be written to the output

writeRSSDoc

public void writeRSSDoc(File file,
               RSS rss,
               String encoding,
               String version)
                 throws Exception

Parameters:

file - the target output file for the document.

rss - the rss object containing the content of the feed

encoding - the file encoding (default is UTF-8)

version - the xml version (default is 1.0)

Throws:

Exception - thrown if the feed cannot be written to the output

writeRSSDoc

public void writeRSSDoc(XMLStreamWriter output,
               RSS rss,
               String encoding,
               String version)
                 throws Exception

For example: to pass the TXW com.sun.xml.txw2.output.IndentingXMLStreamWriter or the stax-utils javanet.staxutils.IndentingXMLStreamWriter for indented printing do this:

 XmlStreamWriter writer = new IndentingXMLStreamWriter(XMLOutputFactory
                .newInstance().createXMLStreamWriter(
                                new FileOutputStream(outputFilePath), encoding));
 RSSDoc.writeFeedDoc(writer, myFeed, null, null);
 

Parameters:

output - the target output for the feed.

rss - the rss object containing the content of the feed

encoding - the file encoding (default is UTF-8)

version - the xml version (default is 1.0)

Throws:

Exception - thrown if the feed cannot be written to the output

readRSSToString

public String readRSSToString(RSS rss,
                     String xmlStreamWriter)
                       throws Exception

This method reads in a Feed element and returns the contents as an rss feed string with formatting specified by the fully qualified XMLStreamWriter class name (uses reflection internally). For example you can pass the TXW com.sun.xml.txw2.output.IndentingXMLStreamWriter or the stax-utils javanet.staxutils.IndentingXMLStreamWriter for indented printing. It will fall back to the feeds' toString() method if the xmlStreamWriter is not recognized. if the XMLStreamWriter class cannot be found in the classpath.

Parameters:

rss - the rss object to be converted to an rss document string.

xmlStreamWriter - the fully qualified XMLStreamWriter class name.

Returns:

an rss feed document string.

Throws:

Exception - thrown if the feed cannot be returned as a String

readRSSToBean

public RSS readRSSToBean(String xmlString)
                  throws Exception

This method reads an xml string into a Feed element.

Parameters:

xmlString - the xml string to be transformed into a RSS element.

Returns:

the RSS element

Throws:

Exception - if the string cannot be parsed into a RSS element.

readRSSToBean

public RSS readRSSToBean(File file)
                  throws Exception

This method reads an xml File object into a Feed element.

Parameters:

file - the file object representing an rss feed.

Returns:

the RSS element.

Throws:

Exception - if the file cannot be parsed into a RSS element.

readRSSToBean

public RSS readRSSToBean(URL url)
                  throws Exception

This method reads an rss file from a URL into a Feed element.

Parameters:

url - the Internet network location of an rss file.

Returns:

the RSS element.

Throws:

Exception - if the URL cannot be parsed into a RSS element.

readRSSToBean

public RSS readRSSToBean(InputStream inputStream)
                  throws Exception

This method reads an rss file from an input stream into a RSS element.

Parameters:

inputStream - the input stream containing an rss file.

Returns:

the RSS element.

Throws:

Exception - if the URL cannot be parsed into a RSS element.

buildRSS

public RSS buildRSS(Channel channel,
           List<Attribute> attributes,
           List<Extension> extensions)
             throws RSSpectException

Parameters:

channel - the unique channel element (required)

attributes - additional attributes (optional)

extensions - additional extensions (optional)

Returns:

an immutable RSS object.

Throws:

RSSpectException - if the format of the data is not valid.

buildAttribute

public Attribute buildAttribute(String name,
                       String value)
                         throws RSSpectException

Parameters:

name - the attribute name.

value - the attribute value.

Returns:

an immutable Attribute object.

Throws:

RSSpectException - if the data is not valid.

buildAuthor

public Author buildAuthor(String author)
                   throws RSSpectException

Parameters:

author - the author element. (required)

Returns:

an immutable Author object.

Throws:

RSSpectException - if the format of the data is not valid.

buildCategory

public Category buildCategory(Attribute domain,
                     String category)
                       throws RSSpectException

Parameters:

domain - the domain attribute

category - the category text

Returns:

an immutable Category object.

Throws:

RSSpectException - if the format of the data is not valid.

buildChannel

public Channel buildChannel(Title title,
                   Link link,
                   Description description,
                   Language language,
                   Copyright copyright,
                   ManagingEditor managingEditor,
                   WebMaster webMaster,
                   PubDate pubDate,
                   LastBuildDate lastBuildDate,
                   List<Category> categories,
                   Generator generator,
                   Docs docs,
                   Cloud cloud,
                   TTL ttl,
                   Image image,
                   Rating rating,
                   TextInput textInput,
                   SkipHours skipHours,
                   SkipDays skipDays,
                   List<Extension> extensions,
                   List<Item> items)
                     throws RSSpectException

Parameters:

title - the title element.

link - the link element.

description - the description element.

language - the language element.

copyright - the copyright element.

managingEditor - the managingEditor element.

webMaster - the webMaster element.

pubDate - the pubDate element.

lastBuildDate - the lastBuildDate element.

categories - the list of categories

generator - the generator element.

docs - the docs element.

cloud - the cloud element.

ttl - the ttl element.

image - the image element.

rating - the rating element.

textInput - the textInput element.

skipHours - the skipHours element.

skipDays - the skipDays element.

items - the list of items.

extensions - the list of extensions.

Returns:

an immutable Channel object.

Throws:

RSSpectException - if the format of the data is not valid.

buildCloud

public Cloud buildCloud(List<Attribute> attributes)
                 throws RSSpectException

Parameters:

attributes - the list of attributes.

Returns:

an immutable Cloud object.

Throws:

RSSpectException - if the format of the data is not valid.

buildComments

public Comments buildComments(String comments)
                       throws RSSpectException

Parameters:

comments - the comments.

Returns:

an immutable Comments object.

Throws:

RSSpectException - if the format of the data is not valid.

buildCopyright

public Copyright buildCopyright(String copyright)
                         throws RSSpectException

Parameters:

copyright - the copyright.

Returns:

an immutable Copyright object.

Throws:

RSSpectException - if the format of the data is not valid.

buildDescription

public Description buildDescription(String description)
                             throws RSSpectException

Parameters:

description - the description.

Returns:

an immutable Description object.

Throws:

RSSpectException - if the format of the data is not valid.

buildDocs

public Docs buildDocs(String docs)
               throws RSSpectException

Parameters:

docs - the documentation information.

Returns:

an immutable Docs object.

Throws:

RSSpectException - if the format of the data is not valid.

buildEnclosure

public Enclosure buildEnclosure(List<Attribute> attributes)
                         throws RSSpectException

Parameters:

attributes - should contain url, length and type

Returns:

an immutable Enclosure object.

Throws:

RSSpectException - if the format of the data is not valid.

buildExtension

public Extension buildExtension(String elementName,
                       List<Attribute> attributes,
                       String content)
                         throws RSSpectException

Parameters:

elementName - the name of the extension element.

attributes - additional attributes.

content - the content of the extension element.

Returns:

an immutable Extension object.

Throws:

RSSpectException - if the format of the data is not valid.

buildGenerator

public Generator buildGenerator(String text)
                         throws RSSpectException

Parameters:

text - the text content.

Returns:

an immutable Generator object.

Throws:

RSSpectException - if the format of the data is not valid.

buildGUID

public GUID buildGUID(Attribute isPermaLink,
             String guid)
               throws RSSpectException

Parameters:

isPermaLink - the isPermaLink attributes.

guid - the guid data.

Returns:

an immutable GUID object.

Throws:

RSSpectException - if the format of the data is not valid.

buildHeight

public Height buildHeight(String height)
                   throws RSSpectException

Parameters:

height - should be a number 400 or less

Returns:

an immutable Height object.

Throws:

RSSpectException - if the format of the data is not valid.

buildImage

public Image buildImage(URL url,
               Title title,
               Link link,
               Width width,
               Height height,
               Description description)
                 throws RSSpectException

Parameters:

url - the url element.

title - the title element.

link - the link element.

width - the width element.

height - the height element.

description - the description element.

Returns:

an immutable Image object.

Throws:

RSSpectException - if the format of the data is not valid.

buildItem

public Item buildItem(Title title,
             Link link,
             Description description,
             Author author,
             List<Category> categories,
             Comments comments,
             Enclosure enclosure,
             GUID guid,
             PubDate pubDate,
             Source source,
             List<Extension> extensions)
               throws RSSpectException

Parameters:

title - the title element.

link - the link element.

description - the description element.

author - the author element.

categories - the list of categories.

comments - the comments element.

enclosure - the enclosure element.

guid - the guid element.

pubDate - the published date element.

source - the source element.

extensions - the list of extensions.

Returns:

an immutable Item object.

Throws:

RSSpectException - if the format of the data is not valid.

buildLanguage

public Language buildLanguage(String language)
                       throws RSSpectException

Parameters:

language - the language.

Returns:

an immutable Language object.

Throws:

RSSpectException - if the format of the data is not valid.

buildLastBuildDate

public LastBuildDate buildLastBuildDate(String lastBuildDate)
                                 throws RSSpectException

Parameters:

lastBuildDate - the last build date.

Returns:

an immutable LastBuildDate object.

Throws:

RSSpectException - if the format of the data is not valid.

buildLink

public Link buildLink(String link)
               throws RSSpectException

Parameters:

link - the link information.

Returns:

an immutable Link object.

Throws:

RSSpectException - if the format of the data is not valid.

buildManagingEditor

public ManagingEditor buildManagingEditor(String managingEditor)
                                   throws RSSpectException

Parameters:

managingEditor - the managing editor.

Returns:

an immutable ManagingEditor object.

Throws:

RSSpectException - if the format of the data is not valid.

buildName

public Name buildName(String name)
               throws RSSpectException

Parameters:

name - the name.

Returns:

an immutable Name object.

Throws:

RSSpectException - if the format of the data is not valid.

buildPubDate

public PubDate buildPubDate(String pubDate)
                     throws RSSpectException

Parameters:

pubDate - the published date.

Returns:

an immutable PubDate object.

Throws:

RSSpectException - If the dateTime format is invalid.

buildRating

public Rating buildRating(String rating)
                   throws RSSpectException

Parameters:

rating - the rating information.

Returns:

an immutable Rating object.

Throws:

RSSpectException - if the format of the data is not valid.

buildSkipDays

public SkipDays buildSkipDays(List<Day> skipDays)
                       throws RSSpectException

Parameters:

skipDays - the days to skip.

Returns:

an immutable SkipDays object.

Throws:

RSSpectException - if the format of the data is not valid.

buildSkipHours

public SkipHours buildSkipHours(List<Hour> skipHours)
                         throws RSSpectException

Parameters:

skipHours - the hours to skip.

Returns:

an immutable SkipHours object.

Throws:

RSSpectException - if the format of the data is not valid.

buildDay

public Day buildDay(String day)
             throws RSSpectException

Parameters:

day - the day of the week.

Returns:

a Day object.

Throws:

RSSpectException - if the format of the data is not valid.

buildHour

public Hour buildHour(String hour)
               throws RSSpectException

Parameters:

hour - the hour of the day.

Returns:

an Hour object.

Throws:

RSSpectException - if the format of the data is not valid.

buildSource

public Source buildSource(Attribute url,
                 String source)
                   throws RSSpectException

Parameters:

url - the url attribute.

source - the source information.

Returns:

an immutable Source object.

Throws:

RSSpectException - if the format of the data is not valid.

buildTextInput

public TextInput buildTextInput(Title title,
                       Description description,
                       Name name,
                       Link link)
                         throws RSSpectException

Parameters:

title - the title element.

description - the description element.

name - the name element.

link - the link element.

Returns:

an immutable TextInput object.

Throws:

RSSpectException - if the format of the data is not valid.

buildTitle

public Title buildTitle(String title)
                 throws RSSpectException

Parameters:

title - the title.

Returns:

an immutable Title object.

Throws:

RSSpectException - if the format of the data is not valid.

buildTTL

public TTL buildTTL(String ttl)
             throws RSSpectException

Parameters:

ttl - the time to live.

Returns:

an immutable TTL object.

Throws:

RSSpectException - if the format of the data is not valid.

buildURL

public URL buildURL(String url)
             throws RSSpectException

Parameters:

url - the url.

Returns:

an immutable URL object.

Throws:

RSSpectException - if the format of the data is not valid.

buildWebMaster

public WebMaster buildWebMaster(String webMaster)
                         throws RSSpectException

Parameters:

webMaster - the web master.

Returns:

an immutable WebMaster object.

Throws:

RSSpectException - if the format of the data is not valid.

buildWidth

public Width buildWidth(String width)
                 throws RSSpectException

Parameters:

width - the width.

Returns:

an immutable Width object.

Throws:

RSSpectException - if the format of the data is not valid.

getEncoding

public String getEncoding()

Returns:

the xml encoding of the document eg. UTF-8

getXmlVersion

public String getXmlVersion()

Returns:

the xml document version of the document eg. 1.0