Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.7)
  3. Reference
  4. Modules Reference

  5. Atom Module Reference

Atom Module Reference

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

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/current/mule-atom.xsd

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 application

ETags

The Atom HTTP connector 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. Write your class to receive 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 and invoke the component method for each entry in the feed:

<http:request-config name="HTTP_request_Configuration" host="localhost"
port="9002"/>
<flow name="eventConsumer">
    <poll frequency="10000">
        <http:request config-ref="HTTP_request_Configuration" path="events" method="GET" doc:name="HTTP Connector"/>
    </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 are 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:

<http:request-config name="HTTP_request_Configuration" host="localhost"
port="9002"/>
<flow name="eventConsumer">
    <poll frequency="10000">
        <http:request config-ref="HTTP_request_Configuration" path="events" method="GET" doc:name="HTTP Connector"/>
    </poll>
    <atom:object-to-feed-transformer/>
    <component class="org.mule.module.atom.event.FeedReceiver"/>
</flow>

Now your component only invokes once for each feed change no matter how many entries you add or update. 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-current.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>

Note: In the code example, spring-beans-current.xsd is a placeholder. To locate the correct version, see http://www.springframework.org/schema/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.

<http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="9002"/>
<flow name="atomPubEventStore">
    <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP Connector"/>
    <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 posts 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 Description

provider-ref

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

Type: string
Required: no
Default: none

No Child Elements of <component…​>

Feed Splitter

Splits the entries of a feed into single entry objects. Each entry is a separate message in Mule.

No Child Elements of <feed-splitter…​>

Filters

Entry last updated filter

Filters 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 Description

lastUpdate

The date from which to filter events from. Any entries that were last updated before this date are not 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.

Type: string
Required: no
Default: none

acceptWithoutUpdateDate

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

Type: boolean
Required: no
Default: true

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

Feed Last Updated Filter

Filters 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 3. Attributes of <feed-last-updated-filter…​>
Name Description

lastUpdate

The date from which to filter events from. Any entries that were last updated before this date are not accepted. The date format is The format for the date is is: yyyy-MM-dd hh:mm:ss, for example 2016-04-13 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.

Type: string
Required: no
Default: none

acceptWithoutUpdateDate

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

Type: boolean
Required: no
Default: true

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

Route Filter

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

Table 4. Attributes of <route-filter…​>
Name Description

route

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

Type: string
Required: no
Default: none

verbs

A comma-separated list of HTTP verbs that are accepted by this filter. By default all verbs are accepted.

Type: string
Required: no
Default: none

No Child Elements of <route-filter…​>

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 5. 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

Atom namespace overview

Javadoc API Reference

The Javadoc for this module can be found here:

Atom Javadoc

Maven

The Atom Module can be included with the following dependency:

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

Points of Etiquette When Polling Atom Feeds

  • 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, such as only the two or three newest items instead of all 30 or so.

  • Don’t poll RSS from services that supports RPC Ping (or other PUSH service, such as PubSubHubBub). 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.

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

  • 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.

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

See Also