javaclass

README.txt

120:14b1b75cd8c2
2005-01-13 Paul Boddie Fixed the importing of package classes.
     1 Importing Java Classes and Libraries
     2 ------------------------------------
     3 
     4 The classhook.py import hook needs to be made available before imports from
     5 Java classes and libraries (.jar files) can take place. This can be done
     6 by either...
     7 
     8   1. Running the classhook.py file directly and then using the interactive
     9      interpreter:
    10 
    11      python -i classhook.py
    12 
    13   2. Putting classhook.py in sys.path or PYTHONPATH and importing the
    14      classhook module before any code importing Java classes and packages.
    15 
    16 Java classes are located using sys.path or PYTHONPATH in the same way that
    17 they would be located using the Java classpath (or CLASSPATH environment
    18 variable).
    19 
    20   * Directories representing packages and containing Java class files must
    21     reside within directories specified on the PYTHONPATH. For example, the
    22     directory mypackage residing within /home/paulb/java would be used as
    23     follows:
    24 
    25     PYTHONPATH=/home/paulb/java python -i classhook.py
    26 
    27     And within Python:
    28 
    29     import mypackage
    30 
    31     Note that the classes within the directory should be assigned to the
    32     package mypackage.
    33 
    34   * Free-standing Java class files must reside in the current directory.
    35     For example, a collection of class files in /home/paulb/classes would be
    36     used as follows:
    37 
    38     cd /home/paulb/classes
    39     python -i /home/paulb/python/classhook.py
    40 
    41     And within Python:
    42 
    43     import __this__
    44 
    45     Note that such free-standing classes should not be assigned to any
    46     package and must therefore appear within the special package __this__
    47     and be imported under such special conditions.
    48 
    49   * Libraries contained within .jar files must be specified directly on the
    50     PYTHONPATH as if they were directories containing package hierarchies.
    51     For example, the library archive.jar, residing within /home/paulb/java
    52     and containing the package mypackage, would be used as follows:
    53 
    54     PYTHONPATH=/home/paulb/java/archive.jar python -i classhook.py
    55 
    56     And within Python:
    57 
    58     import mypackage
    59 
    60 Accessing Python Libraries from Java
    61 ------------------------------------
    62 
    63 To wrap Python libraries for use with Java, skeleton classes need to be
    64 compiled corresponding to each of the wrapped classes. Each of the methods
    65 in the skeleton classes can be empty (or return any permissible value) since
    66 the only purpose they serve is to provide the Java compiler with information
    67 about the Python libraries.
    68 
    69   1. Compile the skeleton classes:
    70 
    71      javac examples/Qt/qtjava/QWidget.java
    72 
    73   2. Compile the Java classes which use the wrapped Python libraries:
    74 
    75      javac -classpath examples/Qt examples/Qt/WidgetTest.java
    76 
    77   3. Run the wrap.py tool on the directory where the skeleton class files
    78      reside, providing the name of the Python package or module being
    79      wrapped. This converts the directory into a Python package:
    80 
    81      PYTHONPATH=. python tools/wrap.py examples/Qt/qtjava qt
    82 
    83      Since the Java class files, if left in the processed directory, would
    84      be detected and imported using the classhook.py import hook, and since
    85      this would result in two conflicting implementations being imported
    86      (with possibly the non-functional Java classes being made available
    87      instead of the generated wrapper classes), the wrap.py tool removes all
    88      processed class files, leaving only Python source files in the
    89      processed directory.
    90 
    91   4. The Java classes which use the wrapped Python libraries can now be
    92      imported and used as described above. The wrapper package needs to
    93      reside in sys.path or PYTHONPATH, as must the wrapped library.
    94 
    95 Issues
    96 ------
    97 
    98 Investigate better exception raising. Currently, exceptions have to be
    99 derived from object so that object.__new__ can be used upon them. However,
   100 this seems to prevent them from being raised, and they need to be wrapped
   101 within Exception so that the information can be transmitted to the
   102 exception's handler.
   103 
   104 Consider nicer ways of writing the method names in Python, perhaps using a
   105 function which takes the individual parameter types as arguments.