1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
<!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>
|
