diff options
| author | jsdelfino <jsdelfino@13f79535-47bb-0310-9956-ffa450edef68> | 2009-11-23 05:48:11 +0000 |
|---|---|---|
| committer | jsdelfino <jsdelfino@13f79535-47bb-0310-9956-ffa450edef68> | 2009-11-23 05:48:11 +0000 |
| commit | 1c2df9a2458897ff6c2393913b2723457e42a0da (patch) | |
| tree | 69652a0305830b4472f39c55ad1168522d8301f1 /sca-cpp/trunk/contrib/doc/RubyExtension.html | |
| parent | e5d978186780787e8dad6681cca139486df93643 (diff) | |
Simplified the automake build using configure options instead of environment variables and cleaned up some of the makefile.am files. Adjusted build instructions. Moved directories that don't yet build or work out of the main build dir and obsolete docs to a contrib dir.
git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@883254 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'sca-cpp/trunk/contrib/doc/RubyExtension.html')
| -rw-r--r-- | sca-cpp/trunk/contrib/doc/RubyExtension.html | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/sca-cpp/trunk/contrib/doc/RubyExtension.html b/sca-cpp/trunk/contrib/doc/RubyExtension.html new file mode 100644 index 0000000000..96a4ad2b82 --- /dev/null +++ b/sca-cpp/trunk/contrib/doc/RubyExtension.html @@ -0,0 +1,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> + |