Table of Contents

Collection Adapters

Collection Adapters provide the business logic that ties the Abdera server framework to specific backend data storage or application systems. Every Atompub server implementation must use at least one Collection Adapter.

Abdera ships with a number of simple Collection Adapter implementations that can be used out of the box. These include adapters for storing Atom entries in the File system, CouchDB, a JCR-repository or a database using JDBC and Ibatis. A Hibernate adapter is also available but is not built by default. The use of these stock Collection Adapters will be discussed later.

The CollectionAdapter interface

Every method on the CollectionAdapter interface takes a RequestContext as input. This object contains all of the information relevant to the request, including the Target, the request headers, the entity payload, etc. It is equivalent to the HttpServletRequest object but provides methods that are specific to the Abdera APIs.

The return value for each of the CollectionAdapter interface methods is a ResponseContext. This object provides all of the information the AbderaServlet needs to render the response. There are several ResponseContext implementations available within Abdera and your implementation can choose to implement more. The available ResponseContext implementations will be discussed later.

There are nine basic methods on the CollectionAdapter interface, each of which reflect a basic capability of an Atompub Collection.

• getFeed(...) - Returns the Collection's Atom Feed. Called when a GET request is sent to the collection's URI
• postEntry(...) - Adds a new entry to the Collection. Called when a POST request containing an Atom entry document is sent to the collection's URI
• getEntry(...) - Retrieves an entry from the Collection. Called when a GET request is sent to the entries edit URI
• updateEntry(...) - Updates an existing entry. Called when a PUT request containing an Atom entry document is sent to the entries edit URI
• deleteEntry(...) - Deletes an existing entry. Called when a DELETE request is sent to the entries edit URI
• optionsEntry(...) - Retrieves options for a given entry. Called when an OPTIONS request is sent to the entries edit URI
• headEntry(...) - Like getEntry, except the entry is not returned. Called when a HEAD request is sent to the entries edit URI
• getCategories(...) - Returns a Categories document. Called when a GET request is sent to the Category Documents URI as configured by the Provider Target Resolver.
• extensionRequest(...) - Called when a request does not match any of the other methods. This allows a CollectionAdapter to flexibly support extensions

The MediaCollectionAdapter interface

The basic CollectionAdapter interface does not support Media Link Entries and Atompub collections that contain media resources. Collection Adapters can implement the MediaCollectionAdapter interface to add support for media link entries. The Provider will automatically detect when a CollectionAdapter supports the MediaCollectionAdapter interface and will dispatch methods accordingly.

• postMedia(...) - Adds a new entry to the Collection. Called when a POST request containing a media resource is sent to the collection's URI
• getMedia(...) - Retrieves an entry from the Collection. Called when a GET request is sent to the edit-media URI
• updateMedia(...) - Updates an existing entry. Called when a PUT request containing a media resource is sent to the edit-media URI
• deleteMedia(...) - Deletes an existing entry. Called when a DELETE request is sent to the edit-media URI
• optionsMedia(...) - Retrieves options for a given entry. Called when an OPTIONS request is sent to the edit-media URI
• headMedia(...) - Like getEntry, except the entry is not returned. Called when a HEAD request is sent to the edit-media URI

The Transactional interface

Some Adapters are required to operate within a Transactional context. A Collection Adapter can implement the Transactional interface in order to have the Provider automatically manage the lifecycle of the transaction.

• start(...) - Called before invoking the CollectionAdapter or MediaCollectionAdapter methods.
• end(...) - Called after invoking the CollectionAdapter or MediaCollectionAdapter methods.
• compensate(...) - Called when an error occurs during the processing of the CollectionAdapter or MediaCollectionAdapter methods.

The ProviderHelper class

The ProviderHelper class (org.apache.abdera.protocol.server.ProviderHelper) provides a range of helpful utility methods intended to make life easier for Collection Adapter developers. Most of the methods are intended to make it easier to return commonly used response codes.

ResponseContext Options

TODO: Discuss specific ResponseContext options

Collection Adapter Implementations

AbstractCollectionAdapter and AbstractEntityCollectionAdapter

The AbstractCollectionAdapter and AbstractEntityCollectionAdapter base classes provide helpful base implementations of the CollectionAdapter interface designed to make it easier to implement CollectionAdapters. The AbstractEntityCollectionAdapter is specifically designed to make it easier to adapt sets of application specific entities - such as database rows, domain objects or files - to Collection entries.

ManagedCollectionAdapter

The ManagedCollectionAdapter is an extension of AbstractCollectionAdapter that uses *.properties files deployed on the server to configure CollectionAdapter instances.

TODO: Expand this

The Feed Configuration *.properties File

TODO: Discuss the configuration file format

BasicAdapter

The BasicAdapter is a simplified extension of ManagedCollectionAdapter that provides interfaces for producing a minimally functional Atompub collection with a constrained set of features.

TODO: Expand this

CouchDbAdapter

The CouchDbAdapter is an extension of ManagedCollectionAdapter that uses CouchDB databases to store Collection entries.

TODO: Expand this

FilesystemAdapter

The FileSystemAdapter is an extension of ManagedCollectionAdapter that uses the Filesystem to store Collection entries.

TODO: Expand this

JCRAdapter

The JCRAdapter is an extension of AbstractEntityCollectionAdapter that uses a JCR Repository to store Collection entries.

TODO: Expand this

IBatisAdapter

The IBastisAdapter is an extension of BasicAdapter that uses IBatis and JDBC to store Collection entries

TODO: Expand this

HibernateAdapter

The HibernateAdapter is an extension of BasicAdapter that uses Hibernate and JDBC to store Collection entries

TODO: Expand this

Todos

TODO: Expand this discussion

TODO: things to discuss...
Handling custom HTTP Operations
Handling conditional requests
Serving Categories Documents
Serving Collection Feeds
Serving Member Entries
Serving Media Resources
Using the Slug header (slug sanitization)
Properly Handling Cache Control Options
Using the EntityTag class to generate Etags
Generating URLs/IRIs

Extra server stuff:
Returning digitally signed documents
Receiving digitally signed documents
Returning encrypted documents
Receiving encrypted documents