Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.2)
  3. Reference Materials for Mule ESB 3
  4. Modules Reference

  5. Atom Module Reference

Atom Module Reference

Introduction

The name Atom applies to a pair of related standards. The Atom Syndication Format is an XML language used for web feeds, while the Atom Publishing Protocol (AtomPub or APP) is a simple HTTP-based protocol for creating and updating web resources. Mule contains support for both.

Namespace and Syntax

XML namespace

http://www.mulesoft.org/schema/mule/atom

XML schema location

http://www.mulesoft.org/schema/mule/atom http://www.mulesoft.org/schema/mule/atom/3.2/mule-atom.xsd

Considerations

Features

The Mule Atom Module includes an implementation of Apache Abdera, making it possible to integrate easily with Atom feeds and Atom Publishing Protocol servers from within a Mule configuration.

The module current supports the following capabilities:

  • Consuming Atom feeds

  • Publishing Atom entries

  • Server side AtomPub support as a Mule service

ETags

The Atom Http endpoint respects ETags and the 304 Not Modified response code by default, so you don’t need to worry about consuming unnecessary updates.

Example Configurations

Consuming Feeds and other Atom resources

One of the most common patterns is for integrating with Atom is polling for feed updates. With Mule this can be done quite easily. You must first write your class which receives an Atom Entry:

EntryReceiver.java 
package org.mule.module.atom.example;

import org.apache.abdera.model.Feed;

public class EntryReceiver {
    public void processEntry(Entry entry) throws Exception {
        //process the entry
    }
}

Use an atom feed splitter to split an incoming feed into individual messages so the component method is invoked for each entry in the feed. The flow configuration would look like so:

<flow name="eventConsumer">
    <poll frequency="10000">
        <http:outbound-endpoint address="http://localhost:9002/events"/>
    </poll>
    <atom:feed-splitter/>
    <atom:entry-last-updated-filter/>
    <component class="org.mule.module.atom.event.EntryReceiver"/>
</flow>

The atom:entry-last-updated-filter is optional. It should only be used to filter older entries from the feed. Note that the atom:entry-last-updated-filter should come after the <atom:feed-splitter/> since you need to split the feed into entries so that the filter can process them. Also note that we do not set a lastUpdate date on the filter. This implies the default behavior that all available entries ise read before the processing of any entries that are new as of the last read.

Accessing the Feed itself

If you need access to the feed itself, parse it using the object-to-feed transformer:

<flow name="eventConsumer">
    <poll frequency="10000">
        <http:outbound-endpoint address="http://localhost:9002/events"/>
    </poll>
    <atom:feed-splitter/>
    <atom:entry-last-updated-filter/>
    <component class="org.mule.module.atom.event.EntryReceiver"/>
</flow>

Now your component is only invoked once for each feed change no matter how many entries were added or updated. The method on your component should expect a org.apache.abdera.model.Feed object.

FeedReceiver.java 
package org.mule.module.atom.example;

import org.apache.abdera.model.Feed;

public void processFeed(Feed feed) throws Exception {
    //do stuff
}

If you want access to the feed object while using the feed splitter, it is available via a header on the current message called 'feed.object'.

Accessing feeds over other Protocols

You can receive feeds and process them using other Mule connectors such as JMS, File or XMPP. To do this, the atom feed needs to be served over the connector. For instance, an atom document is sent over JMS or polled from a file. The atom schema defines a <atom:feed-splitter/> message processor that can split messages received from an endpoint, like so:

Consuming an Atom feed over JMS 
<flow name="feedSplitterConsumer">
    <jms:inbound-endpoint queue="feed.in">
        <atom:feed-splitter/>
    </jms:inbound-endpoint>
    <component class="org.mule.module.atom.event.EntryReceiver"/>
</flow>
Consuming an Atom feed from a file 
<flow name="feedSplitterConsumer">
    <file:inbound-endpoint  path="${mule.working.dir}" pollingFrequency="1000" >
        <file:filename-wildcard-filter pattern="*.atom"/>
        <atom:feed-splitter/>
    </file:inbound-endpoint>
    <component class="org.mule.module.atom.event.EntryReceiver"/>
</flow>

Implementing an AtomPub Server

Abdera’s server side component centers on the notion of a Provider. A Provider manages a service’s Workspaces and Collections.

You can create an AtomPub service in Mule by using the <atom:component/> XML element and reference an Abdera service context.

Creating the Abdera Service Context

The following example shows how to create an Abdera context that builds a JCR repository to store atom entries. These entries can then be served as a feed.

