2005-02-13 Paul Boddie Introduced initial measures for handling circular imports/references.
     1 This file contains some information on the essential concepts and principles
     2 involved in the use of this software.
     4 Installation
     5 ------------
     7 Usually, I issue this command first:
     9   python build
    11 The following should, in any case, be sufficient:
    13   python install
    15 I don't think distutils supports uninstall, but the installation just adds
    16 the java and javaclass packages to your site-packages directory and the
    17 program to the same bin directory that python resides in.
    19 Testing
    20 -------
    22 It should be possible to just run the program and see the results:
    24   python
    26 Class Search Paths
    27 ------------------
    29 Java classes belonging to packages are located using sys.path or PYTHONPATH
    30 in the same way that they would be located using the Java classpath (or
    31 CLASSPATH environment variable). Thus, the rules for locating package
    32 classes are as follows:
    34  * Classes residing within plain directories which represent a package
    35    hierarchy can be accessed by putting the parent directory of the top of
    36    the package hierarchy on the PYTHONPATH (or sys.path). For example, a
    37    package called mypackage, represented by a directory of the same name at
    38    /home/java/classes/mypackage, would be made accessible by adding the
    39    /home/java/classes directory to the PYTHONPATH.
    41  * Classes residing within .jar files can be accessed by putting the path to
    42    each .jar file on the PYTHONPATH. For example, a package called
    43    mypackage, represented by a file located at /home/java/lib/mypackage.jar,
    44    would be made accessible by adding the /home/java/lib/mypackage.jar file
    45    to the PYTHONPATH.
    47 Note that classes not belonging to a package cannot be accessed via such
    48 search paths and are made available using a special module (see "Non-package
    49 Classes" below).
    51 Importing Classes
    52 -----------------
    54 In Python, the following statement should be enough to enable Java class
    55 import:
    57   import javaclass.classhook
    59 (Other modules reside in the javaclass package, so it is possible to access
    60 them without changing Python's import mechanisms, should such modification
    61 be undesirable or unnecessary.)
    63 Importing Non-package Classes
    64 -----------------------------
    66 Classes which do not belong to a package are only accessible when residing
    67 in the current working directory of any program attempting to use them. Such
    68 classes will not be made available automatically, but must be imported from
    69 a special module called __this__.
    71  * Usage of the "import __this__" statement will cause all classes in the
    72    current directory to be made available within the __this__ module.
    74  * Usage of the "from __this__ import" construct will cause all classes in
    75    the current directory to be processsed, but only named classes will be
    76    made available in the global namespace unless "*" was specified (which
    77    will, as usual, result in all such classes being made available).
    79 Running Java Classes
    80 --------------------
    82 Java classes with a public, static main method can be run directly using the
    83 program.
    85   * Free-standing classes (ie. not belonging to packages) can be run from
    86     the directory in which they reside. For example, suitable classes in the
    87     tests directory would be run as follows:
    89     cd tests
    90 MainTest hello world
    92   * Classes residing in packages can be run by ensuring that the packages
    93     are registered on the PYTHONPATH (see "Class Search Paths" above). Then,
    94     the testpackage.MainTest class (for example) would be run as follows:
    96 testpackage.MainTest hello world
    98 Accessing Python Libraries from Java
    99 ------------------------------------
   101 To wrap Python libraries for use with Java, skeleton classes need to be
   102 compiled corresponding to each of the wrapped classes. Each of the methods
   103 in the skeleton classes can be empty (or return any permissible value) since
   104 the only purpose they serve is to provide the Java compiler with information
   105 about the Python libraries.
   107   1. Compile the skeleton classes:
   109      javac examples/Tkinter/tkjava/*.java
   111   2. Compile the Java classes which use the wrapped Python libraries:
   113      javac -classpath examples/Tkinter examples/Tkinter/
   115   3. Run the tool on the directory where the skeleton class files
   116      reside, providing the name of the Python package or module being
   117      wrapped. This converts the directory into a Python package:
   119      python tools/ examples/Tkinter/tkjava Tkinter
   121      Since the Java class files, if left in the processed directory, would
   122      be detected and imported using the special import hook, and since this
   123      would result in two conflicting implementations being imported (with
   124      possibly the non-functional Java classes being made available instead
   125      of the generated wrapper classes), the tool removes all
   126      processed class files, leaving only Python source files in the
   127      processed directory.
   129   4. The Java classes which use the wrapped Python libraries can now be
   130      imported and used as described above. The wrapper package (tkjava in
   131      the above example) needs to reside in sys.path or PYTHONPATH, as must
   132      the wrapped library (Tkinter in the above example).
   134      cd examples/Tkinter
   135 Application
   137 Issues
   138 ------
   140 The test program crashes, fairly quickly under Python 2.4, too. There seems
   141 to be some kind of memory allocation problem.
   143 Implement better importing mechanisms so that circular module dependencies
   144 can be avoided. For example, when dealing with java.lang classes which
   145 depend on classes which then inherit from java.lang.Object,
   146 the classes should all be imported but only initialised after no more
   147 importing is necessary. Since usage of external names is recorded in the
   148 bytecode translation process, it should be possible to reach such a
   149 condition definitively.
   151 Investigate better exception raising. Currently, exceptions have to be
   152 derived from object so that object.__new__ can be used upon them. However,
   153 this seems to prevent them from being raised, and they need to be wrapped
   154 within Exception so that the information can be transmitted to the
   155 exception's handler.
   157 Consider nicer ways of writing the method names in Python, perhaps using a
   158 function which takes the individual parameter types as arguments.
   160 Release Procedures
   161 ------------------
   163 Update the javaclass/ __version__ attribute.
   164 Update the release notes (see above).
   165 Check the file and ensure that all package directories are
   166 mentioned.
   167 Tag, export.
   168 Rename ClassFile to javaclass (and add the release to the directory name).
   169 Archive, upload.