:mod:`jcompile` -- Java 6 Compiler API Wrapper
====================================================

.. module:: jcompile
   :synopsis: Provides access to the Java Compiler API and implements a
              JavaCompiler wrapper class.
.. moduleauthor:: Kay Schluehr <kay@fiber-space.de>

The ``jcompile`` module implements the class ``JavaCompiler`` used to compile Java sources at runtime.
It relies on the Java Compiler API specified in JSR 199.

Classes
-------

.. versionchanged:: 0.3
    JavaCompiler keyword arguments ``remove`` and ``todisk`` were removed.

.. class:: JavaCompiler(processors = None [, store = False])

        :param processors: list of annotation processors that will be invoked by the javac compiler.
        :param store: when store is *True* the generated Java bytecode will be saved and stored
                       in a class file at ``org/jynx/gen``.
        :param remove: when *remove* is True the class file will be deleted after the Java bytecode
                       is loaded.


        .. method:: createClass(className, codeStr, *flags)

            :param className: the name of the Java class that shall be created. The name must coincide with
                              the class name in the source code.
            :param codeStr: the Java source code.
            :param flags: compiler flags specified for javac.
            :return: new Java class imported into Jython.

        .. method:: createAnnotation(annotationName, codeStr, *flags)

            :param annotationName: the name of the Java annotatiom that shall be created. The name must coincide with
                              the annotation name in the source code.
            :param codeStr: the Java annotation code.
            :param flags: compiler flags specified for javac.
            :return: new Java annotation imported into Jython.


**Examples:** ::

    codeStr = '''
    public class %s {
        public static void main(String args[])
        {
            System.out.println("Hello "+args[0]);
        }
    }'''

    Foo = JavaCompiler().createClass("Foo", codeStr%"Foo")

    Foo.main(["Jython!"])


External Links
--------------
| `JSR 199 <http://jcp.org/en/jsr/detail?id=199>`_
| `Blog article about dynamic Java compilation <http://fiber-space.de/wordpress/?p=858>`_