diff options
Diffstat (limited to '')
| -rw-r--r-- | sca-cpp/branches/cpp-contrib/contrib/doc/PythonExtension.html | 281 |
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 <tuscany_sca_install_dir>/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=<path to built Tuscany SCA> + <LI>TUSCANY_SDOCPP=<path to installed Tuscany SDO> + <LI>PYTHON_LIB=<path to Python libraries></LI> + <LI>PYTHON_INCLUDE=<path to Python includes></LI> + <LI>PYTHON_VERSION=<name of the Python version><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 <tuscany_sca_install_dir></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 <tuscany_sca_install_dir>\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=<path to built Tuscany SCA> + <LI>TUSCANY_SDOCPP=<path to installed Tuscany SDO> + <LI>PYTHON_HOME=<path to installed Python> + </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 + <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 <tuscany_sca_install_dir>/extensions/python/bin + directory on Windows and <tuscany_sca_install_dir>/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><implementation.python module="PythonModuleName" path="path/to/module"/> +</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><implementation.python module="PythonModuleName" path="path/to/module" class="PythonClassName"/> +</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><component name="CalculatorComponent"> + <implementation.python module="CalculatorImpl"/> + <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.python module="DivideImpl"/> + <property name="doRounding">true</property> +</component> +</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 <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> + |