ATOM Data Transfer Objects

1 - Overview

Juneau supports generation and consumption of ATOM feeds through the use of DTOs (Data Transfer Objects).
It uses existing support for serializing and parsing POJOs to and from XML to define these ATOM objects.

The examples shown here are pulled from the AtomFeedResource class in the org.apache.juneau.sample.war project.

1.1 - Serializing ATOM feeds

The Juneau ATOM feed DTOs are simply beans with fluent-style setters.
The following code shows a feed being created programmatically using the {@link org.apache.juneau.dto.atom.AtomBuilder} class.

import static org.apache.juneau.dto.atom.AtomBuilder.*; Feed feed = feed("tag:juneau.apache.org", "Juneau ATOM specification", "2016-01-02T03:04:05Z") .subtitle(text("html").text("Describes <em>stuff</em> about Juneau")) .links( link("alternate", "text/html", "http://juneau.apache.org").hreflang("en"), link("self", "application/atom+xml", "http://juneau.apache.org/feed.atom") ) .generator( generator("Juneau").uri("http://juneau.apache.org").version("1.0") ) .entries( entry("tag:juneau.sample.com,2013:1.2345", "Juneau ATOM specification snapshot", "2016-01-02T03:04:05Z") .links( link("alternate", "text/html", "http://juneau.apache.org/juneau.atom"), link("enclosure", "audio/mpeg", "http://juneau.apache.org/audio/juneau_podcast.mp3").length(1337) ) .published("2016-01-02T03:04:05Z") .authors( person("Jane Smith").uri("http://juneau.apache.org").email("janesmith@apache.org") ) .contributors( person("John Smith") ) .content( content("xhtml") .lang("en") .base("http://www.apache.org/") .text("<div><p><i>[Update: Juneau supports ATOM.]</i></p></div>") ) );

To serialize this to ATOM, use the {@link org.apache.juneau.xml.XmlSerializer} class:

Example with no namespaces

// Create a serializer with readable output, no namespaces yet. XmlSerializer serializer = XmlSerializer.create().sq().ws().build(); // Serialize to ATOM/XML String atomXml = serializer.serialize(feed);

Results

<feed> <id> tag:juneau.apache.org </id> <link href='http://juneau.apache.org/' rel='alternate' type='text/html' hreflang='en'/> <link href='http://juneau.apache.org/feed.atom' rel='self' type='application/atom+xml'/> <title type='text'> Juneau ATOM specification </title> <updated>2016-01-02T03:04:05Z</updated> <generator uri='http://juneau.apache.org/' version='1.0'> Juneau </generator> <subtitle type='html'> Describes <em>stuff</em> about Juneau </subtitle> <entry> <author> <name>Jane Smith</name> <uri>http://juneau.apache.org/</uri> <email>janesmith@apache.org</email> </author> <contributor> <name>John Smith</name> </contributor> <id> tag:juneau.apache.org </id> <link href='http://juneau.apache.org/juneau.atom' rel='alternate' type='text/html'/> <link href='http://juneau.apache.org/audio/juneau_podcast.mp3' rel='enclosure' type='audio/mpeg' length='12345'/> <title> Juneau ATOM specification snapshot </title> <updated>2016-01-02T03:04:05Z</updated> <content base='http://www.apache.org/' lang='en' type='xhtml'> <div xmlns="http://www.w3.org/1999/xhtml"><p><i>[Update: Juneau supports ATOM.]</i></p></div> </content> <published>2016-01-02T03:04:05Z</published> </entry> </feed>

The following is the same, except with XML namespaces enabled:

Example with namespaces

// Create a serializer with readable output with namespaces. XmlSerializer serializer = XmlSerializer.create().sq().ws().build(); // Serialize to ATOM/XML String atomXml = serializer.serialize(feed);

Results

<atom:feed xmlns='http://www.apache.org/2013/Juneau' xmlns:atom='http://www.w3.org/2005/Atom/' xmlns:xml='http://www.w3.org/XML/1998/namespace' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'> <atom:id> tag:juneau.apache.org </atom:id> <atom:link href='http://juneau.apache.org/' rel='alternate' type='text/html' hreflang='en'/> <atom:link href='http://juneau.apache.org/feed.atom' rel='self' type='application/atom+xml'/> <atom:title type='text'> Juneau ATOM specification </atom:title> <atom:updated>2016-01-02T03:04:05Z</atom:updated> <atom:generator uri='http://juneau.apache.org/' version='1.0'> Juneau </atom:generator> <atom:subtitle type='html'> Describes <em>stuff</em> about Juneau </atom:subtitle> <atom:entry> <atom:author> <atom:name>Jane Smith</atom:name> <atom:uri>http://juneau.apache.org/</atom:uri> <atom:email>janesmith@apache.org</atom:email> </atom:author> <atom:contributor> <atom:name>John Smith</atom:name> </atom:contributor> <atom:id> tag:juneau.apache.org </atom:id> <atom:link href='http://juneau.apache.org/juneau.atom' rel='alternate' type='text/html'/> <atom:link href='http://juneau.apache.org/audio/juneau_podcast.mp3' rel='enclosure' type='audio/mpeg' length='12345'/> <atom:title> Juneau ATOM specification snapshot </atom:title> <atom:updated>2016-01-02T03:04:05Z</atom:updated> <atom:content xml:base='http://www.apache.org/' xml:lang='en' type='xhtml'> <div xmlns="http://www.w3.org/1999/xhtml"><p><i>[Update: Juneau supports ATOM.]</i></p></div> </atom:content> <atom:published>2016-01-02T03:04:05Z</atom:published> </atom:entry> </atom:feed>

