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