paul@140 | 1 | This file contains some information on the essential concepts and principles
|
paul@140 | 2 | involved in the use of this software.
|
paul@140 | 3 |
|
paul@140 | 4 | Installation
|
paul@140 | 5 | ------------
|
paul@140 | 6 |
|
paul@186 | 7 | To build the software, perhaps as part of a packaging process, you can run the
|
paul@186 | 8 | following command:
|
paul@140 | 9 |
|
paul@147 | 10 | python setup.py build
|
paul@140 | 11 |
|
paul@186 | 12 | To directly install the software in a system-wide location, you can run the
|
paul@186 | 13 | following command:
|
paul@140 | 14 |
|
paul@147 | 15 | python setup.py install
|
paul@140 | 16 |
|
paul@186 | 17 | The installation adds the java and javaclass packages to your site-packages
|
paul@186 | 18 | directory and the runclass.py program to the same bin directory that python
|
paul@186 | 19 | resides in. However, it is arguably preferable to make an operating system
|
paul@186 | 20 | package for the software and use the system's package manager to install and
|
paul@186 | 21 | potentially uninstall the software.
|
paul@140 | 22 |
|
paul@147 | 23 | Testing
|
paul@147 | 24 | -------
|
paul@147 | 25 |
|
paul@147 | 26 | It should be possible to just run the test.py program and see the results:
|
paul@147 | 27 |
|
paul@147 | 28 | python test.py
|
paul@147 | 29 |
|
paul@186 | 30 | Contact, Copyright and Licence Information
|
paul@186 | 31 | ------------------------------------------
|
paul@186 | 32 |
|
paul@186 | 33 | The current Web page for javaclass at the time of release is:
|
paul@186 | 34 |
|
paul@186 | 35 | http://www.boddie.org.uk/python/javaclass.html
|
paul@186 | 36 |
|
paul@186 | 37 | Copyright and licence information can be found in the docs directory - see
|
paul@186 | 38 | docs/COPYING.txt, docs/lgpl-3.0.txt and docs/gpl-3.0.txt for more information.
|
paul@186 | 39 |
|
paul@186 | 40 | Dependencies
|
paul@186 | 41 | ------------
|
paul@186 | 42 |
|
paul@186 | 43 | Python Tested with Python 2.3, although javaclass.classfile
|
paul@186 | 44 | should work on any recent Python 2.x release.
|
paul@186 | 45 |
|
paul@186 | 46 | A Java toolchain Tested with whichever Sun JDK for Java release was current
|
paul@186 | 47 | in 2005. ;-)
|
paul@186 | 48 |
|
paul@122 | 49 | Class Search Paths
|
paul@122 | 50 | ------------------
|
paul@122 | 51 |
|
paul@122 | 52 | Java classes belonging to packages are located using sys.path or PYTHONPATH
|
paul@122 | 53 | in the same way that they would be located using the Java classpath (or
|
paul@122 | 54 | CLASSPATH environment variable). Thus, the rules for locating package
|
paul@122 | 55 | classes are as follows:
|
paul@122 | 56 |
|
paul@122 | 57 | * Classes residing within plain directories which represent a package
|
paul@122 | 58 | hierarchy can be accessed by putting the parent directory of the top of
|
paul@122 | 59 | the package hierarchy on the PYTHONPATH (or sys.path). For example, a
|
paul@122 | 60 | package called mypackage, represented by a directory of the same name at
|
paul@122 | 61 | /home/java/classes/mypackage, would be made accessible by adding the
|
paul@122 | 62 | /home/java/classes directory to the PYTHONPATH.
|
paul@122 | 63 |
|
paul@122 | 64 | * Classes residing within .jar files can be accessed by putting the path to
|
paul@122 | 65 | each .jar file on the PYTHONPATH. For example, a package called
|
paul@122 | 66 | mypackage, represented by a file located at /home/java/lib/mypackage.jar,
|
paul@122 | 67 | would be made accessible by adding the /home/java/lib/mypackage.jar file
|
paul@122 | 68 | to the PYTHONPATH.
|
paul@122 | 69 |
|
paul@122 | 70 | Note that classes not belonging to a package cannot be accessed via such
|
paul@122 | 71 | search paths and are made available using a special module (see "Non-package
|
paul@122 | 72 | Classes" below).
|
paul@122 | 73 |
|
paul@122 | 74 | Importing Classes
|
paul@122 | 75 | -----------------
|
paul@99 | 76 |
|
paul@140 | 77 | In Python, the following statement should be enough to enable Java class
|
paul@140 | 78 | import:
|
paul@99 | 79 |
|
paul@140 | 80 | import javaclass.classhook
|
paul@99 | 81 |
|
paul@140 | 82 | (Other modules reside in the javaclass package, so it is possible to access
|
paul@161 | 83 | them without changing Python's import mechanisms, should such modification
|
paul@161 | 84 | be undesirable or unnecessary.)
|
paul@99 | 85 |
|
paul@122 | 86 | Importing Non-package Classes
|
paul@122 | 87 | -----------------------------
|
paul@99 | 88 |
|
paul@122 | 89 | Classes which do not belong to a package are only accessible when residing
|
paul@122 | 90 | in the current working directory of any program attempting to use them. Such
|
paul@122 | 91 | classes will not be made available automatically, but must be imported from
|
paul@122 | 92 | a special module called __this__.
|
paul@99 | 93 |
|
paul@122 | 94 | * Usage of the "import __this__" statement will cause all classes in the
|
paul@122 | 95 | current directory to be made available within the __this__ module.
|
paul@99 | 96 |
|
paul@122 | 97 | * Usage of the "from __this__ import" construct will cause all classes in
|
paul@122 | 98 | the current directory to be processsed, but only named classes will be
|
paul@122 | 99 | made available in the global namespace unless "*" was specified (which
|
paul@122 | 100 | will, as usual, result in all such classes being made available).
|
paul@99 | 101 |
|
paul@122 | 102 | Running Java Classes
|
paul@122 | 103 | --------------------
|
paul@99 | 104 |
|
paul@122 | 105 | Java classes with a public, static main method can be run directly using the
|
paul@122 | 106 | runclass.py program.
|
paul@99 | 107 |
|
paul@122 | 108 | * Free-standing classes (ie. not belonging to packages) can be run from
|
paul@122 | 109 | the directory in which they reside. For example, suitable classes in the
|
paul@122 | 110 | tests directory would be run as follows:
|
paul@99 | 111 |
|
paul@122 | 112 | cd tests
|
paul@122 | 113 | runclass.py MainTest hello world
|
paul@122 | 114 |
|
paul@122 | 115 | * Classes residing in packages can be run by ensuring that the packages
|
paul@122 | 116 | are registered on the PYTHONPATH (see "Class Search Paths" above). Then,
|
paul@122 | 117 | the testpackage.MainTest class (for example) would be run as follows:
|
paul@99 | 118 |
|
paul@122 | 119 | runclass.py testpackage.MainTest hello world
|
paul@99 | 120 |
|
paul@99 | 121 | Accessing Python Libraries from Java
|
paul@99 | 122 | ------------------------------------
|
paul@99 | 123 |
|
paul@99 | 124 | To wrap Python libraries for use with Java, skeleton classes need to be
|
paul@99 | 125 | compiled corresponding to each of the wrapped classes. Each of the methods
|
paul@99 | 126 | in the skeleton classes can be empty (or return any permissible value) since
|
paul@99 | 127 | the only purpose they serve is to provide the Java compiler with information
|
paul@99 | 128 | about the Python libraries.
|
paul@99 | 129 |
|
paul@99 | 130 | 1. Compile the skeleton classes:
|
paul@99 | 131 |
|
paul@140 | 132 | javac examples/Tkinter/tkjava/*.java
|
paul@99 | 133 |
|
paul@99 | 134 | 2. Compile the Java classes which use the wrapped Python libraries:
|
paul@99 | 135 |
|
paul@140 | 136 | javac -classpath examples/Tkinter examples/Tkinter/Application.java
|
paul@99 | 137 |
|
paul@99 | 138 | 3. Run the wrap.py tool on the directory where the skeleton class files
|
paul@99 | 139 | reside, providing the name of the Python package or module being
|
paul@99 | 140 | wrapped. This converts the directory into a Python package:
|
paul@99 | 141 |
|
paul@140 | 142 | python tools/wrap.py examples/Tkinter/tkjava Tkinter
|
paul@99 | 143 |
|
paul@161 | 144 | Since the Java class files, if left in the processed directory, would
|
paul@161 | 145 | be detected and imported using the special import hook, and since this
|
paul@161 | 146 | would result in two conflicting implementations being imported (with
|
paul@161 | 147 | possibly the non-functional Java classes being made available instead
|
paul@161 | 148 | of the generated wrapper classes), the wrap.py tool removes all
|
paul@161 | 149 | processed class files, leaving only Python source files in the
|
paul@161 | 150 | processed directory.
|
paul@99 | 151 |
|
paul@99 | 152 | 4. The Java classes which use the wrapped Python libraries can now be
|
paul@140 | 153 | imported and used as described above. The wrapper package (tkjava in
|
paul@122 | 154 | the above example) needs to reside in sys.path or PYTHONPATH, as must
|
paul@140 | 155 | the wrapped library (Tkinter in the above example).
|
paul@140 | 156 |
|
paul@140 | 157 | cd examples/Tkinter
|
paul@140 | 158 | runclass.py Application
|
paul@99 | 159 |
|
paul@99 | 160 | Issues
|
paul@99 | 161 | ------
|
paul@99 | 162 |
|
paul@176 | 163 | Fix the class initialisation so that non-Java classes (and already imported
|
paul@176 | 164 | classes) are obtained. Prevent re-entry into module importing for modules
|
paul@176 | 165 | already being imported (if this is not handled already by the Python import
|
paul@176 | 166 | mechanisms).
|
paul@161 | 167 |
|
paul@166 | 168 | Implement better importing mechanisms so that circular module dependencies
|
paul@166 | 169 | can be avoided. For example, when dealing with java.lang classes which
|
paul@166 | 170 | depend on java.security classes which then inherit from java.lang.Object,
|
paul@166 | 171 | the classes should all be imported but only initialised after no more
|
paul@166 | 172 | importing is necessary. Since usage of external names is recorded in the
|
paul@166 | 173 | bytecode translation process, it should be possible to reach such a
|
paul@166 | 174 | condition definitively.
|
paul@166 | 175 |
|
paul@176 | 176 | The test program crashes, fairly quickly under Python 2.4, too. There seems
|
paul@176 | 177 | to be some kind of memory allocation problem.
|
paul@176 | 178 |
|
paul@92 | 179 | Investigate better exception raising. Currently, exceptions have to be
|
paul@92 | 180 | derived from object so that object.__new__ can be used upon them. However,
|
paul@92 | 181 | this seems to prevent them from being raised, and they need to be wrapped
|
paul@92 | 182 | within Exception so that the information can be transmitted to the
|
paul@92 | 183 | exception's handler.
|
paul@92 | 184 |
|
paul@92 | 185 | Consider nicer ways of writing the method names in Python, perhaps using a
|
paul@92 | 186 | function which takes the individual parameter types as arguments.
|
paul@153 | 187 |
|
paul@186 | 188 | New in javaclass 0.2 (Changes since javaclass 0.1)
|
paul@186 | 189 | --------------------------------------------------------
|
paul@186 | 190 |
|
paul@186 | 191 | * Added Braden Thomas' class file serialisation patches.
|
paul@186 | 192 | * Relicensed under the LGPL version 3 or later.
|
paul@186 | 193 |
|
paul@153 | 194 | Release Procedures
|
paul@153 | 195 | ------------------
|
paul@153 | 196 |
|
paul@153 | 197 | Update the javaclass/__init__.py __version__ attribute.
|
paul@153 | 198 | Update the release notes (see above).
|
paul@186 | 199 | Update the setup.py and PKG-INFO files.
|
paul@161 | 200 | Check the setup.py file and ensure that all package directories are
|
paul@161 | 201 | mentioned.
|
paul@153 | 202 | Tag, export.
|
paul@153 | 203 | Archive, upload.
|