The following is the same, except with XML namespaces enabled and the ATOM namespace as the default namespace:

Example with namespaces with ATOM as the default namespace

// Create a serializer with readable output with namespaces. XmlSerializer serializer = XmlSerializer.create().sq().ws().defaultNamespaceUri("atom").build(); // Serialize to ATOM/XML String atomXml = serializer.serialize(feed);

Results

<feed xmlns='http://www.w3.org/2005/Atom/' xmlns:xml='http://www.w3.org/XML/1998/namespace' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'> <id> tag:juneau.apache.org </id> <link href='http://juneau.apache.org/' rel='alternate' type='text/html' hreflang='en'/> <link href='http://juneau.apache.org/feed.atom' rel='self' type='application/atom+xml'/> <title type='text'> Juneau ATOM specification </title> <updated>2016-01-02T03:04:05Z</updated> <generator uri='http://juneau.apache.org/' version='1.0'> Juneau </generator> <subtitle type='html'> Describes &lt;em&stuff&lt;/em&gt; about Juneau </subtitle> <entry> <author> <name>Jane Smith</name> <uri>http://juneau.apache.org/</uri> <email>janesmith@apache.org</email> </author> <contributor> <name>John Smith</name> </contributor> <id> tag:juneau.apache.org </id> <link href='http://juneau.apache.org/juneau.atom' rel='alternate' type='text/html'/> <link href='http://juneau.apache.org/audio/juneau_podcast.mp3' rel='enclosure' type='audio/mpeg' length='12345'/> <title> Juneau ATOM specification snapshot </title> <updated>2016-01-02T03:04:05Z</updated> <content xml:base='http://www.apache.org/' xml:lang='en' type='xhtml'> <div xmlns="http://www.w3.org/1999/xhtml"><p><i>[Update: Juneau supports ATOM.]</i></p></div> </content> <published>2016-01-02T03:04:05Z</published> </entry> </feed>

1.1.1 - ATOM/JSON

The {@link org.apache.juneau.json.JsonSerializer} class can also be used to produce ATOM in JSON format.

ATOM/JSON example

// Get JSON serializer with readable output. Json5Serializer serializer = Json5Serializer.DEFAULT_READABLE; // Serialize to ATOM/JSON String atomXml = serializer.serialize(feed);

Results

{ id: { text: 'tag:juneau.apache.org' }, links: [ { href: 'http://juneau.apache.org/', rel: 'alternate', type: 'text/html', hreflang: 'en' }, { href: 'http://juneau.apache.org/juneau.atom', rel: 'self', type: 'application/atom+xml' } ], title: { type: 'text', text: 'Juneau ATOM specification' }, updated: '2016-01-02T03:04:05Z', generator: { uri: 'http://juneau.apache.org/', version: '1.0', text: 'Juneau' }, subtitle: { type: 'html', text: 'Describes <em>stuff</em> about Juneau' }, entries: [ { authors: [ { name: 'James Bognar', uri: 'http://juneau.apache.org/', email: 'jamesbognar@apache.org' } ], contributors: [ { name: 'Barry M. Caceres' } ], id: { text: 'tag:juneau.apache.org' }, links: [ { href: 'http://juneau.apache.org/juneau.atom', rel: 'alternate', type: 'text/html' }, { href: 'http://juneau.apache.org/audio/juneau_podcast.mp3', rel: 'enclosure', type: 'audio/mpeg', length: 12345 } ], title: { text: 'Juneau ATOM specification snapshot' }, updated: '2016-01-02T03:04:05Z', content: { base: 'http://www.apache.org/', lang: 'en', type: 'xhtml', text: '<div xmlns="http://www.w3.org/1999/xhtml"><p><i>[Update: Juneau supports ATOM.]</i></p></div>' }, published: '2016-01-02T03:04:05Z' } ] }

1.1.2 - ATOM/RDF/XML

The {@link org.apache.juneau.jena.RdfSerializer} class and subclasses can also be used to produce ATOM in various RDF formats.

ATOM/RDF/XML example

