<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 Websites as well as
      directly to user agents."
   </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 &XML-BIND-API; to marshal and unmarshal
         it. The
         main classes are in the <code>org.jboss.resteasy.plugins.providers.atom</code> package and are
         <code>Feed</code>, <code>Entry</code>, <code>Content</code>, and
         <code>Link</code>. If you
         look at the source, you will see that these are annotated with &XML-BIND-API; 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>RESTEasy's atom provider is &XML-BIND-API; based, there are no limits to sending atom objects using XML.
         All the other &XML-BIND-API; providers that RESTEasy has like JSON and fastinfoset can automatically be re-use.
         Just add "atom+" in front of the main subtype. i.e. @Produces("application/atom+json") or
         @Consumes("application/atom+fastinfoset")
      </para>
   </sect1>
   <sect1 id="xml_bind_api_atom">
      <title>Using &XML-BIND-API; with the Atom Provider</title>
      <para>
         The <code>org.jboss.resteasy.plugins.providers.atom.Content</code> class is used to unmarshal and marshal &XML-BIND-API;
         annotated objects that are the body of the content. Here's an example of sending an <code>Entry</code> 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, 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.
      </para>
      <para>
         If the input is an atom document, &XML-BIND-API; 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.
      </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>
