Package com.sun.syndication.propono.atom.client

Client library for interacting with APP web services.

See:
          Description

Class Summary
AtomClientFactory Creates AtomService or ClientCollection based on username, password and end-point URI of Atom protocol service.
ClientAtomService This class models an Atom Publising Protocol Service Document.
ClientCategories Models an Atom protocol Categories element, which may contain ROME Atom Category elements.
ClientCollection Models an Atom collection, extends Collection and adds methods for adding, retrieving, updateing and deleting entries.
ClientEntry Client implementation of Atom entry, extends ROME Entry to add methods for easily getting/setting content, updating and removing the entry from the server.
ClientMediaEntry Client implementation of Atom media-link entry, an Atom entry that provides meta-data for a media file (e.g.
ClientWorkspace Represents Atom protocol workspace on client-side.
EntryIterator Enables iteration over entries in Atom protocol collection.
 

Package com.sun.syndication.propono.atom.client Description

Client library for interacting with APP web services.

Using this client library you can interact with Atom protocol services that provide a Service Document URI and navigate the object model (see below) to find a the colletions you wish to work with. You can also interact with services that provide you with only Collection URIs (e.g. Google Data).

The diagram below shows the classes that make up the Propono Atom Client. Using the AtomClientFactory class (not shown below) you can get a ClientAtomService object and from there you can find the Workspaces and the Collections within them.

Diagram of Atom Client classes

Methods are provided to help you find Workspaces by title and Collections by title and by what content-types they accept. Once you have a ClientCollection you can iterate over the entries in it, get individual entries and add new entries. To create a normal entry you can call createEntry() and to create a media-link entry you call createMediaEntry() -- more about that later.

The code below is a simple example of Atom Client usage. It shows how to connect to an Atom service, find a Workspace by name, find a Collection that accepts entries and post a new Atom entry.

Posting an entry

        
        String username = args[0];
        String password = args[1];
        String title    = args[2];
        String htmltext = args[3];
        String uri      = args[4];
        
        // Connect to service, GET Service Doc.
        ClientAtomService service = 
        AtomClientFactory.getAtomService(uri, username, password);
        
        // Find workspace by name
        ClientWorkspace workspace = (ClientWorkspace)
        service.findWorkspace("My Workspace");
        
        // Find first collection in workspace that will accept entries
        ClientCollection collection = (ClientCollection)
            workspace.findCollection(null, "entry");    
        
        // Create entry, set title and content but don't POST it yet
        ClientEntry entry = collection.createEntry();
        entry.setTitle(title);
        entry.setContent(Content.HTML, htmltext);
        
        // POST entry to collection on server
        collection.addEntry(entry);
        

The ClientEntry and ClientMediaEntry objects are both sub-classes of the ROME Atom Entry class, so you can construct Atom protocol entries just as you would construct ROME entries. You can add in your own extensions via ROME's Extension Module mechanism, but it's not guaranteed that all Atom compliant servers will preserve the extensions you add.

Each Collection provides a boolean accepts(contentType) method so you can test to see if a specific content type is accepted by the collection as well as a getAccepts() so you can get actual content-type range.

If you are posting something other than an Atom Entry, an image or other binary file for example, you simply post it to a collection that accepts the content-type of your file. The Atom service will respond by storing your file and returning an Atom entry that represents the meta-data associated with your file -- that entry is known as a media-link entry and is represented in Propono by the ClientMediaEntry class.

The example below shows how to post a GIF image to the first collection found that accepts GIFs.

Posting an media-link entry

        String username = args[0];
        String password = args[1];
        String slug     = args[2];
        String filepath = args[3];
        String uri      = args[4];
        
        // Connect to service, GET Service Doc.
        ClientAtomService service = 
        AtomClientFactory.getAtomService(uri, username, password);
        
        // Find workspace by name
        ClientWorkspace workspace = (ClientWorkspace)
        service.findWorkspace("My Workspace");
        
        // Find first collection in workspace that will accept a GIF
        ClientCollection collection = (ClientCollection)
        workspace.findCollection(null, "image/gif");    
        
        // Create entry, set title and content but don't POST it yet
        ClientMediaEntry entry = collection.createMediaEntry(
            slug, slug, "image/gif", new FileInputStream(filepath)); 
        
        // POST entry to collection on server
        collection.addEntry(entry);
        

The server gets to decide the file-name that is used to represent your file, but you can pass a 'slug' value to give the server some guidance in creating the name.