com.colorful.atom
Class FeedDoc

java.lang.Object
  com.colorful.atom.FeedDoc

public class FeedDoc
extends java.lang.Object

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

Author:

Bill Brown

Nested Class Summary

static class

FeedDoc.ContentType An enumeration of the different types of supported content.

Field Summary

static Attribute	atomBase the default atom xml namespace attribute of "http://www.w3.org/2005/Atom"
static java.lang.String	encoding the default document encoding of "UTF-8"
static Attribute	lang_en the default library language attribute of "en-US"
static Attribute	sort the Atomsphere sort extension attribute.
static java.util.Comparator<java.lang.String>	SORT_ASC Comparator for sorting feed entries in ascending order.
static java.util.Comparator<java.lang.String>	SORT_DESC Comparator for sorting feed entries in descending order
static java.lang.String	xml_version the default XML version of "1.0"

Constructor Summary

FeedDoc()

Method Summary

static Attribute	buildAttribute(java.lang.String name, java.lang.String value)
static Author	buildAuthor(Name name, URI uri, Email email, java.util.List<Attribute> attributes, java.util.List<Extension> extensions)
static Category	buildCategory(java.util.List<Attribute> attributes, java.lang.String content)
static Content	buildContent(java.lang.String content, java.util.List<Attribute> attributes)
static Contributor	buildContributor(Name name, URI uri, Email email, java.util.List<Attribute> attributes, java.util.List<Extension> extensions)
static Email	buildEmail(java.lang.String email)
static Entry	buildEntry(Id id, Title title, Updated updated, Rights rights, Content content, java.util.List<Author> authors, java.util.List<Category> categories, java.util.List<Contributor> contributors, java.util.List<Link> links, java.util.List<Attribute> attributes, java.util.List<Extension> extensions, Published published, Summary summary, Source source)
static Extension	buildExtension(java.lang.String elementName, java.util.List<Attribute> attributes, java.lang.String content)
static Feed	buildFeed(Id id, Title title, Updated updated, Rights rights, java.util.List<Author> authors, java.util.List<Category> categories, java.util.List<Contributor> contributors, java.util.List<Link> links, java.util.List<Attribute> attributes, java.util.List<Extension> extensions, Generator generator, Subtitle subtitle, Icon icon, Logo logo, java.util.SortedMap<java.lang.String,Entry> entries)
static Generator	buildGenerator(java.util.List<Attribute> attributes, java.lang.String text)
static Icon	buildIcon(java.util.List<Attribute> attributes, java.lang.String atomUri)
static Id	buildId(java.util.List<Attribute> attributes, java.lang.String atomUri)
static Link	buildLink(java.util.List<Attribute> attributes, java.lang.String content)
static Logo	buildLogo(java.util.List<Attribute> attributes, java.lang.String atomUri)
static Name	buildName(java.lang.String name)
static Published	buildPublished(java.util.Date published, java.util.List<Attribute> attributes)
static Rights	buildRights(java.lang.String rights, java.util.List<Attribute> attributes)
static Source	buildSource(Id id, Title title, Updated updated, Rights rights, java.util.List<Author> authors, java.util.List<Category> categories, java.util.List<Contributor> contributors, java.util.List<Link> links, java.util.List<Attribute> attributes, java.util.List<Extension> extensions, Generator generator, Subtitle subtitle, Icon icon, Logo logo)
static Subtitle	buildSubtitle(java.lang.String subtitle, java.util.List<Attribute> attributes)
static Summary	buildSummary(java.lang.String summary, java.util.List<Attribute> attributes)
static Title	buildTitle(java.lang.String title, java.util.List<Attribute> attributes)
static Updated	buildUpdated(java.util.Date updated, java.util.List<Attribute> attributes)
static URI	buildURI(java.lang.String uri)
static Generator	getAtomsphereVersion()
static FeedDoc.ContentType	getContentType(java.util.List<Attribute> attriubtes) Convenience method for getting the content type for this element.
static Entry	readEntryToBean(java.io.File file) This method reads an xml File object into an Entry element.
static Entry	readEntryToBean(java.io.InputStream inputStream) This method reads an atom file from an input stream into a Entry element.
static Entry	readEntryToBean(java.lang.String xmlString) This method reads an xml string into a Entry element.
static Entry	readEntryToBean(java.net.URL url) This method reads an atom file from a URL into a Entry element.
static java.lang.String	readEntryToString(Entry entry) This method reads in an atom Entry element and returns the contents as an atom Entry document String containing the entry.
static java.lang.String	readEntryToString(Entry entry, java.lang.String xmlStreamWriter) This method reads in an Entry element and returns the contents as an atom feed document string
static Feed	readFeedToBean(java.io.File file) This method reads an xml File object into a Feed element.
static Feed	readFeedToBean(java.io.InputStream inputStream) This method reads an atom file from an input stream into a Feed element.
static Feed	readFeedToBean(java.lang.String xmlString) This method reads an xml string into a Feed element.
static Feed	readFeedToBean(java.net.URL url) This method reads an atom file from a URL into a Feed element.
static java.lang.String	readFeedToString(Feed feed) This method reads in a Feed bean and returns the contents as an atom feed string.
static java.lang.String	readFeedToString(Feed feed, java.lang.String xmlStreamWriter) This method reads in a Feed element and returns the contents as an atom feed string with formatting specified by the fully qualified XMLStreamWriter class name (uses reflection internally).
static Feed	sortEntries(Feed feed, java.util.Comparator<java.lang.String> comparator, java.lang.Class<?> elementClass) This method sorts the entries of the feed.
static void	writeEntryDoc(java.io.OutputStream output, Entry entry, java.lang.String encoding, java.lang.String version)
static void	writeEntryDoc(java.io.Writer output, Entry entry, java.lang.String encoding, java.lang.String version)
static void	writeEntryDoc(javax.xml.stream.XMLStreamWriter output, Entry entry, java.lang.String encoding, java.lang.String version) Writes and entry element to a document.
static void	writeFeedDoc(java.io.OutputStream output, Feed feed, java.lang.String encoding, java.lang.String version)
static void	writeFeedDoc(java.io.Writer output, Feed feed, java.lang.String encoding, java.lang.String version)
static void	writeFeedDoc(javax.xml.stream.XMLStreamWriter output, Feed feed, java.lang.String encoding, java.lang.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

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

Field Detail

atomBase

public static final Attribute atomBase

the default atom xml namespace attribute of "http://www.w3.org/2005/Atom"

lang_en

public static final Attribute lang_en

the default library language attribute of "en-US"

encoding

public static java.lang.String encoding

the default document encoding of "UTF-8"

xml_version

public static java.lang.String xml_version

the default XML version of "1.0"

sort

public static final Attribute sort

the Atomsphere sort extension attribute. See the Project Page for more details

SORT_ASC

public static final java.util.Comparator<java.lang.String> SORT_ASC

Comparator for sorting feed entries in ascending order.

SORT_DESC

public static final java.util.Comparator<java.lang.String> SORT_DESC

Comparator for sorting feed entries in descending order

Constructor Detail

FeedDoc

public FeedDoc()

Method Detail

getAtomsphereVersion

public static Generator getAtomsphereVersion()

Returns:

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

writeFeedDoc

public static void writeFeedDoc(java.io.OutputStream output,
                                Feed feed,
                                java.lang.String encoding,
                                java.lang.String version)
                         throws java.lang.Exception

Parameters:

output - the target output for the feed document.

feed - the atom feed object containing the content of the feed

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

version - the xml version (default is 1.0)

Throws:

java.lang.Exception - thrown if the feed cannot be written to the output

writeEntryDoc

public static void writeEntryDoc(java.io.OutputStream output,
                                 Entry entry,
                                 java.lang.String encoding,
                                 java.lang.String version)
                          throws java.lang.Exception

Parameters:

output - the target output for the entry document.

entry - the atom entry object containing the content.

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

version - the xml version (default is 1.0)

Throws:

java.lang.Exception - thrown if the atom document cannot be written to the output

writeFeedDoc

public static void writeFeedDoc(java.io.Writer output,
                                Feed feed,
                                java.lang.String encoding,
                                java.lang.String version)
                         throws java.lang.Exception

Parameters:

output - the target output for the document.

feed - the atom feed object containing the content of the feed

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

version - the xml version (default is 1.0)

Throws:

java.lang.Exception - thrown if the feed cannot be written to the output

writeEntryDoc

public static void writeEntryDoc(java.io.Writer output,
                                 Entry entry,
                                 java.lang.String encoding,
                                 java.lang.String version)
                          throws java.lang.Exception

Parameters:

output - the target output for the entry document.

entry - the atom entry object containing the content.

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

version - the xml version (default is 1.0)

Throws:

java.lang.Exception - thrown if the atom document cannot be written to the output

writeFeedDoc

public static void writeFeedDoc(javax.xml.stream.XMLStreamWriter output,
                                Feed feed,
                                java.lang.String encoding,
                                java.lang.String version)
                         throws java.lang.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));
