javaclass

Changeset

140:1afe376ec3fd
2005-01-22 Paul Boddie raw files shortlog changelog graph Updated the documentation.
README.txt (file) docs/index.html (file)
     1.1 --- a/README.txt	Fri Jan 21 18:22:28 2005 +0100
     1.2 +++ b/README.txt	Sat Jan 22 23:34:27 2005 +0100
     1.3 @@ -1,3 +1,21 @@
     1.4 +This file contains some information on the essential concepts and principles
     1.5 +involved in the use of this software.
     1.6 +
     1.7 +Installation
     1.8 +------------
     1.9 +
    1.10 +Usually, I issue this command first:
    1.11 +
    1.12 +python setup.py build
    1.13 +
    1.14 +The following should, in any case, be sufficient:
    1.15 +
    1.16 +python setup.py install
    1.17 +
    1.18 +I don't think distutils supports uninstall, but the installation just adds the
    1.19 +java and javaclass packages to your site-packages directory and the
    1.20 +runclass.py program to the same bin directory that python resides in.
    1.21 +
    1.22  Class Search Paths
    1.23  ------------------
    1.24  
    1.25 @@ -26,17 +44,14 @@
    1.26  Importing Classes
    1.27  -----------------
    1.28  
    1.29 -The classhook.py import hook needs to be made available before imports from
    1.30 -Java classes and libraries (.jar files) can take place. This can be done
    1.31 -by either...
    1.32 +In Python, the following statement should be enough to enable Java class
    1.33 +import:
    1.34  
    1.35 -  * Running the classhook.py file directly and then using the interactive
    1.36 -    interpreter:
    1.37 +  import javaclass.classhook
    1.38  
    1.39 -    python -i classhook.py
    1.40 -
    1.41 -  * Putting classhook.py in sys.path or PYTHONPATH and importing the
    1.42 -    classhook module before any code importing Java classes and packages.
    1.43 +(Other modules reside in the javaclass package, so it is possible to access
    1.44 +them without changing Python's import mechanisms, should such modification be
    1.45 +undesirable or unnecessary.)
    1.46  
    1.47  Importing Non-package Classes
    1.48  -----------------------------
    1.49 @@ -65,23 +80,12 @@
    1.50      tests directory would be run as follows:
    1.51  
    1.52      cd tests
    1.53 -    python ../runclass.py MainTest hello world
    1.54 -
    1.55 -    If runclass.py is executable and on the PATH, then the following can be
    1.56 -    used instead:
    1.57 -
    1.58 -    cd tests
    1.59      runclass.py MainTest hello world
    1.60  
    1.61    * Classes residing in packages can be run by ensuring that the packages
    1.62      are registered on the PYTHONPATH (see "Class Search Paths" above). Then,
    1.63      the testpackage.MainTest class (for example) would be run as follows:
    1.64  
    1.65 -    python runclass.py testpackage.MainTest hello world
    1.66 -
    1.67 -    If runclass.py is executable and on the PATH, then the following can be
    1.68 -    used instead:
    1.69 -
    1.70      runclass.py testpackage.MainTest hello world
    1.71  
    1.72  Accessing Python Libraries from Java
    1.73 @@ -95,30 +99,32 @@
    1.74  
    1.75    1. Compile the skeleton classes:
    1.76  
    1.77 -     javac examples/Qt/qtjava/QWidget.java
    1.78 +     javac examples/Tkinter/tkjava/*.java
    1.79  
    1.80    2. Compile the Java classes which use the wrapped Python libraries:
    1.81  
    1.82 -     javac -classpath examples/Qt examples/Qt/WidgetTest.java
    1.83 +     javac -classpath examples/Tkinter examples/Tkinter/Application.java
    1.84  
    1.85    3. Run the wrap.py tool on the directory where the skeleton class files
    1.86       reside, providing the name of the Python package or module being
    1.87       wrapped. This converts the directory into a Python package:
    1.88  
    1.89 -     PYTHONPATH=. python tools/wrap.py examples/Qt/qtjava qt
    1.90 +     python tools/wrap.py examples/Tkinter/tkjava Tkinter
    1.91  
    1.92 -     Since the Java class files, if left in the processed directory, would
    1.93 -     be detected and imported using the classhook.py import hook, and since
    1.94 -     this would result in two conflicting implementations being imported
    1.95 -     (with possibly the non-functional Java classes being made available
    1.96 -     instead of the generated wrapper classes), the wrap.py tool removes all
    1.97 -     processed class files, leaving only Python source files in the
    1.98 -     processed directory.
    1.99 +     Since the Java class files, if left in the processed directory, would be
   1.100 +     detected and imported using the special import hook, and since this would
   1.101 +     result in two conflicting implementations being imported (with possibly the
   1.102 +     non-functional Java classes being made available instead of the generated
   1.103 +     wrapper classes), the wrap.py tool removes all processed class files,
   1.104 +     leaving only Python source files in the processed directory.
   1.105  
   1.106    4. The Java classes which use the wrapped Python libraries can now be
   1.107 -     imported and used as described above. The wrapper package (qtjava in
   1.108 +     imported and used as described above. The wrapper package (tkjava in
   1.109       the above example) needs to reside in sys.path or PYTHONPATH, as must
   1.110 -     the wrapped library (qt in the above example).
   1.111 +     the wrapped library (Tkinter in the above example).
   1.112 +
   1.113 +     cd examples/Tkinter
   1.114 +     runclass.py Application
   1.115  
   1.116  Issues
   1.117  ------
     2.1 --- a/docs/index.html	Fri Jan 21 18:22:28 2005 +0100
     2.2 +++ b/docs/index.html	Sat Jan 22 23:34:27 2005 +0100
     2.3 @@ -15,7 +15,10 @@
     2.4  into Python, without the need for a Java virtual machine, so that the classes
     2.5  may be instantiated, accessed, run and manipulated just like Python classes,
     2.6  and that the resulting objects and methods can be accessed and manipulated
     2.7 -just like Python objects and methods.</p>
     2.8 +just like Python objects and methods. It should be possible to run compiled
     2.9 +Java programs with the Python interpreter and not notice that it isn't the
    2.10 +Java virtual machine being used - given sufficient library support for the
    2.11 +program concerned, of course.</p>
    2.12  
    2.13  <h2>Quick Examples</h2>
    2.14  
    2.15 @@ -97,20 +100,26 @@
    2.16  
    2.17  <p class="python-result">20050401</p>
    2.18  
    2.19 +<h2>Getting Started</h2>
    2.20 +
    2.21 +<p>See the <code>README.txt</code> file in the distribution directory.</p>
    2.22 +
    2.23  <h2>Motivation</h2>
    2.24  
    2.25  <p>Pick one of the following:</p>
    2.26  <ul>
    2.27    <li>The need/desire to access Java libraries from Python without firing up
    2.28 -    Java virtual machines or switching to Jython (and thereby losing access
    2.29 -    to various CPython libraries).</li>
    2.30 +    Java virtual machines or switching to Jython (and thereby losing
    2.31 +    convenient access to various CPython libraries).</li>
    2.32 +  <li>Mixing languages available for the Java runtime with Python.</li>
    2.33    <li>Static typing for the Python environment, albeit achieved by writing
    2.34      Java or other appropriate languages.</li>
    2.35    <li>Having an open source environment from top to bottom to run Java
    2.36      bytecode on.</li>
    2.37    <li>Experimentation around import hooks, bytecode generation; observation
    2.38      of different runtime and type systems interacting.</li>
    2.39 -  <li>Using Python libraries from Java.</li>
    2.40 +  <li>Making Python libraries available to Java programs - Tkinter for Java,
    2.41 +    anyone?!</li>
    2.42  </ul>
    2.43  
    2.44  <h2>Limitations</h2>
    2.45 @@ -129,7 +138,69 @@
    2.46      files (and .jar archives). Generally, anyone who is anyone in the Python
    2.47      pantheon has largely recommended against doing anything with the
    2.48      bytecode, despite noble efforts to make exciting things happen by
    2.49 -    transforming it, optimising it, and so on - </li>
    2.50 +    transforming it, optimising it, and so on. (Instead, there's been more
    2.51 +    emphasis on lots of runtime baggage for things which could be done by
    2.52 +    analysis of the code with modified bytecode being produced as a result,
    2.53 +    and let's not get started on some of the syntactical enhancements.)
    2.54 +    Consequently, stability might be an issue for some configurations,
    2.55 +    especially since CPython doesn't fail particularly graciously with badly
    2.56 +    behaved bytecode.</li>
    2.57 +  <li>Some of the translation from Java to Python bytecode takes a few
    2.58 +    liberties. For example, Java exceptions are handled in ways reminiscent
    2.59 +    of a 1980s microcomputer assembly language, whereas Python bytecode has
    2.60 +    higher level constructs for exceptions; this translation can probably be
    2.61 +    done incorrectly, triggering some kind of bytecode misbehaviour, and we
    2.62 +    all know what happens then.</li>
    2.63 +  <li>At the Python level, not all things seem totally right. For example,
    2.64 +    Java bytecode instructions are used to instantiate and then initialise
    2.65 +    exceptions just like other objects, and while Python can support this
    2.66 +    with new-style objects, Python won't let you use new-style objects as
    2.67 +    exceptions. Consequently, when Java exceptions appear in Python programs,
    2.68 +    they will be wrapped in old-style exceptions and have to be handled
    2.69 +    specially.</li>
    2.70 +  <li>In order to support method dispatch properly, special names are used
    2.71 +    for the translated methods which include the type information found in
    2.72 +    the bytecode; things like <code>main___java__lang__String_array_</code>
    2.73 +    and <code>setValue____I_</code> appear when you look inside classes and
    2.74 +    objects. When implementing libraries in Python for Java programs, such
    2.75 +    method naming conventions have to be used because the original code is
    2.76 +    very specific about which method is being invoked, and for specialised
    2.77 +    versions of <code>__init__</code> it becomes necessary to do a
    2.78 +    <code>setattr</code> to add such methods into classes because of various
    2.79 +    "name mangling" measures in the Python compilation process. Now, many
    2.80 +    people might start advocating decorators at this point, but not everyone
    2.81 +    is running the very latest stuff from python.org, and decorators won't
    2.82 +    help you target a specific specialised method anyway.</li>
    2.83 +  <li>Imported and translated bytecode is not written out or cached. This
    2.84 +    means that a fair amount of work happens every time you need to import
    2.85 +    Java classes, although the generation of .pyc files could be introduced
    2.86 +    provided that it captured the slightly different import semantics of
    2.87 +    Java; for example, you can import classes belonging to a package from
    2.88 +    several places on the PYTHONPATH, and this is something that generally
    2.89 +    isn't allowed/supported with the classic Python module import
    2.90 +  mechanisms.</li>
    2.91 +</ul>
    2.92 +
    2.93 +<h2>Suggestions for Python Improvements</h2>
    2.94 +<ul>
    2.95 +  <li>Make the bytecode interpreter more robust when encountering badly
    2.96 +    behaved bytecode, consider bytecode verification and other exciting
    2.97 +    features.</li>
    2.98 +  <li>Allow new-style objects as exceptions. Actually, just do something
    2.99 +    about the whole old-style vs. new-style class thing!</li>
   2.100 +  <li>Allow possible optimisation for things like statically predetermined
   2.101 +    method calls. The debate about static typing intersects slightly with the
   2.102 +    need to define methods with parameters of particular types, but
   2.103 +    supporting Java-style method "coexistence" (or multimethods, or whatever
   2.104 +    the proper name is) would presumably involve doing lots of things to the
   2.105 +    language that were once thought to be highly un-Pythonic. Besides, the
   2.106 +    need to interoperate with statically typed languages shouldn't dictate
   2.107 +    the design of Python, especially if better type systems could be adopted
   2.108 +    instead, leaving the static typing glue for strictly special
   2.109 +  occasions.</li>
   2.110 +  <li>Not that threaded Java programs have been run on Python yet, but with
   2.111 +    Python's current threading architecture I'd expect some
   2.112 +  disappointment.</li>
   2.113  </ul>
   2.114  </body>
   2.115  </html>