<commit_before>User Guide
==========

Overview
--------

JPype is an effort to allow python programs full access to java class
libraries. This is achieved not through re-implementing Python, as
Jython/JPython has done, but rather through interfacing at the native level
in both Virtual Machines.

Eventually, it should be possible to replace Java with python in many, though
not all, situations. JSP, Servlets, RMI servers and IDE plugins are all good
candidates.

Once this integration is achieved, a second phase will be started to separate
the Java logic from the Python logic, eventually allowing the bridging
technology to be used in other environments, I.E. Ruby, Perl, COM, etc ...

Why such a project?
~~~~~~~~~~~~~~~~~~~

As much as I enjoy programming in Python, there is no denying that Java has
the bulk of the mindshare. Just look on Sourceforge, at the time of creation
of this project, there were 3267 Python-related projects, and 12126 Java-
related projects. And that's not counting commercial interests.

Server-side Python is also pretty weak. Zope may be a great application
server, but I have never been able to figure it out. Java, on the other hand,
shines on the server.

So in order to both enjoy the language, and have access to the most popular
libraries, I have started this project.

What about Jython?
~~~~~~~~~~~~~~~~~~

Jython (formerly known as JPython) is a great idea. However, it suffers from
a large number of drawbacks, i.e. it always lags behind CPython, it is slow
and it does not allow access to most Python extensions.

My idea allows using both kinds of libraries in tandem, so the developer is
free to pick and choose.

Using JPype
~~~~~~~~~~~

Here is a sample program to demonstrate how to use JPype : ::

  from jpype import *
  startJVM("d:/tools/j2sdk/jre/bin/client/jvm.dll", "-ea")
  java.lang.System.out.println("hello world")
  shutdownJVM()

This is of course a simple **hello world** type of application. Yet it shows
the 2 most important calls : **startupJVM** and **shutdownJVM**.

The rest will be explained in more details in the next sections.

Core Ideas
----------

Threading
---------

Any non-trivial application will have need of threading. Be it implicitly by
using a GUI, or because you're writing a multi-user server. Or explicitly for
performance reason.

The only real problem here is making sure Java thread and Python threads
cooperate correctly. Thankfully, this is pretty easy to.

Python Threads
~~~~~~~~~~~~~~

For the most part, python threads based on OS level threads (i.e posix
threads), will work without problem. The only thing to remember is to call
**jpype.attachThreadToJVM()** in the thread body to make the JVM usable from
that thread. For threads that you do not start yourself, you can call
**isThreadAttachedToJVM()** to check.

Java Threads
~~~~~~~~~~~~

At the moment, it is not possible to use threads created from Java, since<commit_msg>"...easy to do.", not "...easy to."<commit_after>User Guide
==========

Overview
--------

JPype is an effort to allow python programs full access to java class
libraries. This is achieved not through re-implementing Python, as
Jython/JPython has done, but rather through interfacing at the native level
in both Virtual Machines.

Eventually, it should be possible to replace Java with python in many, though
not all, situations. JSP, Servlets, RMI servers and IDE plugins are all good
candidates.

Once this integration is achieved, a second phase will be started to separate
the Java logic from the Python logic, eventually allowing the bridging
technology to be used in other environments, I.E. Ruby, Perl, COM, etc ...

Why such a project?
~~~~~~~~~~~~~~~~~~~

As much as I enjoy programming in Python, there is no denying that Java has
the bulk of the mindshare. Just look on Sourceforge, at the time of creation
of this project, there were 3267 Python-related projects, and 12126 Java-
related projects. And that's not counting commercial interests.

Server-side Python is also pretty weak. Zope may be a great application
server, but I have never been able to figure it out. Java, on the other hand,
shines on the server.

So in order to both enjoy the language, and have access to the most popular
libraries, I have started this project.

What about Jython?
~~~~~~~~~~~~~~~~~~

Jython (formerly known as JPython) is a great idea. However, it suffers from
a large number of drawbacks, i.e. it always lags behind CPython, it is slow
and it does not allow access to most Python extensions.

My idea allows using both kinds of libraries in tandem, so the developer is
free to pick and choose.

Using JPype
~~~~~~~~~~~

Here is a sample program to demonstrate how to use JPype : ::

  from jpype import *
  startJVM("d:/tools/j2sdk/jre/bin/client/jvm.dll", "-ea")
  java.lang.System.out.println("hello world")
  shutdownJVM()

This is of course a simple **hello world** type of application. Yet it shows
the 2 most important calls : **startupJVM** and **shutdownJVM**.

The rest will be explained in more details in the next sections.

Core Ideas
----------

Threading
---------

Any non-trivial application will have need of threading. Be it implicitly by
using a GUI, or because you're writing a multi-user server. Or explicitly for
performance reason.

The only real problem here is making sure Java thread and Python threads
cooperate correctly. Thankfully, this is pretty easy to do.

Python Threads
~~~~~~~~~~~~~~

For the most part, python threads based on OS level threads (i.e posix
threads), will work without problem. The only thing to remember is to call
**jpype.attachThreadToJVM()** in the thread body to make the JVM usable from
that thread. For threads that you do not start yourself, you can call
**isThreadAttachedToJVM()** to check.

Java Threads
~~~~~~~~~~~~

At the moment, it is not possible to use threads created from Java, since
{'fraction_non_alphanumeric': 0.08748089009682351, 'fraction_numerical': 0.00373704773229149, 'mean_word_length': 4.106678230702515, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7511408', 'n_tokens_mistral': 1614, 'n_tokens_neox': 1518, 'n_words': 893}