1.1 --- a/README.txt Sun Jan 09 22:53:27 2005 +0100
1.2 +++ b/README.txt Mon Jan 10 00:19:27 2005 +0100
1.3 @@ -1,3 +1,100 @@
1.4 +Importing Java Classes and Libraries
1.5 +------------------------------------
1.6 +
1.7 +The classhook.py import hook needs to be made available before imports from
1.8 +Java classes and libraries (.jar files) can take place. This can be done
1.9 +by either...
1.10 +
1.11 + 1. Running the classhook.py file directly and then using the interactive
1.12 + interpreter:
1.13 +
1.14 + python -i classhook.py
1.15 +
1.16 + 2. Putting classhook.py in sys.path or PYTHONPATH and importing the
1.17 + classhook module before any code importing Java classes and packages.
1.18 +
1.19 +Java classes are located using sys.path or PYTHONPATH in the same way that
1.20 +they would be located using the Java classpath (or CLASSPATH environment
1.21 +variable).
1.22 +
1.23 + * Directories representing packages and containing Java class files must
1.24 + reside within directories specified on the PYTHONPATH. For example, the
1.25 + directory mypackage residing within /home/paulb/java would be used as
1.26 + follows:
1.27 +
1.28 + PYTHONPATH=/home/paulb/java python -i classhook.py
1.29 +
1.30 + And within Python:
1.31 +
1.32 + import mypackage
1.33 +
1.34 + Note that the classes within the directory should be assigned to the
1.35 + package mypackage.
1.36 +
1.37 + * Free-standing Java class files must reside in the current directory.
1.38 + For example, a collection of class files in /home/paulb/classes would be
1.39 + used as follows:
1.40 +
1.41 + cd /home/paulb/classes
1.42 + python -i /home/paulb/python/classhook.py
1.43 +
1.44 + And within Python:
1.45 +
1.46 + import __this__
1.47 +
1.48 + Note that such free-standing classes should not be assigned to any
1.49 + package and must therefore appear within the special package __this__
1.50 + and be imported under such special conditions.
1.51 +
1.52 + * Libraries contained within .jar files must be specified directly on the
1.53 + PYTHONPATH as if they were directories containing package hierarchies.
1.54 + For example, the library archive.jar, residing within /home/paulb/java
1.55 + and containing the package mypackage, would be used as follows:
1.56 +
1.57 + PYTHONPATH=/home/paulb/java/archive.jar python -i classhook.py
1.58 +
1.59 + And within Python:
1.60 +
1.61 + import mypackage
1.62 +
1.63 +Accessing Python Libraries from Java
1.64 +------------------------------------
1.65 +
1.66 +To wrap Python libraries for use with Java, skeleton classes need to be
1.67 +compiled corresponding to each of the wrapped classes. Each of the methods
1.68 +in the skeleton classes can be empty (or return any permissible value) since
1.69 +the only purpose they serve is to provide the Java compiler with information
1.70 +about the Python libraries.
1.71 +
1.72 + 1. Compile the skeleton classes:
1.73 +
1.74 + javac examples/Qt/qtjava/QWidget.java
1.75 +
1.76 + 2. Compile the Java classes which use the wrapped Python libraries:
1.77 +
1.78 + javac -classpath examples/Qt examples/Qt/WidgetTest.java
1.79 +
1.80 + 3. Run the wrap.py tool on the directory where the skeleton class files
1.81 + reside, providing the name of the Python package or module being
1.82 + wrapped. This converts the directory into a Python package:
1.83 +
1.84 + PYTHONPATH=. python tools/wrap.py examples/Qt/qtjava qt
1.85 +
1.86 + Since the Java class files, if left in the processed directory, would
1.87 + be detected and imported using the classhook.py import hook, and since
1.88 + this would result in two conflicting implementations being imported
1.89 + (with possibly the non-functional Java classes being made available
1.90 + instead of the generated wrapper classes), the wrap.py tool removes all
1.91 + processed class files, leaving only Python source files in the
1.92 + processed directory.
1.93 +
1.94 + 4. The Java classes which use the wrapped Python libraries can now be
1.95 + imported and used as described above. The wrapper package needs to
1.96 + reside in sys.path or PYTHONPATH, as must the wrapped library.
1.97 +
1.98 +Issues
1.99 +------
1.100 +
1.101 Investigate better exception raising. Currently, exceptions have to be
1.102 derived from object so that object.__new__ can be used upon them. However,
1.103 this seems to prevent them from being raised, and they need to be wrapped