README file for PyLucene
  ------------------------

  Contents
  --------

   - Welcome
   - Differences between PyLucene with GCJ and PyLucene with JCC


  Welcome
  -------

  Welcome to PyLucene, a Python extension for Java Lucene.
  PyLucene is a project maintained by the Open Source Applications Foundation.

  PyLucene now comes in two flavors: the original PyLucene built with GCJ and
  the new PyLucene built with JCC, a code generator integrating Java classes
  with Python via C++ and Java's Native Invocation Interface.

  PyLucene with GCJ can be found in the 'gcj' sub-directory.
  PyLucene with JCC can be found in the 'jcc' sub-directory.

  For more information on PyLucene, consider joining the PyLucene mailing list
  at pylucene-dev@osafoundation.org or visit http://pylucene.osafoundation.org.
  See http://lists.osafoundation.org/mailman/listinfo/pylucene-dev for more
  information on the PyLycene mailing list.

  For more information on GCJ, please visit http://gcc.gnu.org/java.

  For more information on JCC, please see view the README file in the
  jcc/jcc sub-directory.


  Differences between PyLucene with GCJ and PyLucene with JCC
  -----------------------------------------------------------

  PyLucene with JCC being completely generated by JCC, there are inevitable
  differences with handcoded PyLucene with GCJ. Below is an attempt to list
  them. Differences omitted here can be be found by diff'ing the unit tests
  and samples which were duplicated and ported from PyLucene with GCJ to
  PyLucene with JCC.

    - The Python module name is now called 'lucene'. This makes it possible
      to have both flavors of PyLucene installed at the same time to do
      comparisons. Also, given that PyLucene is really no longer
      hand-crafted, giving it a module name identical to the original felt
      like the right thing to do.

    - There are several functions where PyLucene formerly accepted a Python
      int, but the underlying Java code expected a long. Such casts must be
      done explicitly now, using long().  Failure to do so will raise a
      InvalidArgsError.

    - Berkeley DB support is dropped. It is simpler and easier to implement
      it in Python directly via a Python implementation of the classes in
      org.apache.lucene.store. For an example, please refer to
      jcc/test/test_PythonDirectory.py.

    - Writing extensions of Java Lucene classes in Python is now
      considerably easier and described in jcc/jcc/README. PyLucene with JCC
      comes with many extension examples in its test cases and "Lucene in
      Action" samples.

    - To run, PyLucene with JCC requires a Java Runtime Environment to be
      present and found. This is not really that different from PyLucene
      with GCJ as libgcj.so is that runtime environment. On platforms such
      as Mac OS X, a Java Runtime Environment is installed by default.

    - Before using any classes in the PyLucene with JCC package, the Java VM
      must be started. Because starting a Java VM can require lots of
      configuration parameters, this is not done automatically.
      Starting the Java VM in Python is usually as simple as this:

        >>> import lucene
        >>> lucene.initVM(lucene.CLASSPATH)

      See jcc/README and jcc/jcc/README for more information.

    - Threading is now fully supported. It is no longer necessary to use any
      of the PyLucene with gcj threading kludges.

      The only requirement before using PyLucene APIs from a thread not
      created by the Java VM is to call attachCurrentThread() on the JCCEnv
      object returned by the initVM() or getVMEnv() functions.

    - At this time, PyLucene with JCC has only been built and tested on
      Intel Mac OS X 10.4.10. It is expected to build and run on other Unix
      flavors. Better support on other platforms and Windows is forthcoming.