diff options
Diffstat (limited to 'site/trunk/site-publish/sca-java-bindingatom.html')
| -rw-r--r-- | site/trunk/site-publish/sca-java-bindingatom.html | 589 |
1 files changed, 589 insertions, 0 deletions
diff --git a/site/trunk/site-publish/sca-java-bindingatom.html b/site/trunk/site-publish/sca-java-bindingatom.html new file mode 100644 index 0000000000..1a2596918d --- /dev/null +++ b/site/trunk/site-publish/sca-java-bindingatom.html @@ -0,0 +1,589 @@ + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE- 2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<HTML> + <HEAD> + <!-- generateKeywords macro --> + <META name="description" content="Apache Tuscany"> + <META name="keywords" content="apache, apache tuscany, tuscany, service, services, fabric, soa, service oriented architecture, sca, service component architecture, das, sdo, csa, ruby, opensource"> + <!-- generateKeywords macro end --> + + <LINK type="text/css" rel="stylesheet" href="http://tuscany.apache.org/stylesheets/default.css"> + <LINK rel="SHORTCUT ICON" href="https://cwiki.apache.org/confluence/display/TUSCANY/$images/favicon.ico"> + <TITLE>Apache Tuscany : SCA Java binding.atom</TITLE> + <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD> + + <BODY onload="init()"> + <!-- topNav macro --> + <TABLE valign="top" border="0" cellspacing="0" cellpadding="0" width="100%" background="http://tuscany.apache.org/images/TuscanyLogoNEW_Text_120px_bg.jpg"> + <TR> + <TD valing="top" align="left"> + <A href="https://cwiki.apache.org/confluence/pages/viewpage.action?spaceKey=TUSCANY&title=$siteroot"><IMG src="http://tuscany.apache.org/images/TuscanyLogoNEW_Text_120px_bg.jpg" height="91" width="25" border="0"></A> + </TD> + <TD> + <A href="http://tuscany.apache.org/"><IMG src="http://tuscany.apache.org/images/TuscanyLogo.jpg" border="0"></A> + </TD> + + <TD width="100%"> + + </TD> + + <!-- Adds the edit page link to the top banner--> + <TD valign="bottom"> + <DIV style="padding: 2px 10px; margin: 0px;"> + <A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=98605"> + <IMG src="http://tuscany.apache.org/images/notep_16.gif" height="16" width="16" border="0" align="absmiddle" title="Edit Page"></A> + </DIV> + </TD> + + </TR> + </TABLE> + <!-- topNav macro end --> + + <!-- breadCrumbs macro --> + <TABLE border="0" cellpadding="2" cellspacing="0" width="100%"> + <TR class="topBar"> + <TD align="left" valign="middle" class="topBarDiv" nowrap="true" width="100%"> + <A href="home.html" title="Apache Tuscany">Apache Tuscany</A> > <A href="home.html" title="Home">Home</A> > <A href="sca-overview.html" title="SCA Overview">SCA Overview</A> > <A href="sca-java.html" title="SCA Java">SCA Java</A> > <A href="java-sca-documentation-menu.html" title="Java SCA Documentation Menu">Java SCA Documentation Menu</A> > <A href="" title="SCA Java binding.atom">SCA Java binding.atom</A> + </TD> + + <TD align="right" valign="middle" class="topBarDiv" align="left" nowrap="true"> + <A href="http://mail-archives.apache.org/mod_mbox/tuscany-user">User List</A> | <A href="http://mail-archives.apache.org/mod_mbox/tuscany-dev">Dev List</A> | <A href="http://issues.apache.org/jira/browse/Tuscany">Issue Tracker</A> + </TD> + </TR> + </TABLE> + <!-- breadCrumbs macro end --> + + + <TABLE border="0" cellpadding="0" width="100%" bgcolor="#FFFFFF"> + <TR> + <TD align="left" valign="top"> + + <!-- pageContent macro --> + <DIV id="PageContent"> + + <DIV class="pagecontent"> + <DIV class="wiki-content"> + <TABLE class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><TBODY><TR> +<TD class="confluenceTd" valign="top" width="15%"> +<DIV class="panel" style="background-color: #ECF4D1;border-color: #C3CDA1;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #C3CDA1;background-color: #C3CDA1;"><B>General</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;"> +<P><A href="home.html" title="Home">Home</A><BR> +<A href="http://www.apache.org/licenses/LICENSE-2.0.html" class="external-link" rel="nofollow">License </A><BR> +<A href="sca-java-get-involved.html" title="SCA Java Get Involved">Get Involved</A><BR> +<A href="sca-java-found-a-bug.html" title="SCA Java Found A Bug">Found a Bug?</A></P> +</DIV></DIV> + +<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>SCA Java</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;"> +<P><A href="sca-java.html" title="SCA Java">SCA Java Home</A><BR> +<A href="tuscany-dashboard.html" title="Tuscany Dashboard">SCA Dashboard</A><BR> +<A href="java-sca-tools.html" title="Java SCA Tools">Tools </A><BR> +<A href="tuscany-sca-java-faq.html" title="Tuscany SCA Java - FAQ">FAQ</A></P> +</DIV></DIV> + +<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>SCA Java 1.x</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;"> +<P><A href="sca-java-releases.html" title="SCA Java Releases">Downloads</A><BR> +<A href="java-sca-documentation-menu.html" title="Java SCA Documentation Menu">Documentation</A><BR> +<A href="https://svn.apache.org/repos/asf/tuscany/sca-java-1.x/trunk/" class="external-link" rel="nofollow">1.x Source Code</A><BR> +<A href="http://tinyurl.com/8rlxd3" class="external-link" rel="nofollow">Roadmap</A></P> +</DIV></DIV> + +<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>SCA Java 2.x</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;"> +<P><A href="sca-java-2x-releases.html" title="SCA Java 2.x Releases">Downloads</A><BR> +<A href="http://tuscany.apache.org/documentation-2x/" class="external-link" rel="nofollow">Documentation</A><BR> +<A href="https://svn.apache.org/repos/asf/tuscany/sca-java-2.x/trunk/" class="external-link" rel="nofollow">2.x Source Code</A><BR> +<A href="http://tinyurl.com/8rlxd3" class="external-link" rel="nofollow">Roadmap</A></P> +</DIV></DIV> + + +<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>Documentation</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;"> +<P><A href="sca-java-user-guide.html" title="SCA Java User Guide">User Guide</A><BR> +<A href="sca-java-architecture-guide.html" title="SCA Java Architecture Guide">Architecture Guide</A><BR> +<A href="sca-java-development-guide.html" title="SCA Java Development Guide">Developer Guide</A><BR> +<A href="sca-java-extension-development-guide.html" title="SCA Java Extension Development Guide">Extension Developer Guide</A></P> +</DIV></DIV> + +<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>Resources</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;"> +<P><A href="tuscany-sca-java-faq.html" title="Tuscany SCA Java - FAQ">FAQ</A><BR> +<A href="https://svn.apache.org/repos/asf/incubator/tuscany/java/sca" class="external-link" rel="nofollow">Source Code</A></P> +</DIV></DIV> +</TD> +<TD class="confluenceTd" valign="top" width="85%"> + +<H3><A name="SCAJavabinding.atom-%3Cbinding.atom%3EIntroduction"></A><binding.atom> Introduction</H3> + +<P>The Tuscany Java SCA runtime supports Atom using the <binding.atom> extension. Tuscany can communicate with services that provide or consume items described in the Atom Syndication Format and Atom Publishing Protocol. The Atom protcol is an additional conceptual layer that operates on top of the Hyper Text Transfer Protocol, so it is useful to understand that underlying protocol as well. Reference materials on these specifications is available here.</P> + +<UL> + <LI><A href="http://tools.ietf.org/html/rfc2616" class="external-link" rel="nofollow">Hyper Text Transfer Protocol</A>.</LI> + <LI><A href="http://tools.ietf.org/html/rfc4287" class="external-link" rel="nofollow">Atom Syndication Format</A>.</LI> + <LI><A href="http://tools.ietf.org/html/rfc5023" class="external-link" rel="nofollow">Atom Publishing Protocol</A>.</LI> +</UL> + + +<P><IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/lightbulb_on.gif" height="16" width="16" align="absmiddle" alt="" border="0"> Some of the function described here is included in the Tuscany 1.3.2 and 1.4 releases. The complete timeline of available and future plans is given in the <A href="http://tuscany.apache.org/sca-java-roadmap.html" class="external-link" rel="nofollow">Tuscany Web 2.0 Roadmap</A>.</P> + + +<H3><A name="SCAJavabinding.atom-UsingtheTuscanyAtombinding"></A>Using the Tuscany Atom binding</H3> + +<P>The primary use of the Atom binding is to provide support for collections that can be shared in a distributed fashion. Examples of shared collections includes shopping carts, telephone directories, insurance forms, and blog sites. These collections of items can be added, retrieved, updated, and deleted using the 4 basic actions of the HTTP protocol:</P> +<UL> + <LI>POST (create or add)</LI> + <LI>GET (retreive or query)</LI> + <LI>PUT (update)</LI> + <LI>DELETE (destroy or remove</LI> +</UL> + + +<P>The simplest way to use the Atom binding is to declare a collection as a service and provide an HTTP address where one can access the service. This service is declared in an SCA composite file which describes the SCA domain.</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <service name=<SPAN class="code-quote">"customer"</SPAN> promote=<SPAN class="code-quote">"CustomerCollection"</SPAN>> + <tuscany:binding.atom uri = <SPAN class="code-quote">"http:<SPAN class="code-comment">//localhost:8084/customer"</SPAN>/> +</SPAN> </service> +</PRE> +</DIV></DIV> + +<P>The service can be implemented in Java or any of the the Tuscany implementation types. For example, here is a way to create an implmentation for the above CustomerCollection service in the Java type.</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <component name=<SPAN class="code-quote">"CustomerCollection"</SPAN>> + <implementation.java class=<SPAN class="code-quote">"org.apache.tuscany.sca.binding.atom.CustomerCollectionImpl"</SPAN>/> + </component> +</PRE> +</DIV></DIV> + +<P>A collection that uses the Atom binding usually implements the Collection interface given in the package org.apache.tuscany.sca.binding.atom.collection. This interface declares the basic access methods mentioned above (post, get, put, and delete), and the data types on the methods are expressed as Atom type objects Feed and Entry. In other words, one can view the collection as an Atom Feed, and manipulate items in the Feed as Atom Entries. This shows the basic methods of the Atom Collection intergface in Tuscany:</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> +<SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">interface</SPAN> Collection { + + Entry post(Entry entry); + Entry get(<SPAN class="code-object">String</SPAN> id) <SPAN class="code-keyword">throws</SPAN> NotFoundException; + void put(<SPAN class="code-object">String</SPAN> id, Entry entry) <SPAN class="code-keyword">throws</SPAN> NotFoundException; + void delete(<SPAN class="code-object">String</SPAN> id) <SPAN class="code-keyword">throws</SPAN> NotFoundException; + + Feed getFeed(); + Feed query(<SPAN class="code-object">String</SPAN> queryString); +} +</PRE> +</DIV></DIV> + +<P>It is up to the developer or implementer of the shopping cart, telephone directory, or blog site to provide the code that implements the Collection interface. The developer or implementor also provides the code that translates from the business objects (shopping cart items, directory entries, insurance forms, blog articles) to the Atom model objects Feed and Entry.</P> + +<P>One of the features of using this binding is that your business objects (shopping cart items, directory entries, insurance forms, and blog articles) can now be easily published and shared by the many Atom supporting tools such as feed readers, web browsers, and syndication aggregation. In other words, people can access your collection most anywhere on any device.</P> + +<H3><A name="SCAJavabinding.atom-Example"></A>Example</H3> + +<P>Continuing with the CustomerCollection example shown above, let's see how one of the common access methods. In this case, let's look at the post method and how one would add a new item to the collection. When you declared your Atom binding in your SCA composite, you also provided a uri for your collection. Using a web browser or other device, a user performs an HTTP put request to this uri, with the body of the put containing the data. Tuscany SCA performs the task of invoking the correct service and finding the Java implementation for your collection and calling the correct method. </P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <SPAN class="code-keyword">public</SPAN> Entry post(Entry entry) { + <SPAN class="code-comment">// 1. Validate entry fields +</SPAN> <SPAN class="code-keyword">if</SPAN> (entry.getTitle() != <SPAN class="code-keyword">null</SPAN> ) { + entryID = <SPAN class="code-quote">"tag:"</SPAN> + site <SPAN class="code-quote">","</SPAN> + todaysDate + <SPAN class="code-quote">":"</SPAN> + title; + entry.setID( entryID ); + } + <SPAN class="code-comment">// 2. Provide any additional data. +</SPAN> entry.setUpdated( <SPAN class="code-keyword">new</SPAN> Date() ); + <SPAN class="code-comment">// 3. Store data in local collection or data base. +</SPAN> entries.put(id, entry); + <SPAN class="code-comment">// 4. Return entry to poster. +</SPAN> <SPAN class="code-keyword">return</SPAN> entry; + } +</PRE> +</DIV></DIV> + +<P>Much of the code consists of converting from a Feed or Entry to a business data model and storing to a collection.</P> + +<P>Tuscany uses the Apache Abdera project to provide a model for Atom data. Please see <A href="http://incubator.apache.org/abdera/" class="external-link" rel="nofollow">Apache Abdera</A> for the Java method to access Atom Feeds and Entries, and how to easily convert these Java objects to and from XML.</P> + +<H3><A name="SCAJavabinding.atom-OtherFeaturesoftheTuscanyAtomBinding"></A>Other Features of the Tuscany Atom Binding</H3> + +<P>More advanced features of the Tuscany Atom binding are described below.</P> + +<H4><A name="SCAJavabinding.atom-DataCachingusingETags%2CLastModified%2CandotherHeaderCommands"></A>Data Caching using ETags, Last-Modified, and other Header Commands</H4> + +<P>Atom feeds and entries can often be very large pieces of data. Since Tuscany uses the Atom data binding as one of its supported bindings, there is the potential that many requests for data may have large pieces of data associated with a request.</P> + +<P>Hyper Text Transfer Protocol (HTTP), the basis of the web, has support to help limit or cache the amount of data shared between a client and server by adding tags to a resource reques. These header tags are the ETag and the Last-Modified tags. When used with a predicate tag such as If-Match, If-Not-Match, If-Modified-Since, If-Unmodified-Since, etc., the client and the server can avoid shipping large pieces of data when updated data is not needed. </P> + +<P>The following entry scenarios show how Tuscany supports this form of caching throught ETags, Last-Modified, and other Header Commands.</P> + +<UL> + <LI>Posting new entry data to a feed<BR> + (Show entry data post request, item does not exist on server, server response code 200, return entry data body)</LI> + <LI>Updating existing entry data in a feed<BR> + (Show data update put, If-Match precondition, item is newer and matching, matching return code 412)</LI> + <LI>Requesting existing entry data<BR> + (Show get via ETag, If-None-Match precondition, modified entry data item, matching entry body returned) </LI> + <LI>Requesting stale entry data<BR> + (Show get via ETAG, If-None-Match precondition, unmodified entry data item, not modified return code 304)</LI> + <LI>Requesting up-to-date entry data<BR> + (Show request via last-modified date, entry data is unmodified, Not modified return code 304)</LI> + <LI>Requesting out-of-date entry data<BR> + (Show request via last-modified date, entry data is modified, updated data is returned)</LI> +</UL> + + +<P>Tuscany provides a test case ProviderEntryEntityTagsTest.java in module binding.atom.abdera that validates these Entry caching scenarios via JTest. Additionally, the following Feed scenarios are provided in the test case ProviderFeedEntityTagsTest.java.</P> + +<UL> + <LI>Test feed basics<BR> + (Request Atom feed. Check that feed is non-null, has Id, title, and updated values. Check for Etag and Last-Modified headers)</LI> + <LI>Test Unmodified If-Match predicate<BR> + (Request feed based on existing ETag. Use If-Match predicate in request header. Expect status 200 and feed body.)</LI> + <LI>Test Unmodified If-None-Match predicate<BR> + (Request feed based on existing ETag. Use If-None-Match predicate in request header. Expect status 304, item not modified, no feed body.)</LI> + <LI>Test Unmodified If-Unmodified-Since predicate<BR> + (Request feed based on very current Last-Modified. Use If-Unmodified-Since predicate in request header. Expect status 304, item not modified, no feed body.)</LI> + <LI>Test Unmodified If-Modified-Since predicate<BR> + (Request feed based on very old Last-Modified. Use If-Modified-Since predicate in request header. Expect status 200, feed in body.)</LI> + <LI>Test Modified If-None-Match predicate<BR> + (Request feed based on existing ETag. Use If-None-Match predicate in request header. Expect status 200, feed in body.)</LI> + <LI>Test Modified If-Match predicate<BR> + (Request feed based on existing ETag. Use If-Match predicate in request header. Expect status 412, precondition failed, no feed in body.)</LI> + <LI>Test Modified If-UnModified-Since predicate<BR> + (Request feed based on very recent Last-Mod date. Use If-Unmodified-Since predicate in request header. Expect status 304, no feed in body.)</LI> + <LI>Test Modified If-Modified-Since predicate<BR> + (Request feed based on very old Last-Mod date. Use If-Modified-Since predicate in request header. Expect status 200, feed in body.)</LI> +</UL> + + +<P>Support of Web 2.0 data caching via ETags and Last-Modified fields allow the Tuscany user to save bandwidth and re-requests of data. Especially in the area of content feeds which can have very large data objects, the ability to cache improves server performance and reduces network bottlenecks. A full end-to-end demonstration of this network savings is being created via Jira TUSCANY-2537 which will show caching in the feed aggregator sample.</P> + +<H4><A name="SCAJavabinding.atom-SupportforNegotiatedContentTypes"></A>Support for Negotiated Content Types</H4> + +<P>Requests for data now respond with negotiated content types. In other words, the requester can now state which content types are preferred, and the responder can provide different content types. The data preference is expressed in the request header "Accept" parameter.</P> + +<P>These data binding types are supported:</P> +<UL> + <LI>Atom XML format (Request header Accept=application/atom+xml)</LI> + <LI>Atom in JSON format (Request header Accept=application/atom+json)</LI> +</UL> + + +<P>The following content types are requestable in different data bindings</P> +<UL> + <LI>Atom entry data (MIME type application/atom+xxx;type=entry where xxx=xml or json)</LI> + <LI>Atom feed data (MIME type application/atom+xxx;type=feed where xxx=xml or json)</LI> +</UL> + + +<P>For example, the requester asks for an Atom entry with no Accept header or Accept header value is application/atom+xml. The returned response body contains:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Atom Entry response body as XML</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> +<?xml version='1.0' encoding='UTF-8'?> +<entry xmlns=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.w3.org/2005/Atom"</SPAN>> +</SPAN> <title type=<SPAN class="code-quote">"text"</SPAN>>customer Fred Farkle</title> + <updated>2008-08-08T18:40:30.484Z</updated> + <author> + <name>Apache Tuscany</name> + </author> + <content type=<SPAN class="code-quote">"text"</SPAN>>Fred Farkle</content> + <id>urn:uuid:customer-91d349b3-4b8b-4cfa-b9e9-d999f9937085</id> + <link href=<SPAN class="code-quote">"urn:uuid:customer-91d349b3-4b8b-4cfa-b9e9-d999f9937085"</SPAN> rel=<SPAN class="code-quote">"edit"</SPAN> /> + <link href=<SPAN class="code-quote">"urn:uuid:customer-91d349b3-4b8b-4cfa-b9e9-d999f9937085"</SPAN> rel=<SPAN class="code-quote">"alternate"</SPAN> /> +</entry> +</PRE> +</DIV></DIV> + +<P>In contrast, the requester asks for an Atom entry with Accept header value is application/atom+json. The returned response body contains:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Atom Entry response body as JSON</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> +{ + <SPAN class="code-quote">"id"</SPAN>:<SPAN class="code-quote">"urn:uuid:customer-91d349b3-4b8b-4cfa-b9e9-d999f9937085"</SPAN>, + <SPAN class="code-quote">"title"</SPAN>:<SPAN class="code-quote">"customer Fred Farkle"</SPAN>, + <SPAN class="code-quote">"content"</SPAN>:<SPAN class="code-quote">"Fred Farkle"</SPAN>, + <SPAN class="code-quote">"updated"</SPAN>:<SPAN class="code-quote">"2008-08-08T18:40:30.484Z"</SPAN>, + <SPAN class="code-quote">"authors"</SPAN>:[{ + <SPAN class="code-quote">"name"</SPAN>:<SPAN class="code-quote">"Apache Tuscany"</SPAN> + } + ], + <SPAN class="code-quote">"links"</SPAN>:[{ + <SPAN class="code-quote">"href"</SPAN>:<SPAN class="code-quote">"urn:uuid:customer-91d349b3-4b8b-4cfa-b9e9-d999f9937085"</SPAN>, + <SPAN class="code-quote">"rel"</SPAN>:<SPAN class="code-quote">"edit"</SPAN> + },{ + <SPAN class="code-quote">"href"</SPAN>:<SPAN class="code-quote">"urn:uuid:customer-91d349b3-4b8b-4cfa-b9e9-d999f9937085"</SPAN>, + <SPAN class="code-quote">"rel"</SPAN>:<SPAN class="code-quote">"alternate"</SPAN> + } + ] +} +</PRE> +</DIV></DIV> + +<P>The ability to view entires and feeds in multiple data formats allows the Tuscany user extreme flexibility in parsing and processing data returned by a service or collection.</P> + +<H4><A name="SCAJavabinding.atom-ServiceandWorkspaceDocumentSupport%28application%2Fatomsvcxml%29"></A>Service and Workspace Document Support (application/atomsvc+xml)</H4> + +<P>Prior to this implementation, there was a dummy service document provided when you visited an Atom feed service address with an "atomsvc" extension. For example, running the the Atom service binding unit tests, one could visit <A href="http://localhost:8080/customer/atomsvc" class="external-link" rel="nofollow">http://localhost:8080/customer/atomsvc</A> and receive the following service document:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Tuscany Atom Binding Dummy Service document</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <?xml version='1.0' encoding='UTF-8'?> + <service xmlns=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.w3.org/2007/app"</SPAN> xmlns:atom=<SPAN class="code-quote">"http://www.w3.org/2005/Atom"</SPAN>> +</SPAN> <workspace> + <atom:title type=<SPAN class="code-quote">"text"</SPAN>>resource</atom:title> + <collection href=<SPAN class="code-quote">"http:<SPAN class="code-comment">//luck.ibm.com:8084/customer"</SPAN>> +</SPAN> <atom:title type=<SPAN class="code-quote">"text"</SPAN>>collection</atom:title> + <accept>application/atom+xml;type=entry</accept> + <categories /> + </collection> + </workspace> + </service> +</PRE> +</DIV></DIV> +<P>This dummy implementation did not provide a true collection name, URL to the collection, accept MIME types or categories.</P> + +<P>Following the inclusion of TUSCANY-2597 and the new implentation, the Tuscany Atom binding will correctly populate an atomsvc document with information from the feed and give correct information for discovery. Now , running the the Atom service binding unit tests, one could visit <A href="http://localhost:8080/customer/atomsvc" class="external-link" rel="nofollow">http://localhost:8080/customer/atomsvc</A> and receive the following service document:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Tuscany Atom Binding Service document</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> +<?xml version='1.0' encoding='UTF-8'?> +<service xmlns=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.w3.org/2007/app"</SPAN> xmlns:atom=<SPAN class="code-quote">"http://www.w3.org/2005/Atom"</SPAN>> +</SPAN> <workspace xml:base=<SPAN class="code-quote">"http:<SPAN class="code-comment">//localhost:8084/"</SPAN>> +</SPAN> <atom:title type=<SPAN class="code-quote">"text"</SPAN>>workspace</atom:title> + <collection href=<SPAN class="code-quote">"http:<SPAN class="code-comment">//localhost:8084/customer"</SPAN>> +</SPAN> <atom:title type=<SPAN class="code-quote">"text"</SPAN>>customers</atom:title> + <accept>application/atom+xml; type=feed</accept> + <accept>application/json; type=feed</accept> + <accept>application/atom+xml; type=entry</accept> + <accept>application/json; type=entry</accept> + <categories /> + </collection> + </workspace> +</service> +</PRE> +</DIV></DIV> + +<P>The service document is now properly populated with URLs, titles, accept MIME types and categories. These are elements that are needed for collection discovery and visitatin.</P> + +<H4><A name="SCAJavabinding.atom-SupportforfullJavaScriptAtomclient."></A>Support for full JavaScript Atom client.</H4> +<P><A name="SCAJavabinding.atom-JavaScriptAtomClient"></A><BR> +After creating and publishing your SCA service, it can be tedious converting to and from Atom Feeds and Entries on the client side. Tuscany provides a full JavaScript object model for Atom Feeds, Entries, and other data objects. This benefits customers and client developers by providing an easy model to use in HTML, JSP, scripts, GUIs, and other client side technology.</P> + +<P>For example, prior to this feature, developers would have to develop code in XML to manipulate nodes in the XML document that represented the current page:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Tuscany client side XML Document Manipulation (old style)</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <SPAN class="code-keyword">var</SPAN> entries = feed.getElementsByTagName(<SPAN class="code-quote">"entry"</SPAN>); + <SPAN class="code-keyword">var</SPAN> list = ""; + <SPAN class="code-keyword">for</SPAN> (<SPAN class="code-keyword">var</SPAN> i=0; i<entries.length; i++) { + <SPAN class="code-keyword">var</SPAN> item = entries[i].getElementsByTagName(<SPAN class="code-quote">"content"</SPAN>)[0].firstChild.nodeValue; + list += item + ' <br>'; + } +</PRE> +</DIV></DIV> + +<P>Using the new JavaScript client object model, the code is greatly simplified and easier to understand:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Tuscany client side JavaScript Atom Object Model (new style)</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <SPAN class="code-keyword">var</SPAN> entries = feed.getEntries(); + <SPAN class="code-keyword">var</SPAN> list = ""; + <SPAN class="code-keyword">for</SPAN> (<SPAN class="code-keyword">var</SPAN> i=0; i<entries.length; i++) { + <SPAN class="code-keyword">var</SPAN> item = entries[i].getContent(); + list += item + ' <br>'; + } +</PRE> +</DIV></DIV> + +<P>Additionally, the Tuscany Atom JavaScript client provides full deserialization and serialization to and from the JavaScript Atom model and its XML format. In other words let's say you create an HTML page that scrapes a data base and wants to submit the data as an entry to a collection of blog articles. You can create the Entry data using the JavaScript Entry model:</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <SPAN class="code-keyword">var</SPAN> entry = <SPAN class="code-keyword">new</SPAN> Entry(); + entry.setNamespace( <SPAN class="code-quote">"http:<SPAN class="code-comment">//www.w3.org/2005/Atom"</SPAN> ); +</SPAN> entry.setTitle( <SPAN class="code-quote">"Atom-Powered Robots Run Amok"</SPAN> ); + entry.setId( <SPAN class="code-quote">"urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a"</SPAN> ); + entry.setUpdated( <SPAN class="code-quote">"2003-12-13T18:30:02Z"</SPAN> ); + entry.setContent( <SPAN class="code-quote">"Some text."</SPAN> ); + entry.addAuthor( <SPAN class="code-keyword">new</SPAN> Person( <SPAN class="code-quote">"John Doe"</SPAN> ) ); + entry.addAuthor( <SPAN class="code-keyword">new</SPAN> Person( <SPAN class="code-quote">"Mark Pilgrim"</SPAN>, <SPAN class="code-quote">"f8dy@example.com"</SPAN> )); + entry.addContributor( <SPAN class="code-keyword">new</SPAN> Person( <SPAN class="code-quote">"Sam Ruby"</SPAN> )); + entry.addContributor( <SPAN class="code-keyword">new</SPAN> Person( <SPAN class="code-quote">"Joe Gregorio"</SPAN> )); + entry.addLink( <SPAN class="code-keyword">new</SPAN> Link( <SPAN class="code-quote">"http:<SPAN class="code-comment">//example.org/edit/first-post.atom"</SPAN>, <SPAN class="code-quote">"edit"</SPAN> ));</SPAN> +</PRE> +</DIV></DIV> + +<P>Now to convert this code to XML and submit it to a site is easy using the Tuscany Atom JavaScript client:</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <SPAN class="code-keyword">var</SPAN> text = entry.toXML(); +</PRE> +</DIV></DIV> + +<P>The text string now contains the fully serialized XML format of the Entry object</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <SPAN class="code-quote">"<?xml version="</SPAN>1.0"?> + <entry xmlns=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.w3.org/2005/Atom"</SPAN>> +</SPAN> <title>Atom-Powered Robots Run Amok</title> + <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> + <updated>2003-12-13T18:30:02Z</updated> + <author><name>John Doe</name></author> + <content>Some text.</content> + <link rel=<SPAN class="code-quote">"edit"</SPAN> href=<SPAN class="code-quote">"http:<SPAN class="code-comment">//example.org/edit/first-post.atom"</SPAN>/> +</SPAN> </entry>" +</PRE> +</DIV></DIV> + +<P>Similarly the Tuscany Atom JavaScript client contains methods for deserializing from XML reperesentations to a JavaScript Atom model:</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <SPAN class="code-keyword">var</SPAN> feed = <SPAN class="code-keyword">new</SPAN> Feed(); + feed.readFromXML( xmlString ); +</PRE> +</DIV></DIV> + +<P>A full example showing how to use this client model is given in implementation-widgets-runtime. The store.html page shows the older style of document XML manipulation. The storeJS.html page shows the newer style of JavaScript object manipulation.</P> + +<H4><A name="SCAJavabinding.atom-SupportforPostingandPuttingMediaItems"></A>Support for Posting and Putting Media Items</H4> +<P>The Atom Publishing Protocol provides for a separate space for storage of media resources. The purpose of a separate space for these resources is to keep feeds and entries from growing too large with the contents of typically large items. Media resources can be any binary object that is supported by a MIME type, but typically media resources include video, image, and audio type files.</P> + +<P>Media resources are maintained by the collection implementor, and are given a dual identity. There is a location in the media respository, typically where one places the media files, and there is a location in the feed or entry space. This second reference is known as a media link entry.</P> + +<P>The Tuscany package at org.apache.tuscany.sca.binding.atom.collection (in tuscany-binding-atom-abdera package) has the following interface for MediaCollection:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Tuscany MediaCollection interface</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> + /** + * Creates a <SPAN class="code-keyword">new</SPAN> media entry + * + * @param title + * @param slug + * @param contentType + * @param media + */ + Entry postMedia(<SPAN class="code-object">String</SPAN> title, <SPAN class="code-object">String</SPAN> slug, <SPAN class="code-object">String</SPAN> contentType, InputStream media); + + /** + * Update a media entry. + * + * @param id + * @param contentType + * @param media + * @<SPAN class="code-keyword">return</SPAN> + */ + void putMedia(<SPAN class="code-object">String</SPAN> id, <SPAN class="code-object">String</SPAN> contentType, InputStream media) <SPAN class="code-keyword">throws</SPAN> NotFoundException; +</PRE> +</DIV></DIV> + +<P>These two methods are used to create (post) new media files, and update (put) new media information and edits. The media resources may be retrieved (get) or removed (delete) via the normal HTTP get and delete operations and the links returned by the post and get methods.</P> + +<P>For instance, when creating a media resource, one typically posts the following information via an HTTP post request:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Requesting New Media Creation (postMedia method invoke)</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> +POST /edit/ HTTP/1.1 +Host: media.example.org +Content-Type: image/png +Slug: The Beach +Authorization: Basic ZGFmZnk6c2VjZXJldA== +Content-Length: nnn +...binary data... +</PRE> +</DIV></DIV> + +<P>In turn, the Tuscany invocation framework invokes the postMedia shown above on the media collection implementation. The media collection implementation may then take the binary data from the media InputStream and store it to a media repository. The media collection implemenation should construct a proper Entry item via XML construction or some Atom model framework such as Apache Abdera. The Entry should contain the required elements (title, id, updated, summary, content, edit link, edit-media link) in order to provide the proper Atom Pub Protocol return headers and Entry data as given here:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Affirming New Media Creation (postMedia method return)</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> +HTTP/1.1 201 Created +Content-Length: nnn +Content-Type: application/atom+xml;type=entry;charset=<SPAN class="code-quote">"utf-8"</SPAN> +Location: http:<SPAN class="code-comment">//example.org/media/edit/the_beach.atom +</SPAN><?xml version=<SPAN class="code-quote">"1.0"</SPAN>?> +<entry xmlns=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.w3.org/2005/Atom"</SPAN>> +</SPAN> <title>The Beach</title> + <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> + <updated>2005-10-07T17:17:08Z</updated> + <author><name>Daffy</name></author> + <summary type=<SPAN class="code-quote">"text"</SPAN> /> + <content type=<SPAN class="code-quote">"image/png"</SPAN> + src=<SPAN class="code-quote">"http:<SPAN class="code-comment">//media.example.org/the_beach.png"</SPAN>/> +</SPAN> <link rel=<SPAN class="code-quote">"edit-media"</SPAN> + href=<SPAN class="code-quote">"http:<SPAN class="code-comment">//media.example.org/edit/the_beach.png"</SPAN> /> +</SPAN> <link rel=<SPAN class="code-quote">"edit"</SPAN> + href=<SPAN class="code-quote">"http:<SPAN class="code-comment">//example.org/media/edit/the_beach.atom"</SPAN> /> +</SPAN></entry> +</PRE> +</DIV></DIV> + +<P>Note that the edit link provides the Atom Feed link to the media entry, and the edit-media link provides the media repository link to the media entry. Use these links to get and delete media.</P> + +<P>A special convention has been implemented to allow the media collection implementation to return properties in the response header. The summary element of the Entry returned may contain a set of key=value properties separated via commas. For example, in order to provide return Content-Type and Content-Length values in the response header, one can created this text in the postMedia Entry summary element: <TT>Content-Type=image/jpg,Content-Length=21642</TT>.</P> + +<P>The putMedia method acts in much the same way, but the URI to the item should contain an ID to the media being updated. For instance, if the usual post and get feed URI is <TT><A href="http://localhost:8084/receipt" class="external-link" rel="nofollow">http://localhost:8084/receipt</A></TT>, then to update the media given above one would put to the URI <TT><A href="http://localhost:8084/receipt/urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a" class="external-link" rel="nofollow">http://localhost:8084/receipt/urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</A></TT>. Here is an example of a put request:</P> +<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Requesting Media Update (putMedia method invoke)</B></DIV><DIV class="codeContent panelContent"> +<PRE class="code-java"> +PUT /edit/urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a HTTP/1.1 +Host: media.example.org +Content-Type: image/png +Authorization: Basic ZGFmZnk6c2VjZXJldA== +Content-Length: nnn +...binary data... +</PRE> +</DIV></DIV> + +<P>After the above put request, the Atom binding will invoke the media collection implementation putMedia method. The media collection should update the media if the ID exists (and a 200 OK status code will return), or the media collection should throw a NotFoundException if the ID does not exist (and a 404 not found status code will return).</P> + +<P>The above scenarios are documents in the MediaCollectionTestCase unit test case in the binding-atom-abdera module in the Tuscany code base.</P> + +<H3><A name="SCAJavabinding.atom-SecurityPolicysupportinHTTPandWeb2.0Bindings"></A>Security Policy support in HTTP and Web 2.0 Bindings</H3> + +<DIV class="panelMacro"><TABLE class="infoMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>work in progress</TD></TR></TABLE></DIV> + +<H3><A name="SCAJavabinding.atom-Scenarios"></A>Scenarios</H3> + +<UL> + <LI>A Web 2.0 application requires that a user get authenticated before it can access the application.</LI> + <LI>A Web 2.0 application requires that all communication between client/server be done using SSL.</LI> + <LI>A given service, exposed using a web 2.0 binding requires user authentication.</LI> + <LI>A given operation, exposed using a web 2.0 binding requires user authentication.</LI> +</UL> + + +<H3><A name="SCAJavabinding.atom-PolicyInterceptor"></A>Policy Interceptor</H3> + +<P>The design approach that is being considered is to inject policy security interceptors, that would properly validate and enforce the security intents.<BR> +The authentication will be done using JAAS modules for authentication, and initially we would support authenticating to a list of username/password supplied by the application or using an LDAP.</P> + +<P><SPAN class="image-wrap" style="display: block; text-align: center"><IMG src="sca-java-bindinghttp-security-policy-section.data/high_level_design.jpg" style="border: 0px solid black"></SPAN></P> +</TD></TR></TBODY></TABLE> + </DIV> + </DIV> + </DIV> + <!-- pageContent macro end --> + + </TD> + </TR> + </TABLE> + + <!-- footer macro --> + <SCRIPT src="http://www.google-analytics.com/urchin.js" type="text/javascript"> + </SCRIPT> + <SCRIPT type="text/javascript"> + _uacct = "UA-1174707-5"; + urchinTracker(); + </SCRIPT> + + <A href="http://www.statcounter.com/" target="_blank"><IMG src="http://c26.statcounter.com/counter.php?sc_project=2619156&java=0&security=94bd7e7d&invisible=0" alt="website stats" border="0"></A> + + <DIV class="footer"> + Copyright � 2003-2012, The Apache Software Foundation </BR> + Apache Tuscany and the Apache Tuscany project logo are trademarks of The Apache Software Foundation. + </DIV> + <!-- footer macro end --> + + </BODY> +</HTML> |