summaryrefslogtreecommitdiffstats
path: root/sca-cpp/branches/cpp-contrib/contrib/doc/PythonExtension.html
diff options
context:
space:
mode:
Diffstat (limited to 'sca-cpp/branches/cpp-contrib/contrib/doc/PythonExtension.html')
-rw-r--r--sca-cpp/branches/cpp-contrib/contrib/doc/PythonExtension.html281
1 files changed, 281 insertions, 0 deletions
diff --git a/sca-cpp/branches/cpp-contrib/contrib/doc/PythonExtension.html b/sca-cpp/branches/cpp-contrib/contrib/doc/PythonExtension.html
new file mode 100644
index 0000000000..f51af0d6c9
--- /dev/null
+++ b/sca-cpp/branches/cpp-contrib/contrib/doc/PythonExtension.html
@@ -0,0 +1,281 @@
+<!--
+ 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 - Python Extension</TITLE>
+</HEAD>
+
+<BODY>
+<DIV ID="bodyColumn">
+ <DIV ID="contentBox">
+ <DIV CLASS="section">
+ <H1>Tuscany SCA Native - Python Extension</H1>
+
+ <P>The Tuscany Python extension allows Python 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 Python extension:</P>
+ <UL>
+ <LI><A HREF="../samples/PythonCalculator/README.html">PythonCalculator</A></LI>
+ <LI><A HREF="../samples/PythonWeatherForecast/README.html">PythonWeatherForecast</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 Python 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 Python 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 Python 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>Python version 2.5</TD>
+
+ <TD>
+ <A HREF="http://www.python.org/download/"
+ TARGET="_blank">http://www.python.org/download/</A><BR/>
+ Please download and follow the installation instructions.
+ </TD>
+ </TR>
+ </TBODY>
+ </TABLE>
+ </DIV>
+
+ <DIV CLASS="section">
+ <A NAME="install"><H2>Installing the Tuscany SCA Python Extension</H2></A>
+ <A NAME="linuxbin"><H3>Getting the Tuscany SCA Python Extension working with the binary release on Linux and Mac OS X</H3></A>
+ <OL>
+ <LI>Ensure the Python libraries are available on the PATH environment variable</LI>
+ <LI>Add the &lt;tuscany_sca_install_dir&gt;/extensions/python/lib directory to the PYTHONPATH environment variable</LI>
+ </OL>
+ <A NAME="linuxsrc"><H3>Getting the Tuscany SCA Python 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=&lt;path to built Tuscany SCA&gt;
+ <LI>TUSCANY_SDOCPP=&lt;path to installed Tuscany SDO&gt;
+ <LI>PYTHON_LIB=&lt;path to Python libraries&gt;</LI>
+ <LI>PYTHON_INCLUDE=&lt;path to Python includes&gt;</LI>
+ <LI>PYTHON_VERSION=&lt;name of the Python version&gt;<BR/>
+ Note: If you are using a default installation of Python 2.5 these are usually:<BR/>
+ PYTHON_LIB=/usr/lib<BR/>
+ PYTHON_INCLUDE=/usr/include/python2.5<BR/>
+ PYTHON_VERSION=python2.5<BR/></LI>
+ </UL></LI>
+ <LI>Build the Python source only with the following command sequence:
+ <UL>
+ <LI>cd &lt;tuscany_sca_install_dir&gt;</LI>
+ <LI>./configure --prefix=$TUSCANY_SCACPP --enable-python --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 Python Extension working with the binary release on Windows</H3></A>
+ <OL>
+ <LI>Ensure the Python libraries are available on the PATH environment variable</LI>
+ <LI>Add the &lt;tuscany_sca_install_dir&gt;\extensions\python\bin directory to the PYTHONPATH environment variable</LI>
+ </OL>
+ <A NAME="winsrc"><H3>Getting the Tuscany SCA Python 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=&lt;path to built Tuscany SCA&gt;
+ <LI>TUSCANY_SDOCPP=&lt;path to installed Tuscany SDO&gt;
+ <LI>PYTHON_HOME=&lt;path to installed Python&gt;
+ </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 &lt;to where you unzipped the source&gt;</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 &lt;tuscany_sca_install_dir&gt;/projects/tuscany_sca/tuscany_sca.dsw
+ in Visual Studio 6 or at at &lt;tuscany_sca_install_dir&gt;/projectsvc7/tuscany_sca/tuscany_sca.sln
+ in Visual Studio 7.1 - you can build projects individually
+ <LI>Set the TUSCANY_SCACPP environment variable to point to the 'deploy' directory that was just created</LI>
+ </OL>
+ </DIV>
+
+
+ <DIV CLASS="section">
+ <A NAME="pm"><H2>The Tuscany Python Programming Model</H2></A>
+ <P>This section will explain
+ the Tuscany Python programming model to help you to write your own Python
+ components and clients.
+ </P>
+ <P>The Tuscany Python component and client support comes from a Python extension
+ package that is built in the &lt;tuscany_sca_install_dir&gt;/extensions/python/bin
+ directory on Windows and &lt;tuscany_sca_install_dir&gt;/extensions/python/lib on
+ Linux and Mac OS X. This package must be made available to your Python environment by
+ adding this directory to your PYTHONPATH environment variable. This makes the sca
+ module available for use by clients and allows references and properties to be
+ used in your Python components
+ </P>
+ <A NAME="clients"><H3>Clients</H3></A>
+ <P>Using the sca module, a Python client can search for an SCA service with:
+ </P>
+<PRE>import sca
+
+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>Python component implementations are standard Python scripts, where class-level
+ functions or module-level functions can be invoked by the Tuscany runtime. To
+ use a Python component implementation, use the implementation.python element in
+ your .composite file. For example, the following snippet will use the Python script
+ at path/to/module/PythonModuleName.py, where the path is relative to the location of
+ the composite file:
+ </P>
+<PRE>&lt;implementation.python module="PythonModuleName" path="path/to/module"/&gt;
+</PRE>
+ <P>To instantiate a class instance and use a class-level function, the Python class must
+ have a default constructor (an __init__ method that takes no arguments besides
+ 'self') and the class attribute must be defined in the implementation.python element
+ in your composite, like so:
+ </P>
+<PRE>&lt;implementation.python module="PythonModuleName" path="path/to/module" class="PythonClassName"/&gt;
+</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 Python as xml.etree.ElementTree Element objects (see the <A HREF="../samples/PythonWeatherForecast/README.html">
+ PythonWeatherForecast sample</A> for a demonstration).
+ </P>
+ <P>You can write a componentType file for your Python component, but you don't have to - the Python
+ extension automatically exposes a service and adds references and properties to your Python component
+ implementation classes based on the information in the composite file.
+ </P>
+
+ <A NAME="references"><H3>References</H3></A>
+ <P>References are automatically added to your Python component implementation when
+ the runtime loads the implementation script, so they can be used like so:
+ </P>
+<PRE># The module-level div function
+def div(val1, val2):
+ # Use the divideService reference
+ result = divideService.divide(val1, val2)
+ return result
+</PRE>
+ <P>and in your composite file:
+ </P>
+<PRE>&lt;component name="CalculatorComponent"&gt;
+ &lt;implementation.python module="CalculatorImpl"/&gt;
+ &lt;reference name="divideService"&gt;DivideComponent/DivideService&lt;/reference&gt;
+&lt;/component&gt;
+</PRE>
+ <A NAME="properties"><H3>Properties</H3></A>
+ <P>A composite with a property defined for a component like so:
+ </P>
+<PRE>&lt;component name="DivideComponent"&gt;
+ &lt;implementation.python module="DivideImpl"/&gt;
+ &lt;property name="doRounding"&gt;true&lt;/property&gt;
+&lt;/component&gt;
+</PRE>
+ <P>means the property is automatically instantiated and assigned the
+ property value in the Python component implementation, so it can be
+ used like so:
+ </P>
+<PRE>def divide(val1, val2):
+ result = float(val1) / float(val2)
+ print "Python - DivideImpl.divide " + str(val1) + " / " + str(val2) + " = " + str(result)
+
+ # Use the doRounding property
+ if doRounding:
+ result = round(result)
+ print "Python - DivideImpl.divide is rounding the result to " + str(result)
+
+ return result
+</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&nbsp;<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>
+