| |
| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <!-- |
| 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. |
| --> |
| |
| <HTML> |
| <HEAD> |
| <META CONTENT="text/html; charset=iso-8859-1" HTTP-EQUIV="Content-Type"> |
| <META CONTENT="text/css" HTTP-EQUIV="Content-Style-Type"> |
| <STYLE MEDIA="all" TYPE="text/css"> |
| @import url("css/maven-base.css"); |
| @import url("css/maven-theme.css"); |
| </STYLE> |
| |
| <LINK HREF="css/maven-theme.css" MEDIA="print" REL="stylesheet" |
| TYPE="text/css"> |
| <TITLE>Tuscany SCA Native - REST Extension</TITLE> |
| </HEAD> |
| |
| <BODY> |
| <DIV ID="bodyColumn"> |
| <DIV ID="contentBox"> |
| <DIV CLASS="section"> |
| <H1>Tuscany SCA Native - REST Extension</H1> |
| |
| <P>This document describes the deployment and use of the REST |
| binding support in the Apache Tuscany SCA Native runtime. |
| </P> |
| <P>The Tuscany REST extension allows SCA services and references to be invoked |
| via HTTP REST calls |
| </P> |
| <P>The following samples demonstrate use of the REST extension:</P> |
| <UL> |
| <LI><A HREF="../samples/RestCalculator/README.html">RestCalculator</A></LI> |
| <LI><A HREF="../samples/RestCustomer/README.html">RestCustomer</A></LI> |
| <LI><A HREF="../samples/RestYahoo/README.html">RestYahoo</A></LI> |
| <LI><A HREF="../samples/AlertAggregator/README.html">AlertAggregator</A></LI> |
| </UL> |
| </DIV> |
| <DIV CLASS="section"> |
| <H2>Contents</H2> |
| <OL> |
| <LI><A HREF="#requirements">System Requirements</A></LI> |
| <LI><A HREF="#install">Installing the Tuscany SCA REST Extension..</A> |
| <UL> |
| <LI><A HREF="#linuxbin">..from the binary release on Linux and Mac OS X</A></LI> |
| <LI><A HREF="#linuxsrc">..from the source release on Linux and Mac OS X</A></LI> |
| <LI><A HREF="#winbin">..from the binary release on Windows</A></LI> |
| <LI><A HREF="#winsrc">..from the source release on Windows</A></LI> |
| </UL></LI> |
| <LI><A HREF="#deploy">Deploying the Tuscany REST Service extension to the HTTPD server</A></LI> |
| <LI><A HREF="#resource">The Tuscany REST extension resource pattern</A></LI> |
| <LI><A HREF="#rpc">The Tuscany REST extension RPC pattern</A></LI> |
| <LI><A HREF="#help">Getting help</A></LI> |
| </OL> |
| </DIV> |
| <DIV CLASS="section"> |
| <A NAME="requirements"><H2>System Requirements</H2></A> |
| |
| <P>In order to install and use the Tuscany SCA REST Extension there are some |
| extra requirements in addition to the <A HREF="../GettingStarted.html#requirements">Tuscany |
| SCA requirements</A>:</P> |
| <TABLE CLASS="bodyTable"> |
| |
| <TBODY> |
| <TR CLASS="a"> |
| <TD><B>Software</B></TD> |
| <TD><B>Download Link</B></TD> |
| </TR> |
| <TR CLASS="b"> |
| <TD>Apache HTTPD version 2.2</TD> |
| <TD> |
| <A HREF="http://httpd.apache.org" |
| TARGET="_blank">http://httpd.apache.org</A><BR/> |
| Please download and follow the installation instructions. This is required |
| for building the REST Service extension and for hosting and running REST services. |
| </TD> |
| </TR> |
| <TR CLASS="a"> |
| <TD>libcurl version 7.15 or higher</TD> |
| <TD> |
| <A HREF="http://curl.haxx.se/download.html" |
| TARGET="_blank">http://curl.haxx.se/download.html</A><BR/> |
| Please download and follow the installation instructions. This is required |
| for building the REST Reference extension and for calling REST references.<BR/> |
| On Windows, the extension was developed and tested against the "Win32 - MSVC 7.15.1 devel" |
| library provided by Chris Drake. On Linux the libcurl libraries were built from |
| the 7.16.1 source. On Mac OS X the library was downloaded, built and installed via the |
| standard "port" command. |
| </TD> |
| </TR> |
| </TBODY> |
| </TABLE> |
| </DIV> |
| |
| <DIV CLASS="section"> |
| <A NAME="install"><H2>Installing the Tuscany SCA REST Extension</H2></A> |
| <A NAME="linuxbin"><H3>Getting the Tuscany SCA REST Extension working with the binary release on Linux and Mac OS X</H3></A> |
| <OL> |
| <LI>Follow the <A HREF="#deploy">deployment steps</A> below to ensure the HTTPD server |
| invokes Tuscany when it receives an appropriate HTTP request</LI> |
| <LI>Ensure the libcurl and HTTPD libraries are available on the LD_LIBRARY_PATH environment variable on Linux and |
| the DYLD_LIBRARY_PATH environment variable on Mac OS X</LI> |
| </OL> |
| <A NAME="linuxsrc"><H3>Getting the Tuscany SCA REST Extension working with the source release on Linux and Mac OS X</H3></A> |
| <OL> |
| <LI>You will need the Tuscany SCA and SDO libraries - follow the instructions |
| <A HREF="../GettingStarted.html">here</A> to build the SCA libraries and default extensions</LI> |
| <LI>The following environment variables are required: |
| <UL> |
| <LI>TUSCANY_SCACPP=<path to built Tuscany SCA> |
| <LI>TUSCANY_SDOCPP=<path to installed Tuscany SDO> |
| <LI>APR_INCLUDE=<path to APR includes></LI> |
| <LI>HTTPD_INCLUDE=<path to HTTPD includes><BR/> |
| Note: If you are using a default installation of HTTPD these are usually:<BR/> |
| APR_INCLUDE=/usr/include/apr-1<BR/> |
| HTTPD_INCLUDE=/usr/include/httpd</LI> |
| <LI>CURL_INCLUDE=<path to libcurl includes></LI> |
| <LI>CURL_LIB<path to libcurl libraries><BR/> |
| Note: If you are using a default installation of libcurl these are usually:<BR/> |
| CURL_INCLUDE=/usr/include/curl<BR/> |
| CURL_LIB=/usr/lib</LI> |
| </UL></LI> |
| <LI>Build the REST source only with the following command sequence: |
| <UL> |
| <LI>cd <tuscany_sca_install_dir></LI> |
| <LI>./configure --prefix=$TUSCANY_SCACPP --enable-restbinding --enable-cpp=no --enable-wsbinding=no</LI> |
| <LI>make</LI> |
| <LI>make install</LI> |
| </UL> |
| NOTE: If you don't provide a --prefix configure option, it will by default install into |
| /usr/local/tuscany/sca</LI> |
| </OL> |
| |
| <A NAME="winbin"><H3>Getting the Tuscany SCA REST Extension working with the binary release on Windows</H3></A> |
| <OL> |
| <LI>Follow the <A HREF="#deploy">deployment steps</A> below to ensure the HTTPD server |
| invokes Tuscany when it receives an appropriate HTTP request</LI> |
| <LI>Ensure the libcurl and HTTPD libraries are available on the PATH environment variable</LI> |
| </OL> |
| <A NAME="winsrc"><H3>Getting the Tuscany SCA REST Extension working with the source release on Windows</H3></A> |
| <OL> |
| <LI>Unzip the supplied source zip file</LI> |
| <LI>The following environment variables are required: |
| <UL> |
| <LI>TUSCANY_SCACPP=<path to built Tuscany SCA> |
| <LI>TUSCANY_SDOCPP=<path to installed Tuscany SDO> |
| <LI>HTTPD_HOME=<path to installed HTTPD server> |
| <LI>LIBCURL_HOME=<path to installed libcurl libraries> |
| </UL></LI> |
| <LI>You must have set up the environment for Microsoft Visual C++ tools. The build command |
| will call vcvars32 to set the environment. Ensure the directory containing this is on your path. |
| This will be where you installed the compiler.</LI> |
| <LI>Build the source: |
| <UL> |
| <LI>cd <to where you unzipped the source></LI> |
| <LI>build</LI> |
| </UL> |
| This will build all the projects and put the required output into the 'deploy' directory<BR/><BR/> |
| Alternatively, open the workspace at <tuscany_sca_install_dir>/projects/tuscany_sca/tuscany_sca.dsw |
| in Visual Studio 6 or at at <tuscany_sca_install_dir>/projectsvc7/tuscany_sca/tuscany_sca.sln |
| in Visual Studio 7.1 - you can build projects individually |
| or build the samples to rebuild all the projects</LI> |
| </OL> |
| </DIV> |
| |
| |
| <DIV CLASS="section"> |
| <A NAME="deploy"><H2>Deploying the Tuscany REST Service extension to the HTTPD server</H2></A> |
| <P>The following samples demonstrate use of the REST extension:</P> |
| <UL> |
| <LI><A HREF="../samples/RestCalculator/README.html">RestCalculator</A></LI> |
| <LI><A HREF="../samples/RestCustomer/README.html">RestCustomer</A></LI> |
| <LI><A HREF="../samples/RestYahoo/README.html">RestYahoo</A></LI> |
| <LI><A HREF="../samples/AlertAggregator/README.html">AlertAggregator</A></LI> |
| </UL> |
| <P>Each of these samples generate a set of configuration files for the HTTPD server. Use the startserver |
| script that comes with each sample to generate the files and start the server with the REST Service |
| extension enabled. The instructions below detail the information that is provided in these configuration |
| files.</P> |
| <OL> |
| <LI>On Windows, load the sca_rest_module into HTTPD by adding the following line to the conf/httpd.conf file: |
| <PRE>LoadModule sca_rest_module <path to installed Tuscany SCA>/extensions/rest/service/bin/tuscany_sca_mod_rest.dll</PRE> |
| On Linux, use the following line: |
| <PRE>LoadModule sca_rest_module <path to installed Tuscany SCA>/extensions/rest/service/lib/libtuscany_sca_mod_rest.so</PRE> |
| On Mac OS X, use the following line: |
| <PRE>LoadModule sca_rest_module <path to installed Tuscany SCA>/extensions/rest/service/lib/libtuscany_sca_mod_rest.dylib</PRE> |
| </LI> |
| <LI>Set a TuscanyHome directive to the installation of Tuscany SCA Native: |
| <PRE>TuscanyHome <path to installed Tuscany SCA></PRE> |
| </LI> |
| <LI>Create a Location directive for the URL to be used and set the sca_rest_module as the handler to |
| be invoked when requests for the location are received. Also set the TuscanyRoot directive for |
| this Location, set to the location of the SCA application to be invoked: |
| <PRE> |
| <Location /rest> |
| SetHandler sca_rest_module |
| TuscanyRoot <path to installed Tuscany SCA>/samples/RestCalculator/deploy/ |
| </Location> |
| </PRE> |
| The above example will mean that calls to http://myserver/rest will be handled by Tuscany SCA Native |
| and configured to invoke the RestCalculator sample application. |
| </LI> |
| </OL> |
| </DIV> |
| |
| <DIV CLASS="section"> |
| <A NAME="resource"><H2>Tuscany REST Extension Resource Pattern</H2></A> |
| <P>If the SCA service or reference uses an <interface.rest> interface, CRUD |
| (Create, Retrieve, Update, Delete) methods are mapped to HTTP verbs to access resource |
| representations as follows:</P> |
| <UL> |
| <LI>uri = create(resource)<BR/> |
| HTTP POST <binding-uri> + an XML element representing the resource to create<BR/> |
| Returns Location header containing the uri of the created resource</LI> |
| <LI>resource = retrieve()<BR/> |
| HTTP GET <binding-uri><BR/> |
| Returns an XML element representing the REST resource</LI> |
| <LI>resource = retrieve(uri, parm-value-1, parm-value-n)<BR/> |
| HTTP GET uri/parm-value-1/parm-value-n<BR/> |
| or if uri ends with a '?':<BR/> |
| HTTP GET uri?parm-name-1=parm-value1&parm-name-n=parm-value-n<BR/> |
| Returns an XML element representing the REST resource</LI> |
| <LI>update(resource)<BR/> |
| HTTP PUT <binding-uri> + an XML element representing the updated resource</LI> |
| <LI>update(uri, parm-1, parm-n, resource)<BR/> |
| HTTP PUT uri/parm-value-1/parm-value-n + an XML element representing the updated resource<BR/> |
| or if uri ends with a '?':<BR/> |
| HTTP PUT uri?parm-name-1=parm-value1&parm-name-n=parm-value-n + an XML element representing the updated resource</LI> |
| <LI>delete()<BR/> |
| HTTP DELETE <binding-uri></LI> |
| <LI>delete(uri, parm-1, parm-n)<BR/> |
| HTTP DELETE uri/parm-value-1/parm-value-n<BR/> |
| or if uri ends with a '?':<BR/> |
| HTTP DELETE uri?parm-name-1=parm-value1&parm-name-n=parm-value-n</LI> |
| </UL> |
| <P>In this mode, HTTP return codes are used almost as described in the Atom spec. Also |
| GET returns etags with the retrieved resource representations to help caching by clients.</P> |
| </DIV> |
| |
| <DIV CLASS="section"> |
| <A NAME="rpc"><H2>Tuscany REST Extension RPC Pattern</H2></A> |
| <P>If the SCA service/reference does not use an <interface.rest> interface, then this is |
| not a real REST pattern, we simply flow method calls over XML / HTTP as follows:</P> |
| <UL><LI>result = method-abc(parm-1, parm-n) |
| <UL> |
| <LI>if single input parameter of complex type:<BR/> |
| HTTP POST <binding-uri>/method-abc + XML element representing the complex parameter</LI> |
| <LI>or if multiple parameters including parameters of complex types:<BR/> |
| HTTP POST <binding-uri>/method-abc + Mime multipart/form-data body containing one parameter per part</LI> |
| <LI>or if multiple parameters all of simple types:<BR/> |
| HTTP GET <binding-uri>/method-abc?parm-1-name=parm-1-value&parm-n-name=parm-n-value</LI> |
| </UL> |
| Returns an XML element representing the result</LI> |
| </UL> |
| </DIV> |
| |
| <DIV CLASS="section"> |
| <A NAME="help"><H2>Getting Help</H2></A> |
| |
| <P>First place to look is at the Tuscany FAQ at |
| <A HREF="http://incubator.apache.org/tuscany/faq.html" |
| TARGET="_blank">http://incubator.apache.org/tuscany/faq.html</A> </P> |
| |
| <P>Any problem with this release can be reported to the Tuscany |
| <A HREF="http://incubator.apache.org/tuscany/mail-lists.html" |
| TARGET="_blank">mailing lists</A> or create a JIRA issue at <A HREF="http://issues.apache.org/jira/browse/Tuscany" |
| TARGET="_blank">http://issues.apache.org/jira/browse/Tuscany</A>.</P> |
| </DIV> |
| </DIV> |
| </DIV> |
| </BODY> |
| |
| </HTML> |
| |
