javaclass

README.txt

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