You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by va...@apache.org on 2009/01/31 04:14:05 UTC
svn commit: r739497 - in
/lucene/pylucene/site/src/documentation/content/xdocs: ./ documentation/
jcc/ jcc/documentation/
Author: vajda
Date: Sat Jan 31 03:14:04 2009
New Revision: 739497
URL: http://svn.apache.org/viewvc?rev=739497&view=rev
Log:
converted plain text docs to forrest format
Added:
lucene/pylucene/site/src/documentation/content/xdocs/documentation/
lucene/pylucene/site/src/documentation/content/xdocs/documentation/install.xml (with props)
lucene/pylucene/site/src/documentation/content/xdocs/documentation/readme.xml (with props)
lucene/pylucene/site/src/documentation/content/xdocs/jcc/
lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/
lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/install.xml (with props)
lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml (with props)
lucene/pylucene/site/src/documentation/content/xdocs/jcc/index.xml (with props)
Modified:
lucene/pylucene/site/src/documentation/content/xdocs/index.xml
lucene/pylucene/site/src/documentation/content/xdocs/site.xml
lucene/pylucene/site/src/documentation/content/xdocs/tabs.xml
Added: lucene/pylucene/site/src/documentation/content/xdocs/documentation/install.xml
URL: http://svn.apache.org/viewvc/lucene/pylucene/site/src/documentation/content/xdocs/documentation/install.xml?rev=739497&view=auto
==============================================================================
--- lucene/pylucene/site/src/documentation/content/xdocs/documentation/install.xml (added)
+++ lucene/pylucene/site/src/documentation/content/xdocs/documentation/install.xml Sat Jan 31 03:14:04 2009
@@ -0,0 +1,105 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<!--
+ 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.
+-->
+<document>
+
+ <header>
+ <title>Installing PyLucene</title>
+ </header>
+
+ <body>
+ <section id="building">
+ <title>Building PyLucene</title>
+ <p>
+ PyLucene is completely code-generated by JCC whose sources are
+ included with the PyLucene sources.
+ </p>
+ <p>
+ Before building PyLucene, JCC must be built first. See
+ JCC's <a href="site:jcc/documentation/install">installation
+ instructions</a> for building and installing it.
+ </p>
+ <p>
+ Once JCC is built and installed, PyLucene is built via a Makefile which
+ invokes JCC. See PyLucene's Makefile for configuration instructions.
+ </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 --files command line argument, this behaviour can be tuned to
+ workaround various limits, for example:
+ </p>
+ <ul>
+ <li>
+ to break up the large wrapper class file into about 2 files:<br/>
+ <code>--files 2</code>
+ </li>
+ <li>
+ to break up the large wrapper class file into about 10 files:<br/>
+ <code>--files 10</code>
+ </li>
+ <li>
+ to generate one C++ file per Java class wrapped:<br/>
+ <code>--files separate</code>
+ </li>
+ </ul>
+ </section>
+ <section id="requirements">
+ <title>Requirements</title>
+ <p>
+ To build PyLucene a Java Development Kit (JDK)
+ and <a href="http://ant.apache.org">Ant</a> are required; use of the
+ resulting PyLucene binaries requires only a Java Runtime Environment
+ (JRE).
+ </p>
+ <p>
+ The <a href="http://pypi.python.org/pypi/setuptools">setuptools</a>
+ package is required to build and run PyLucene on Python 2.3.5. With
+ later versions of Python, setuptools is only required for shared
+ mode. See JCC's <a href="site:jcc/documentation/install">installation
+ instructions</a> for more information.
+ </p>
+ </section>
+ <section id="solaris">
+ <title>Notes for Solaris</title>
+ <p>
+ PyLucene's Makefile is a GNU Makefile. Be sure to
+ use <code>gmake</code> instead of plain <code>make</code>.
+ </p>
+ <p>
+ Just as when building JCC, Python's distutils 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>.<br/>
+ </p>
+ <p>
+ To build PyLucene, use the following shell command to ensure that
+ the C++ compiler is used:<br/>
+ <code>
+ $ CC=CC gmake
+ </code>
+ </p>
+ </section>
+ </body>
+
+</document>
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/documentation/install.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/documentation/install.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: lucene/pylucene/site/src/documentation/content/xdocs/documentation/readme.xml
URL: http://svn.apache.org/viewvc/lucene/pylucene/site/src/documentation/content/xdocs/documentation/readme.xml?rev=739497&view=auto
==============================================================================
--- lucene/pylucene/site/src/documentation/content/xdocs/documentation/readme.xml (added)
+++ lucene/pylucene/site/src/documentation/content/xdocs/documentation/readme.xml Sat Jan 31 03:14:04 2009
@@ -0,0 +1,318 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<!--
+ 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.
+-->
+<document>
+
+ <header>
+ <title>PyLucene Features</title>
+ </header>
+
+ <body>
+ <warning>
+ 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="site:jcc/documentation/readme">here</a>.
+ </warning>
+ <section id="install">
+ <title>Installing PyLucene</title>
+ <p>
+ PyLucene is a Python extension built with
+ <a href="site:jcc/about/index">JCC</a>.
+ </p>
+ <p>
+ To build PyLucene, JCC needs to be built first. Sources for JCC are
+ included with the PyLucene sources. Instructions for building and
+ installing JCC are <a href="site:jcc/documentation/install">here</a>.
+ </p>
+ <p>
+ Instruction for building PyLucene
+ are <a href="site:documentation/install">here</a>.
+ </p>
+ </section>
+ <section id="api">
+ <title>API documentation</title>
+ <p>
+ PyLucene is closely tracking Java Lucene releases. It intends to
+ supports the entire Lucene API.
+ </p>
+ <p>
+ PyLucene also includes a number of Lucene contrib packages: the
+ Snowball analyzer and stemmers, the highlighter package, analyzers
+ for other languages than english, regular expression queries,
+ specialized queries such as 'more like this' and more.
+ </p>
+ <p>
+ This document only covers the pythonic extensions to Lucene offered
+ by PyLucene as well as some differences between the Java and Python
+ APIs. For the documentation on Java Lucene APIs,
+ see <a href="http://lucene.apache.org/java/docs/api/index.html">here</a>.
+ </p>
+ <p>
+ To help with debugging and to support some Lucene APIs, PyLucene also
+ exposes some Java runtime APIs.
+ </p>
+ <section id="samples">
+ <title>Samples</title>
+ <p>
+ The best way to learn PyLucene is to look at the many samples
+ included with the PyLucene source release or on the web at:
+ </p>
+ <ul>
+ <li>
+ <a href="http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples">http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples</a>
+ </li>
+ <li>
+ <a href="http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples/LuceneInAction">http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples/LuceneInAction</a>
+ </li>
+ </ul>
+ <p>
+ A large number of samples are shipped with PyLucene. Most notably,
+ all the samples published in
+ the <a href="http://www.manning.com/hatcher2"><em>Lucene in
+ Action</em></a> book that did not depend on a third party Java
+ library for which there was no obvious Python equivalent were
+ ported to Python and PyLucene.
+ </p>
+ <p>
+ <em>Lucene in Action</em> is a great companion to learning
+ Lucene. Having all the samples available in Python should make it
+ even easier for Python developers.
+ </p>
+ <p>
+ <em>Lucene in Action</em> was written by Erik Hatcher and Otis
+ Gospodnetic, both part of the Java Lucene development team, and is
+ available from
+ <a href="http://www.manning.com/hatcher2">Manning Publications</a>.
+ </p>
+ </section>
+ <section id="threading">
+ <title>Threading support with attachCurrentThread</title>
+ <p>
+ Before PyLucene APIs can be used from a thread other than the main
+ thread that was not created by the Java Runtime, the
+ <code>attachCurrentThread()</code> method must be called on the
+ <code>JCCEnv</code> object returned by the <code>initVM()</code>
+ or <code>getVMEnv()</code> functions.
+ </p>
+ </section>
+ <section id="exceptions">
+ <title>Exception handling with lucene.JavaError</title>
+ <p>
+ Java exceptions are caught at the language barrier and reported to
+ Python by raising a JavaError instance whose args tuple contains the
+ actual Java Exception instance.
+ </p>
+ </section>
+ <section id="arrays">
+ <title>Handling Java arrays</title>
+ <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 array elements but not to change the array
+ size.
+ </p>
+ <p>
+ A few Lucene APIs take array arguments and expect values to be
+ returned in them. To call such an API and be able to retrieve the
+ array values after the call, a Java array needs to instantiated
+ first.<br/>
+ For example, accessing termDocs:
+ </p>
+ <source>
+ termDocs = reader.termDocs(Term("isbn", isbn))
+ docs = JArray('int')(1) # allocate an int[1] array
+ freq = JArray('int')(1) # allocate an int[1] array
+ if termDocs.read(docs, freq) == 1:
+ bits.set(docs[0]) # access the array's first element
+ </source>
+ <p>
+ In addition to <code>'int'</code>, the <code>'JArray'</code>
+ function accepts <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. The <code>JArray('object')</code> constructor takes a second
+ argument denoting the class of the object elements. This argument
+ is optional and defaults to Object.
+ </p>
+ <p>
+ To convert a char or byte array to a Python string use a
+ <code>''.join(array)</code> construct.
+ </p>
+ <p>
+ Instead of an integer denoting the size of the desired Java array,
+ a sequence of objects of the expected element type may be passed
+ in to the array constructor.<br/>
+ For example:
+ </p>
+ <source>
+ # creating a Java array of double from the [1.5, 2.5] list
+ JArray('double')([1.5, 2.5])
+ </source>
+ <p>
+ All methods that expect an array also accept a sequence of Python
+ objects of the expected element type. If no values are expected
+ from the array arguments after the call, it is hence not necessary
+ to instantiate a Java array to make such calls.
+ </p>
+ <p>
+ See <a href="site:jcc/documentation/readme">JCC</a> for more
+ information about handling arrays.
+ </p>
+ </section>
+ <section id="differences">
+ <title>Differences between the Java Lucene and PyLucene APIs</title>
+ <ul>
+ <li>
+ The PyLucene API exposes all Java Lucene classes in a flat namespace
+ in the PyLucene module. For example, the Java import
+ statement <code>import
+ org.apache.lucene.index.IndexReader;</code> corresponds to the
+ Python import statement <code>from lucene import
+ IndexReader</code>
+ </li>
+ <li>
+ Downcasting is a common operation in Java but not a concept in
+ Python. Because the wrapper objects implementing exactly the
+ APIs of the declared type of the wrapped object, all classes
+ implement two class methods called instance_ and cast_ that
+ verify and cast an instance respectively.
+ </li>
+ </ul>
+ </section>
+ <section id="python">
+ <title>Pythonic extensions to the Java Lucene APIs</title>
+ <p>
+ Java is a very verbose language. Python, on the other hand, offers
+ many syntactically attractive constructs for iteration, property
+ access, etc... As the Java Lucene samples from the <em>Lucene in
+ Action</em> book were ported to Python, PyLucene received a number
+ of pythonic extensions listed here:
+ </p>
+ <ul>
+ <li>
+ Iterating search hits is a very common operation. Hits instances
+ are iterable in Python. Two values are returned for each
+ iteration, the zero-based number of the document in the Hits
+ instance and the document instance itself.<br/>
+ The Java loop:
+ <source>
+ for (int i = 0; i < hits.length(); i++) {
+ Document doc = hits.doc(i);
+ System.out.println(hits.score(i) + " : " + doc.get("title"));
+ }
+ </source>
+ can be written in Python:
+ <source>
+ for hit in hits:
+ hit = Hit.cast_(hit)
+ print hit.getScore(), ':', hit.getDocument['title']
+ </source>
+ if hit.iterator()'s next() method were declared to return
+ <code>Hit</code> instead of <code>Object</code>, the above
+ cast_() call would not be unnecessary.<br/>
+ The same java loop can also be written:
+ <source>
+ for i xrange(len(hits)):
+ print hits.score(i), ':', hits[i]['title']
+ </source>
+ </li>
+ <li>
+ Hits instances partially implement the Python 'sequence'
+ protocol.<br/>
+ The Java expressions:
+ <source>
+ hits.length()
+ doc = hits.get(i)
+ </source>
+ are better written in Python:
+ <source>
+ len(hits)
+ doc = hits[i]
+ </source>
+ </li>
+ <li>
+ Document instances have fields whose values can be accessed
+ through the mapping protocol.<br/>
+ The Java expression:
+ <source>
+ doc.get("title")
+ </source>
+ is better written in Python:
+ <source>
+ doc['title']
+ </source>
+ </li>
+ <li>
+ Document instances can be iterated over for their fields.<br/>
+ The Java loop:
+ <source>
+ Enumeration fields = doc.fields();
+ while (fields.hasMoreElements()) {
+ Field field = (Field) fields.nextElement();
+ ...
+ }
+ </source>
+ is better written in Python:
+ <source>
+ for field in doc.getFields():
+ field = Field.cast_(field)
+ ...
+ </source>
+ Once JCC heeds Java 1.5 annotations and once Java Lucene
+ makes use of them, such casting should become unncessary.
+ </li>
+ </ul>
+ </section>
+ <section id="extensions">
+ <title>Extending Java Lucene classes from Python</title>
+ <p>
+ Many areas of the Lucene API expect the programmer to provide
+ their own implementation or specialization of a feature where
+ the default is inappropriate. For example, text analyzers and
+ tokenizers are an area where many parameters and environmental
+ or cultural factors are calling for customization.
+ </p>
+ <p>
+ PyLucene enables this by providing Java extension points listed
+ below that serve as proxies for Java to call back into the
+ Python implementations of these customizations.
+ </p>
+ <p>
+ These extension points are simple Java classes that JCC
+ generates the native C++ implementations for. It is easy to add
+ more such extensions classes into the 'java' directory of the
+ PyLucene source tree.
+ </p>
+ <p>
+ To learn more about this topic, please refer to the JCC
+ <a href="site:jcc/documentation/readme">documentation</a>.
+ </p>
+ <p>
+ Please refer to the classes in the 'java' tree for currently
+ available extension points. Examples of uses of these extension
+ points are to be found in PyLucene's unit tests and <em>Lucene
+ in
+ Action</em> <a href="http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples/LuceneInAction">samples</a>.
+ </p>
+ </section>
+ </section>
+ </body>
+
+</document>
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/documentation/readme.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/documentation/readme.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: lucene/pylucene/site/src/documentation/content/xdocs/index.xml
URL: http://svn.apache.org/viewvc/lucene/pylucene/site/src/documentation/content/xdocs/index.xml?rev=739497&r1=739496&r2=739497&view=diff
==============================================================================
--- lucene/pylucene/site/src/documentation/content/xdocs/index.xml (original)
+++ lucene/pylucene/site/src/documentation/content/xdocs/index.xml Sat Jan 31 03:14:04 2009
@@ -24,13 +24,28 @@
<section id="introduction">
<title>What is PyLucene ?</title>
<p>
- PyLucene is a <a href="http://www.python.org">Python</a> extension for accessing Java <a href="http://lucene.apache.org/java/">Lucene</a>. Its goal is to allow you to use Lucene's text indexing and searching capabilities from Python. It is API compatible with the latest version of Java Lucene, version 2.4.0 as of October 19th, 2008.
+ PyLucene is a <a href="http://www.python.org">Python</a> extension
+ for accessing
+ Java <a href="http://lucene.apache.org/java/">Lucene</a>. Its goal
+ is to allow you to use Lucene's text indexing and searching
+ capabilities from Python. It is API compatible with the latest
+ version of Java Lucene, version 2.4.0 as of October 19th, 2008.
</p>
<p>
- PyLucene is built with <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc/README">JCC</a>, a C++ code generator that makes it possible to call into Java classes from Python via Java's Native Invocation Interface (JNI). Sources for JCC are included with the PyLucene sources.
+ PyLucene is not a Lucene port but a Python wrapper around
+ Java Lucene. PyLucene embeds a Java VM with Lucene into a Python
+ process. The PyLucene Python extension, a Python module called
+ <code>lucene</code>, is machine-generated by JCC.
</p>
<p>
- See the <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/README">README</a> file for more information and documentation about PyLucene.
+ PyLucene is built with <a href="site:jcc/about/index">JCC</a>, a C++
+ code generator that makes it possible to call into Java classes from
+ Python via Java's Native Invocation Interface (JNI). Sources for JCC
+ are included with the PyLucene sources.
+ </p>
+ <p>
+ See <a href="site:documentation/readme">here</a> for more
+ information and documentation about PyLucene.
</p>
</section>
<section id="requirements">
@@ -39,13 +54,22 @@
PyLucene is supported on Mac OS X, Linux, Solaris and Windows.
</p>
<p>
- PyLucene requires Python version 2.x (x >= 3.5) and Java version 1.x (x >= 4). Building PyLucene requires GNU Make, a recent version of <a href="http://ant.apache.org">Ant</a> capable of building Java <a href="http://lucene.apache.org/java/">Lucene</a> and a C++ compiler. Use of <a href="http://peak.telecommunity.com/DevCenter/setuptools">setuptools</a> is recommended.
- </p>
- <p>
- See the JCC <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc/INSTALL">INSTALL</a> file for more information about building JCC from sources.
- </p>
- <p>
- See the PyLucene <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/INSTALL">INSTALL</a> file for more information about building PyLucene from sources.
+ PyLucene requires Python version 2.x (x >= 3.5) and Java version 1.x
+ (x >= 4). Building PyLucene requires GNU Make, a recent version
+ of <a href="http://ant.apache.org">Ant</a> capable of building
+ Java <a href="http://lucene.apache.org/java/">Lucene</a> and a C++
+ compiler. Use
+ of <a href="http://pypi.python.org/pypi/setuptools">setuptools</a>
+ is recommended.
+ </p>
+ <p>
+ See the JCC <a href="site:jcc/documentation/install">installation
+ instructions</a> for more information about building JCC from sources.
+ </p>
+ <p>
+ See the PyLucene <a href="site:documentation/install">installation
+ instructions</a> for more information about building PyLucene from
+ sources.
</p>
</section>
<section id="news">
@@ -53,7 +77,9 @@
<section id="news20090108">
<title>08 Jan 2009 - PyLucene joins Apache Lucene as a Subproject</title>
<p>
- The Lucene PMC is pleased to announce the arrival of PyLucene as a Lucene subproject. PyLucene was previously hosted at the Open Source Applications Foundation since its inception in early 2004.
+ The Lucene PMC is pleased to announce the arrival of PyLucene as a
+ Lucene subproject. PyLucene was previously hosted at the Open
+ Source Applications Foundation since its inception in early 2004.
</p>
</section>
</section>
Added: lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/install.xml
URL: http://svn.apache.org/viewvc/lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/install.xml?rev=739497&view=auto
==============================================================================
--- lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/install.xml (added)
+++ lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/install.xml Sat Jan 31 03:14:04 2009
@@ -0,0 +1,231 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<!--
+ 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.
+-->
+<document>
+
+ <header>
+ <title>JCC Installation Instructions</title>
+ </header>
+
+ <body>
+ <section id="build">
+ <title>Building JCC</title>
+ <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>
+ <ol>
+ <li>
+ Edit <code>setup.py</code> and review that values in
+ the <code>INCLUDE</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 its generating code for.
+ </li>
+ <li>
+ At the command line, enter
+ <source>
+ $ python setup.py build
+ $ sudo python setup.py install
+ </source>
+ </li>
+ </ol>
+ </section>
+ <section id="requirements">
+ <title>Requirements</title>
+ <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>
+ </section>
+ <section id="shared">
+ <title>Shared Mode: <code>--shared</code></title>
+ <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). This shared library capability is a feature
+ currently under development.
+ </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 eacg JCC-built Python
+ extension and only one such extension can be used in a given Python
+ process.
+ </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>
+ </section>
+ <section id="mac">
+ <title>Notes for Mac OS X</title>
+ <p>
+ On Mac OS X, Java is installed by Apple's setup as a framework. The
+ values for <code>INCLUDE</code> and <code>LFLAGS</code>
+ for <code>darwin</code> should be correct and ready to use.
+ </p>
+ </section>
+ <section id="linux">
+ <title>Notes for Linux</title>
+ <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>
+ 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.
+ </li>
+ <li>
+ 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>
+ </li>
+ </ul>
+ <p>
+ See earlier section about <a href="#shared">Shared Mode</a> for
+ Linux support.
+ </p>
+ </section>
+ <section id="solaris">
+ <title>Notes for Solaris</title>
+ <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>
+ <source>
+ $ CC=CC python setup.py build
+ </source>
+ <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>
+ </section>
+ <section id="windows">
+ <title>Notes for Windows</title>
+ <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>
+ Adding the Python directory to PATH is recommended.
+ </li>
+ <li>
+ Adding the Java directories containing the necessary DLLs and to
+ <code>PATH</code> is a must.
+ </li>
+ <li>
+ 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).
+ </li>
+ </ul>
+ </section>
+ <section id="python">
+ <title>Notes for Python 2.3</title>
+ <p>
+ To use JCC with Python 2.3, setuptools is required
+ </p>
+ <ol>
+ <li>
+ download <a href="http://pypi.python.org/pypi/setuptools">setuptools</a>.
+ </li>
+ <li>
+ edit the downloaded <code>setuptools</code> egg file to use
+ python2.3 instead of python2.4.
+ </li>
+ <li>
+ At the command line, run:
+ <source>
+ $ sudo sh setuptools-0.6c7-py2.4.egg
+ </source>
+ </li>
+ </ol>
+ </section>
+ </body>
+
+</document>
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/install.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/install.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml
URL: http://svn.apache.org/viewvc/lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml?rev=739497&view=auto
==============================================================================
--- lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml (added)
+++ lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml Sat Jan 31 03:14:04 2009
@@ -0,0 +1,721 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<!--
+ 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.
+-->
+<document>
+
+ <header>
+ <title>JCC Features</title>
+ </header>
+
+ <body>
+ <warning>
+ 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="site:jcc/documentation/readme">here</a>.
+ </warning>
+ <section id="install">
+ <title>Installing JCC</title>
+ <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">here</a> for more
+ information and operating system specific notes.
+ </p>
+ </section>
+ <section id="use">
+ <title>Generating C++ and Python wrappers with JCC</title>
+ <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 types are found in one of the
+ following ways:
+ </p>
+ <ul>
+ <li>
+ the type is one of the requested classes
+ </li>
+ <li>
+ the type is one of the requested classes' superclass or implemented
+ interfaces
+ </li>
+ <li>
+ the type is available from one of the packages listed via the
+ <code>--package</code> command line argument
+ </li>
+ </ul>
+ <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>
+ <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
+ --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
+ --install # installing it into Python's site-packages
+ # directory.
+ </source>
+ <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>
+ to break up the large wrapper class file into about 2 files:<br/>
+ <code>--files 2</code>
+ </li>
+ <li>
+ to break up the large wrapper class file into about 10 files:<br/>
+ <code> --files 10</code>
+ </li>
+ <li>
+ to generate one C++ file per Java class wrapped:<br/>
+ <code>--files separate</code>
+ </li>
+ </ul>
+ <p>
+ The <code>--prefix</code> and <code>--root</code> arguments are
+ passed through to <code>distutils</code>' <code>setup()</code>.
+ </p>
+ </section>
+ <section id="classpath">
+ <title>Classpath considerations</title>
+ <p>
+ When generating wrappers for Python, the JAR files passed to JCC
+ via <code>--jar</code> are copied into the resulting Python extension
+ as resources and added to the extension'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 more jar files automatically copied into resulting python
+ extension 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 public classes contained in them unless they're explicitely
+ named on the command line.
+ </p>
+ </section>
+ <section id="setuptools">
+ <title>Using <code>distutils</code> vs <code>setuptools</code></title>
+ <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>
+ </section>
+ <section id="egg">
+ <title>Distributing an egg</title>
+ <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>
+ </section>
+ <section id="api">
+ <title>JCC's runtime API functions</title>
+ <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 resources files along with the extension when
+ JCC is invoked with the <code>--install</code> command line
+ argument. For example:
+ <source>
+ >>> import lucene
+ >>> lucene.initVM(classpath=lucene.CLASSPATH)
+ </source>
+ </li>
+ <li>
+ <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. For example:
+ <source>
+ >>> import lucene
+ >>> lucene.initVM(lucene.CLASSPATH, initialheap='32m')
+ >>> lucene.Runtime.getRuntime().totalMemory()
+ 33357824L
+ </source>
+ </li>
+ <li>
+ <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.
+ </li>
+ <li>
+ <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.
+ </li>
+ <li>
+ <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>
+ >>> import lucene
+ >>> lucene.initVM(lucene.CLASSPATH,
+ vmargs='-Xcheck:jni,-verbose:jni,-verbose:gc')
+ </source>
+ </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>
+ <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.
+ </li>
+ <li>
+ <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.
+ </li>
+ </ul>
+ <p>
+ There are several differences between JNI's <code>findClass()</code>
+ and Java's <code>Class.forName()</code>:
+ </p>
+ <ul>
+ <li>
+ className is a '/' separated string of names
+ </li>
+ <li>
+ the class loaders are different, <code>findClass()</code> may find
+ classes that <code>Class.forName()</code> won't.
+ </li>
+ </ul>
+ <p>
+ For example:
+ </p>
+ <source>
+ >>> 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>
+ </section>
+ <section id="casting">
+ <title>Type casting and instance checks</title>
+ <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 annotations. JCC does not heed annotations at the moment. A
+ Java API declared to return <code>Object</code> will wrap objects as
+ such.
+ </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>
+ <source>
+ if BooleanQuery.instance_(query):
+ booleanQuery = BooleanQuery.cast_(query)
+
+ print booleanQuery.getClauses()
+ </source>
+ </section>
+ <section id="arrays">
+ <title>Handling arrays</title>
+ <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 or byte 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>
+ >>> array = JArray('int')(size)
+ # the resulting Java int array is initialized with zeroes
+
+ >>> array = JArray('int')(sequence)
+ # the sequence must only contain ints
+ # the resulting Java int array contains the ints in the sequence
+ </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>
+ # cast obj to an array of ints
+ >>> JArray('int').cast_(obj)
+ # cast obj to an array of Document
+ >>> JArray('object').cast_(obj, Document)
+ </source>
+ <p>
+ In both cases, the java type of obj must be compatible with the
+ array type it is being cast to.
+ </p>
+ <source>
+ # using nested array:
+
+ >>> 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>
+ 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>
+ # is d array of Object ? are d's elements of type Object ?
+ >>> JArray('object').instance_(d)
+ True
+
+ # can it receive Object instances ?
+ >>> JArray('object').assignable_(d)
+ False
+
+ # is it array of Document ? are d's elements of type Document ?
+ >>> JArray('object').instance_(d, Document)
+ True
+
+ # is it array of Class ? are d's elements of type Class ?
+ >>> JArray('object').instance_(d, Class)
+ False
+
+ # can it receive Document instances ?
+ >>> JArray('object').assignable_(d, Document)
+ True
+ </source>
+ </section>
+ <section id="exceptions">
+ <title>Exception reporting</title>
+ <p>
+ Exceptions that occur in the Java VM and that escape to C++ are
+ reported as a <code>javaError</code> C++ exception. Failure to
+ handle the exception causes 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>
+ </section>
+ <section id="extensions">
+ <title>Writing Java class extensions in Python</title>
+ <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>
+ <source>
+ package org.osafoundation.lucene.analysis;
+
+ import org.apache.lucene.analysis.Analyzer;
+ import org.apache.lucene.analysis.TokenStream;
+ import java.io.Reader;
+
+ public class PythonAnalyzer extends Analyzer {
+ private long pythonObject;
+
+ public PythonAnalyzer()
+ {
+ }
+
+ public void pythonExtension(long pythonObject)
+ {
+ this.pythonObject = pythonObject;
+ }
+ public long pythonExtension()
+ {
+ return this.pythonObject;
+ }
+
+ public void finalize()
+ throws Throwable
+ {
+ pythonDecRef();
+ }
+
+ public native void pythonDecRef();
+ public native TokenStream tokenStream(String fieldName, Reader reader);
+ }
+ </source>
+ <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>
+ <source>
+ class _analyzer(PythonAnalyzer):
+ def tokenStream(self, fieldName, reader):
+ class _tokenStream(PythonTokenStream):
+ def __init__(self):
+ super(_tokenStream, self).__init__()
+ self.TOKENS = ["1", "2", "3", "4", "5"]
+ self.INCREMENTS = [1, 2, 1, 0, 1]
+ self.i = 0
+ def next(self):
+ if self.i == len(self.TOKENS):
+ return None
+ t = Token(self.TOKENS[self.i], self.i, self.i)
+ t.setPositionIncrement(self.INCREMENTS[self.i])
+ self.i += 1
+ return t
+ def reset(self):
+ pass
+ def close(self):
+ pass
+ return _tokenStream()
+ </source>
+ <p>
+ When an <code>__init__()</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>
+ </section>
+ <section id="python">
+ <title>Pythonic protocols</title>
+ <p>
+ When generating wrappers for Python, JCC attempts to detect which
+ classes can be made iterable:
+ </p>
+ <ul>
+ <li>
+ When a class declares to implement java.util.Iterator or something
+ compatible with it, JCC makes it iterable from Python.
+ </li>
+ <li>
+ When a Java class declares a method called <code>iterator()</code>
+ with no arguments returning a type compatible
+ with <code>java.util.Iterator</code>, this class is made iterable
+ from Python.
+ </li>
+ <li>
+ 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>.
+ </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>
+ <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>
+ 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>
+ <source>
+ for i in xrange(len(hits)):
+ doc = hits[i]
+ ...
+ </source>
+ <p>
+ is made possible by:
+ </p>
+ <source>
+ --sequence org.apache.lucene.search.Hits
+ 'length:()I'
+ 'doc:(I)Lorg/apache/lucene/document/Document;'
+ </source>
+ </section>
+ </body>
+
+</document>
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: lucene/pylucene/site/src/documentation/content/xdocs/jcc/index.xml
URL: http://svn.apache.org/viewvc/lucene/pylucene/site/src/documentation/content/xdocs/jcc/index.xml?rev=739497&view=auto
==============================================================================
--- lucene/pylucene/site/src/documentation/content/xdocs/jcc/index.xml (added)
+++ lucene/pylucene/site/src/documentation/content/xdocs/jcc/index.xml Sat Jan 31 03:14:04 2009
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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 document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Welcome to JCC, PyLucene's code generator</title>
+ </header>
+ <body>
+ <section id="introduction">
+ <title>What is JCC ?</title>
+ <p>
+ JCC is a C++ code generator that produces a C++ object interface
+ wrapping a Java library via Java's Native Interface (JNI). JCC
+ also generates C++ wrappers that conform to Python's C type system
+ making the instances of Java classes directly available to a Python
+ interpreter.
+ </p>
+ <p>
+ When generating Python wrappers, JCC produces a complete Python
+ extension via the <code>distutils</code>
+ or <a href="http://pypi.python.org/pypi/setuptools"><code>setuptools</code></a>
+ packages.
+ </p>
+ <p>
+ See <a href="site:jcc/documentation/readme">here</a> for more
+ information and documentation about JCC.
+ </p>
+ </section>
+ <section id="requirements">
+ <title>Requirements</title>
+ <p>
+ JCC is supported on Mac OS X, Linux, Solaris and Windows.
+ </p>
+ <p>
+ JCC requires Python version 2.x (x >= 3.5) and Java version 1.x
+ (x >= 4). Building JCC requires a C++ compiler. Use of
+ <a href="http://pypi.python.org/pypi/setuptools"><code>setuptools</code></a>
+ is recommended.
+ </p>
+ <p>
+ See the <a href="site:jcc/documentation/install">installation
+ instructions</a> for more information about building JCC from sources.
+ </p>
+ </section>
+ <section id="source">
+ <title>Source Code</title>
+ <p>
+ The source code to JCC is part of PyLucene's and can be obtained with
+ a subversion client
+ from <a href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc">here</a>.
+ </p>
+ </section>
+ <section id="contact">
+ <title>Mailing List</title>
+ <p>
+ If you'd like to contribute to JCC or are having issues or questions
+ with JCC, please subscribe to the PyLucene developer <a href="site:resources/contact">mailing list</a>.
+ </p>
+ </section>
+ </body>
+</document>
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/jcc/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: lucene/pylucene/site/src/documentation/content/xdocs/jcc/index.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: lucene/pylucene/site/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/lucene/pylucene/site/src/documentation/content/xdocs/site.xml?rev=739497&r1=739496&r2=739497&view=diff
==============================================================================
--- lucene/pylucene/site/src/documentation/content/xdocs/site.xml (original)
+++ lucene/pylucene/site/src/documentation/content/xdocs/site.xml Sat Jan 31 03:14:04 2009
@@ -37,18 +37,32 @@
See FAQ: "How can I use a start-up-page other than index.html?"
-->
<site label="PyLucene" href="" xmlns="http://apache.org/forrest/linkmap/1.0"
- tab="">
- <about label="About">
+ tab="home">
+ <about label="About" tab="home">
<index label="Index" href="index.html" description="Welcome to PyLucene"/>
<!--
<linkmap label="Documentation ToC" href="linkmap.html" description="Table of Contents for this example site"/>
-->
</about>
- <resources label="Resources" href="resources/">
+ <documentation label="Documentation" href="documentation/" tab="home">
+ <install label="Installation" href="install.html"/>
+ <readme label="Features" href="readme.html" />
+ </documentation>
+ <resources label="Resources" href="resources/" tab="home">
<svn label="Source Code" href="version_control.html"/>
<contact label="Mailing Lists" href="mailing_lists.html" />
<issues label="Issue Tracking" href="ext:jira" />
</resources>
+
+ <jcc label="JCC" href="jcc/" tab="jcc">
+ <about label="About" tab="jcc">
+ <index label="Index" href="index.html" description="Welcome to JCC"/>
+ </about>
+ <documentation label="Documentation" href="documentation/" tab="jcc">
+ <install label="Installation" href="install.html"/>
+ <readme label="Features" href="readme.html"/>
+ </documentation>
+ </jcc>
<!--
<samples label="Samples" href="samples/" tab="samples">
<index label="Overview" href="index.html"/>
@@ -119,5 +133,6 @@
<cocoon href="http://cocoon.apache.org/"/>
<xml.apache.org href="http://xml.apache.org/"/>
<jira href="http://issues.apache.org/jira/browse/PyLucene"/>
+ <svn href="http://svn.apache.org/repos/asf/lucene/pylucene/trunk"/>
</external-refs>
</site>
Modified: lucene/pylucene/site/src/documentation/content/xdocs/tabs.xml
URL: http://svn.apache.org/viewvc/lucene/pylucene/site/src/documentation/content/xdocs/tabs.xml?rev=739497&r1=739496&r2=739497&view=diff
==============================================================================
--- lucene/pylucene/site/src/documentation/content/xdocs/tabs.xml (original)
+++ lucene/pylucene/site/src/documentation/content/xdocs/tabs.xml Sat Jan 31 03:14:04 2009
@@ -30,7 +30,8 @@
Tabs can be embedded to a depth of two. The second level of tabs will only
be displayed when their parent tab is selected.
-->
- <tab id="" label="Home" dir="" indexfile="index.html"/>
+ <tab id="home" label="Home" dir="" indexfile="index.html"/>
+ <tab id="jcc" label="JCC" dir="jcc" indexfile="index.html"/>
<!-- Add new tabs here, eg:
<tab label="How-Tos" dir="community/howto/"/>
<tab label="XML Site" dir="xml-site/"/>