// Get RDF/XML serializer with readable output. RdfSerializer serializer = RdfSerializer.create() .xmlabbrev() .ws() .sq() .rdfxml_tab(3) .build(); // Serialize to ATOM/RDF/XML String atomRdfXml = serializer.serialize(feed);

Results

<rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#' xmlns:j='http://www.apache.org/juneau/' xmlns:jp='http://www.apache.org/juneaubp/' xmlns:atom='http://www.w3.org/2005/Atom/' xmlns:j.0='http://www.w3.org/XML/1998/'> <rdf:Description> <atom:id rdf:parseType='Resource'> <atom:text>tag:juneau.apache.org</atom:text> </atom:id> <atom:links> <rdf:Seq> <rdf:li rdf:parseType='Resource'> <atom:href>http://juneau.apache.org/</atom:href> <atom:rel>alternate</atom:rel> <atom:type>text/html</atom:type> <atom:hreflang>en</atom:hreflang> </rdf:li> <rdf:li rdf:parseType='Resource'> <atom:href>http://juneau.apache.org/feed.atom</atom:href> <atom:rel>self</atom:rel> <atom:type>application/atom+xml</atom:type> </rdf:li> </rdf:Seq> </atom:links> <atom:title rdf:parseType='Resource'> <atom:type>text</atom:type> <atom:text>Juneau ATOM specification</atom:text> </atom:title> <atom:updated>2016-01-02T03:04:05Z</atom:updated> <atom:generator rdf:parseType='Resource'> <atom:uri rdf:resource='http://juneau.apache.org/'/> <atom:version>1.0</atom:version> <atom:text>Juneau</atom:text> </atom:generator> <atom:subtitle rdf:parseType='Resource'> <atom:type>html</atom:type> <atom:text>A &lt;em&gt;lot&lt;/em&gt; of effort went into making this effortless</atom:text> </atom:subtitle> <atom:entries> <rdf:Seq> <rdf:li rdf:parseType='Resource'> <atom:authors> <rdf:Seq> <rdf:li rdf:parseType='Resource'> <atom:name>James Bognar</atom:name> <atom:uri rdf:resource='http://juneau.apache.org/'/> <atom:email>james.bognar@salesforce.com</atom:email> </rdf:li> </rdf:Seq> </atom:authors> <atom:contributors> <rdf:Seq> <rdf:li rdf:parseType='Resource'> <atom:name>Barry M. Caceres</atom:name> </rdf:li> </rdf:Seq> </atom:contributors> <atom:id rdf:parseType='Resource'> <atom:text>tag:juneau.apache.org</atom:text> </atom:id> <atom:links> <rdf:Seq> <rdf:li rdf:parseType='Resource'> <atom:href>http://juneau.apache.org/juneau.atom</atom:href> <atom:rel>alternate</atom:rel> <atom:type>text/html</atom:type> </rdf:li> <rdf:li rdf:parseType='Resource'> <atom:href>http://juneau.apache.org/audio/juneau_podcast.mp3</atom:href> <atom:rel>enclosure</atom:rel> <atom:type>audio/mpeg</atom:type> <atom:length>12345</atom:length> </rdf:li> </rdf:Seq> </atom:links> <atom:title rdf:parseType='Resource'> <atom:text>Juneau ATOM specification snapshot</atom:text> </atom:title> <atom:updated>2016-01-02T03:04:05Z</atom:updated> <atom:content rdf:parseType='Resource'> <j.0:namespacebase rdf:resource='http://www.apache.org/'/> <j.0:namespacelang>en</j.0:namespacelang> <atom:type>xhtml</atom:type> <atom:text>&lt;div xmlns="http://www.w3.org/1999/xhtml"&gt;&lt;p&gt;&lt;i&gt;[Update: Juneau supports ATOM.]&lt;/i&gt;&lt;/p&gt;&lt;/div&gt;</atom:text> </atom:content> <atom:published>2016-01-02T03:04:05Z</atom:published> </rdf:li> </rdf:Seq> </atom:entries> </rdf:Description> </rdf:RDF>

1.1.3 - ATOM/HTML

The {@link org.apache.juneau.html.HtmlSerializer} class can be used to produce ATOM in HTML format.

The following is the output produced by the AtomFeedResource in the org.apache.juneau.sample.war project:

Example ATOM/HTML results

1.2 - Parsing ATOM feeds

Use the {@link org.apache.juneau.xml.XmlParser} to convert ATOM/XML feeds back into their original POJOs:

// Create a serializer with readable output with namespaces XmlSerializer serializer = XmlSerializer.DEFAULT_SQ_READABLE; // Serialize to ATOM/XML String atomXml = serializer.serialize(feed); // Get an XML parser to convert it back into a POJO XmlParser parser = XmlParser.DEFAULT; // Convert the XML back into a POJO Feed feed2 = parser.parse(atomXml, Feed.class);

ATOM Feed objects can also be constructed from the other media types using the appropriate parsers.

*** fín ***