1 Class Search Paths
2 ------------------
3
4 Java classes belonging to packages are located using sys.path or PYTHONPATH
5 in the same way that they would be located using the Java classpath (or
6 CLASSPATH environment variable). Thus, the rules for locating package
7 classes are as follows:
8
9 * Classes residing within plain directories which represent a package
10 hierarchy can be accessed by putting the parent directory of the top of
11 the package hierarchy on the PYTHONPATH (or sys.path). For example, a
12 package called mypackage, represented by a directory of the same name at
13 /home/java/classes/mypackage, would be made accessible by adding the
14 /home/java/classes directory to the PYTHONPATH.
15
16 * Classes residing within .jar files can be accessed by putting the path to
17 each .jar file on the PYTHONPATH. For example, a package called
18 mypackage, represented by a file located at /home/java/lib/mypackage.jar,
19 would be made accessible by adding the /home/java/lib/mypackage.jar file
20 to the PYTHONPATH.
21
22 Note that classes not belonging to a package cannot be accessed via such
23 search paths and are made available using a special module (see "Non-package
24 Classes" below).
25
26 Importing Classes
27 -----------------
28
29 The classhook.py import hook needs to be made available before imports from
30 Java classes and libraries (.jar files) can take place. This can be done
31 by either...
32
33 * Running the classhook.py file directly and then using the interactive
34 interpreter:
35
36 python -i classhook.py
37
38 * Putting classhook.py in sys.path or PYTHONPATH and importing the
39 classhook module before any code importing Java classes and packages.
40
41 Importing Non-package Classes
42 -----------------------------
43
44 Classes which do not belong to a package are only accessible when residing
45 in the current working directory of any program attempting to use them. Such
46 classes will not be made available automatically, but must be imported from
47 a special module called __this__.
48
49 * Usage of the "import __this__" statement will cause all classes in the
50 current directory to be made available within the __this__ module.
51
52 * Usage of the "from __this__ import" construct will cause all classes in
53 the current directory to be processsed, but only named classes will be
54 made available in the global namespace unless "*" was specified (which
55 will, as usual, result in all such classes being made available).
56
57 Running Java Classes
58 --------------------
59
60 Java classes with a public, static main method can be run directly using the
61 runclass.py program.
62
63 * Free-standing classes (ie. not belonging to packages) can be run from
64 the directory in which they reside. For example, suitable classes in the
65 tests directory would be run as follows:
66
67 cd tests
68 python ../runclass.py MainTest hello world
69
70 If runclass.py is executable and on the PATH, then the following can be
71 used instead:
72
73 cd tests
74 runclass.py MainTest hello world
75
76 * Classes residing in packages can be run by ensuring that the packages
77 are registered on the PYTHONPATH (see "Class Search Paths" above). Then,
78 the testpackage.MainTest class (for example) would be run as follows:
79
80 python runclass.py testpackage.MainTest hello world
81
82 If runclass.py is executable and on the PATH, then the following can be
83 used instead:
84
85 runclass.py testpackage.MainTest hello world
86
87 Accessing Python Libraries from Java
88 ------------------------------------
89
90 To wrap Python libraries for use with Java, skeleton classes need to be
91 compiled corresponding to each of the wrapped classes. Each of the methods
92 in the skeleton classes can be empty (or return any permissible value) since
93 the only purpose they serve is to provide the Java compiler with information
94 about the Python libraries.
95
96 1. Compile the skeleton classes:
97
98 javac examples/Qt/qtjava/QWidget.java
99
100 2. Compile the Java classes which use the wrapped Python libraries:
101
102 javac -classpath examples/Qt examples/Qt/WidgetTest.java
103
104 3. Run the wrap.py tool on the directory where the skeleton class files
105 reside, providing the name of the Python package or module being
106 wrapped. This converts the directory into a Python package:
107
108 PYTHONPATH=. python tools/wrap.py examples/Qt/qtjava qt
109
110 Since the Java class files, if left in the processed directory, would
111 be detected and imported using the classhook.py import hook, and since
112 this would result in two conflicting implementations being imported
113 (with possibly the non-functional Java classes being made available
114 instead of the generated wrapper classes), the wrap.py tool removes all
115 processed class files, leaving only Python source files in the
116 processed directory.
117
118 4. The Java classes which use the wrapped Python libraries can now be
119 imported and used as described above. The wrapper package (qtjava in
120 the above example) needs to reside in sys.path or PYTHONPATH, as must
121 the wrapped library (qt in the above example).
122
123 Issues
124 ------
125
126 Investigate better exception raising. Currently, exceptions have to be
127 derived from object so that object.__new__ can be used upon them. However,
128 this seems to prevent them from being raised, and they need to be wrapped
129 within Exception so that the information can be transmitted to the
130 exception's handler.
131
132 Consider nicer ways of writing the method names in Python, perhaps using a
133 function which takes the individual parameter types as arguments.