Use Atom bindings in SCA applications

Use an Atom binding in a Service Component Architecture (SCA) application to expose collections of data as an Atom feed or to reference existing external Atom feeds.

If we are unfamiliar with the Atom protocol, refer to documentation on the Atom Syndication Format, an XML-based document format that describes web feeds, and the Atom Publishing Protocol, a protocol for publishing and updating web resources.

Use the Atom binding to work with services that provide or consume entries described in the Atom Syndication Format and Atom Publishing Protocol. An SCA component can reference existing external web feeds defined using the Atom protocol and work with them inside a Java implementation. Also, we can use the Atom binding to compose new services and expose them as an Atom feed.

This topic describes the following procedures:

• Expose an Atom feed service using an Atom binding.

• Use an Atom binding reference to access services exposed by SCA applications using the Atom binding or to access external Atom feeds.

• Expose an Atom feed service using an Atom binding.

  1. Configure the Atom feed service in an SCA composite definition.

     Specify the uniform resource identifier (URI) of the Atom feed in a service in the composite definition of an SCA composite. The following example of a composite definition has a service exposed over the Atom binding:

     <component name="NewsServiceComponent">
       <implementation.java class="com.ibm.test.atom.NewsServiceImpl"/>
       <service name="NewsService">
         <t:binding.atom uri="http://localhost:9080/newsService"/>
       </service>
     </component>

     The example Atom binding URI, http://localhost:9080/newsService, is an absolute URI. To run applications that use an Atom binding in product clusters, specify a relative URI; for example:

     <t:binding.atom uri="/newsService"/>

  2. Access the service.

     For example, to access the NewsService service, either use an SCA reference in another component or directly access the URI http://localhost:9080/newsService from a web browser. If accessed from a web browser, the browser handles the output as an Atom feed.

     The following example shows XML tagging for an Atom feed returned from the NewsService service:

     <?xml version="1.0" encoding="UTF-8"?>
     <feed xmlns="http://www.w3.org/2005/Atom">
       <title type="text">Feed</title>
       <id>Feed1329090360</id>
       <entry>
         <id>Item1</id>
         <title type="text">item</title>
         <content type="application/xml">
           <ns2:root xmlns:ns2="http://tuscany.apache.org/xmlns/sca/databinding/jaxb/1.0"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="item">
           <name xmlns="">First Item Name</name>
           <title xmlns="">First Item Title</title>
         </ns2:root>
       </content>
       <link href="Item1"></link>
      </entry>
     </feed>

  3. Manipulate the Atom feed using HTTP actions.

     We can manipulate the collections of items exposed by an Atom service using the four basic actions of the HTTP protocol:

     • POST (create or add)

     • GET (retrieve or query)

     • PUT (update)

     • DELETE (remove)

     The Java implementation class for the component should implement the org.apache.tuscany.sca.data.collection.Collection interface or an interface that extends the Collection interface. The following methods are defined in the org.apache.tuscany.sca.data.collection.Collection interface:

     public abstract Entry[] getAll()

     Returns every entry in the feed

     public abstract Entry[] query(String s)

     Queries the feed for entries based on some matching criteria

     public abstract Object post(Object obj, Object obj1)

     Add a new entry to the feed

     public abstract Object get(Object obj) throws NotFoundException

     Returns a single entry identified by the provided key value.

     public abstract void put(Object obj, Object obj1) throws NotFoundException

     Updates an existing entry identified by the provided key value

     public abstract void delete(Object obj) throws NotFoundException

     Delete an existing entry identified by the provided key value

• Use an Atom binding reference to access services exposed by SCA applications using the Atom binding or to access external Atom feeds.

  1. Configure an Atom binding reference to access an exposed service.

     Specify a reference in the composite definition of an SCA composite that accesses an exposed service. The following example is a reference definition that accesses the NewsService service:

     <reference name="newsServiceRef" target="NewsServiceComponent/NewsService">
         <t:binding.atom/>
     </reference>

  2. Configure an Atom binding reference to access an external Atom feed.

     Specify a reference in the composite definition of an SCA composite that accesses an external Atom feed, for example:

     <reference name="atomFeed">
         <tuscany:binding.atom uri="http://feeds.feedburner.com/blogspot/Dcni?format=xml"/>
     </reference>

  3. Work with the Atom binding reference inside a Java implementation.

     A Java implementation class for an SCA component containing the two example references might define them as follows:

     @Reference( required = false)
     public Collection newsServiceRef;
      @Reference( required = false)
     public Collection atomFeed;

  4. Use the Collection API in the implementation to manipulate the feed.

     For example, to add a new entry to the NewsService feed, the implementation might call:

     MyEntry entry = new MyEntry("Title", "Content");
     newsServiceRef.post("mykey-10-15", entry);

     To retrieve an entry from the external feed, the implementation code might use the following example code:

     atomFeed.get("idtag-20090321");

What to do next

Deploy the SCA component in an application.

If the Atom feed service is deployed to a cluster and the target attribute, @target, is used to point to the service, the target URI resolves to an HTTP port for an individual cluster member. To maintain failover and load balancing in this situation, we can use an absolute URI on the binding.atom element that points to a proxy server endpoint rather than the target attribute on the reference element. For more information, see the topics on resolving SCA references and on routing HTTP requests to an SCA service when using an external web server.

Subtopics

• (dist)(zos) Secure data exposed by Atom bindings
  We can secure collections of data that are exposed by an Atom binding in a Service Component Architecture (SCA) application. An Atom binding can expose data as an Atom feed or reference existing external Atom feeds.

• (dist)(zos) Use Widget implementation in JavaScript with Atom bindings
  The JavaScript code in an HTML file can use Service Component Architecture (SCA) references defined in a Tuscany Widget implementation. Use Widget implementation to work with data in Atom collections that an SCA service returns in JavaScript.

Related tasks

Resolve SCA references

Route HTTP requests to an SCA service when using an external web server

Specify bindings in an SCA environment

Related information:

Atom Syndication Format
Atom Publishing Protocol