diff options
Diffstat (limited to '')
| -rw-r--r-- | site/trunk/site-publish/documentation-2x/sca-java-bindinghttp.html | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/site/trunk/site-publish/documentation-2x/sca-java-bindinghttp.html b/site/trunk/site-publish/documentation-2x/sca-java-bindinghttp.html new file mode 100644 index 0000000000..0456869213 --- /dev/null +++ b/site/trunk/site-publish/documentation-2x/sca-java-bindinghttp.html @@ -0,0 +1,324 @@ + + + + + + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<HTML> + <HEAD> + <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"> + + <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/TUSCANYxDOCx2x/$images/favicon.ico"> + <TITLE>SCA Java binding.http : Apache Tuscany</TITLE> + <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD> + + <STYLE> + .spacetree * ul { + padding-left:0px; + margin-left: 0px; + } + .spacetree * li { + margin-left: 5px; + padding-left:5px; + } + </STYLE> + + <BODY onload="init()"> + <!-- topNav --> + <TABLE border="0" cellpadding="2" cellspacing="0" width="100%"> + <TR class="topBar"> + <TD align="left" valign="middle" class="topBarDiv" align="left" nowrap=""> + <A href="https://cwiki.apache.org/geronimo"> Home</A> > <A href="index.html" title="Apache Tuscany Docs 2.x">Apache Tuscany Docs 2.x</A> > <A href="index.html" title="Index">Index</A> > <A href="sca-java-extensions-guide.html" title="SCA Java Extensions Guide">SCA Java Extensions Guide</A> > <A href="" title="SCA Java binding.http">SCA Java binding.http</A> + </TD> + <TD align="right" valign="middle" nowrap=""> + <FORM name="search" action="http://www.google.com/search" method="get"> + <INPUT type="hidden" name="ie" value="UTF-8"> + <INPUT type="hidden" name="oe" value="UTF-8"> + <INPUT type="hidden" name="domains" value=""> + <INPUT type="hidden" name="sitesearch" value=""> + <INPUT type="text" name="q" maxlength="255" value=""> + <INPUT type="submit" name="btnG" value="Google Search"> + </FORM> + </TD> + </TR> + </TABLE> + + + <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="index.html" title="Apache Tuscany Docs 2.x">Apache Tuscany Docs 2.x</A> > <A href="index.html" title="Index">Index</A> > <A href="sca-java-extensions-guide.html" title="SCA Java Extensions Guide">SCA Java Extensions Guide</A> > <A href="" title="SCA Java binding.http">SCA Java binding.http</A> + </TD> + + <TD align="right" valign="middle" class="topBarDiv" align="left" nowrap="true"> + <A href="http://tuscany.apache.org/">Tuscany Home</A> | <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> + + <TABLE border="0" cellpadding="0" width="100%" bgcolor="#FFFFFF"> + <TR> + <TD valign="top" align="left" width="22%" bgcolor="#F9F9F9" class="noprint"> + <DIV class="tabletitle">Table of Contents</DIV> + <DIV class="spacetree"> + + + </DIV> + </TD> + <TD align="left" valign="top" width="78%"> + <!-- pageContent --> + <DIV id="PageContent"> + <DIV class="pageheader" style="padding: 6px 0px 0px 0px;"> + <!-- We'll enable this once we figure out how to access (and save) the logo resource --> + <!--img src="http://geronimo.apache.org/images/confluence_logo.gif" style="float: left; margin: 4px 4px 4px 10px;" border="0"--> + <DIV style="margin: 0px 10px 0px 10px" class="smalltext">Apache Tuscany Docs 2.x</DIV> + <DIV style="margin: 0px 10px 8px 10px" class="pagetitle">SCA Java binding.http</DIV> + + <DIV class="greynavbar" align="right" style="padding: 2px 10px; margin: 0px;"> +<!-- --> + <A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=5964959"> + <IMG src="http://geronimo.apache.org/images/icons/notep_16.gif" height="16" width="16" border="0" align="absmiddle" title="Edit Page"></A> + <A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=5964959">Edit Page</A> + + <A href="https://cwiki.apache.org/confluence/pages/listpages.action?key=TUSCANYxDOCx2x"> + <IMG src="http://geronimo.apache.org/images/icons/browse_space.gif" height="16" width="16" border="0" align="absmiddle" title="Browse Space"></A> + <A href="https://cwiki.apache.org/confluence/pages/listpages.action?key=TUSCANYxDOCx2x">Browse Space</A> + + <A href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964959"> + <IMG src="http://geronimo.apache.org/images/icons/add_page_16.gif" height="16" width="16" border="0" align="absmiddle" title="Add Page"></A> + <A href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964959">Add Page</A> + + <A href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964959"> + <IMG src="http://geronimo.apache.org/images/icons/add_blogentry_16.gif" height="16" width="16" border="0" align="absmiddle" title="Add News"></A> + <A href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964959">Add News</A> +<!-- --> + </DIV> + </DIV> + + <DIV class="pagecontent"> + <DIV class="wiki-content"> + +<H3><A name="SCAJavabinding.http-%3Cbinding.http%3EIntroduction"></A><binding.http> Introduction</H3> + +<P>The Tuscany Java SCA runtime supports Hyper Text Transfer Protocol (HTTP) using the <binding.http> extension. Tuscany can communicate with services that provide or consume business data objects via the well known actions of HTTP, for example POST, GET, PUT, and DELETE. In HTTP interactions between a client and a server takes place as a series of requests and responses. Information is comunicated by reads and rights over server socket ports. HTTP actions, also known as verbs, are communicated between a client and a server in the requests and responses. Each request and response consists of a header and a body. Typically the header contains the request action name, a URI indicating the location of object of the object of the action, and a number property name and value pairs containing other meta information about the transaction (e.g. body length, modification dates, MIME type, etc.). The body contains the subject of the action, whether it be a text or binary encoding of the data, an error message, or a serialized object.</P> + +<P>More information on the HTTP protocol is located at:</P> +<UL> + <LI><A href="http://tools.ietf.org/html/rfc2616" class="external-link" rel="nofollow">Hyper Text Transfer 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 advanced 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>. Users should also be aware of the <A href="http://tuscany.apache.org/sca-java-bindingatom.html" class="external-link" rel="nofollow">Atom binding</A> and <A href="http://tuscany.apache.org/sca-java-bindingrss.html" class="external-link" rel="nofollow">RSS binding</A> which sit on top of the HTTP binding, but have additional features and data types associated with the actions.</P> + +<P>A Tuscany protocol binding such as the HTTP binding, is a way to fit a common protocol into the Tuscany abstraction and way of doing things. Each binding identifies itself to the Tuscany runtime and states under what conditions it is available. The Tuscany runtime uses the binding to translate invocations and data from the Tuscany world into the world of the protocol and back. So in the case of the HTTP binding, Tuscany uses the HTTP request and response mechanism to share business data between service components.</P> + + +<H3><A name="SCAJavabinding.http-UsingtheTuscanyHTTPbinding"></A>Using the Tuscany HTTP binding</H3> + +<P>The primary use of the HTTP binding is to share resources and services over HTTP over the web in a distributed fashion. Resources are items that have a resource implementation such as web content. Services are items that have data types and a defined business interfaces such as shared collections. 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 HTTP binding is to declare a resource that can be shared over the web via HTTP and provide an HTTP address where one can access the resource. This resource 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"> + <component name=<SPAN class="code-quote">"ResourceServiceComponent"</SPAN>> + <tuscany:implementation.resource location=<SPAN class="code-quote">"content"</SPAN>/> + <service name=<SPAN class="code-quote">"Resource"</SPAN>> + <tuscany:binding.http uri=<SPAN class="code-quote">"http:<SPAN class="code-comment">//localhost:8085/webcontent"</SPAN>/> +</SPAN> </service> + </component> +</PRE> +</DIV></DIV> +<P>No further implementation is needed with a resource. It is served on the web like any other static web content.</P> + +<P>The HTTP binding can also declare a business service that can be shared over the web and provide an HTTP address where one can access the service. This resource 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"> + <component name=<SPAN class="code-quote">"HTTPBindingComponent"</SPAN>> + <implementation.java class=<SPAN class="code-quote">"org.apache.tuscany.sca.binding.http.TestBindingImpl"</SPAN>/> + <service name=<SPAN class="code-quote">"TestBindingImpl"</SPAN>> + <tuscany:binding.http uri=<SPAN class="code-quote">"http:<SPAN class="code-comment">//localhost:8085/httpbinding"</SPAN>/> +</SPAN> </service> + </component> +</PRE> +</DIV></DIV> + +<H3><A name="SCAJavabinding.http-ExampleHTTPServletandServiceImplementations"></A>Example HTTP Servlet and Service Implementations</H3> + +<P>A service that uses the HTTP binding usually implements the javax.servlet.Servlet interface. This interface declares the basic access methods mentioned in the J2EE specification: init, destroy, service, getServletInfo, etc. The Tuscany runtime ensures that the proper method is invoked whenever a service does one of the HTTP actions. For example here is a TestService implemented in the package org.apache.tuscany.sca.binding.http;</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> +@Service(Servlet.class) +<SPAN class="code-keyword">public</SPAN> class TestServiceImpl <SPAN class="code-keyword">implements</SPAN> Servlet { + + <SPAN class="code-keyword">public</SPAN> void init(ServletConfig config) <SPAN class="code-keyword">throws</SPAN> ServletException { + } + + <SPAN class="code-keyword">public</SPAN> void service(ServletRequest request, ServletResponse response) <SPAN class="code-keyword">throws</SPAN> ServletException, IOException { + response.getOutputStream().print(<SPAN class="code-quote">"<html><body><p>Hello from Tuscany HTTP service</body></html>"</SPAN>); + } + +} +</PRE> +</DIV></DIV> + +<P>Another way of implementing an HTTP service is to use a collection interface that matches the actions of the HTTP protocol. In this case, the methods must be named post, get, put, and delete. Tuscany ensures that the proper method is invoked via the request and response protocol of HTTP:</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> +<SPAN class="code-keyword">public</SPAN> class TestGetImpl { + + <SPAN class="code-keyword">public</SPAN> InputStream get(<SPAN class="code-object">String</SPAN> id) { + <SPAN class="code-keyword">return</SPAN> <SPAN class="code-keyword">new</SPAN> ByteArrayInputStream((<SPAN class="code-quote">"<html><body><p>This is the service GET method, item="</SPAN> + id + <SPAN class="code-quote">"</body></html>"</SPAN>).getBytes()); + + } +} +</PRE> +</DIV></DIV> + +<P>So using the common verbs of HTTP and Java object serialization, one can implement services and run them anywhere the HTTP protocol is implemented. The service developer or implementer simply creates methods for post, get, put, and delete, and a business collection such as a shopping cart, telephone directory, insurance form, or blog sites can be created. See the Tuscany module binding-http-runtime for complete examples.</P> + +<P>Unlike the Atom or RSS bindings, which have defined data types which encapsulate the business objects, the HTTP binding uses Java object serialization for passing business object data back and forth. Thus it is up to the developer or implementer to deserialize the data and reconstitute a business object.</P> + +<H3><A name="SCAJavabinding.http-AdvancedFeaturesoftheTuscanyHTTPBinding"></A>Advanced Features of the Tuscany HTTP Binding</H3> + +<H4><A name="SCAJavabinding.http-HTTPConditionalActionsandCachingusingETagsandLastModified"></A>HTTP Conditional Actions and Caching using ETags and Last-Modified</H4> + +<P>The HTTP specification provides a set of methods for HTTP clients and servers to interact. These methods form the foundation of the World Wide Web. Tuscany implements many of these methods a binding interface to a collection. The main methods are:</P> + +<UL> + <LI>GET - retrieves an item from a collection</LI> + <LI>POST - creates or adds an item to a collection</LI> + <LI>PUT - updates or replaces an item in a collection</LI> + <LI>DELETE - removes an item in a a collection</LI> +</UL> + + +<P>The HTTP specification (HTTP 1.1 Chapter 13 - Caching) also provides a mechanism by which these methods may be executed conditionally. To perform conditional methods, an HTTP client puts 3 items in the HTTP request header:</P> + +<UL> + <LI>ETag - entity tag, a unique identifier to an item in a collection. Normally created and returned by the server when creating (POST) a new item.</LI> + <LI>LastModified - an updated field. Normally a string containing a date and time of the last modification of the item.</LI> + <LI>Predicate - a logical test (e.g. IfModified, IfUnmodified) to use with the ETag and LastModified to determine whether to act.</LI> +</UL> + + +<P>The complete list of predicates is given in the HTTP specification.</P> + +<P>The most common use of conditional methods is to prevent two requests to the server instead of one conditional request. For example, a common scenario is to check if an item has been modified, if not changed update it with a new version, if changed do not update it. With a conditional PUT method (using the IfUnmodifed predicate and a LastModified date), this can be done in one action. Another common use is to prevent multiple GETs of an item to ensure we have a valid copy. Rather than doing a second request of a large item, one can do a conditional GET request (using an IfModified predicate and a LastModified date), and avoid the second request if our object is still valid. The server responds with either a normal response body, or status code 304 (Not Modified), or status code 412 (precondition failed).</P> + +<P>Tuscany implements the logic to move these caching items to and from the HTTP request and response headers, and deliver them to the collection implementation. The items are delivered to a user implementation via a serializable object called CacheContext. This object contains the value of the ETag, the LastModified value, and any predicates. It is up to the implementer of a collection to provide the correct server logic to act on these predicates. The CacheContext class is found in found in the Tuscany module package org.apache.tuscany.sca.binding.http.</P> + +<P>To implement conditional actions on your service, the developer or implementer implements any of the condional HTTP actions: conditionalPost, conditionalGet, conditionalPut, or conditionalDelete. Tuscany automatically routes a request with proper request header fields (ETag, LastModified, and predicates) to the proper collection method.</P> + +<P>For example, the TestBindingCacheImpl class in package org.apache.tuscany.sca.binding.http implements a server collection which pays attention to conditional methods. Notice that this collection implements conditionalGet, conditionalPut, conditionalPost, and conditionalDelete methods as well as get, put, post, delete. The server collection can look at the CacheContext obect to determine whether an item or a status code should be returned. In this example code, the conditionalGet checked the If-Modified predicate and determines whether the item is not modified and if so, throws a NotModifiedException.</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <SPAN class="code-keyword">public</SPAN> InputStream conditionalGet(<SPAN class="code-object">String</SPAN> id, HTTPCacheContext cacheContext) + <SPAN class="code-keyword">throws</SPAN> NotModifiedException, PreconditionFailedException { + + <SPAN class="code-keyword">if</SPAN> (cacheContext != <SPAN class="code-keyword">null</SPAN>) { + <SPAN class="code-keyword">if</SPAN> (cacheContext.ifModifiedSince) { + <SPAN class="code-keyword">if</SPAN> ((id.equals(<SPAN class="code-quote">"1"</SPAN>)) + && (0 > cacheContext.lastModifiedDate + .compareTo(<SPAN class="code-keyword">new</SPAN> Date()))) + <SPAN class="code-keyword">throw</SPAN> <SPAN class="code-keyword">new</SPAN> NotModifiedException(<SPAN class="code-quote">"item 1 was modified on "</SPAN> + + <SPAN class="code-keyword">new</SPAN> Date()); + } + ... + ... +</PRE> +</DIV></DIV> + +<P>For a full example of all conditional methods and many combinations of predicates, one can look to the module http-binding unit tests to understand how these conditional request work. The HTTPBindingCacheTestCase contains 36 tests of all 4 HTTP conditonal methods. Various predicates are tested with various ETags and LastModified fields. The fields are tested in both the positive and negative cases.</P> + +<P>Here is a complete list of the tests:</P> +<UL> + <LI>testGet() - tests normal GET method of collection, expects item</LI> + <LI>testConditionalGetIfModifiedNegative() - tests not modified GET, expects item</LI> + <LI>testConditionalGetIfModifiedPositive() - tests modified GET, expect code 304</LI> + <LI>testConditionalGetIfUnmodifiedNegative() - tests unmodifed GET, expects item</LI> + <LI>testConditionalGetIfUnmodifiedPositive() - tests modified GET, expects code 412</LI> + <LI>testConditionalGetIfMatchNegative() - tests matching GET, expects code 412</LI> + <LI>testConditionalGetIfMatchPositive() - tests matching GET, expects item</LI> + <LI>testConditionalGetIfNoneMatchNegative - tests unmatching GET, expects item</LI> + <LI>testConditionalGetIfNoneMatchPositive() - tests unmatching GET, expects code 412</LI> +</UL> + + +<P>Similarly, there are 9 tests each for DELETE, POST, and PUT, making a total of 36 test cases.</P> + +<H4><A name="SCAJavabinding.http-DifferencesBetweenHTTPBindingCachingandAtomBindingCachinginTuscany"></A>Differences Between HTTP Binding Caching and Atom Binding Caching in Tuscany</H4> + +<P>A similar sort of conditional posting is implemented in the Atom Binding. The difference is that the HTTP binding requires an implementer to provide conditional methods. The Atom binding caching uses the Abdera Atom model objects to automatically derive an ETag and a LastModified tags. In the Atom model, the Entry or Feed ID is used to make an item ETag field. The Atom Entry or Feed updated field is used to make an item LastModified field.</P> + +<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"> Use the HTTP binding caching when you are not using Atom Entries and Feeds as your business objects. However, the more flexible HTTP binding caching requires you to implement special conditional methods. Use the Atom binding when you can model your business data in terms of Atom Entries and Feeds. The more constrictive Atom binding caching will derive caching tags from your data model fields.</P> + +<H3><A name="SCAJavabinding.http-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.http-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.http-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/policy_interceptors_high_level_design.jpg" style="border: 0px solid black"></SPAN></P> + + </DIV> + + </DIV> + </DIV> + </TD> + </TR> + </TABLE> + + <!-- footer --> + <TABLE border="0" cellpadding="2" cellspacing="0" width="100%"> + <TR> + <TD align="left" valign="middle" class="footer"> + + <IMG src="http://static.delicious.com/img/delicious.small.gif" height="10" width="10" alt="Delicious"> + <A href="http://delicious.com/save" onclick="window.open('http://delicious.com/save?v=5&noui&jump=close&url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title),'delicious','toolbar=no,width=550,height=550'); return false;">Bookmark this on Delicious</A> + + <IMG src="http://digg.com/img/badges/16x16-digg-guy.gif" width="16" height="16" alt="Digg!"> + <A href="" onclick="window.open('http://digg.com/submit?url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)+'&topic=programming');">Digg this</A> + <!-- Slicker, but no text + <script type="text/javascript"> + digg_skin = 'icon'; + digg_window = 'new'; + digg_title = 'Apache Geronimo v2.2 Documentation : SCA Java binding.http'; + digg_topic = 'programming'; + </script> + <script src="http://digg.com/tools/diggthis.js" type="text/javascript"></script> + --> + + </TD> + <TD align="right" valign="middle" class="footer"> + <A href="http://cwiki.apache.org/GMOxPMGT/geronimo-privacy-policy.html">Privacy Policy</A> - + Copyright © 2003-2010, The Apache Software Foundation, Licensed under <A href="http://www.apache.org/licenses/LICENSE-2.0">ASL 2.0.</A> + </TD> + </TR> + </TABLE> + + </BODY> +</HTML>
\ No newline at end of file |