abdera-config.xml 
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:a="http://abdera.apache.org"
       xsi:schemaLocation="
           http://abdera.apache.org http://abdera.apache.org/schemas/abdera-spring.xsd
           http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <a:provider id="provider">
        <a:workspace title="JCR Workspace">
            <ref bean="jcrAdapter"/>
        </a:workspace>
    </a:provider>

    <bean id="jcrRepository" class="org.apache.jackrabbit.core.TransientRepository" destroy-method="shutdown"/>

    <bean id="jcrAdapter"
          class="org.apache.abdera.protocol.server.adapters.jcr.JcrCollectionAdapter" init-method="initialize">
        <property name="author" value="Mule"/>
        <property name="title" value="Event Queue"/>
        <property name="collectionNodePath" value="entries"/>
        <property name="repository" ref="jcrRepository"/>
        <property name="credentials">
            <bean class="javax.jcr.SimpleCredentials">
                <constructor-arg>
                    <value>username</value>
                </constructor-arg>
                <constructor-arg>
                    <value>password</value>
                </constructor-arg>
            </bean>
        </property>
        <property name="href" value="events"/>
    </bean>
</beans>

The <a:provider> creates an Abdera DefaultProvider and allows you to add workspaces and collections to it. This provider reference is used by the the <atom:component/> in Mule to store any events sent to the component.

<flow name="atomPubEventStore">
    <http:inbound-endpoint address="http://localhost:9002"/>
    <atom:component provider-ref="provider"/>
</flow>

Publishing to the Atom Component

You may also want to publish Atom entries or media entries to the <atom:component/> or to an external AtomPub collection. Here is a simple outbound endpoint which creates an Abdera Entry via the entry-builder-transformer and POSTs it to the AtomPub collection:

outbound-endpoint address="http://localhost:9002/events" mimeType="application/atom+xml;type=entry" connector-ref="HttpConnector">
    <atom:entry-builder-transformer>
        <atom:entry-property name="author" evaluator="string" expression="Ross Mason"/>
        <atom:entry-property name="content" evaluator="payload" expression=""/>
        <atom:entry-property name="title" evaluator="header" expression="title"/>
        <atom:entry-property name="updated" evaluator="function" expression="now"/>
        <atom:entry-property name="id" evaluator="function" expression="uuid"/>
    </atom:entry-builder-transformer>
</outbound-endpoint>

You could also create the Entry manually for more flexibility and send it as your Mule message payload. Here’s a simple example of how to create an Abdera Entry:

Create an Abdera Entry 
package org.mule.providers.abdera.example;

import java.util.Date;

import org.apache.abdera.Abdera;
import org.apache.abdera.factory.Factory;
import org.apache.abdera.model.Entry;
import org.mule.transformer.AbstractTransformer;

public class EntryTransformer extend AbstractTransformer {
    public Object doTransform(Object src, String encoding) {
        Factory factory = Abdera.getInstance().getFactory();

        Entry entry = factory.newEntry();
        entry.setTitle("Some Event");
        entry.setContent("Foo bar");
        entry.setUpdated(new Date());
        entry.setId(factory.newUuidUri());
        entry.addAuthor("Dan Diephouse");

        return entry;
    }
}

You can also post Media entries quite simply. In this case it takes whatever your message payload is and post it to the collection as a media entry. You can supply your own Slug via configuration or by setting a property on the mule message.

Post Message Payload as Media Entry 
<flow name="blobEventPublisher">
    <inbound-endpoint ref="quartz.in"/>
    <component class="org.mule.module.atom.event.BlobEventPublisher"/>

    <outbound-endpoint address="http://localhost:9002/events"
          exchange-pattern="request-response" mimeType="text/plain">
       <message-properties-transformer scope="outbound">
           <add-message-property key="Slug" value="Blob Event"/>
       </message-properties-transformer>
   </outbound-endpoint>
</flow>

Route Filtering

The atom module also includes an <atom:route-filter/>. This allows ATOM requests to be filtered by request path and HTTP verb.
The route attribute defines a type of URI Template loosely based on Ruby on Rails style Routes. For example:

"feed" or ":feed/:entry"

For reference, see the Ruby On Rails routing.

For example, this filter can be used for content-based routing in Mule:

Route Filtering 
<flow name="customerService">
        <inbound-endpoint address="http://localhost:9002" exchange-pattern="request-response"/>
        <choice>
            <when>
                <atom:route-filter route="/bar/:foo"/>
                <outbound-endpoint address="vm://queue1" exchange-pattern="request-response"/>
            </when>
            <when>
                <atom:route-filter route="/baz" verbs="GET,POST"/>
                <outbound-endpoint address="vm://queue2" exchange-pattern="request-response"/>
            </when>
        </choice>
    </flow>

Configuration Reference

