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 {@link com.sun.syndication.propono.atom.client.AtomClientFactory} class (not shown below) you can get a {@link com.sun.syndication.propono.atom.client.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 {@link com.sun.syndication.propono.atom.client.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 {@link com.sun.syndication.propono.atom.client.ClientEntry} and {@link com.sun.syndication.propono.atom.client.ClientMediaEntry} objects are both sub-classes of the ROME Atom {@link com.sun.syndication.feed.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 {@link com.sun.syndication.propono.atom.client.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.