org.apache.juneau.dto.atom.package.html Maven / Gradle / Ivy
ATOM Data Transfer Objects
Table of Contents
{@doc package-summary.html#Overview Overview}
{@doc package-summary.html#Serialize Serializing ATOM feeds}
{@doc package-summary.html#AtomJson ATOM/JSON}
{@doc package-summary.html#AtomRdfXml ATOM/RDF/XML}
{@doc package-summary.html#AtomHtml ATOM/HTML}
{@doc package-summary.html#Parse Parsing ATOM feeds}
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("[email protected]" )
)
.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 s = XmlSerializer.create ().sq().ws().build();
// Serialize to ATOM/XML
String atomXml = s.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> [email protected]</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 s = XmlSerializer.create ().sq().ws().build();
// Serialize to ATOM/XML
String atomXml = s.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> [email protected]</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 s = XmlSerializer.create ().sq().ws().defaultNamespaceUri("atom" ).build();
// Serialize to ATOM/XML
String atomXml = s.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 <em&stuff</em> about Juneau
</subtitle>
<entry>
<author>
<name> Jane Smith</name>
<uri> http://juneau.apache.org/</uri>
<email> [email protected]</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.
JsonSerializer s = SimpleJsonSerializer.DEFAULT_READABLE ;
// Serialize to ATOM/JSON
String atomJson = s.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: '[email protected]'
}
],
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 s = RdfSerializer.create ()
.xmlabbrev()
.ws()
.sq()
.set(RdfProperties.RDF_rdfxml_tab , 3)
.build();
// Serialize to ATOM/RDF/XML
String atomRdfXml = s.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 <em>lot</em> 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> [email protected]</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> <div xmlns="http://www.w3.org/1999/xhtml"><p><i>[Update: Juneau supports ATOM.]</i></p></div></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 s = XmlSerializer.DEFAULT_SQ_READABLE ;
// Serialize to ATOM/XML
String atomXml = s.serialize(feed);
// Get an XML parser to convert it back into a POJO
XmlParser p = XmlParser.DEFAULT ;
// Convert the XML back into a POJO
Feed feed2 = p.parse(atomXml, Feed.class );
ATOM Feed objects can also be constructed from the other media types using the appropriate parsers.
*** fín ***