You can 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.
Before you begin
If you 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.
About this task
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, you can use the Atom binding to compose
new services and expose them as an Atom feed.
This topic describes
the following procedures:
Procedure
- Expose an Atom feed service using an Atom
binding.
- 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"/>
- 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>
- Manipulate the Atom feed using HTTP actions.
You
can manipulate the collections of items exposed by an Atom service
by 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)
- Adds 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
- Deletes 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.
- 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>
- 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>
- Work with the Atom binding reference inside a Java implementation.
A Java implementation class for an SCA component that contains
the two example references might define them as follows:
@Reference(required = false)
public Collection newsServiceRef;
@Reference(required = false)
public Collection atomFeed;
- 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 your 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, you 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.