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
292
|
<!--
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">
<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 - Ruby Extension</TITLE>
</HEAD>
<BODY>
<DIV ID="bodyColumn">
<DIV ID="contentBox">
<DIV CLASS="section">
<H1>Tuscany SCA Native - Ruby Extension</H1>
<P>The Tuscany Ruby extension allows Ruby scripts to be used as components in
SCA composites and as clients that can invoke SCA services.
</P>
<P>The following samples demonstrate use of the Ruby extension:</P>
<UL>
<LI><A HREF="../samples/RubyCalculator/README.html">RubyCalculator</A></LI>
<LI><A HREF="../samples/RubyBigBank/README.html">RubyBigBank</A></LI>
<LI><A HREF="../samples/RestCalculator/README.html">RestCalculator</A></LI>
<LI><A HREF="../samples/RestYahoo/README.html">RestYahoo</A></LI>
<LI><A HREF="../samples/HTTPDBigBank/README.html">HTTPDBigBank</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 Ruby 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="#pm">The Tuscany Ruby Programming Model</A></LI>
<UL>
<LI><A HREF="#clients">Clients</A></LI>
<LI><A HREF="#components">SCA Components</A></LI>
<LI><A HREF="#references">Component references</A></LI>
<LI><A HREF="#properties">Component properties</A></LI>
</UL>
<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 Ruby 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>Ruby version 1.8.x</TD>
<TD>
<A HREF="http://www.ruby-lang.org"
TARGET="_blank">http://www.ruby-lang.org</A><BR/>
Please download and follow the installation instructions. You should
be able to build the Tuscany SCA Ruby Extension with other versions of Ruby.
The extension has been tested with the
<A HREF="http://rubyforge.org/frs/download.php/12751/ruby185-21.exe">Ruby 1.8.5 One-Click Installer</A>
on Windows and the <A HREF="ftp://ftp.ruby-lang.org/pub/ruby/ruby-1.8.5-p12.tar.gz">1.8.5 source code</A>
(compiled locally) on Linux.
</TD>
</TR>
</TBODY>
</TABLE>
</DIV>
<DIV CLASS="section">
<A NAME="install"><H2>Installing the Tuscany SCA Ruby Extension</H2></A>
<A NAME="linuxbin"><H3>Getting the Tuscany SCA Ruby Extension working with the binary release on Linux and Mac OS X</H3></A>
<OL>
<LI>Ensure the Ruby libraries are available on the PATH environment variable</LI>
</OL>
<A NAME="linuxsrc"><H3>Getting the Tuscany SCA Ruby 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>RUBY_LIB=<path to Ruby libraries></LI>
<LI>RUBY_INCLUDE=<path to Ruby includes><BR/>
Note: If you are using a default installation of Ruby these are usually:<BR/>
RUBY_LIB=/usr/lib<BR/>
RUBY_INCLUDE=/usr/lib/ruby/1.8/i386-linux</LI>
</UL></LI>
<LI>Build the Ruby source only with the following command sequence:
<UL>
<LI>cd <tuscany_sca_install_dir></LI>
<LI>./configure --prefix=$TUSCANY_SCACPP --enable-ruby --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 Ruby Extension working with the binary release on Windows</H3></A>
<OL>
<LI>Ensure the Ruby libraries are available on the PATH environment variable</LI>
</OL>
<A NAME="winsrc"><H3>Getting the Tuscany SCA Ruby 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>RUBY_HOME=<path to installed Ruby>
</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="pm"><H2>The Tuscany Ruby Programming Model</H2></A>
<P>This section will explain the Tuscany Ruby programming model to help you to
write your own Ruby components and clients.
</P>
<P>The Tuscany Ruby component and client support comes from a Ruby extension
library that is built in the <tuscany_sca_install_dir>/extensions/ruby/bin
directory on Windows and <tuscany_sca_install_dir>/extensions/ruby/lib on
Linux and Mac OS X.
</P>
<A NAME="clients"><H3>Clients</H3></A>
<P>Using the Ruby SCA extension library, a Ruby client can search for an SCA service with:
</P>
<PRE>require("libtuscany_sca_ruby")
calculator = SCA::locateService("CalculatorComponent/CalculatorService")
</PRE>
<P>This finds the component and service as defined in the composite and componentType
side files and returns a proxy object that can call the SCA service. You can then
simply call a business method on "calculator", like this:
</P>
<PRE>result = calculator.add(12.3, 45.6)</PRE>
</P>
<A NAME="components"><H3>Components</H3></A>
<P>Ruby component implementations are standard Ruby scripts, where class-level
functions or module-level functions can be invoked by the Tuscany runtime. To
use a Ruby component implementation, use the implementation.ruby element in
your .composite file. For example:
</P>
<PRE><implementation.ruby script="CalculatorImpl.rb"/>
</PRE>
<P>To instantiate a class instance and use a class-level function, the Ruby class must
have a default constructor (an initialize() method that takes no arguments) and the
class attribute must be definde in the implementation.ruby element
in your composite, like so:
</P>
<PRE><implementation.ruby script="CalculatorImpl.rb" class="CalculatorImpl"/>
</PRE>
<P>Tuscany currently supports passing simple types (strings, ints, floats, etc) as well
as Service Data Objects into and out of Ruby components. Service Data Objects are represented
in Ruby as REXML Document objects (see the <A HREF="../samples/RubyBigBank/README.html">
Ruby BigBank sample</A> for a demonstration).
</P>
<P>You can write a componentType file for your Ruby component, but you don't have to - the Ruby
extension introspects Ruby component implementation classes for you and binds public
attributes to references and properties.
</P>
<A NAME="references"><H3>References</H3></A>
<P>References can be invoked from Ruby component implementations by the use of public
attributes in the component implementation classes, like this:
</P>
<PRE>class CalculatorImpl
# Define the public attribute that corresponds to the divideService reference
attr_writer :divideService
...
def div(arg1, arg2)
print "Ruby - CalculatorImpl.div\n"
# Invoke the divideService reference
@divideService.divide(arg1.to_f, arg2.to_f)
end
...
end
</PRE>
<P>and in your composite file:
</P>
<PRE><component name="CalculatorComponent">
<implementation.ruby script="CalculatorImpl.rb"/>
<reference name="divideService">DivideComponent/DivideService</reference>
</component>
</PRE>
<A NAME="properties"><H3>Properties</H3></A>
<P>A composite with a property defined for a component like so:
</P>
<PRE><component name="DivideComponent">
<implementation.ruby script="DivideImpl.rb" class="DivideImpl"/>
<property name="round">true</property>
</component>
</PRE>
<P>allows a public attribute of a Ruby component implementation class to be
assigned the property value, so it can be used like so:
</P>
<PRE>class DivideImpl
# Define the public attribute that corresponds to the round property
attr_writer :round
...
def divide(arg1, arg2)
print "Ruby - DivideImpl.divide ", arg1, " / ", arg2, "\n"
res = arg1.to_f / arg2.to_f
# Use the round property
if @round then
res = res.round
print "DivideImpl.divide rounding\n"
end
print "DivideImpl.divide ", res, "\n"
res
end
end
</PRE>
</P>
</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>
|