Component

Represents an Abdera component.

Table 1. Attributes of <component…​>
Name Type Required Default Description

provider-ref

string

no

The id of the Atom provider that is defined as Spring bean.

No Child Elements of <component…​>

Feed splitter

Will split the entries of a feed into single entry objects. Each entry will be a separate message in Mule.

No Child Elements of <feed-splitter…​>

Filters

Entry last updated filter

Will filter ATOM entry objects based on their last update date. This is useful for filtering older entries from the feed. This filter works only on Atom Entry objects not Feed objects.

Table 2. Attributes of <entry-last-updated-filter…​>
Name Type Required Default Description

lastUpdate

string

no

The date from which to filter events from. Any entries that were last updated before this date will not be accepted. The date format is: yyyy-MM-dd hh:mm:ss, for example 2008-12-25 13:00:00. If only the date is important you can omit the time part. You can set the value to 'now' to set the date and time that the server is started. Do not set this attribute if you want to receive all available entries then any new entries going forward. This is the default behavior and suitable for many scenarios.

acceptWithoutUpdateDate

boolean

no

true

Whether an entry should be accepted if it doesn’t have a Last Update date set.
Table 3. Child Elements of <entry-last-updated-filter…​>
Name Cardinality Description

Feed last updated filter

Will filter the whole ATOM Feed based on its last update date. This is useful for processing a feed that has not been updated since a specific date.

This filter works only on Atom Feed objects.

Typically it is better to set the lastUpdated attribute on an inbound ATOM endpoint with splitFeed=false rather than use this filter, however, this filter can be used elsewhere in a flow.

Table 4. Attributes of <feed-last-updated-filter…​>
Name Type Required Default Description

lastUpdate

string

no

The date from which to filter events from. Any entries that were last updated before this date will not be accepted. The date format is The format for the date is is: yyyy-MM-dd hh:mm:ss, for example 2008-12-25 13:00:00. If only the date is important you can omit the time part. You can set the value to 'now' to set the date and time that the server is started. Do not set this attribute if you want to receive all available entries then any new entries going forward. This is the default behavior and suitable for many scenarios.

acceptWithoutUpdateDate

boolean

no

true

Whether a Feed should be accepted if it doesn’t have a Last Update date set.

No Child Elements of <feed-last-updated-filter…​>

Route filter

Allows ATOM requests to be filtered by request path and HTTP verb.

Table 5. Attributes of <route-filter…​>
Name Type Required Default Description

route

string

no

The URI request path made for an ATOM request. This matches against the path of the request URL. The route attribute defines a type of URI Template loosely based on Ruby on Rails style Routes. For example: "feed" or ":feed/:entry". For reference, see the Ruby On Rails routing http://guides.rubyonrails.org/routing.html

verbs

string

no

A comma-separated list of HTTP verbs that will be accepted by this filter. By default all verbs are accepted.
Table 6. Child Elements of <route-filter…​>
Name Cardinality Description

Transformers

Entry builder transformer

A transformer that uses expressions to configure an Atom Entry. The user can specify one or more expressions that are used to configure properties on the bean.

No Attributes of <entry-builder-transformer…​>

Table 7. Child Elements of <entry-builder-transformer…​>
Name Cardinality Description

entry-property

0..1

Object to feed transformer

Transforms the payload of the message to a org.apache.abdera.model.Feed instance.

No Child Elements of <object-to-feed-transformer…​>

Schema

Javadoc API Reference

The Javadoc for this module can be found here: atom

Maven

The ATOM Module can be included with the following dependency:

<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-module-atom</artifactId>
  <version>3.2.0</version>
</dependency>

Points of Etiquette When Polling Atom Feeds

  1. Make use of HTTP cache. Send Etag and LastModified headers. Recognize 304 Not modified response. This way you can save a lot of bandwidth. Additionally some scripts recognize the LastModified header and return only partial contents (ie. only the two or three newest items instead of all 30 or so).

  2. Don’t poll RSS from services that supports RPC Ping (or other PUSH service, such as PubSubHubBub). I.e. if you’re receiving PUSH notifications from a service, you don’t have to poll the data in the standard interval — do it once a day to check if the mechanism still works or not (ping can be disabled, reconfigured, damaged, etc). This way you can fetch RSS only on receiving notification, not every hour or so.

  3. Check the TTL (in RSS) or cache control headers (Expires in ATOM), and don’t fetch until resource expires.

  4. Try to adapt to frequency of new items in each single RSS feed. If in the past week there were only two updates in particular feed, don’t fetch it more than once a day. AFAIR Google Reader does that.

  5. Lower the rate at night hours or other time when the traffic on your site is low.

See Also