javaclass

Annotated README.txt

99:0546fc332f6f
2005-01-10 Paul Boddie Added some notes about using the software.
paul@99 1
Importing Java Classes and Libraries
paul@99 2
------------------------------------
paul@99 3
paul@99 4
The classhook.py import hook needs to be made available before imports from
paul@99 5
Java classes and libraries (.jar files) can take place. This can be done
paul@99 6
by either...
paul@99 7
paul@99 8
  1. Running the classhook.py file directly and then using the interactive
paul@99 9
     interpreter:
paul@99 10
paul@99 11
     python -i classhook.py
paul@99 12
paul@99 13
  2. Putting classhook.py in sys.path or PYTHONPATH and importing the
paul@99 14
     classhook module before any code importing Java classes and packages.
paul@99 15
paul@99 16
Java classes are located using sys.path or PYTHONPATH in the same way that
paul@99 17
they would be located using the Java classpath (or CLASSPATH environment
paul@99 18
variable).
paul@99 19
paul@99 20
  * Directories representing packages and containing Java class files must
paul@99 21
    reside within directories specified on the PYTHONPATH. For example, the
paul@99 22
    directory mypackage residing within /home/paulb/java would be used as
paul@99 23
    follows:
paul@99 24
paul@99 25
    PYTHONPATH=/home/paulb/java python -i classhook.py
paul@99 26
paul@99 27
    And within Python:
paul@99 28
paul@99 29
    import mypackage
paul@99 30
paul@99 31
    Note that the classes within the directory should be assigned to the
paul@99 32
    package mypackage.
paul@99 33
paul@99 34
  * Free-standing Java class files must reside in the current directory.
paul@99 35
    For example, a collection of class files in /home/paulb/classes would be
paul@99 36
    used as follows:
paul@99 37
paul@99 38
    cd /home/paulb/classes
paul@99 39
    python -i /home/paulb/python/classhook.py
paul@99 40
paul@99 41
    And within Python:
paul@99 42
paul@99 43
    import __this__
paul@99 44
paul@99 45
    Note that such free-standing classes should not be assigned to any
paul@99 46
    package and must therefore appear within the special package __this__
paul@99 47
    and be imported under such special conditions.
paul@99 48
paul@99 49
  * Libraries contained within .jar files must be specified directly on the
paul@99 50
    PYTHONPATH as if they were directories containing package hierarchies.
paul@99 51
    For example, the library archive.jar, residing within /home/paulb/java
paul@99 52
    and containing the package mypackage, would be used as follows:
paul@99 53
paul@99 54
    PYTHONPATH=/home/paulb/java/archive.jar python -i classhook.py
paul@99 55
paul@99 56
    And within Python:
paul@99 57
paul@99 58
    import mypackage
paul@99 59
paul@99 60
Accessing Python Libraries from Java
paul@99 61
------------------------------------
paul@99 62
paul@99 63
To wrap Python libraries for use with Java, skeleton classes need to be
paul@99 64
compiled corresponding to each of the wrapped classes. Each of the methods
paul@99 65
in the skeleton classes can be empty (or return any permissible value) since
paul@99 66
the only purpose they serve is to provide the Java compiler with information
paul@99 67
about the Python libraries.
paul@99 68
paul@99 69
  1. Compile the skeleton classes:
paul@99 70
paul@99 71
     javac examples/Qt/qtjava/QWidget.java
paul@99 72
paul@99 73
  2. Compile the Java classes which use the wrapped Python libraries:
paul@99 74
paul@99 75
     javac -classpath examples/Qt examples/Qt/WidgetTest.java
paul@99 76
paul@99 77
  3. Run the wrap.py tool on the directory where the skeleton class files
paul@99 78
     reside, providing the name of the Python package or module being
paul@99 79
     wrapped. This converts the directory into a Python package:
paul@99 80
paul@99 81
     PYTHONPATH=. python tools/wrap.py examples/Qt/qtjava qt
paul@99 82
paul@99 83
     Since the Java class files, if left in the processed directory, would
paul@99 84
     be detected and imported using the classhook.py import hook, and since
paul@99 85
     this would result in two conflicting implementations being imported
paul@99 86
     (with possibly the non-functional Java classes being made available
paul@99 87
     instead of the generated wrapper classes), the wrap.py tool removes all
paul@99 88
     processed class files, leaving only Python source files in the
paul@99 89
     processed directory.
paul@99 90
paul@99 91
  4. The Java classes which use the wrapped Python libraries can now be
paul@99 92
     imported and used as described above. The wrapper package needs to
paul@99 93
     reside in sys.path or PYTHONPATH, as must the wrapped library.
paul@99 94
paul@99 95
Issues
paul@99 96
------
paul@99 97
paul@92 98
Investigate better exception raising. Currently, exceptions have to be
paul@92 99
derived from object so that object.__new__ can be used upon them. However,
paul@92 100
this seems to prevent them from being raised, and they need to be wrapped
paul@92 101
within Exception so that the information can be transmitted to the
paul@92 102
exception's handler.
paul@92 103
paul@92 104
Consider nicer ways of writing the method names in Python, perhaps using a
paul@92 105
function which takes the individual parameter types as arguments.