Introduction
Apache Abdera provides an implementation of the IETF Atom Syndication Format and Atom Publishing Protocol standards (RFC's 4287 and 5023).
Abdera is composed of a number of individual modules:
- Core: Provides the core interfaces used throughout Abdera:
- Feed Object Model - A set of Java interfaces and abstract classes modeled after the various document and element types defined by the Atom specifications.
- Parser and Factory interfaces - Interfaces that provide the mechanisms for creating and consuming Atom documents.
- ExtensionFactory - The primary means by which extensions to the Atom format are integrated into Abdera. Extension Factories are used by both the Parser and Factory.
- Writer - The means by which Feed Object Model objects are serialized into XML or other formats
- ParseFilter - Provides a means of filtering the stream of parse events
- Converter - Base interfaces and utilities for converting objects into Feed Object Model objects
- XPath - Base interface for navigating the Feed Object Model using XPath
- Dependencies: Contains all of the other jars and code Abdera depends on
- Parser: Provide an implementation of the Feed Object Model based on the Apache Axiom project
- Protocol: Provides the base interfaces and utility classes used for the RFC 5023 (Atompub) implementation
- Server: Provides framework code used to build Atompub servers
- Client: Provides an Atompub client implementation that is based on the Apache Commons HTTP Client.
- Spring: Extends the Server module by adding support for the Spring framework
- Security: Provides support for XML Digital Signatures and XML Encryption
- Extensions: Provides support for a number of standard and non-standard extensions to the Atom format
- Atom Threading Extensions
- Atom License Extension
- Atompub Feature Discovery
- Atom Bidi Attribute
- Feed Paging and Archiving
- GeoRSS
- Simple Sharing Extensions
- MediaRSS
- OpenSearch
- GData and WSSE Autbentication
- Examples: Provides a number of examples
Downloading Abdera
- Binary
- Source
Building with Ant
export ABDERA_XMLSECURITY=true export ABDERA_SPRING=true ant -f build/build.xml zips
Set ABDERA_XMLSECURITY to true to build the security module.
Set ABDERA_SPRING to true to build the spring module.
Building with Maven
Getting Started
The two most common uses for Abdera are creating and parsing Atom documents.
Abdera abdera = new Abdera();
Parser parser = abdera.getParser();
URL url = new URL("http://www.snellspace.com/wp/wp-atom1.php");
Document<Feed> doc = parser.parse(url.openStream(),url);
Feed feed = doc.getRoot();
System.out.println(feed.getTitle());
for (Entry entry : feed.getEntries()) {
System.out.println("\t" + entry.getTitle());
)
Abdera abdera = new Abdera();
Feed feed = abdera.newFeed();
feed.setId("tag:example.org,2007:/foo");
feed.setTitle("Test Feed");
feed.setSubtitle("Feed subtitle");
feed.setUpdated(new Date());
feed.addAuthor("James Snell");
feed.addLink("http://example.com");
feed.addLink("http://example.com/foo","self");
Entry entry = feed.addEntry();
entry.setId("tag:example.org,2007:/foo/entries/1");
entry.setTitle("Entry title");
entry.setSummaryAsHtml("<p>This is the entry title</p>");
entry.setUpdated(new Date());
entry.setPublished(new Date());
entry.addLink("http://example.com/foo/entries/1");
As you can see in both of these examples, the first step to using Abdera is to create an instance of the Abdera object. This special thread-safe class bootstraps the Abdera configuration and provides access to all of the other components. One of the most important tasks that the Abdera object performs is the automatic discovery of extensions.
Creating a new instance of the Abdera object can be time consuming so it is recommended that only a single instance be creating per application. The Abdera object and it's direct children (Parser, Factory, XPath, etc) are threadsafe and can be stored statically.
public class MyApplication {
private static Abdera abdera = null;
public static synchronized Abdera getInstance() {
if (abdera == null) abdera = new Abdera();
return abdera;
}
}
Once an Abdera instance is created, you can begin parsing and creating Atom documents.
Configuring Abdera
Abdera uses a powerful and flexible configuration mechanism that, fortunately, most developers will never actually have to even think much about. Abdera uses it's configuration model to automatically discover the various implementation classes for it's Parser, Factory, Feed Object Model, ExtensionFactories, etc. The closest most developers will ever need to get to the configuration system is when implementing a new ExtensionFactory for a new Atom format extension. Implementation of Extension Factories will be covered later. For now, we can skip the details about the Abdera configuration system.
The Feed Object Model
The Feed Object Model is the set of objects you will use to interact with Atom documents. It contains classes such as "Feed", "Entry", "Person" etc, all of which are modeled closely after the various elements and documents defined by the two Atom specifications. The Javadocs for the Feed Object Model can be found here.
TODO Complete this
Getting Started
Downloading Abdera
Building from source using Ant
Building from source using Maven
Setting up the classpath
Creating an Abdera instance
The Abdera Factory
Creating an Atom Document
Creating an Atom Feed
Creating an Atom Entry
Creating other Atom objects
Creating an atom:id value
Understanding IRIs
Working with links
Working with person constructs
Working with date constructs
Working with text options
Working with content options
Text and HTML Content
XHTML Content
XML Content
Binary Content
Linked Content
Working with Documents
The Abdera Parser
Parsing a Atom Document
Customizing the Parse Options
Using a Parse Filter
Using a Whitelist ParseFilter
Using a Blacklist ParseFilter
Using a Compound ParseFilter
Using Named Parsers
Implementing a Named Parser
Registering a Named Parser
The Abdera Writer
Writing an Atom Document
Customizing the Write Options
Using Named Writers
Using the Pretty XML Writer
Implementing a Named Writer
Registering a Named Parser
Abdera and XPath
Navigating Atom Documents with XPath
Using XPath functions
Using XPath variables
Using XSLT to transform Abdera objects
Abdera Security
Creating the AbderaSecurity object
Signing an Atom Document
Initializing signing keys
Customizing Signature options
Signing linked resources
Verifying a signed Atom Document
Encrypting an Atom Document
Customizing Encryption options
Using Diffie-Hellman Key Exchange
Decrypting an Atom Document
Abdera Client
Creating the AbderaClient object
Retrieving an Atom document
Posting an Atom document
Posting media resources
Updating an Atom document
Updating media resources
Deleting Atom documents and media resources
Using Custom HTTP Operations
Using SSL
Customizing the request options
Detecting lost updates
Use Basic Authentication
Use WSSE Authentication
Use GoogleLogin Authentication
Use Client Cert Authentication
Use Custom Authentication
Using the client cache
Handling Error conditions
Abdera Server
Implementing a Provider
Implementing a Target Resolver
Using the Regex Target Resolver
Implementing a Subject Resolver
Configuring the Abdera servlet
Integrating with Spring
ItemManagers and Object Pooling
Handling custom HTTP Operations
Handling conditional requests
Serving Service Documents
Serving Categories Documents
Serving Collection Feeds
Serving Member Entries
Serving Media Resources
Using the Slug header
Reporting Errors
Properly Handling Cache Control Options
Abdera Extensions
Using the Dynamic Extension API
Using Simple Extensions
Using Complex Extensions
Navigating Extensions
Using static extensions
Implementing an ExtensionFactory
Registering an ExtensionFactory
Implementing a static extension
Listing registered ExtensionFactory instances
GeoRSS Extensions
Adding coordinates to an Atom document
Getting coordinates from an Atom document
JSON Extension
Serializing an Atom document as JSON
Bidi Extension
Adding the bidirectional attribute to Atom
Using the Unicode bidi characters
Determining the text direction using the bidi attribute
Guessing the text direction using xml:lang
Guessing the text direction using text properties
Guessing the text direction using Java's bidi support
Guessing the text direction using the character set encoding
Rendering bidi text
Features Extension
Adding features to a service document
Reading features from a service document
Paging and Archiving Extension
Adding paging links to an Atom feed
Making a complete Atom feed
Making an archive Atom feed
Detecting a complete Atom feed
Detecting an archive Atom feed
License Extension
Adding license links to an Atom element
Reading license links from an Atom element
Threading Extensions
Adding replies links to an Atom element
Adding in-reply-to elements
Reading replies links from an Atom element
Reading in-reply-to elements
Replying to Atom resources
Replying to non-Atom resources
Media Extensions
Adding media extensions to an Atom entry
Reading media extensions from an Atom entry
OpenSearch Extensions
Adding OpenSearch extensions to an Atom document
Reading OpenSearch extensions from an Atom document
Simple Sharing Extensions
Adding SSE extensions to an Atom document
Reading SSE extensions from an Atom document
Merging SSE documents
Detecting and Resolving SSE conflicts
Other
MIME Types
Entity Tags
Atom Dates
Language Tags
Filtering restricted XML characters
Unicode normalization