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 2012/08/23 02:29:05 UTC
svn commit: r829811 - in /websites/staging/lucene/trunk/content: ./
pylucene/features.html pylucene/jcc/features.html pylucene/jcc/install.html
Author: buildbot
Date: Thu Aug 23 00:29:05 2012
New Revision: 829811
Log:
Staging update by buildbot for lucene
Modified:
websites/staging/lucene/trunk/content/ (props changed)
websites/staging/lucene/trunk/content/pylucene/features.html
websites/staging/lucene/trunk/content/pylucene/jcc/features.html
websites/staging/lucene/trunk/content/pylucene/jcc/install.html
Propchange: websites/staging/lucene/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Aug 23 00:29:05 2012
@@ -1 +1 @@
-1376318
+1376328
Modified: websites/staging/lucene/trunk/content/pylucene/features.html
==============================================================================
--- websites/staging/lucene/trunk/content/pylucene/features.html (original)
+++ websites/staging/lucene/trunk/content/pylucene/features.html Thu Aug 23 00:29:05 2012
@@ -132,11 +132,10 @@
<div id="main">
<h1 class="title"></h1>
- <div><p><warning>
-Before calling any PyLucene API that requires the Java VM, start it by
+ <div><h2 id="warning">Warning</h2>
+<p>Before calling any PyLucene API that requires the Java VM, start it by
calling <i>initVM(classpath, ...)</i>.
-More about this function in <a href="jcc/features.html">here</a>.
-</warning></p>
+More about this function in <a href="jcc/features.html">here</a>.</p>
<h2 id="installing-pylucene">Installing PyLucene</h2>
<p>PyLucene is a Python extension built with
<a href="jcc/">JCC</a>.</p>
Modified: websites/staging/lucene/trunk/content/pylucene/jcc/features.html
==============================================================================
--- websites/staging/lucene/trunk/content/pylucene/jcc/features.html (original)
+++ websites/staging/lucene/trunk/content/pylucene/jcc/features.html Thu Aug 23 00:29:05 2012
@@ -135,34 +135,28 @@
<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
+calling <i>initVM(classpath, ...)</i>. 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>
+via <i>distutils</i> or <i>setuptools</i>.</p>
<p>See <a href="install.html">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>python 2.7: <b>python -m jcc</b></li>
+<li>python 2.6: <b>python -m jcc.<strong>main</strong></b></li>
+<li>python 2.5: <b>python -m jcc</b></li>
+<li>python 2.4:<ul>
+<li>no setuptools: <b>python <i>site-packages</i>/jcc/<strong>init</strong>.py</b></li>
+<li>with setuptools: <b>python <i>site-packages</i>/<i>jcc egg directory</i>/jcc/<strong>init</strong>.py</b></li>
+</ul>
</li>
+<li>python 2.3: <b>python <i>site-packages</i>/<i>jcc egg directory</i>/jcc/<strong>init</strong>.py</b></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
@@ -178,7 +172,7 @@ 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
+name on the command line or via the <i>--jar</i> 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>
@@ -192,7 +186,7 @@ interfaces </p>
</li>
<li>
<p>the type is available from one of the packages listed via the
-<code>--package</code> command line argument</p>
+<i>--package</i> command line argument</p>
</li>
</ul>
<p>Overloaded methods are supported and are selected at runtime on the
@@ -201,10 +195,10 @@ basis of the type and number of argument
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>
+called <i>field</i> when it finds Java methods
+named <i>setField(value)</i>,
+<i>getField()</i> or
+<i>isField()</i>.</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
@@ -285,7 +279,7 @@ $ python -m jcc # run JCC to w
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
+<p>Using the <i>--files</i> command line argument, this behaviour
can be tuned to workaround various limits:<br/>
for example:</p>
<ul>
@@ -302,47 +296,47 @@ for example:</p>
<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>
+<p>The <i>--prefix</i> and <i>--root</i> arguments are
+passed through to <i>distutils</i>' <i>setup()</i>.</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
+via <i>--jar</i> 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
+module's <i>CLASSPATH</i> 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
+to be made findable via JCC's <i>--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>
+extension's <i>CLASSPATH</i> variable before starting the VM
+with <i>initVM(CLASSPATH)</i>.</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
+and runtime, use the <i>--include</i> option. This option
+works like the <i>--jar</i> 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>
+the one with the shared classes by using the <i>--import</i>
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-wzxhzdk86distutilswzxhzdk87-vs-wzxhzdk88setuptoolswzxhzdk89">Using <code>distutils</code> vs <code>setuptools</code></h2>
+<h2 id="using-wzxhzdk66distutilswzxhzdk67-vs-wzxhzdk68setuptoolswzxhzdk69">Using <i>distutils</i> vs <i>setuptools</i></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>
+if <i>setuptools</i> is found to be installed, it is used
+over <i>distutils</i>. If you want to force the use
+of <i>distutils</i> over <i>setuptools</i>, use
+the <i>--use-distutils</i> 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,
+<p>The <i>--bdist</i> option can be used to ask JCC to
+invoke <i>distutils</i> with <i>bdist</i>
+or <i>setuptools</i>
+with <i>bdist_egg</i>. If <i>setuptools</i> is used,
the resulting egg has to be installed with the
-<a href="http://peak.telecommunity.com/DevCenter/EasyInstall"><code>easy_install</code></a>
+<a href="http://peak.telecommunity.com/DevCenter/EasyInstall"><i>easy_install</i></a>
installer which is normally part of a Python installation that
-includes <code>setuptools</code>.</p>
+includes <i>setuptools</i>.</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>
@@ -350,31 +344,31 @@ Python extension it produces.</p>
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
+<p>Instead, the <i>initVM()</i> function must be called from the
main thread before using any of the wrapped classes. It takes the
following keyword arguments:</p>
<ul>
<li>
-<p><code>classpath</code><br/>
+<p><i>classpath</i><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
+JCC exports a <i>CLASSPATH</i> 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.
+invoked with the <i>--install</i> 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.
+<i>CLASSPATH</i> string exported by the module
+<i>initVM</i> is imported from.
<pre><code>
>>> import lucene
>>> lucene.initVM(classpath=lucene.CLASSPATH)
</code></pre></p>
</li>
<li>
-<p><code>initialheap</code><br/>
+<p><i>initialheap</i><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.
+similar <i>-Xms</i> java command line argument.
<pre><code>
>>> import lucene
>>> lucene.initVM(initialheap='32m')
@@ -383,19 +377,19 @@ similar <code>-Xms</code> java command l
</code></pre></p>
</li>
<li>
-<p><code>maxheap</code><br/>
+<p><i>maxheap</i><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>
+the similar <i>-Xmx</i> java command line argument.</p>
</li>
<li>
-<p><code>maxstack</code><br/>
+<p><i>maxstack</i><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>
+similar <i>-Xss</i> java command line argument.</p>
</li>
<li>
-<p><code>vmargs</code><br/>
+<p><i>vmargs</i><br/>
A string of comma separated additional options to pass to the VM
startup rountine. These are passed through as-is. For example:
<pre><code>
@@ -404,34 +398,34 @@ startup rountine. These are passed throu
</code></pre></p>
</li>
</ul>
-<p>The <code>initVM()</code> and <code>getVMEnv()</code> functions
+<p>The <i>initVM()</i> and <i>getVMEnv()</i> functions
return a JCCEnv object that has a few utility methods on it:</p>
<ul>
<li>
-<p><code>attachCurrentThread(name, asDaemon)</code><br/>
+<p><i>attachCurrentThread(name, asDaemon)</i><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
+<p><i>detachCurrentThread()</i>
+The opposite of <i>attachCurrentThread()</i>. 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>
+<p>There are several differences between JNI's <i>findClass()</i>
+and Java's <i>Class.forName()</i>:</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>
+<p>the class loaders are different, <i>findClass()</i> may find
+classes that <i>Class.forName()</i> won't.</p>
</li>
</ul>
<p>For example:</p>
@@ -452,14 +446,14 @@ classes that <code>Class.forName()</code
<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
+unless the <i>--no-generics</i> 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>
+called <i>cast_</i> 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
+called <i>instance_</i> that tests whether the wrapped java
instance is of the given type. For example:</p>
<pre><code>
if BooleanQuery.instance_(query):
@@ -470,23 +464,23 @@ instance is of the given type. For examp
<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>
+to heed type parameters unless the <i>--no-generics</i>
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
+accessible as a tuple via the <i>parameters_</i> property.</p>
+<p>For example, an <i>ArrayList<Document></i> instance,
+has <i>(<type 'Document'>,)</i>
+for <i>parameters_</i> and its <i>get()</i> 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
+parameters use the <i>of_()</i> 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
+example, <i>java.util.ArrayList<E></i> is declared to
+accept one type parameter. Its wrapper's <i>of_()</i> method
hence accepts one parameter, a Python class, to use as type
-parameter for the return type of its <code>get()</code> method, among
+parameter for the return type of its <i>get()</i> method, among
others: </p>
<pre><code>
>>> a = ArrayList().of_(Document)
@@ -502,7 +496,7 @@ others: </p>
<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 />
+Downcasting from <i>Object</i> is then necessary:<br />
</p>
<pre><code>
>>> a = ArrayList()
@@ -520,16 +514,16 @@ Downcasting from <code>Object</code> is
<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
+template. The <i>[]</i> is available for read
+access. This template, <i>JArray<T></i>, accomodates all
+java primitive types, <i>jstring</i>, <i>jobject</i> and
wrapper class arrays.</p>
-<p>Java arrays are returned to Python in a <code>JArray</code> wrapper
+<p>Java arrays are returned to Python in a <i>JArray</i> 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>
+a <i>''.join(array)</i> 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
@@ -543,22 +537,22 @@ forms:</p>
# the resulting Java int array contains the ints in the sequence
</code></pre>
-<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>
+<p>Instead of <i>'int'</i>, you may also use one
+of <i>'object'</i>, <i>'string'</i>, <i>'bool'</i>,
+<i>'byte'</i>, <i>'char'</i>, <i>'double'</i>,
+<i>'float'</i>, <i>'long'</i> and <i>'short'</i>
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
+the <i>JArray('object')</i> 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
+optional and defaults to <i>Object</i>.</p>
+<p>As with the <i>Object</i> types, the <i>JArray</i> types
+also include a <i>cast_</i> 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
+plain <i>Object</i>. 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>
+wrapped by <i>JArray('object')</i>. For example:</p>
<pre><code>
# cast obj to an array of ints
>>> JArray('int').cast_(obj)
@@ -597,7 +591,7 @@ array type it is being cast to.</p>
</code></pre>
<p>To verify that a Java object is of a given array type, use
-the <code>instance_()</code> method available on the array
+the <i>instance_()</i> 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>
@@ -625,26 +619,26 @@ above:</p>
<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
+reported as a <i>javaError</i> 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
+VM are reported with a <i>JavaError</i> python exception
+object. The <i>getJavaException()</i> method can be called
+on <i>JavaError</i> 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
+are reported to the Java VM as a <i>RuntimeException</i> or as
+a <i>PythonException</i> when using shared
mode. See <a href="install.html">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>
+implements a special method called <i>pythonExtension()</i>
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
@@ -687,20 +681,20 @@ public class PythonAnalyzer extends Anal
}
</code></pre>
-<p>The <code>pythonExtension()</code> methods is what makes this class
+<p>The <i>pythonExtension()</i> 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
+the <i>pythonObject</i> instance variable.</p>
+<p>The implementation of the native <i>pythonDecRef()</i> method
is generated by JCC and is necessary because it seems
-that <code>finalize()</code> cannot itself be native. Since an
+that <i>finalize()</i> 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>
+for <i>pythonDecRef()</i> and a <i>finalize()</i>
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
+class and the other native methods, <i>tokenStream()</i> in
the example above.</p>
<p>The corresponding Python class(es) are implemented as follows:</p>
<pre><code>
@@ -732,13 +726,13 @@ class _analyzer(PythonAnalyzer):
return _tokenStream()
</code></pre>
-<p>When an <code><strong>init</strong>()</code> is declared, <code>super()</code>
+<p>When an <i><strong>init</strong>()</i> is declared, <i>super()</i>
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>
+call <i>super()</i> 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="http://svn.apache.org/viewvc/lucene/pylucene/trunk/samples">samples</a>.</p>
@@ -752,8 +746,8 @@ Following are the steps and constraints
<a href="install.html">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>
+with the link flags <i>"-framework", "Python"</i> in
+the <i>LFLAGS</i> value.</p>
</li>
<li>
<p>As described in the previous section, define one or more Java
@@ -763,41 +757,41 @@ of these classes implement the bridges i
Java.</p>
</li>
<li>
-<p>The <code>org.apache.jcc.PythonVM</code> Java class is going be
+<p>The <i>org.apache.jcc.PythonVM</i> 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>
+<i>jcc/classes</i> directory and the full path to this
+directory must be on the Java <i>CLASSPATH</i>.</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.
+called <i>libjcc.dylib</i> on Mac OS X,
+<i>libjcc.so</i> on Linux or <i>jcc.dll</i> 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>
+via the <i>-Djava.library.path</i> 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
+calling its static <i>start()</i> 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
+<i>sys.argv</i>. Note that the program name string is
purely informational, and is not used by the
-<code>start()</code> code other than to initialize that
+<i>start()</i> 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>
+instance to be used in this Java VM. <i>start()</i>
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>
+later time via the static <i>get()</i> method defined
+on the <i>org.apache.jcc.PythonVM</i> 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
+object by calling <i>acquireThreadState()</i> method on the
Python VM instance. It should then release the Python thread state
-before terminating by calling <code>releaseThreadState()</code>.
+before terminating by calling <i>releaseThreadState()</i>.
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
@@ -806,14 +800,14 @@ Java VM thread.</p>
<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
+section by calling the <i>instantiate()</i> 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>
+import and instantiate from it. The <i><strong>init</strong>()</i>
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
+and, if defined, must call <i>super()</i> in order to
+initialize the Java side. The <i>instantiate()</i> method is
+declared to return <i>java.lang.Object</i> but the return
value is actually an instance of the Java extension class used and
must be downcast to it.</p>
</li>
@@ -824,23 +818,23 @@ classes can be made iterable:</p>
<ul>
<li>
<p>When a class declares to
-implement <code>java.lang.Iterable</code>, JCC makes it iterable
+implement <i>java.lang.Iterable</i>, JCC makes it iterable
from Python.</p>
</li>
<li>
-<p>When a Java class declares a method called <code>next()</code>
+<p>When a Java class declares a method called <i>next()</i>
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>
+iterable. Its <i>next()</i> method is assumed to terminate
+iteration by returning <i>null</i>.</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
+to do so via the <i>--mapping</i> 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
+<p>For example, <i>System.getProperties()['java.class.path']</i> is
made possible by:</p>
<pre><code>
--mapping java.util.Properties
@@ -851,7 +845,7 @@ made possible by:</p>
</code></pre>
<p>JCC generates Python sequence length and get methods for a class
-when requested to do so via the <code>--sequence</code> command line
+when requested to do so via the <i>--sequence</i> 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
Modified: websites/staging/lucene/trunk/content/pylucene/jcc/install.html
==============================================================================
--- websites/staging/lucene/trunk/content/pylucene/jcc/install.html (original)
+++ websites/staging/lucene/trunk/content/pylucene/jcc/install.html Thu Aug 23 00:29:05 2012
@@ -167,7 +167,7 @@ Native Invocation Interface and expects
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-wzxhzdk13-sharedwzxhzdk14-flag">Shared Mode: Support for the <code>--shared</code> Flag</h2>
+<h2 id="shared-mode-support-for-the-wzxhzdk13-sharedwzxhzdk14-flag">Shared Mode: Support for the <i>--shared</i> 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