FeedDoc.writeFeedDoc(writer,myFeed,null,null);  
        

Parameters:

output - the target output for the feed.

feed - the atom feed object containing the content of the feed

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

version - the xml version (default is 1.0)

Throws:

java.lang.Exception - thrown if the feed cannot be written to the output

writeEntryDoc

public static void writeEntryDoc(javax.xml.stream.XMLStreamWriter output,
                                 Entry entry,
                                 java.lang.String encoding,
                                 java.lang.String version)
                          throws java.lang.Exception

Writes and entry element to a document.

Parameters:

output - the target output for the entry document.

entry - the atom entry object containing the content of the entry

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

version - the xml version (default is 1.0)

Throws:

java.lang.Exception - thrown if the feed cannot be written to the output see writeFeedDoc(XMLStreamWriter output,Feed feed,String encoding,String version)

readFeedToString

public static java.lang.String readFeedToString(Feed feed,
                                                java.lang.String xmlStreamWriter)
                                         throws java.lang.Exception

This method reads in a Feed element and returns the contents as an atom 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

readFeedToString(Feed)

if the XMLStreamWriter class cannot be found in the classpath.

Parameters:

feed - the feed to be converted to an atom document string.

xmlStreamWriter - the fully qualified XMLStreamWriter class name.

Returns:

