javaclass

README.txt

122:bbadc235f0a8
2005-01-13 Paul Boddie Hopefully improved the clarity of the documentation, adding notes on running classes. Minor change to runclass.py, hopefully making it executable.
     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.