[CONF] Apache Tuscany: SCA Java binding.http (page created)

[co...@apache.org]

SCA Java binding.http (TUSCANY) created by Dan Becker
   http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+binding.http

Content:
---------------------------------------------------------------------

{section:border=false}
{column:width=15%}
{include: SCA Java Subproject Menu}
{include: Java SCA Menu New}
{column}
{column:width=85%}

h3. <binding.http> Introduction

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.

More information on the HTTP protocol is located at:
* [Hyper Text Transfer Protocol|http://tools.ietf.org/html/rfc2616].

(on) 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 [Tuscany Web 2.0 Roadmap|http://tuscany.apache.org/sca-java-roadmap.html]. Users should also be aware of the [Atom binding|http://tuscany.apache.org/sca-java-bindingatom.html] and [RSS binding|http://tuscany.apache.org/sca-java-bindingrss.html] which sit on top of the HTTP binding, but have additional features and data types associated with the actions.

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.


h3. Using the Tuscany HTTP binding

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:
* POST (create or add)
* GET (retreive or query)
* PUT (update)
* DELETE (destroy or remove

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.
{code}
    <component name="ResourceServiceComponent">
        <tuscany:implementation.resource location="content"/>
    	<service name="Resource">
    		<tuscany:binding.http uri="http://localhost:8085/webcontent"/>
    	</service>
    </component>
{code}
No further implementation is needed with a resource. It is served on the web like any other static web content.

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.
{code}
    <component name="HTTPBindingComponent">
        <implementation.java class="org.apache.tuscany.sca.binding.http.TestBindingImpl"/>
    	<service name="TestBindingImpl">
    		<tuscany:binding.http uri="http://localhost:8085/httpbinding"/>
    	</service>
    </component>
{code}

h3. Exampler HTTP Servlet and Service Implementations

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;
{code}
@Service(Servlet.class)
public class TestServiceImpl implements Servlet {

    public void init(ServletConfig config) throws ServletException {
    }

    public void service(ServletRequest request, ServletResponse response) throws ServletException, IOException {
        response.getOutputStream().print("<html><body><p>Hello from Tuscany HTTP service</body></html>");
    }

}
{code}

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:
{code}
public class TestGetImpl {
    
    public InputStream get(String id) {
        return new ByteArrayInputStream(("<html><body><p>This is the service GET method, item=" + id + "</body></html>").getBytes());

    }
}
{code}

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.

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.

h3. Advanced Features of the Tuscany HTTP Binding

{column}
{section}

---------------------------------------------------------------------
CONFLUENCE INFORMATION
This message is automatically generated by Confluence

Unsubscribe or edit your notifications preferences
   http://cwiki.apache.org/confluence/users/viewnotifications.action

If you think it was sent incorrectly contact one of the administrators
   http://cwiki.apache.org/confluence/administrators.action

If you want more information on Confluence, or have a bug to report see
   http://www.atlassian.com/software/confluence