an atom feed document string.

Throws:

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

readEntryToString

public static java.lang.String readEntryToString(Entry entry,
                                                 java.lang.String xmlStreamWriter)
                                          throws java.lang.Exception

This method reads in an Entry element and returns the contents as an atom feed document string

Parameters:

entry - the entry to be converted to an atom document string.

xmlStreamWriter - the XMLStreamWriter to use

Returns:

the atom entry document string.

Throws:

java.lang.Exception - if the entry cannot be returned as a String see readFeedToString(Feed feed, String xmlStreamWriter)

readFeedToString

public static java.lang.String readFeedToString(Feed feed)
                                         throws java.lang.Exception

This method reads in a Feed bean and returns the contents as an atom feed string.

Parameters:

feed - the feed to be converted to an atom string.

Returns:

an atom feed document string.

Throws:

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

readEntryToString

public static java.lang.String readEntryToString(Entry entry)
                                          throws java.lang.Exception

This method reads in an atom Entry element and returns the contents as an atom Entry document String containing the entry.

Parameters:

entry - the entry to be converted to an atom entry document string.

Returns:

an atom entry document string containing the entry argument passed in.

Throws:

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

readFeedToBean

public static Feed readFeedToBean(java.lang.String xmlString)
                           throws java.lang.Exception

This method reads an xml string into a Feed element.

Parameters:

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

Returns:

the atom Feed element

Throws:

java.lang.Exception - if the string cannot be parsed into a Feed element.

readEntryToBean

public static Entry readEntryToBean(java.lang.String xmlString)
                             throws java.lang.Exception

