1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
<chapter id="Atom">
<title>RESTEasy Atom Support</title>
<para>
From W3.org (http://tools.ietf.org/html/rfc4287):
</para>
<para>
"Atom is an XML-based document format that describes lists of related
information known as "feeds". Feeds are composed of a number of
items, known as "entries", each with an extensible set of attached
metadata. For example, each entry has a title.
The primary use case that Atom addresses is the syndication of Web
content such as weblogs and news headlines to Web sites as well as
directly to user agents."
</para>
<para>
Atom is the next-gen RSS feed. Although it is used primarily for the syndication of blogs and news, many
are starting to use this format as the envelope for Web Services, for example, distributed notifications, job
queues, or simply a nice format for sending or receiving data in bulk from a service.
</para>
<sect1 id="resteasy_atom">
<title>RESTEasy Atom API and Provider</title>
<para>RESTEasy has defined a simple object model in Java to represent Atom and uses JAXB to marshal and unmarshal
it. The
main classes are in the org.jboss.resteasy.plugins.providers.atom package and are Feed, Entry, Content, and
Link. If you
look at the source, you'd see that these are annotated with JAXB annotations. The distribution contains
the javadocs for this project and are a must to learn the model. Here is a simple example of sending
an atom feed using the RESTEasy API.
</para>
<programlisting><![CDATA[
import org.jboss.resteasy.plugins.providers.atom.Content;
import org.jboss.resteasy.plugins.providers.atom.Entry;
import org.jboss.resteasy.plugins.providers.atom.Feed;
import org.jboss.resteasy.plugins.providers.atom.Link;
import org.jboss.resteasy.plugins.providers.atom.Person;
@Path("atom")
public class MyAtomService
{
@GET
@Path("feed")
@Produces("application/atom+xml")
public Feed getFeed() throws URISyntaxException
{
Feed feed = new Feed();
feed.setId(new URI("http://example.com/42"));
feed.setTitle("My Feed");
feed.setUpdated(new Date());
Link link = new Link();
link.setHref(new URI("http://localhost"));
link.setRel("edit");
feed.getLinks().add(link);
feed.getAuthors().add(new Person("Bill Burke"));
Entry entry = new Entry();
entry.setTitle("Hello World");
Content content = new Content();
content.setType(MediaType.TEXT_HTML_TYPE);
content.setText("Nothing much");
entry.setContent(content);
feed.getEntries().add(entry);
return feed;
}
}]]></programlisting>
<para>Because RESTEasy's atom provider is JAXB based, you are not limited to sending atom objects using XML.
You can automatically re-use all the other JAXB providers that RESTEasy has like JSON and fastinfoset.
All you have to do is have "atom+" in front of the main subtype. i.e. @Produces("application/atom+json") or
@Consumes("application/atom+fastinfoset")
</para>
</sect1>
<sect1 id="jaxb_atom">
<title>Using JAXB with the Atom Provider</title>
<para>
The org.jboss.resteasy.plugins.providers.atom.Content class allows you to unmarshal and marshal JAXB
annotated objects that are the body of the content. Here's an example of sending an Entry with
a Customer object attached as the body of the entry's content.
</para>
<programlisting><![CDATA[
@XmlRootElement(namespace = "http://jboss.org/Customer")
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer
{
@XmlElement
private String name;
public Customer()
{
}
public Customer(String name)
{
this.name = name;
}
public String getName()
{
return name;
}
}
@Path("atom")
public static class AtomServer
{
@GET
@Path("entry")
@Produces("application/atom+xml")
public Entry getEntry()
{
Entry entry = new Entry();
entry.setTitle("Hello World");
Content content = new Content();
content.setJAXBObject(new Customer("bill"));
entry.setContent(content);
return entry;
}
}]]></programlisting>
<para>
The Content.setJAXBObject() method is used to tell the content object you are sending back
a Java JAXB object and want it marshalled appropriately. If you are using a different base
format other than XML, i.e. "application/atom+json", this attached JAXB object will be marshalled
into that same format.
</para>
<para>
If you have an atom document as your input, you can also extract JAXB objects from Content using the
Content.getJAXBObject(Class clazz) method. Here is an example of an input atom document and extracting
a Customer object from the content.
</para>
<programlisting><![CDATA[
@Path("atom")
public static class AtomServer
{
@PUT
@Path("entry")
@Produces("application/atom+xml")
public void putCustomer(Entry entry)
{
Content content = entry.getContent();
Customer cust = content.getJAXBObject(Customer.class);
}
}
]]></programlisting>
</sect1>
</chapter>
|
