[[_atom]]
== RESTEasy Atom Support

From W3.org (http://tools.ietf.org/html/rfc4287): 

"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 Websites as well as directly to user agents." 

[[_resteasy_atom]]
=== RESTEasy Atom API and Provider

RESTEasy has defined a simple object model in Java to represent Atom and uses {xml-binding} 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 will see that these are annotated with {xml-binding} 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. 

[source,java]
----

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() {
        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;
    }
}
----

RESTEasy's atom provider is {xml-binding} based, there are no limits to sending atom objects using XML.
All the other {xml-binding} providers that RESTEasy has like JSON and fastinfoset can automatically be re-use.
Just add "atom+" in front of the main subtype.
i.e.
s
[source,java]
----
@Produces("application/atom+json") or @Consumes("application/atom+fastinfoset")
----

[[_xml_bind_api_atom]]
=== Using {xml-binding} with the Atom Provider

The `org.jboss.resteasy.plugins.providers.atom.Content` class is used to unmarshal and marshal {xml-binding}
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.

[source,java]
----
@XmlRootElement(namespace = "https://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;
    }
}
----

The `Content.setJAXBObject()` method is used to tell the content object, an object is being sent back and it is to be marshalled appropriately.
If using a different base format than XML, i.e.
"application/atom+json", this attached object will be marshalled into that same format. 

If the input is an atom document, {xml-binding} objects can be extracted 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. 

[source,java]
----

@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);
    }
}
----