This method reads an xml string into a Entry element.

Parameters:

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

Returns:

the atom Entry element

Throws:

java.lang.Exception - if the string cannot be parsed into a Entry element.

readFeedToBean

public static Feed readFeedToBean(java.io.File file)
                           throws java.lang.Exception

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

Parameters:

file - the file object representing an atom file.

Returns:

the atom Feed element.

Throws:

java.lang.Exception - if the file cannot be parsed into a Feed element.

readEntryToBean

public static Entry readEntryToBean(java.io.File file)
                             throws java.lang.Exception

This method reads an xml File object into an Entry element.

Parameters:

file - the file object representing an atom file.

Returns:

the atom Entry element.

Throws:

java.lang.Exception - if the file cannot be parsed into an Entry element.

readFeedToBean

public static Feed readFeedToBean(java.net.URL url)
                           throws java.lang.Exception

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

Parameters:

url - the Internet network location of an atom file.

Returns:

the atom Feed element.

Throws:

java.lang.Exception - if the URL cannot be parsed into a Feed element.

readEntryToBean

public static Entry readEntryToBean(java.net.URL url)
                             throws java.lang.Exception

This method reads an atom file from a URL into a Entry element.

Parameters:

url - the Internet network location of an atom file.

Returns:

the atom Entry element.

Throws:

java.lang.Exception - if the URL cannot be parsed into a Entry element.

readFeedToBean

public static Feed readFeedToBean(java.io.InputStream inputStream)
                           throws java.lang.Exception

This method reads an atom file from an input stream into a Feed element.

Parameters:

inputStream - the input stream containing an atom file.

Returns:

the atom Feed element.

Throws:

java.lang.Exception - if the URL cannot be parsed into a Feed element.

readEntryToBean

public static Entry readEntryToBean(java.io.InputStream inputStream)
                             throws java.lang.Exception

This method reads an atom file from an input stream into a Entry element.

Parameters:

inputStream - the input stream containing an atom file.

Returns:

the atom Entry element.

Throws:

java.lang.Exception - if the URL cannot be parsed into a Feed element.

buildFeed

public static Feed buildFeed(Id id,
                             Title title,
                             Updated updated,
                             Rights rights,
                             java.util.List<Author> authors,
                             java.util.List<Category> categories,
                             java.util.List<Contributor> contributors,
                             java.util.List<Link> links,
                             java.util.List<Attribute> attributes,
                             java.util.List<Extension> extensions,
                             Generator generator,
                             Subtitle subtitle,
                             Icon icon,
                             Logo logo,
                             java.util.SortedMap<java.lang.String,Entry> entries)
                      throws AtomSpecException

Parameters:

id - the unique id element (optional)

title - the title element (optional)

updated - the updated element (optional)

rights - the rights element (optional)

authors - a list of author elements (optional)

categories - a list of category elements (optional)

contributors - a list of contributor elements (optional)

links - a list of link elements (optional)

attributes - additional attributes (optional)

extensions - a list of extension elements (optional)

generator - the generator element (optional)

subtitle - the subtitle element (optional)

icon - the icon element (optional)

logo - the logo element (optional)

entries - a list of entry elements (optional)

Returns:

an immutable Feed object.

Throws:

AtomSpecException - if the data violates the specification.

buildAttribute

public static Attribute buildAttribute(java.lang.String name,
                                       java.lang.String value)

Parameters:

name - the attribute name.

value - the attribute value.

Returns:

an immutable Attribute object.

buildAuthor

public static Author buildAuthor(Name name,
                                 URI uri,
                                 Email email,
                                 java.util.List<Attribute> attributes,
                                 java.util.List<Extension> extensions)
                          throws AtomSpecException

Parameters:

name - the name element. (required)

uri - the uri element.

email - the email element.

attributes - additional attributes.

extensions - a list of extension elements.

Returns:

an immutable Author object.

Throws:

AtomSpecException - if the data violates the specification.

buildCategory

