JBoss.orgCommunity Documentation

第 23 章 RESTEasy 对 Atom 的支持

23.1. RESTEasy Atom API and Provider
23.2. 使用 JAXB 和 Atom 提供程序

阅读 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 Web sites as well as directly to user agents."

Atom是一种基于XML的文档格式,它描述了称为"feeds"的相关信息的列表。 Feeds 由许多项(称为"entries")组成,每个项都带有一组可扩展的附加元数据。 例如,每个Feeds都有一个标题。 Atom解决的主要用例是将Web内容(例如weblogs和新闻标题)联合到网站以及直接联系到用户代理。

Atom是新一代的RSS提要。虽然它主要用于博客和新闻的联合,但是许多人开始使用这种格式作为Web服务的替代,例如,分散通知,作业方式,或者只是一种从服务批量发送 或接收数据的好格式。

RESTEasy 在 Java 中定义了一个简单的对象模型来表示 Atom,并使用 JAXB 对其进行编组和反编组。主要的类在 org.jboss.resteasy.plugins.providers.atom 包中,它们是 Feed、 Entry、 Content 和 Link。如果查看源代码,就会看到这些文件都带有 JAXB 注解。这个发行版包含了这个项目的 javadocs,是学习这个模型的必修课。下面是一个使用 RESTEasy API 发送atom提要的简单示例。

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

由于 RESTEasy 的atom提供程序是基于 JAXB 的,因此您不必局限于使用 XML 发送atom对象。您可以自动重用 RESTEasy 拥有的所有其他 JAXB 提供程序,如 JSON 和 fastinfoset。你所要做的就是在主子类型前面加上"atom+"。即@Produces("application/atom+json")或@Consumes("application/atom+fastinfoset")

org.jboss.resteasy.plugins.providers.atom.Content 类允许您对作为内容主体的 JAXB 注释对象进行编组和反编组。下面是发送一个条目的示例,其中附加了一个 Customer 对象作为条目内容的主体。

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

Content.setJAXBObject() 方法用于告诉内容对象您正在发送回一个 Java JAXB 对象,并希望它被适当地编组。如果您使用与 XML 不同的基本格式,即"application/atom+json",那么附加的 JAXB 对象将被编组为相同的格式。

如果您有一个 atom document 作为输入,还可以使用 Content.getJAXBObject(Class clazz) 方法从 Content 中提取 JAXB 对象。下面是一个输入 atom document 和从内容中提取 Customer 对象的示例。

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