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