public static Category buildCategory(java.util.List<Attribute> attributes,
                                     java.lang.String content)
                              throws AtomSpecException

Parameters:

attributes - the attributes list which must contain "term" and may contain "scheme", "label" or others

content - the undefined element content.

Returns:

an immutable Category object.

Throws:

AtomSpecException - if the data violates the specification.

buildContent

public static Content buildContent(java.lang.String content,
                                   java.util.List<Attribute> attributes)
                            throws AtomSpecException

Parameters:

content - the content of this element

attributes - additional attributes.

Returns:

an immutable Content object.

Throws:

AtomSpecException

buildContributor

public static Contributor buildContributor(Name name,
                                           URI uri,
                                           Email email,
                                           java.util.List<Attribute> attributes,
                                           java.util.List<Extension> extensions)
                                    throws AtomSpecException

Parameters:

name - the name element. (required)

uri - the uri element.

email - the email element.

attributes - additional attributes.

extensions - a list of extension elements.

Returns:

an immutable Contributor object.

Throws:

AtomSpecException - if the data violates the specification.

buildEmail

public static Email buildEmail(java.lang.String email)

Parameters:

email - a human-readable email for the person

Returns:

an immutable Email object.

buildEntry

public static Entry buildEntry(Id id,
                               Title title,
                               Updated updated,
                               Rights rights,
                               Content content,
                               java.util.List<Author> authors,
                               java.util.List<Category> categories,
                               java.util.List<Contributor> contributors,
                               java.util.List<Link> links,
                               java.util.List<Attribute> attributes,
                               java.util.List<Extension> extensions,
                               Published published,
                               Summary summary,
                               Source source)
                        throws AtomSpecException

Parameters:

id - the id element (required)

title - the title element (required)

updated - the updated element (required)

rights - the rights element (optional)

content - the content element (optional)

authors - a list of author elements (optional)

categories - a list of category elements (optional)

contributors - a list of contributor elements (optional)

links - a list of link elements (optional)

attributes - additional attributes.(optional)

extensions - a list of extension elements (optional)

published - the published element (optional)

summary - the summary element (optional)

source - the source element (optional)

Returns:

an immutable Entry object.

Throws:

AtomSpecException - if the data violates the specification.

buildExtension

public static Extension buildExtension(java.lang.String elementName,
                                       java.util.List<Attribute> attributes,
                                       java.lang.String content)

Parameters:

elementName - the name of the extension element.

attributes - additional attributes.

content - the content of the extension element.

Returns:

an immutable Extension object.

buildGenerator

public static Generator buildGenerator(java.util.List<Attribute> attributes,
                                       java.lang.String text)
                                throws AtomSpecException

Parameters:

attributes - the attributes list which can contain "uri" and or "version" or others

text - the text content.

Returns:

an immutable Generator object.

Throws:

AtomSpecException

buildIcon

public static Icon buildIcon(java.util.List<Attribute> attributes,
                             java.lang.String atomUri)
                      throws AtomSpecException

Parameters:

atomUri - the URI reference.

attributes - additional attributes.

Returns:

an immutable Icon object.

Throws:

AtomSpecException

buildId

public static Id buildId(java.util.List<Attribute> attributes,
                         java.lang.String atomUri)
                  throws AtomSpecException

Parameters:

atomUri - the URI reference.

attributes - additional attributes.

Returns:

an immutable Id object.

Throws:

AtomSpecException

buildLink

public static Link buildLink(java.util.List<Attribute> attributes,
                             java.lang.String content)
                      throws AtomSpecException

Parameters:

attributes - the attributes list which must contain "href" and may contain "rel", "type", "hreflang", "title", "length" or others

content - the undefined link content.

Returns:

an immutable Link object.

Throws:

AtomSpecException - if the data violates the specification.

buildLogo

public static Logo buildLogo(java.util.List<Attribute> attributes,
                             java.lang.String atomUri)
                      throws AtomSpecException

Parameters:

atomUri - the logo uri reference.

attributes - additional attributes.

