Atom Format Enhancements

This is the proposed functionality for providing additional Atom Formatting (ASF) support. It includes tools which support the serialization and deserialization of data in the Atom Syndication Format. This page DOES NOT address support for the Atom Publication Protocol.

Atom Format

Atom Data Structure

Data to be encoded and serialized in Atom Format is contained in a data structure using simple java.util.* data structures Map and List along with java.util.* data types such as String and Date. Three such data structures are supported, one for each of the three Atom document types: Feed, Entry and Service. The keys used in these Maps correspond to the names of the atom elements specified by ASF. The Groovy code below demonstrates the data structure.

feedMap = [
                 authors : [personMap1, personMap2],
           categories : [categoryMap1],
           contributors : [personMap1],
           generator : generatorMap1,
            id : string | number,
           links : [[href: String, rel: 'self' ]],  
           rights : string
           subtitle : textMap1,
             title : textMap2,
           updated : date,
           entries : [
                         entryMap1,
                         entryMap2,
                         entryMap3
                         ]
   ]

entryMap = [
           authors : [personMap1, personMap2],
      categories : [categoryMap1, categoryMap2],
      content : textMap | (media types?),
      contributors : [personMap1, personMap2],
      id : string | number,
          links : [[href: String, rel: 'self' ]],  
      published : date,
      rights : string,
      summary : textMap,
      title : textMap,
      updated : date,
   ]

personMap = [
                name: string...
                
 

The above is not a complete specification of data types and structures. Some of this is to be determined.

Atom APIs

The APIs which interprets and creates the above data structure are similar to the JSON APIs. The should be accessible to Java, Groovy and PHP development. The will also be used by the Atom Renderer. Not that the encode API supports the streaming of Atom documents.

public class Atom {
        
        public static Object decode(String str) throws IOException, XMLStreamException { ... }
        public static Object decode(InputStream is) throws IOException, XMLStreamException { ... }
        public static Object decode(Reader reader) throws IOException, XMLStreamException { ... }
        public static Object decode(URL url) throws IOException, XMLStreamException  { ... }

        public static String encode(Object obj, String atomElement) throws IOException, XMLStreamException { ... } 
        public static void encode(Object obj, String atomElement, OutputStream os) throws IOException, ...{ ... }
        public static void encode(Object obj, String atomElement, Writer writer) throwsIOException, XMLStreamException  { ... }
}

Note that, unlike JSON, the encode() method specifies the type of the data being encoded. The Atom document structures "feed", "entry" or "service", will be supported, as well as the atom element "context". It is possible to extend this support to any (or all) atom elements "author", "title", etc... It has yet to be determined whether "exposing" other elements is useful.

The APIs above are not exhaustive, but summarize the functionality. There will be additional APIs which default the AtomElement type if not specified and possibly those that support pretty print formatting.

Also, there will be some smart encoding functionality which allows the user some flexibility with data structures. For example, allow a Feed to be represented by a List of Entries, and provide a default mechanism to capture the required Feed data.

Finally, we must provide a migration path. There must be an easily specified config that defaults to the current zero.atom behavior.

Design Question: This proposal assumes that the zero.atom component will continue to leverage the Abdera libraries. However, it provides a parsing solution for the developer which uses common data structures, so Abdera knowledge is not required of the user of this function. Is this reasonable?

Atom Renderer

The function of the Atom Renderer will be extended to support the data structures specified above. The following Groovy code segment demonstrates the use of the Atom Renderer. There will be an additional field "request.atom.document" in which the document type can be specified. This will only be required if it cannot be determined by the data structure in "request.atom.output".

request.view=atom'
request.atom.output=obj
request.atom.document='feed'|'entry'|'service'
render()

Note: This new functionality extends the current rendering functionality which means that the Abdera Document Types are still valid data structures for "request.atom.output".

Atom Template

A set of groovy templates will be provided (feed.gt, entry.gt and service.gt) to allow the developer to render Atom documents using the View Renderer. These will only support the strict data structures described above, (ie, no "smart encoding"). This limits the logic in the template files to loops, optional elements checking, and simple error checking. The Groovy code below shows how it how be invoked to achieve the same results as the Atom Renderer.

zput("/request/headers/out/Content-Type", "application/atom+xml")
request.view="atom/feed.gt"
 

Design Question: Since this provides the same functionality as the Atom Renderer above, should we even provide this functionality? Pro: Users seem to like the idea of templates they can "tweak". Con: Additional work required to support this.

XOXO Format

The XOXO Format is a microformat (ref) used to encode structured data in XHTML. This mechanism for sharing structured data is common for the Atom format because a Feed reader will render the data in a human readable, structured format.

Each list is encoded within a "ul" element. Each map is encoded within a "dl" element. The list of supported data types have not been determined, but will include String, Date, Number.

XOXO APIs

The Xoxo APIs are similar to both the Json and Atom APIs.

public class Xoxo {
        
        public static Object decode(String str) throws IOException, XMLStreamException { ... }
        public static Object decode(InputStream is) throws IOException, XMLStreamException { ... }
        public static Object decode(Reader reader) throws IOException, XMLStreamException { ... }
        public static Object decode(URL url) throws IOException, XMLStreamException  { ... }

        public static String encode(Object obj) throws IOException, XMLStreamException { ... } 
        public static void encode(Object obj, OutputStream os) throws IOException, ...{ ... }
        public static void encode(Object obj, Writer writer) throwsIOException, XMLStreamException  { ... }
}

The Groovy code below shows a usage example:

contentObject = [
      number : 1,
      text : 'testText',
      date : new Date(0),
                list : ['a', 'b', 'c'],
                map : [A:'a', B:'b', C:'c']

entry.content.value = Xoxo.encode(contentObject)
entry.content.type = 'XMTML'

Note that the same information can be transferred in the atom:content using JSON encoding, by invoking Json.encode(contentObject) instead of Xoxo.encode(contentObject). However the data in Xoxo format is nicely displayed by a Feed Reader.

Custom Converters

The design pattern for this Atom solution follows that of the Json design pattern. This will enable us to provide a custom converter mechanism for Atom in the same way as we do for Json. We will provide a custom converter for the data types in the zero.resource component. Additional custom converters to be provided are yet to be determined.