You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by bu...@apache.org on 2011/08/11 14:38:06 UTC
svn commit: r794203 - in
/websites/staging/lucene/trunk/content/lucene/pylucene/jcc: ./ install.html
readme.html
Author: buildbot
Date: Thu Aug 11 12:38:06 2011
New Revision: 794203
Log:
Staging update by buildbot
Added:
websites/staging/lucene/trunk/content/lucene/pylucene/jcc/
websites/staging/lucene/trunk/content/lucene/pylucene/jcc/install.html
websites/staging/lucene/trunk/content/lucene/pylucene/jcc/readme.html
Added: websites/staging/lucene/trunk/content/lucene/pylucene/jcc/install.html
==============================================================================
--- websites/staging/lucene/trunk/content/lucene/pylucene/jcc/install.html (added)
+++ websites/staging/lucene/trunk/content/lucene/pylucene/jcc/install.html Thu Aug 11 12:38:06 2011
@@ -0,0 +1,381 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+
+
+<head>
+ <!--
+
+
+ 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.
+ -->
+ <link href="../css/pylucene.css" rel="stylesheet" type="text/css">
+ <title>Apache Lucene - </title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
+ <meta name="Distribution" content="Global"/>
+ <meta name="Robots" content="index,follow"/>
+ <meta name="keywords"
+ content="apache, apache lucene, apache solr, solr, lucene
+ search, information retrieval, spell checking, faceting, inverted index, open source"/>
+ <link rel="shortcut icon" type="image/x-icon" href="../images/favicon.ico"/>
+ <script type="text/javascript" src="../scripts/prototype.js"></script>
+ <script type="text/javascript" src="../scripts/effects.js"></script>
+ <script type="text/javascript" src="../scripts/search.js"></script>
+ <script type="text/javascript" src="../scripts/slides.js"></script>
+ <script type="text/javascript" src="../scripts/jquery.js"></script>
+</head>
+
+<body id="home">
+<div id="wrap">
+ <div id="header">
+ <div id="logo">
+
+ <a href="index.html"><img border="0" src="../images/lucene_logo_green_300.png" alt="Lucene Logo"/></a>
+
+ </div>
+ <div id="search">
+ <script type="text/javascript">
+ function getBlank(input, stdValue) {
+ if (input.value == stdValue) {
+ input.value = '';
+ }
+ return true;
+ }
+
+ function selectProvider(form) {
+ provider = form.elements['searchProvider'].value;
+ if (provider == "any") {
+ if (Math.random() > 0.5) {
+ provider = "lucid";
+ } else {
+ provider = "sl";
+ }
+ }
+
+ if (provider == "lucid") {
+ form.action = "http://search.lucidimagination.com/p:lucene";
+ } else if (provider == "sl") {
+ form.action = "http://search-lucene.com/lucene";
+ }
+
+ days = 90; // cookie will be valid for 90 days
+ date = new Date();
+ date.setTime(date.getTime() + (days * 24 * 60 * 60 * 1000));
+ expires = "; expires=" + date.toGMTString();
+ document.cookie = "searchProvider=" + provider + expires + "; path=/";
+ return true;
+ }
+ </script>
+ <form id="quick-search" method="GET" onsubmit="return selectProvider(this)"
+ action="http://search-lucene.com/lucene"
+ name="searchform">
+ <fieldset>
+ <input type="search" name="q" value="Search with Apache Solr..." class="class1 class2 hint" accesskey="q"
+ onfocus="getBlank(this, 'Search with Apache Solr...')">
+ <span style="color:white">@</span>
+ <select name="searchProvider" id="searchProvider">
+ <option value="any">select provider</option>
+ <option value="lucid">Lucid Find</option>
+ <option value="sl">Search-Lucene</option>
+ </select>
+ </fieldset>
+ <script type="text/javascript">
+ if (document.cookie.length > 0) {
+ cStart = document.cookie.indexOf("searchProvider=");
+ if (cStart != -1) {
+ cStart = cStart + "searchProvider=".length;
+ cEnd = document.cookie.indexOf(";", cStart);
+ if (cEnd == -1) {
+ cEnd = document.cookie.length;
+ }
+ provider = unescape(document.cookie.substring(cStart, cEnd));
+ document.forms['searchform'].elements['searchProvider'].value = provider;
+ }
+ }
+ </script>
+ </form>
+</div>
+ <div id="nav">
+
+<ul>
+ <li><a href="index.html">PyLucene</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/PYLUCENE">Bug Tracker</a></li>
+ <li><a href="mailing-lists.html">Discussion</a></li>
+ <li><a class="last" href="../">Lucene</a></li>
+</ul>
+
+ </div>
+
+
+ </div>
+ <div id="content-wrap" class="clearfix">
+ <div id="main">
+ <h1 class="title"></h1>
+
+ <div><h2 id="getting_jccs_source_code">Getting JCC's Source Code</h2>
+<p>JCC's source code is included with PyLucene's. If you've downloaded
+the PyLucene source code already, JCC's is to be found in
+the <code>jcc</code> subdirectory.</p>
+<p>To get the JCC source code only from SVN use:<br/>
+<code>$ svn co
+http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc jcc</code></p>
+<h2 id="building_jcc">Building JCC</h2>
+<p>JCC is a Python extension written in Python and C++. It requires a
+Java Runtime Environment to operate as it uses Java's reflection
+APIs to do its work. It is built and installed
+via <code>distutils</code>
+or <a href="http://pypi.python.org/pypi/setuptools">setuptools</a>.</p>
+<ul>
+<li>Edit <code>setup.py</code> and review that values in
+the <code>INCLUDES</code>, <code>CFLAGS</code>,
+<code>DEBUG_CFLAGS</code>, <code>LFLAGS</code>
+and <code>JAVAC</code> are correct for your system. These values
+are also going to be compiled into JCC's <code>config.py</code>
+file and are going to be used by JCC when
+invoking <code>distutils</code> or <code>setuptools</code> to
+compile extensions it is generating code for.</li>
+<li>At the command line, enter:
+<source>
+$ python setup.py build
+$ sudo python setup.py install
+</source></li>
+</ul>
+<h2 id="requirements">Requirements</h2>
+<p>JCC requires a Java Development Kit to be present. It uses the Java
+Native Invocation Interface and expects <code><jni.h></code>
+and the Java libraries to be present at build and runtime.</p>
+<p>JCC requires a C++ compiler. A recent C++ compiler for your
+platform is expected to work as expected.</p>
+<h2 id="shared_mode_support_for_the_code--sharedcode_flag">Shared Mode: Support for the <code>--shared</code> Flag</h2>
+<p>JCC includes a small runtime that keeps track of the Java VM and of
+Java objects escaping it. Because there can be only one Java VM
+embedded in a given process at a time, the JCC runtime must be
+compiled as a shared library when more than one JCC-built Python
+extension is going to be imported into a given Python process.</p>
+<p>Shared mode depends on <code>setuptools</code>' capability of
+building plain shared libraries (as opposed to shared libraries for
+Python extensions).</p>
+<p>Currently, shared mode is supported with <code>setuptools
+0.6c7</code> and above out of the box on Mac OS X and Windows. On
+Linux, a patch to <code>setuptools</code> needs to be applied
+first. This patch is included in the JCC source distribution in
+the <code>jcc/patches</code> directory, <code>patch.43</code>. This
+patch was submitted to the <code>setuptools</code> project
+via <a href="http://bugs.python.org/setuptools/issue43">issue
+43</a>.</p>
+<p>The <code>shared mode disabled</code> error reported during the
+build of JCC's on Linux contains the exact instructions on how to
+patch the <code>setuptools</code> installation
+with <code>patch.43</code> on your system.</p>
+<p>Shared mode is also required when embedding Python in a Java VM as
+JCC's runtime shared library is used by the JVM to load JCC and
+bootstrap the Python VM via the JNI.</p>
+<p>When shared mode is not enabled, not supported
+or <code>distutils</code> is used instead
+of <code>setuptools</code>, static mode is used instead. The JCC
+runtime code is statically linked with each JCC-built Python
+extension and only one such extension can be used in a given Python
+process at a time.</p>
+<p>As setuptools grows its shared library building capability it is
+expected that more operating systems should be supported with shared
+mode in the future.</p>
+<p>Shared mode can be forced off by building JCC with
+the <code>NO_SHARED</code> environment variable set.</p>
+<p>There are two defaults to consider here:</p>
+<ul>
+<li>
+<p>Is JCC built with shared mode support or not ?</p>
+</li>
+<li>
+<p>By default, on Mac OS X and Windows this is the case.</p>
+</li>
+<li>
+<p>By default, on Linux, this is the case.
+ if <code>setuptools</code> is patched.</p>
+</li>
+<li>
+<p>On other operating systems shared mode support is off by
+ default - not supported - because shared mode depends on
+ <code>setuptools</code>'s capability of building a regular
+ shared library which is still an experimental feature.</p>
+</li>
+<li>
+<p>Is a JCC-built Python extension built with shared mode ?<br/>
+ By default, no, shared mode is enabled only with
+ the <code>--shared</code> command line argument.</p>
+</li>
+</ul>
+<h2 id="notes_for_mac_os_x">Notes for Mac OS X</h2>
+<p>On Mac OS X, Java is installed by Apple's setup as a framework. The
+values in <code>setup.py</code> for <code>INCLUDES</code>
+and <code>LFLAGS</code> for <code>darwin</code> should be correct
+and ready to use.</p>
+<p>However, if you intend to use the 'system' Python from a Java VM
+ on Mac OS X -- Python embedded in Java --
+ you will need to add the flags <code>"-framework", "Python"</code>
+ to the <code>LFLAGS</code> value.</p>
+<h2 id="notes_for_linux">Notes for Linux</h2>
+<p>JCC has been built and tested on a variety of Linux distributions,
+32- and 64-bit. Getting the java configuration correct is important
+and is done differently for every distribution.<br/>
+For example:</p>
+<ul>
+<li>
+<p>On Ubuntu, to install Java 5, these commands may be used:
+<source>
+ $ sudo apt-get install sun-java5-jdk
+ $ sudo update-java-alternatives -s java-1.5.0-sun
+</source>
+The samples flags for Linux in JCC's setup.py should be close to
+correct.</p>
+</li>
+<li>
+<p>On Gentoo, the <code>java-config</code> utility should be used to
+locate, and possibly change, the default java installation.
+The sample flags for Linux in JCC's <code>setup.py</code> should
+be changed to reflect the root of the Java installation which may
+be obtained via:
+<source>
+ $ java-config -O
+</source></p>
+</li>
+</ul>
+<p>See earlier section about <a href="#shared">Shared Mode</a> for
+Linux support.</p>
+<h2 id="notes_for_solaris">Notes for Solaris</h2>
+<p>At this time, JCC has been built and tested only on Solaris 11 with Sun
+Studio C++ 12, Java 1.6 and Python 2.4.</p>
+<p>Because JCC is written in C++, Python's <code>distutils</code> must
+be nudged a bit to invoke the correct compiler. Sun Studio's C
+compiler is called <code>cc</code> while its C++ compiler is
+called <code>CC</code>. To build JCC, use the following shell
+command to ensure that the C++ compiler is used:</p>
+<p><source>
+$ CC=CC python setup.py build
+</source></p>
+<p>Shared mode is not currently implemented for
+Solaris, <code>setuptools</code> needs to be taught how to build
+plain shared libraries on Solaris first.</p>
+<h2 id="notes_for_windows">Notes for Windows</h2>
+<p>At this time, JCC has been built and tested on Win2k and WinXP with
+a variety of Python and Java versions.</p>
+<ul>
+<li>
+<p>Adding the Python directory to <code>PATH</code> is recommended.</p>
+</li>
+<li>
+<p>Adding the Java directories containing the necessary DLLs and to
+<code>PATH</code> is a must.</p>
+</li>
+<li>
+<p>Adding the directory containing <code>javac.exe</code>
+to <code>PATH</code> is required for shared mode (enabled by
+default if <code>setuptools >= 0.6c7</code> is found to be
+installed).</p>
+</li>
+</ul>
+<h2 id="notes_for_python_23">Notes for Python 2.3</h2>
+<p>To use JCC with Python 2.3, setuptools is required</p>
+<ul>
+<li>
+<p>download <a href="http://pypi.python.org/pypi/setuptools">setuptools</a>.</p>
+</li>
+<li>
+<p>edit the downloaded <code>setuptools</code> egg file to use
+python2.3 instead of python2.4.</p>
+</li>
+<li>
+<p>At the command line, run:<br/>
+<code>$ sudo sh setuptools-0.6c7-py2.4.egg</code></p>
+</li>
+</ul></div>
+
+ <div><h1 id="news">News</h1>
+<h1 id="23_jul_2011_-_pylucene_33-3_available">23 Jul 2011 - PyLucene 3.3-3 available</h1>
+<p>This release tracks Lucene Core's recent 3.3 <a href="http://lucene.apache.org/#1+July+2011+-+Lucene+Core+3.3+and+Solr+3.3+Available">release</a>.</p>
+<p>See <a href="http://svn.apache.org/repos/asf/lucene/pylucene/tags/pylucene_3_3/CHANGES">PyLucene 3.3 CHANGES</a> and <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc/CHANGES">JCC 2.10 CHANGES</a> for details.<br/></p>
+<p>Source distributions are available <a href="http://www.apache.org/dyn/closer.cgi/lucene/pylucene/">here</a>.</p>
+<h1 id="09_jun_2011_-_pylucene_320-1_available">09 Jun 2011 - PyLucene 3.2.0-1 available</h1>
+<p>This release tracks Lucene Core's recent 3.2 <a href="http://lucene.apache.org/java/docs/index.html#4+June+2011+-+Lucene+Core+3.2">release</a>.</p>
+<p>See <a href="http://svn.apache.org/repos/asf/lucene/pylucene/tags/pylucene_3_2_0/CHANGES">PyLucene 3.2.0 CHANGES</a> and <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc/CHANGES">JCC 2.9 CHANGES</a> for details.<br/></p>
+<p>Source distributions are available <a href="http://www.apache.org/dyn/closer.cgi/lucene/pylucene/">here</a>.</p>
+<h1 id="04_apr_2011_-_pylucene_310-1_available">04 Apr 2011 - PyLucene 3.1.0-1 available</h1>
+<p>This release tracks Lucene Core's recent 3.1 <a href="http://lucene.apache.org/java/docs/index.html#31+March+2011+-+Lucene+Core+3.1">release</a>.</p>
+<p>See <a href="http://svn.apache.org/repos/asf/lucene/pylucene/tags/pylucene_3_1_0/CHANGES">PyLucene 3.1.0 CHANGES</a> and <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc/CHANGES">JCC 2.8 CHANGES</a> for details.<br/></p>
+<p>Source distributions are available <a href="http://www.apache.org/dyn/closer.cgi/lucene/pylucene/">here</a>.</p></div>
+
+
+ <div><h2 id="the_apache_software_foundation">The Apache Software Foundation</h2>
+<p>The <a href="http://www.apache.org">Apache Software Foundation</a> provides support for the Apache community of open-source software projects. The Apache projects are defined by collaborative consensus based processes, an open, pragmatic software license and a desire to create high quality software that leads the way in its field. Apache Lucene, Apache Solr, Apache PyLucene, Apache Open Relevance Project and their respective logos are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p></div>
+
+ </div>
+
+ <div id="sidebar">
+ <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="features.html">Features</a></li>
+<li><a href="install.html">Install</a></li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+</ul>
+<h1 id="related_projects">Related Projects</h1>
+<ul>
+<li><a href="http://hadoop.apache.org">Apache Hadoop</a></li>
+<li><a href="http://incubator.apache.org/connectors/">Apache ManifoldCF</a></li>
+<li><a href="http://incubator.apache.org/lucene.net/">Apache Lucene.Net</a></li>
+<li><a href="http://incubator.apache.org/lucy/">Apache Lucy</a></li>
+<li><a href="http://mahout.apache.org">Apache Mahout</a></li>
+<li><a href="http://nutch.apache.org">Apache Nutch</a></li>
+<li><a href="http://incubator.apache.org/opennlp">Apache OpenNLP</a></li>
+<li><a href="http://tika.apache.org">Apache Tika</a></li>
+<li><a href="http://zookeeper.apache.org">Apache Zookeeper</a></li>
+</ul>
+ </div>
+
+ </div>
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. <a href="../privacy.html">Privacy Policy</a>
+ <br/>
+ Apache and the Apache feather logo are trademarks of The Apache Software Foundation. Apache Lucene, Apache Solr and their
+ respective logos are trademarks of the Apache Software Foundation. Please see the <a href="http://www.apache.org/foundation/marks/">Apache Trademark Policy</a>
+ for more information.
+ </p>
+ </div>
+</div>
+</div>
+<script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-94576-12']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+
+</script>
+</body>
+</html>
Added: websites/staging/lucene/trunk/content/lucene/pylucene/jcc/readme.html
==============================================================================
--- websites/staging/lucene/trunk/content/lucene/pylucene/jcc/readme.html (added)
+++ websites/staging/lucene/trunk/content/lucene/pylucene/jcc/readme.html Thu Aug 11 12:38:06 2011
@@ -0,0 +1,1014 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+
+
+<head>
+ <!--
+
+
+ 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.
+ -->
+ <link href="../css/pylucene.css" rel="stylesheet" type="text/css">
+ <title>Apache Lucene - </title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
+ <meta name="Distribution" content="Global"/>
+ <meta name="Robots" content="index,follow"/>
+ <meta name="keywords"
+ content="apache, apache lucene, apache solr, solr, lucene
+ search, information retrieval, spell checking, faceting, inverted index, open source"/>
+ <link rel="shortcut icon" type="image/x-icon" href="../images/favicon.ico"/>
+ <script type="text/javascript" src="../scripts/prototype.js"></script>
+ <script type="text/javascript" src="../scripts/effects.js"></script>
+ <script type="text/javascript" src="../scripts/search.js"></script>
+ <script type="text/javascript" src="../scripts/slides.js"></script>
+ <script type="text/javascript" src="../scripts/jquery.js"></script>
+</head>
+
+<body id="home">
+<div id="wrap">
+ <div id="header">
+ <div id="logo">
+
+ <a href="index.html"><img border="0" src="../images/lucene_logo_green_300.png" alt="Lucene Logo"/></a>
+
+ </div>
+ <div id="search">
+ <script type="text/javascript">
+ function getBlank(input, stdValue) {
+ if (input.value == stdValue) {
+ input.value = '';
+ }
+ return true;
+ }
+
+ function selectProvider(form) {
+ provider = form.elements['searchProvider'].value;
+ if (provider == "any") {
+ if (Math.random() > 0.5) {
+ provider = "lucid";
+ } else {
+ provider = "sl";
+ }
+ }
+
+ if (provider == "lucid") {
+ form.action = "http://search.lucidimagination.com/p:lucene";
+ } else if (provider == "sl") {
+ form.action = "http://search-lucene.com/lucene";
+ }
+
+ days = 90; // cookie will be valid for 90 days
+ date = new Date();
+ date.setTime(date.getTime() + (days * 24 * 60 * 60 * 1000));
+ expires = "; expires=" + date.toGMTString();
+ document.cookie = "searchProvider=" + provider + expires + "; path=/";
+ return true;
+ }
+ </script>
+ <form id="quick-search" method="GET" onsubmit="return selectProvider(this)"
+ action="http://search-lucene.com/lucene"
+ name="searchform">
+ <fieldset>
+ <input type="search" name="q" value="Search with Apache Solr..." class="class1 class2 hint" accesskey="q"
+ onfocus="getBlank(this, 'Search with Apache Solr...')">
+ <span style="color:white">@</span>
+ <select name="searchProvider" id="searchProvider">
+ <option value="any">select provider</option>
+ <option value="lucid">Lucid Find</option>
+ <option value="sl">Search-Lucene</option>
+ </select>
+ </fieldset>
+ <script type="text/javascript">
+ if (document.cookie.length > 0) {
+ cStart = document.cookie.indexOf("searchProvider=");
+ if (cStart != -1) {
+ cStart = cStart + "searchProvider=".length;
+ cEnd = document.cookie.indexOf(";", cStart);
+ if (cEnd == -1) {
+ cEnd = document.cookie.length;
+ }
+ provider = unescape(document.cookie.substring(cStart, cEnd));
+ document.forms['searchform'].elements['searchProvider'].value = provider;
+ }
+ }
+ </script>
+ </form>
+</div>
+ <div id="nav">
+
+<ul>
+ <li><a href="index.html">PyLucene</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/PYLUCENE">Bug Tracker</a></li>
+ <li><a href="mailing-lists.html">Discussion</a></li>
+ <li><a class="last" href="../">Lucene</a></li>
+</ul>
+
+ </div>
+
+
+ </div>
+ <div id="content-wrap" class="clearfix">
+ <div id="main">
+ <h1 class="title"></h1>
+
+ <div><h2 id="warning">Warning</h2>
+<p><em>Before calling any PyLucene API that requires the Java VM, start it by
+calling <code>initVM(classpath, ...)</code>. More about this function
+in <a href="#api">here</a>.</em></p>
+<h2 id="installing_jcc">Installing JCC</h2>
+<p>JCC is a Python extension written in Python and C++. It requires a
+Java Runtime Environment (JRE) to operate as it uses Java's
+reflection APIs to do its work. It is built and installed
+via <code>distutils</code> or <code>setuptools</code>.</p>
+<p>See <a href="site:jcc/documentation/install">installation</a> for more
+information and operating system specific notes.</p>
+<h2 id="invoking_jcc">Invoking JCC</h2>
+<p>JCC is installed as a package and how to invoke it depends on the
+Python version used:</p>
+<ul>
+<li>python 2.7: <code>python -m jcc</code></li>
+<li>python 2.6: <code>python -m jcc.<strong>main</strong></code></li>
+<li>python 2.5: <code>python -m jcc</code></li>
+<li>
+<p>python 2.4:</p>
+</li>
+<li>
+<p>no setuptools: <code>python </code><em><code>site-packages</code></em><code>/jcc/<strong>init</strong>.py</code></p>
+</li>
+<li>
+<p>with setuptools: <code>python </code><em><code>site-packages</code></em>/<em><code>jcc egg directory</code></em><code>/jcc/<strong>init</strong>.py</code></p>
+</li>
+<li>
+<p>python 2.3: <code>python </code><em><code>site-packages</code></em>/<em><code>jcc egg directory</code></em><code>/jcc/<strong>init</strong>.py</code></p>
+</li>
+</ul>
+<h2 id="generating_c_and_python_wrappers_with_jcc">Generating C++ and Python wrappers with JCC</h2>
+<p>JCC started as a C++ code generator for hiding the gory details of
+accessing methods and fields on Java classes via
+Java's <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/invocation.html">Native Invocation Interface</a>.
+These C++ wrappers make it possible to access a Java object as if it
+was a regular C++ object very much like GCJ's
+<a href="http://gcc.gnu.org/onlinedocs/gcj/About-CNI.html">CNI
+interface</a>.</p>
+<p>It then became apparent that JCC could also generate the C++
+wrappers for making these classes available to Python. Every class
+that gets thus wrapped becomes a
+<a href="http://docs.python.org/ext/defining-new-types.html">CPython
+type</a>.</p>
+<p>JCC generates wrappers for all public classes that are requested by
+name on the command line or via the <code>--jar</code> command line
+argument. It generates wrapper methods for all public methods and
+fields on these classes whose return type and parameter types are
+found in one of the following ways:</p>
+<ul>
+<li>
+<p>the type is one of the requested classes</p>
+</li>
+<li>
+<p>the type is one of the requested classes' superclass or implemented
+interfaces </p>
+</li>
+<li>
+<p>the type is available from one of the packages listed via the
+<code>--package</code> command line argument</p>
+</li>
+</ul>
+<p>Overloaded methods are supported and are selected at runtime on the
+basis of the type and number of arguments passed in.</p>
+<p>JCC does not generate wrappers for methods or fields which don't
+satisfy these requirements. Thus, JCC can avoid generating code for
+runaway transitive closures of type dependencies.</p>
+<p>JCC generates property accessors for a property
+called <em><code>field</code></em> when it finds Java methods
+named <code>set</code><em><code>Field</code></em><code>(value)</code>,
+<code>get</code><em><code>Field</code></em><code>()</code> or
+<code>is</code><em><code>Field</code></em><code>()</code>.</p>
+<p>The C++ wrappers are declared in a C++ namespace structure that
+mirrors the Java classes' Java packages. The Python types are
+declared in a flat namespace at the top level of the resulting
+Python extension module.</p>
+<p>JCC's command-line arguments are best illustrated via the PyLucene
+example:</p>
+<p><source>
+$ python -m jcc # run JCC to wrap
+--jar lucene.jar # all public classes in the lucene jar file
+--jar analyzers.jar # and the lucene analyzers contrib package
+--jar snowball.jar # and the snowball contrib package
+--jar highlighter.jar # and the highlighter contrib package
+--jar regex.jar # and the regex search contrib package
+--jar queries.jar # and the queries contrib package
+--jar extensions.jar # and the Python extensions package
+--package java.lang # including all dependencies found in the
+ # java.lang package
+--package java.util # and the java.util package
+--package java.io # and the java.io package
+java.lang.System # and to explicitely wrap java.lang.System
+java.lang.Runtime # as well as java.lang.Runtime
+java.lang.Boolean # and java.lang.Boolean
+java.lang.Byte # and java.lang.Byte
+java.lang.Character # and java.lang.Character
+java.lang.Integer # and java.lang.Integer
+java.lang.Short # and java.lang.Short
+java.lang.Long # and java.lang.Long
+java.lang.Double # and java.lang.Double
+java.lang.Float # and java.lang.Float
+java.text.SimpleDateFormat
+ # and java.text.SimpleDateFormat
+java.io.StringReader
+ # and java.io.StringReader
+java.io.InputStreamReader
+ # and java.io.InputStreamReader
+java.io.FileInputStream
+ # and java.io.FileInputStream
+java.util.Arrays # and java.util.Arrays
+--exclude org.apache.lucene.queryParser.Token
+ # while explicitely not wrapping
+ # org.apache.lucene.queryParser.Token
+--exclude org.apache.lucene.queryParser.TokenMgrError
+ # nor org.apache.lucene.queryParser.TokenMgrError
+--exclude org.apache.lucene.queryParser.ParseException
+ # nor.apache.lucene.queryParser.ParseException
+--python lucene # generating Python wrappers into a module
+ # called lucene
+--version 2.4.0 # giving the Python extension egg version 2.4.0
+--mapping org.apache.lucene.document.Document
+ 'get:(Ljava/lang/String;)Ljava/lang/String;'
+ # asking for a Python mapping protocol wrapper
+ # for get access on the Document class by
+ # calling its get method
+--mapping java.util.Properties
+ 'getProperty:(Ljava/lang/String;)Ljava/lang/String;'
+ # asking for a Python mapping protocol wrapper
+ # for get access on the Properties class by
+ # calling its getProperty method
+--sequence org.apache.lucene.search.Hits
+ 'length:()I'
+ 'doc:(I)Lorg/apache/lucene/document/Document;'
+ # asking for a Python sequence protocol wrapper
+ # for length and get access on the Hits class by
+ # calling its length and doc methods
+--files 2 # generating all C++ classes into about 2 .cpp
+ # files
+--build # and finally compiling the generated C++ code
+ # into a Python egg via setuptools - when
+ # installed - or a regular Python extension via
+ # distutils or setuptools otherwise
+--module collections.py
+ # copying the collections.py module into the egg
+--install # installing it into Python's site-packages
+ # directory.
+</source></p>
+<p>There are limits to both how many files can fit on the command line
+and how large a C++ file the C++ compiler can handle. By default,
+JCC generates one large C++ file containing the source code for all
+wrapper classes.</p>
+<p>Using the <code>--files</code> command line argument, this behaviour
+can be tuned to workaround various limits:<br/>
+for example:</p>
+<ul>
+<li>
+<p>to break up the large wrapper class file into about 2 files:<br/>
+<code>--files 2</code></p>
+</li>
+<li>
+<p>to break up the large wrapper class file into about 10 files:<br/>
+<code> --files 10</code></p>
+</li>
+<li>
+<p>to generate one C++ file per Java class wrapped:<br/>
+<code>--files separate</code></p>
+</li>
+</ul>
+<p>The <code>--prefix</code> and <code>--root</code> arguments are
+passed through to <code>distutils</code>' <code>setup()</code>.</p>
+<h2 id="classpath_considerations">Classpath considerations</h2>
+<p>When generating wrappers for Python, the JAR files passed to JCC
+via <code>--jar</code> are copied into the resulting Python extension
+egg as resources and added to the extension
+module's <code>CLASSPATH</code> variable. Classes or JAR files that
+are required by the classes contained in the argument JAR files need
+to be made findable via JCC's <code>--classpath</code> command line
+argument. At runtime, these need to be appended to the
+extension's <code>CLASSPATH</code> variable before starting the VM
+with <code>initVM(CLASSPATH)</code>.</p>
+<p>To have such required jar files also automatically copied into
+resulting Python extension egg and added to the classpath at build
+and runtime, use the <code>--include</code> option. This option
+works like the <code>--jar</code> option except that no wrappers are
+generated for the classes contained in them unless they're
+explicitely named on the command line. </p>
+<p>When more than one JCC-built extension module is going to be used in
+the same Python VM and these extension modules share Java classes,
+only one extension module should be generated with wrappers for these
+shared classes. The other extension modules must be built by importing
+the one with the shared classes by using the <code>--import</code>
+command line parameter. This ensures that only one copy of the
+wrappers for the shared classes are generated and that they are
+compatible among all extension modules sharing them.</p>
+<h2 id="using_codedistutilscode_vs_codesetuptoolscode">Using <code>distutils</code> vs <code>setuptools</code></h2>
+<p>By default, when building a Python extension,
+if <code>setuptools</code> is found to be installed, it is used
+over <code>distutils</code>. If you want to force the use
+of <code>distutils</code> over <code>setuptools</code>, use
+the <code>--use-distutils</code> command line argument.</p>
+<h2 id="distributing_an_egg">Distributing an egg</h2>
+<p>The <code>--bdist</code> option can be used to ask JCC to
+invoke <code>distutils</code> with <code>bdist</code>
+or <code>setuptools</code>
+with <code>bdist_egg</code>. If <code>setuptools</code> is used,
+the resulting egg has to be installed with the
+<a href="http://peak.telecommunity.com/DevCenter/EasyInstall"><code>easy_install</code></a>
+installer which is normally part of a Python installation that
+includes <code>setuptools</code>.</p>
+<h2 id="jccs_runtime_api_functions">JCC's runtime API functions</h2>
+<p>JCC includes a small runtime component that is compiled into any
+Python extension it produces.</p>
+<p>This runtime component makes it possible to manage the Java VM from
+Python. Because a Java VM can be configured with a myriad of
+options, it is not automatically started when the resulting Python
+extension module is loaded into the Python interpreter.</p>
+<p>Instead, the <code>initVM()</code> function must be called from the
+main thread before using any of the wrapped classes. It takes the
+following keyword arguments:</p>
+<ul>
+<li><code>classpath</code><br/>
+A string containing one or more directories or jar files for the
+Java VM to search for classes. Every Python extension produced by
+JCC exports a <code>CLASSPATH</code> variable that is hardcoded to
+the jar files that it was produced from. A copy of each jar file
+is installed as a resource file with the extension when JCC is
+invoked with the <code>--install</code> command line argument.
+This parameter is optional and defaults to the
+<code>CLASSPATH</code> string exported by the module
+<code>initVM</code> is imported from.
+<source><blockquote>
+<blockquote>
+<blockquote>import lucene
+lucene.initVM(classpath=lucene.CLASSPATH)
+</source></blockquote>
+</blockquote>
+</blockquote>
+</li>
+<li>
+<p><code>initialheap</code><br/>
+The initial amount of Java heap to start the Java VM with. This
+argument is a string that follows the same syntax as the
+similar <code>-Xms</code> java command line argument.
+<source></p>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>import lucene
+lucene.initVM(initialheap='32m')
+lucene.Runtime.getRuntime().totalMemory()
+ 33357824L
+</source></p>
+</blockquote>
+</blockquote>
+</blockquote>
+</li>
+<li>
+<p><code>maxheap</code><br/>
+The maximum amount of Java heap that could become available to the
+Java VM. This argument is a string that follows the same syntax as
+the similar <code>-Xmx</code> java command line argument.</p>
+</li>
+<li>
+<p><code>maxstack</code><br/>
+The maximum amount of stack space that available to the Java
+VM. This argument is a string that follows the same syntax as the
+similar <code>-Xss</code> java command line argument.</p>
+</li>
+<li>
+<p><code>vmargs</code><br/>
+A string of comma separated additional options to pass to the VM
+startup rountine. These are passed through as-is. For example:
+<source></p>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>import lucene
+lucene.initVM(vmargs='-Xcheck:jni,-verbose:jni,-verbose:gc')
+</source></p>
+</blockquote>
+</blockquote>
+</blockquote>
+</li>
+</ul>
+<p>The <code>initVM()</code> and <code>getVMEnv()</code> functions
+return a JCCEnv object that has a few utility methods on it:</p>
+<ul>
+<li>
+<p><code>attachCurrentThread(name, asDaemon)</code><br/>
+Before a thread created in Python or elsewhere but not in the Java
+VM can be used with the Java VM, this method needs to be
+invoked. The two arguments it takes are optional and
+self-explanatory.</p>
+</li>
+<li>
+<p><code>detachCurrentThread()</code>
+The opposite of <code>attachCurrentThread()</code>. This method
+should be used with extreme caution as Python's and java VM's
+garbage collectors may use a thread detached too early causing a
+system crash. The utility of this method seems dubious at the
+moment.</p>
+</li>
+</ul>
+<p>There are several differences between JNI's <code>findClass()</code>
+and Java's <code>Class.forName()</code>:</p>
+<ul>
+<li>
+<p>className is a '/' separated string of names</p>
+</li>
+<li>
+<p>the class loaders are different, <code>findClass()</code> may find
+classes that <code>Class.forName()</code> won't.</p>
+</li>
+</ul>
+<p>For example:</p>
+<source>
+
+<blockquote>
+<blockquote>
+<blockquote>
+<p>from lucene import *
+initVM(CLASSPATH)
+findClass('org/apache/lucene/document/Document')
+<Class: class org.apache.lucene.document.Document>
+Class.forName('org.apache.lucene.document.Document')
+Traceback (most recent call last):
+File "<stdin>", line 1, in <module>
+lucene.JavaError: java.lang.ClassNotFoundException:
+ org/apache/lucene/document/Document
+Class.forName('java.lang.Object')
+<Class: class java.lang.Object>
+</source></p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h2 id="type_casting_and_instance_checks">Type casting and instance checks</h2>
+<p>Many Java APIs are declared to return types that are less specific
+than the types actually returned. In Java 1.5, this is worked around
+with type parameters. JCC generates code to heed type parameters
+unless the <code>--no-generics</code> is used. See next section for
+details on Java generics support.</p>
+<p>In C++, casting the object into its actual type is supported via the
+regular C casting operator.</p>
+<p>In Python each wrapped class has a class method
+called <code>cast_</code> that implements the same functionality.</p>
+<p>Similarly, each wrapped class has a class method
+called <code>instance_</code> that tests whether the wrapped java
+instance is of the given type. For example:</p>
+<p><source>
+if BooleanQuery.instance_(query):
+ booleanQuery = BooleanQuery.cast_(query)</p>
+<p>print booleanQuery.getClauses()
+</source></p>
+<h2 id="handling_generic_classes">Handling generic classes</h2>
+<p>Java 1.5 added support for parameterized types. JCC generates code
+to heed type parameters unless the <code>--no-generics</code>
+command line parameter is used. Java type parameterization is a
+runtime feature. The same class is used for all its
+parameterizations. Similarly, JCC wrapper objects all use the same
+class but store type parameterizations on instances and make them
+accessible as a tuple via the <code>parameters_</code> property.</p>
+<p>For example, an <code>ArrayList<Document></code> instance,
+has <code>(<type 'Document'>,)</code>
+for <code>parameters_</code> and its <code>get()</code> method uses
+that type parameter to wrap its return values.</p>
+<p>To allocate an instance of a generic Java class with specific type
+parameters use the <code>of_()</code> method. This method accepts
+one or more Python wrapper classes to use as type parameters. For
+example, <code>java.util.ArrayList<E></code> is declared to
+accept one type parameter. Its wrapper's <code>of_()</code> method
+hence accepts one parameter, a Python class, to use as type
+parameter for the return type of its <code>get()</code> method, among
+others: </p>
+<source>
+
+<blockquote>
+<blockquote>
+<blockquote>
+<p>a = ArrayList().of_(Document)
+a
+<ArrayList: []>
+a.parameters_
+(<type 'Document'>,)
+a.add(Document())
+True
+a.get(0)
+<Document: Document<>>
+</source></p>
+</blockquote>
+</blockquote>
+</blockquote>
+<p>The use of type parameters is, of course, optional. A generic Java
+class can still be used as before, without type parameters.
+Downcasting from <code>Object</code> is then necessary:<br />
+</p>
+<source>
+
+<blockquote>
+<blockquote>
+<blockquote>
+<p>a = ArrayList()
+a
+<ArrayList: []>
+a.parameters_
+(None,)
+a.add(Document())
+True
+a.get(0)
+<Object: Document<>>
+Document.cast_(a.get(0))
+<Document: Document<>>
+</source></p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h2 id="handling_arrays">Handling arrays</h2>
+<p>Java arrays are wrapped with a C++ JArray
+template. The <code>[]</code> is available for read
+access. This template, <code>JArray<T></code>, accomodates all
+java primitive types, <code>jstring</code>, <code>jobject</code> and
+wrapper class arrays.</p>
+<p>Java arrays are returned to Python in a <code>JArray</code> wrapper
+instance that implements the Python sequence protocol. It is
+possible to change an array's elements but not to change an array's
+size.</p>
+<p>To convert a char array to a Python string use
+a <code>''.join(array)</code> construct.</p>
+<p>Any Java method expecting an array can be called with the corresponding
+sequence object from python.</p>
+<p>To instantiate a Java array from Python, use one of the following
+forms:</p>
+<source>
+
+<blockquote>
+<blockquote>
+<blockquote>
+<p>array = JArray('int')(size)</p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h1 id="the_resulting_java_int_array_is_initialized_with_zeroes">the resulting Java int array is initialized with zeroes</h1>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>array = JArray('int')(sequence)</p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h1 id="the_sequence_must_only_contain_ints">the sequence must only contain ints</h1>
+<h1 id="the_resulting_java_int_array_contains_the_ints_in_the_sequence">the resulting Java int array contains the ints in the sequence</h1>
+</source>
+
+<p>Instead of <code>'int'</code>, you may also use one
+of <code>'object'</code>, <code>'string'</code>, <code>'bool'</code>,
+<code>'byte'</code>, <code>'char'</code>, <code>'double'</code>,
+<code>'float'</code>, <code>'long'</code> and <code>'short'</code>
+to create an array of the corresponding type.</p>
+<p>Because there is only one wrapper class for object arrays,
+the <code>JArray('object')</code> type's constructor takes a second
+argument denoting the class of the object elements. This argument is
+optional and defaults to <code>Object</code>.</p>
+<p>As with the <code>Object</code> types, the <code>JArray</code> types
+also include a <code>cast_</code> method. This method becomes useful
+when the array returned to Python is wrapped as a
+plain <code>Object</code>. This is the case, for example, with
+nested arrays since there is no distinct Python type for every
+different java object array class - all java object arrays are
+wrapped by <code>JArray('object')</code>. For example:</p>
+<source>
+
+<h1 id="cast_obj_to_an_array_of_ints">cast obj to an array of ints</h1>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>JArray('int').cast_(obj)</p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h1 id="cast_obj_to_an_array_of_document">cast obj to an array of Document</h1>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>JArray('object').cast_(obj, Document)
+</source></p>
+</blockquote>
+</blockquote>
+</blockquote>
+<p>In both cases, the java type of obj must be compatible with the
+array type it is being cast to.</p>
+<source>
+
+<h1 id="using_nested_array">using nested array:</h1>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>d = JArray('object')(1, Document)
+d[0] = Document()
+d
+JArray<object>[<Document: Document<>>]
+d[0]
+<Document: Document<>>
+a = JArray('object')(2)
+a[0] = d
+a[1] = JArray('int')([0, 1, 2])
+a
+JArray<object>[<Object: [Lorg.apache.lucene.document.Document;@694f12>, <Object: [I@234265>]
+a[0]
+<Object: [Lorg.apache.lucene.document.Document;@694f12>
+a[1]
+<Object: [I@234265>
+JArray('object').cast_(a[0])[0]
+<Object: Document<>>
+JArray('object').cast_(a[0], Document)[0]
+<Document: Document<>>
+JArray('int').cast_(a[1])
+JArray<int>[0, 1, 2]
+JArray('int').cast_(a[1])[0]
+0
+</source></p>
+</blockquote>
+</blockquote>
+</blockquote>
+<p>To verify that a Java object is of a given array type, use
+the <code>instance_()</code> method available on the array
+type. This is not the same as verifying that it is assignable with
+elements of a given type. For example, using the arrays created
+above:</p>
+<source>
+
+<h1 id="is_d_array_of_object__are_ds_elements_of_type_object_">is d array of Object ? are d's elements of type Object ?</h1>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>JArray('object').instance_(d)
+True</p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h1 id="can_it_receive_object_instances_">can it receive Object instances ?</h1>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>JArray('object').assignable_(d)
+False</p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h1 id="is_it_array_of_document__are_ds_elements_of_type_document_">is it array of Document ? are d's elements of type Document ?</h1>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>JArray('object').instance_(d, Document)
+True</p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h1 id="is_it_array_of_class__are_ds_elements_of_type_class_">is it array of Class ? are d's elements of type Class ?</h1>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>JArray('object').instance_(d, Class)
+False</p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h1 id="can_it_receive_document_instances_">can it receive Document instances ?</h1>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>JArray('object').assignable_(d, Document)
+True
+</source></p>
+</blockquote>
+</blockquote>
+</blockquote>
+<h2 id="exception_reporting">Exception reporting</h2>
+<p>Exceptions that occur in the Java VM and that escape to C++ are
+reported as a <code>javaError</code> C++ exception. When using
+Python wrappers, the C++ exceptions are handled and reported with
+Python exceptions. When using C++ only, failure to handle the
+exception in your C++ code will cause the process to crash.</p>
+<p>Exceptions that occur in the Java VM and that escape to the Python
+VM are reported with a <code>JavaError</code> python exception
+object. The <code>getJavaException()</code> method can be called
+on <code>JavaError</code> objects to obtain the original java
+exception object wrapped as any other Java object. This Java object
+can be used to obtain a Java stack trace for the error, for example.</p>
+<p>Exceptions that occur in the Python VM and that escape to the Java
+VM, as for example can happen in Python extensions (see topic below)
+are reported to the Java VM as a <code>RuntimeException</code> or as
+a <code>PythonException</code> when using shared
+mode. See <a href="site:jcc/documentation/install">installation
+instructions</a> for more information about shared mode.</p>
+<h2 id="writing_java_class_extensions_in_python">Writing Java class extensions in Python</h2>
+<p>JCC makes it relatively easy to extend a Java class from
+Python. This is done via an intermediary class written in Java that
+implements a special method called <code>pythonExtension()</code>
+and that declares a number of native methods that are to be
+implemented by the actual Python extension.</p>
+<p>When JCC sees these special extension java classes it generates the
+C++ code implementing the native methods they declare. These native
+methods call the corresponding Python method implementations passing
+in parameters and returning the result to the Java VM caller.</p>
+<p>For example, to implement a Lucene analyzer in Python, one would
+implement first such an extension class in Java:</p>
+<p><source>
+package org.apache.pylucene.analysis;</p>
+<p>import org.apache.lucene.analysis.Analyzer;
+import org.apache.lucene.analysis.TokenStream;
+import java.io.Reader;</p>
+<p>public class PythonAnalyzer extends Analyzer {
+private long pythonObject;</p>
+<p>public PythonAnalyzer()
+{
+}</p>
+<p>public void pythonExtension(long pythonObject)
+{
+ this.pythonObject = pythonObject;
+}
+public long pythonExtension()
+{
+ return this.pythonObject;
+}</p>
+<p>public void finalize()
+ throws Throwable
+{
+ pythonDecRef();
+}</p>
+<p>public native void pythonDecRef();
+public native TokenStream tokenStream(String fieldName, Reader reader);
+}
+</source></p>
+<p>The <code>pythonExtension()</code> methods is what makes this class
+recognized as an extension class by JCC. They should be included
+verbatim as above along with the declaration of
+the <code>pythonObject</code> instance variable.</p>
+<p>The implementation of the native <code>pythonDecRef()</code> method
+is generated by JCC and is necessary because it seems
+that <code>finalize()</code> cannot itself be native. Since an
+extension class wraps the Python instance object it's going to be
+calling methods on, its ref count needs to be decremented when this
+Java wrapper class disappears. A declaration
+for <code>pythonDecRef()</code> and a <code>finalize()</code>
+implementation should always be included verbatim as above.</p>
+<p>Really, the only non boilerplate user input is the constructor of the
+class and the other native methods, <code>tokenStream()</code> in
+the example above.</p>
+<p>The corresponding Python class(es) are implemented as follows:</p>
+<p><source>
+class <em>analyzer(PythonAnalyzer):
+ def tokenStream(_self, fieldName, reader):
+ class _tokenStream(PythonTokenStream):
+ def <strong>init</strong>(self</em>):
+ super(<em>tokenStream, self</em>).<strong>init</strong>()
+ self_.TOKENS = ["1", "2", "3", "4", "5"]
+ self_.INCREMENTS = [1, 2, 1, 0, 1]
+ self_.i = 0
+ self_.posIncrAtt = self_.addAttribute(PositionIncrementAttribute.class_)
+ self_.termAtt = self_.addAttribute(TermAttribute.class_)
+ self_.offsetAtt = self_.addAttribute(OffsetAttribute.class_)
+ def incrementToken(self_):
+ if self_.i == len(self_.TOKENS):
+ return False
+ self_.termAtt.setTermBuffer(self_.TOKENS[self_.i])
+ self_.offsetAtt.setOffset(self_.i, self_.i)
+ self_.posIncrAtt.setPositionIncrement(self_.INCREMENTS[self_.i])
+ self_.i += 1
+ return True
+ def end(self_):
+ pass
+ def reset(self_):
+ pass
+ def close(self_):
+ pass
+ return _tokenStream()
+</source></p>
+<p>When an <code><strong>init</strong>()</code> is declared, <code>super()</code>
+must be called or else the Java wrapper class will not know about
+the Python instance it needs to invoke.</p>
+<p>When a java extension class declares native methods for which there
+are public or protected equivalents available on the parent class,
+JCC generates code that makes it possible to
+call <code>super()</code> on these methods from Python as well.</p>
+<p>There are a number of extension examples available in PyLucene's test
+<a href="http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/test">suite</a>
+and <a href="site:documentation/readme">samples</a>.</p>
+<h2 id="embedding_a_python_vm_in_a_java_vm">Embedding a Python VM in a Java VM</h2>
+<p>Using the same techniques used when writing a Python extension of a
+Java class, JCC may also be used to embed a Python VM in a Java VM.
+Following are the steps and constraints to follow to achieve this:</p>
+<ul>
+<li>
+<p>JCC must be built in shared mode. See
+<a href="site:jcc/documentation/install">installation
+instructions</a> for more information about shared mode.
+Note that for this use on Mac OS X, JCC must also be built
+with the link flags <code>"-framework", "Python"</code> in
+the <code>LFLAGS</code> value.</p>
+</li>
+<li>
+<p>As described in the previous section, define one or more Java
+classes to be "extended" from Python to provide the
+implementations of the native methods declared on them. Instances
+of these classes implement the bridges into the Python VM from
+Java.</p>
+</li>
+<li>
+<p>The <code>org.apache.jcc.PythonVM</code> Java class is going be
+used from the Java VM's main thread to initialize the embedded
+Python VM. This class is installed inside the JCC egg under the
+<code>jcc/classes</code> directory and the full path to this
+directory must be on the Java <code>CLASSPATH</code>.</p>
+</li>
+<li>
+<p>The JCC egg directory contains the JCC shared runtime library - not
+the JCC Python extension shared library - but a library
+called <code>libjcc.dylib</code> on Mac OS X,
+<code>libjcc.so</code> on Linux or <code>jcc.dll</code> on Windows.
+This directory must be added to the Java VM's shared library path
+via the <code>-Djava.library.path</code> command line parameter.</p>
+</li>
+<li>
+<p>In the Java VM's main thread, initialize the Python VM by
+calling its static <code>start()</code> method passing it a
+Python program name string and optional start-up arguments
+in a string array that will be made accessible in Python via
+<code>sys.argv</code>. Note that the program name string is
+purely informational, and is not used by the
+<code>start()</code> code other than to initialize that
+Python variable. This method returns the singleton PythonVM
+instance to be used in this Java VM. <code>start()</code>
+may be called multiple times; it will always return the same
+singleton instance. This instance may also be retrieved at any
+later time via the static <code>get()</code> method defined
+on the <code>org.apache.jcc.PythonVM</code> class.</p>
+</li>
+<li>
+<p>Any Java VM thread that is going to be calling into the Python VM
+should start with acquiring a reference to the Python thread state
+object by calling <code>acquireThreadState()</code> method on the
+Python VM instance. It should then release the Python thread state
+before terminating by calling <code>releaseThreadState()</code>.
+Calling these methods is optional but strongly recommended as it
+ensures that Python is not creating and throwing away a thread
+state everytime the Python VM is entered and exited from a given
+Java VM thread.</p>
+</li>
+<li>
+<p>Any Java VM thread may instantiate a Python object for which an
+extension class was defined in Java as described in the previous
+section by calling the <code>instantiate()</code> method on the
+PythonVM instance. This method takes two string parameters, the
+name of the Python module and the name of the Python class to
+import and instantiate from it. The <code><strong>init</strong>()</code>
+constructor on this class must be callable without any parameters
+and, if defined, must call <code>super()</code> in order to
+initialize the Java side. The <code>instantiate()</code> method is
+declared to return <code>java.lang.Object</code> but the return
+value is actually an instance of the Java extension class used and
+must be downcast to it.</p>
+</li>
+</ul>
+<h2 id="pythonic_protocols">Pythonic protocols</h2>
+<p>When generating wrappers for Python, JCC attempts to detect which
+classes can be made iterable:</p>
+<ul>
+<li>
+<p>When a class declares to
+implement <code>java.lang.Iterable</code>, JCC makes it iterable
+from Python.</p>
+</li>
+<li>
+<p>When a Java class declares a method called <code>next()</code>
+with no arguments returning an object type, this class is made
+iterable. Its <code>next()</code> method is assumed to terminate
+iteration by returning <code>null</code>.</p>
+</li>
+</ul>
+<p>JCC generates a Python mapping get method for a class when requested
+to do so via the <code>--mapping</code> command line option which
+takes two arguments, the class to generate the mapping get for and
+the Java method to use. The method is specified with its name
+followed by ':' and its Java
+<a href="http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/types.html#wp16432">signature</a>.</p>
+<p>For example, <code>System.getProperties()['java.class.path']</code> is
+made possible by:</p>
+<p><source>
+--mapping java.util.Properties
+ 'getProperty:(Ljava/lang/String;)Ljava/lang/String;'
+ # asking for a Python mapping protocol wrapper
+ # for get access on the Properties class by
+ # calling its getProperty method
+</source></p>
+<p>JCC generates Python sequence length and get methods for a class
+when requested to do so via the <code>--sequence</code> command line
+option which takes three arguments, the class to generate the
+sequence length and get for and the two java methods to use. The
+methods are specified with their name followed by ':' and their Java
+<a href="http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/types.html#wp16432">signature</a>. For example:</p>
+<p><source>
+for i in xrange(len(hits)):
+doc = hits[i]
+...
+</source></p>
+<p>is made possible by:</p>
+<p><source>
+--sequence org.apache.lucene.search.Hits
+ 'length:()I'
+ 'doc:(I)Lorg/apache/lucene/document/Document;'
+</source></p></div>
+
+ <div><h1 id="news">News</h1>
+<h1 id="23_jul_2011_-_pylucene_33-3_available">23 Jul 2011 - PyLucene 3.3-3 available</h1>
+<p>This release tracks Lucene Core's recent 3.3 <a href="http://lucene.apache.org/#1+July+2011+-+Lucene+Core+3.3+and+Solr+3.3+Available">release</a>.</p>
+<p>See <a href="http://svn.apache.org/repos/asf/lucene/pylucene/tags/pylucene_3_3/CHANGES">PyLucene 3.3 CHANGES</a> and <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc/CHANGES">JCC 2.10 CHANGES</a> for details.<br/></p>
+<p>Source distributions are available <a href="http://www.apache.org/dyn/closer.cgi/lucene/pylucene/">here</a>.</p>
+<h1 id="09_jun_2011_-_pylucene_320-1_available">09 Jun 2011 - PyLucene 3.2.0-1 available</h1>
+<p>This release tracks Lucene Core's recent 3.2 <a href="http://lucene.apache.org/java/docs/index.html#4+June+2011+-+Lucene+Core+3.2">release</a>.</p>
+<p>See <a href="http://svn.apache.org/repos/asf/lucene/pylucene/tags/pylucene_3_2_0/CHANGES">PyLucene 3.2.0 CHANGES</a> and <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc/CHANGES">JCC 2.9 CHANGES</a> for details.<br/></p>
+<p>Source distributions are available <a href="http://www.apache.org/dyn/closer.cgi/lucene/pylucene/">here</a>.</p>
+<h1 id="04_apr_2011_-_pylucene_310-1_available">04 Apr 2011 - PyLucene 3.1.0-1 available</h1>
+<p>This release tracks Lucene Core's recent 3.1 <a href="http://lucene.apache.org/java/docs/index.html#31+March+2011+-+Lucene+Core+3.1">release</a>.</p>
+<p>See <a href="http://svn.apache.org/repos/asf/lucene/pylucene/tags/pylucene_3_1_0/CHANGES">PyLucene 3.1.0 CHANGES</a> and <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc/CHANGES">JCC 2.8 CHANGES</a> for details.<br/></p>
+<p>Source distributions are available <a href="http://www.apache.org/dyn/closer.cgi/lucene/pylucene/">here</a>.</p></div>
+
+
+ <div><h2 id="the_apache_software_foundation">The Apache Software Foundation</h2>
+<p>The <a href="http://www.apache.org">Apache Software Foundation</a> provides support for the Apache community of open-source software projects. The Apache projects are defined by collaborative consensus based processes, an open, pragmatic software license and a desire to create high quality software that leads the way in its field. Apache Lucene, Apache Solr, Apache PyLucene, Apache Open Relevance Project and their respective logos are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p></div>
+
+ </div>
+
+ <div id="sidebar">
+ <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="features.html">Features</a></li>
+<li><a href="install.html">Install</a></li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+</ul>
+<h1 id="related_projects">Related Projects</h1>
+<ul>
+<li><a href="http://hadoop.apache.org">Apache Hadoop</a></li>
+<li><a href="http://incubator.apache.org/connectors/">Apache ManifoldCF</a></li>
+<li><a href="http://incubator.apache.org/lucene.net/">Apache Lucene.Net</a></li>
+<li><a href="http://incubator.apache.org/lucy/">Apache Lucy</a></li>
+<li><a href="http://mahout.apache.org">Apache Mahout</a></li>
+<li><a href="http://nutch.apache.org">Apache Nutch</a></li>
+<li><a href="http://incubator.apache.org/opennlp">Apache OpenNLP</a></li>
+<li><a href="http://tika.apache.org">Apache Tika</a></li>
+<li><a href="http://zookeeper.apache.org">Apache Zookeeper</a></li>
+</ul>
+ </div>
+
+ </div>
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. <a href="../privacy.html">Privacy Policy</a>
+ <br/>
+ Apache and the Apache feather logo are trademarks of The Apache Software Foundation. Apache Lucene, Apache Solr and their
+ respective logos are trademarks of the Apache Software Foundation. Please see the <a href="http://www.apache.org/foundation/marks/">Apache Trademark Policy</a>
+ for more information.
+ </p>
+ </div>
+</div>
+</div>
+<script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-94576-12']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+
+</script>
+</body>
+</html>