Returns:

an immutable Logo object.

Throws:

AtomSpecException

buildName

public static Name buildName(java.lang.String name)

Parameters:

name - a human-readable name for the person

Returns:

an immutable Name object.

buildPublished

public static Published buildPublished(java.util.Date published,
                                       java.util.List<Attribute> attributes)
                                throws AtomSpecException

Parameters:

published - the date formatted to [RFC3339]

Returns:

an immutable Published object.

Throws:

AtomSpecException

buildRights

public static Rights buildRights(java.lang.String rights,
                                 java.util.List<Attribute> attributes)
                          throws AtomSpecException

Parameters:

rights - the rights text.

attributes - additional attributes.

Returns:

an immutable Rights object.

Throws:

AtomSpecException

buildSource

public static Source buildSource(Id id,
                                 Title title,
                                 Updated updated,
                                 Rights rights,
                                 java.util.List<Author> authors,
                                 java.util.List<Category> categories,
                                 java.util.List<Contributor> contributors,
                                 java.util.List<Link> links,
                                 java.util.List<Attribute> attributes,
                                 java.util.List<Extension> extensions,
                                 Generator generator,
                                 Subtitle subtitle,
                                 Icon icon,
                                 Logo logo)
                          throws AtomSpecException

Parameters:

id - the unique id element (optional)

title - the title element (optional)

updated - the updated element (optional)

rights - the rights element (optional)

authors - a list of author elements (optional)

categories - a list of category elements (optional)

contributors - a list of contributor elements (optional)

links - a list of link elements (optional)

attributes - additional attributes (optional)

extensions - a list of extension elements (optional)

generator - the generator element (optional)

subtitle - the subtitle element (optional)

icon - the icon element (optional)

logo - the logo element (optional)

Returns:

an immutable Source object.

Throws:

AtomSpecException - if the data violates the specification.

buildSubtitle

public static Subtitle buildSubtitle(java.lang.String subtitle,
                                     java.util.List<Attribute> attributes)
                              throws AtomSpecException

Parameters:

subtitle - the subtitle text.

attributes - additional attributes.

Returns:

an immutable Subtitle object.

Throws:

AtomSpecException

buildSummary

public static Summary buildSummary(java.lang.String summary,
                                   java.util.List<Attribute> attributes)
                            throws AtomSpecException

Parameters:

summary - the summary text.

attributes - additional attributes.

Returns:

an immutable Summary object.

Throws:

AtomSpecException

buildTitle

public static Title buildTitle(java.lang.String title,
                               java.util.List<Attribute> attributes)
                        throws AtomSpecException

Parameters:

title - the title text

attributes - additional attributes.

Returns:

an immutable Title object.

Throws:

AtomSpecException

buildUpdated

public static Updated buildUpdated(java.util.Date updated,
                                   java.util.List<Attribute> attributes)
                            throws AtomSpecException

Parameters:

updated - the date formatted to [RFC3339]

Returns:

a immutable Updated object.

Throws:

AtomSpecException

buildURI

public static URI buildURI(java.lang.String uri)

Parameters:

uri - the content of the uri according to Section 7 of [RFC3986]

Returns:

and immutable URI object.

getContentType

public static FeedDoc.ContentType getContentType(java.util.List<Attribute> attriubtes)

Convenience method for getting the content type for this element. Examines the "type" and "src" attributes if they exist in the list.

Returns:

the content type for this element. One of TEXT,HTML,XHTML,OTHER or EXTERNAL

sortEntries

public static Feed sortEntries(Feed feed,
                               java.util.Comparator<java.lang.String> comparator,
                               java.lang.Class<?> elementClass)
                        throws AtomSpecException

This method sorts the entries of the feed. The Updated, Title and Summary are currently the only elementInstance types supported.

Parameters:

feed - the feed whose entries are to be sorted

comparator - used to determine sort order

elementClass - serves as the key element for the entries collection

Returns:

the sorted feed.

Throws:

AtomSpecException - if the data violates the specification.