javaclass

Changeset

99:0546fc332f6f
2005-01-10 Paul Boddie raw files shortlog changelog graph Added some notes about using the software.
README.txt (file)
     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