Files changed (54)
Binary file modified.
+In the past, mainstream concurrent programming generally meant ensuring that the code interacting with relatively slow network, disk, database, and other I/O resources did not unduly slow things down.
+Exploiting parallelism was typically only seen in such domains as scientific computing with the apps running on supercomputers.
+The semiconductor industry continues to work feverishly to uphold Mooreâs Law of exponential increase in chip density.
+For a variety of reasons this old approach no longer works as well, so now chip designers are cramming chips with more CPUs and hardware threads.
+Speeding up execution means harnessing the parallelism of the hardware, and it is now our job as software developers to do that work.
+The Java platform is arguably the most robust environment for running concurrent code today, and this functionality can be readily be used from Jython.
+This is especially true with respect to a concurrency model based on threads, which is what todayâs hardware natively exposes.
+This means we have to be concerned with thread safety, which arises as an issue because of the existence of mutable objects that are shared between threads.
+(Mutable state might be avoidable in functional programming, but it would be hard to avoid in any but the most trivial Python code.) If you attempt to solve concurrency issues through synchronization, you run into other problems: besides the potential performance hit, there are opportunities for deadlock and livelock.
+ Queues and related objects -- like synchronization barriers -- provide a structured mechanism to hand over objects between threads.
+One issue that you will have to consider in writing concurrent code is how much to make your implementation dependent on the Java platform.
+- If you are porting an existing Python code base that uses concurrency, you can just use the standard Python threading module.
+ Such code can still interoperate with Java, because Jython threads are always mapped to Java threads.
+ (If you are coming from Java, you will recognize this API, since it is substantially based on Javaâs.)
+ This means you can just use these standard Python types, and still get high performance concurrency.
+ So if it fits your appâs needs, you may want to consider using such collections as CopyOnWriteArrayList and ConcurrentSkipListMap (new in Java 6).
+ This is particular true of the executor services for running and managing tasks against thread pools.
+ So for example, avoid using threading.Timer, because you can use timed execution services in its place.
+ In particular, these constructs have been optimized to work in the context of a with-statement, as we will discuss.
+In practice, using Javaâs support for higher level primitives should not impact the portability of your code so much.
+Using tasks in particular tends to keep all of this well isolated, and such thread safety considerations as thread confinement and safe publication remain the same.
+Be careful not to inadvertently invoke the function; target takes a reference to the function object (typically a name if a normal function).
+Calling the function instead creates an amusing bug where your target function runs now, so everything looks fine at first.
+But no concurrency is happening, because the function call is actually being run by the invoking thread, not this new thread.
+The target function can be a regular function, or an object that is callable (implements __call__).
+As we will see, publishing results into variables is safe in Jython, but itâs not the nicest way.
+ Upon JVM shutdown, any daemon threads are simply terminated, without an opportunityâor needâto perform cleanup or orderly shutdown.
+ This lack of cleanup means itâs important that daemon threads never hold any external resources, such as database connections or file handles.
+ For similar reasons, a daemon thread should never make an import attempt, as this can interfere with Jythonâs orderly shutdown.
+ In production, the only use case for daemon threads is when they are strictly used to work with in-memory objects, typically for some sort of housekeeping.
+ Likewise, a later example demonstrating deadlock uses daemon threads to enable shutdown without waiting on these deadlocked threads.
+The threading.local class enables each thread to have its own instances of some objects in an otherwise shared environment.
+Its usage is deceptively simple:simply create an instance of threading.local, or a subclass, and assign it to a variable or other name.
+Threads can then share the variable, but with a twist: each thread will see a different, thread-specific version of the object.
+This object can have arbitrary attributes added to it, each of which will not be visible to other threads.
+But one unique, and potentially useful, aspect is that any attributes specified in __slots__ will be *shared* across threads.
+Usually they donât make sense because threads are not the right scope, but an object or a function is, especially through a closure.
+If you are using thread locals, you are implicitly adopting a model where threads are partitioning the work.
+ Historically, this may have been in fact faster, but it now slows things down, and unnecessarily limits what a given thread can do.
+ A future refactoring of Jython will likely remove the use of âThreadStateâ completely, simultaneously speeding and cleaning things up.
+ And of course, if you are using code whose architecture mandates thread locals, itâs just something you will have to work with.
+Take advantage of the fact that Python is a dynamic language, with strong support for metaprogramming, and remember that the Jython implementation makes these techniques accessible when working with even recalcitrant Java code.
+They do not work well in a task-oriented model, because you donât want to associate context with a worker thread that will be assigned to arbitrary tasks.
+This restriction also applies to much of the supporting runtime as well as extension modules that do not release the GIL.
+(Unfortunately development efforts to remove the GIL in CPython have so far only had the effect of slowing down Python execution significantly.)
+The impact of the GIL on CPython programming is that threads are not as useful as they are in Jython.
+Concurrency will only be seen in interacting with I/O as well as scenarios where computation is performed by an extension module on data structures managed outside of CPythonâs runtime.
+Instead, developers typically will use a process-oriented model to evade the restrictiveness of the GIL.
+This is because all Python threads are mapped to Java threads and use standard Java garbage collection support (the main reason for the GIL in CPython is because of the reference counting GC system).
+The important ramification here is that you can use threads for compute-intensive tasks that are written in Python.
+This is true whether the import goes through the import statement, the equivalent __import__ builtin, or related code.
+Itâs important to note that even if the corresponding module has already been imported, the module import lock will still be acquired, if only briefly.
+Just keep in mind that thread(s) performing such imports will be forced to run single threaded because of this lock.
+So as you can see, you need to do at least two imports of a given module; one in the background thread; the other in the actual place(s) where the moduleâs namespace is being used.
+Hereâs why we need the module import lock: upon the first import, the import procedure runs the (implicit) top-level function of the module.
+Even though many modules are often declarative in nature, in Python all definitions are done at runtime.
+Such definitions potentially include further imports (recursive imports), and the top-level function can certainly perform much more complex tasks.
+Note that in the current implementation, the module import lock is global for the entire Jython runtime.
+Although there are other options, the object you submit to be executed should implement Javaâs Callable interface (a call method without arguments), as this best maps into working with a Python method or function.
+Tasks move through the states of being created, submitted (to an executor), started, and completed.
+This might be one thread, a thread pool, or as many threads as necessary to run all currently submitted tasks concurrently.
+The specific choice comprises the executor policy, but generally you want to use a thread pool so as to control the degree of concurrency.
+*Futures* allow code to access the result of a computation -- or an exception, if thrown -- in a task only at the point when itâs needed.
+We are going to look at how we can use this functionality by using the example of downloading web pages.
+We will wrap this up so itâs easy to work with, tracking the state of the download, as well as any timing information.
+In Jython any other task could be done in this fashion, whether it is a database query or a computationally intensive task written in Python.
+Upon completion of a future, either the result is returned, or an exception is thrown into the caller.
+(This pushing of the exception into the asynchronous caller is thus similar to how a coroutine works when send is called on it.)
+However, you may need to take into account that this shutdown can happen during extraordinary times in your code.
+Hereâs the Jython version of a robust shutdown function, shutdown_and_await_termination, as provided in the standard Java docs.
+The scenario is that instead of waiting for all the futures to complete, as our code did with invokeAll, or otherwise polling them, the completion service will push futures as they are completed onto a synchronized queue.
+Although it may be tempting to then schedule everything through the completion serviceâs queue, there are limits.
+For example, if youâre writing a scalable web spider, you would want to externalize this work queue, but for simple management, it would certainly suffice.
+ Why use tasks instead of threads? A common practice too often seen in production code is the addition of threading in a haphazard fashion:
+ This can result in a ratsâ nest of threads synchronizing on a variety of objects, often with timers and other event sources thrown in the mix.
+ Itâs certainly possible to make this sort of setup workâjust debug awayâbut using tasks, with explicit wait-on dependencies and time scheduling, makes it far simpler to build a simple, scalable system.
+- Can the (unintended) interaction of two or more threads corrupt a mutable object? This is especially dangerous for a collection like a list or a dictionary, because such corruption could potentially render the underlying data structure unusable or even produce infinite loops when traversing it.
+ In this case, there can be a data race with another thread in the time between retrieving the current value, and then updating with the incremented value.
+Jython ensures that its underlying mutable collection types -- dict, list, and set -- cannot be corrupted.
+However, other Java collection objects that your code might use would typically not have such no-corruption guarantees.
+If you need to use LinkedHashMap, so as to support an ordered dictionary, you will need to consider thread safety if it will be both shared and mutated.
+For example, we use this idea in Jython to test that certain operations on the list type are atomic.
+The net result should be right where you started, an empty list, which is what the test code asserts.
+Commonly used objects like strings, numbers, datetimes, tuples, and frozen sets are immutable, and you can create your own immutable objects too.
+We use synchronization to control the entry of threads into code blocks corresponding to synchronized resources.
+(In Jython, but unlike CPython, such locks are always reentrant; thereâs no distinction between threading.Lock and threading.RLock.) Other threads have to wait until that thread exits the lock.
+You should generally manage the entry and exit of such locks through a with-statement; failing that, you must use a try-finally to ensure that the lock is always released when exiting a block of code.
+Itâs actually slower than the with-statement, and using the with-statement version also results in more idiomatic Python code.
+This module provides a ``make_synchronized`` decorator function, which wraps any callable in Jython in a synchronized block.
+Even in the case of an exception, the synchronization lock is always released upon exit from the function.
+Again, this version is also slower than the with-statement form, and it doesnât use explicit locks.
+ Jythonâs current runtime (as of 2.5.1) can execute the with-statement form more efficiently through both runtime support and how this statement is compiled.
+ The reason is that most JVMs can perform analysis on a chunk of code (the *compilation unit*, including any inlining) to avoid synchronization overhead, so long as two conditions are met.
+ The with-statementâs semantics make it relatively easy for us to do that when working with built-in types like threading.Lock, while avoiding the overhead of Java runtime reflection.
+ In the future, support of the new invokedynamic bytecode should collapse these performance differences.
+You may want to use the synchronizers in Java.util.concurrent instead of their wrapped versions in threading.
+Also, you may want to use factories like Collections.synchronizedMap, when applicable, to ensure the underlying Java object has the desired synchronization.
+Without a timeout or other change in strategyâAlice just gets tired of waiting on Bob!âthis deadlock will not be broken.
+Avoiding deadlocks can be done by never acquiring locks such that a cycle like that can be created.
+If we rewrote the example so that locks are acquired in the same order (Bob always allows Alice to go first), there would be no deadlocks.
+(Synchronized queues are also called blocking queues, and thatâs how they are described in java.util.concurrent.) Such queues represent a thread-safe way to send objects from one or more producing threads to one or more consuming threads.
+If you need to implement another policy, such as last-in, first-out or based on a priority, you can use the comparable synchronized queues in java.util.concurrent as appropriate.
+(Note these have since been implemented in Python 2.6, so they will be made available when Jython 2.6 is eventually released.)
+Condition objects allow for one thread to notify another thread thatâs waiting on a condition to wake up; notifyAll is used to wake up all such threads.
+Your code needs to bracket waiting and notifying the condition by acquiring the corresponding lock, then finally (as always!) releasing it.
+For example, hereâs how we actually implement a Queue in the standard library of Jython (just modified here to use the with-statement).
+We canât use a standard Java blocking queue, because the requirement of being able to join on the queue when thereâs no more work to be performed requires a third condition variable.
+You can use semaphores to describe scenarios where itâs possible for multiple threads to enter, or use locks that are set up to distinguish reads from writes.
+Data races and object corruption do not occur, and itâs not possible for other threads to see an inconsistent view.
+In addition, atomic operations will often use underlying support in the CPU, such as a compare-and-swap instruction.
+Python guarantees the atomicity of certain operations, although at best itâs only informally documented.
+Fredrik Lundhâs article on âThread Synchronization Methods in Pythonâ summarizes the mailing list discussions and the state of the CPython implementation.
+For CPython, this atomicity emerges from combining its Global Interpreter Lock (GIL), the Python bytecode virtual machine execution loop, and the fact that types like dict and list are implemented natively in C and do not release the GIL.
+Despite the fact that this is in some sense accidentally emergent, it is a useful simplification for the developer.
+In particular, because dict is a ConcurrentHashMap, we also expose the following methods to atomically update dictionaries:
+Often, you still need to use synchronization to prevent data races, and this has to be done with care to avoid deadlocks and starvation.
+In practice, you probably donât need to share a large percentage of the mutable objects used in your code.
+ For example, if you are building up a buffer that is only pointed to by a local variable, you donât need to synchronize.
+ Itâs an easy prescription to follow, so long as you are not trying to keep around these intermediate objects to avoid allocation overhead: donât do that.
+ For example, if you are using modjy, then the database connection pools and thread pools are the responsibility of the servlet container.
+ (But donât do things like share database connections across threads.) Caches and databases then are where you will see shared state.
+ Send and receive messages to an actor (effectively an independent thread) and let it manipulate any objects it owns on your behalf.
+ The message queue can then ensure any accesses are appropriately serialized, so there are no thread safety issues.
+For example, if you use StringIO, you have to pay the cost that this class uses list, which is synchronized.
+Although itâs possible to further optimize the Jython implementation of the Python standard library, if a section of code is hot enough, you may want to consider rewriting that in Java to ensure no additional synchronization overhead.
+Lastly, thread confinement is not perfect in Python, because of the possibility of introspecting on frame objects.
+This is because the memory model is not as surprising to our conventional reasoning about how programs operate.
+In order to maximize Java performance, itâs allowed for a CPU to arbitrarily re-order the operations performed by Java code, subject to the constraints imposed by *happens-before* and *synchronizes-with* relationships.
+(The published Java memory model goes into more details on these constraints.) Although such reordering is not visible within a given thread, the problem is that itâs visible to other threads.
+Of course, this visibility only applies to changes made to non-local objects; thread confinement still applies.
+In particular, this means you cannot rely on the apparent sequential ordering of Java code when looking at two or more threads.
+The fundamental thing to know about Python, and what we have implemented in Jython, is that setting any attribute in Python is a volatile write; and getting any attribute is a volatile read.
+This is because Python attributes are stored in dictionaries, and in Jython, this follows the semantics of the backing ConcurrentHashMap.
+Because this is always a memory-fenced operation in Python, your code simply needs to ensure that the object itself is built in a thread-safe fashion; then publish it all at once by setting the appropriate variable to this object.
+If you need to create module-level objectsâsingletonsâthen you should do this in the top-level script of the module so that the module import lock is in effect.
+In particular, if a thread is waiting on most any synchronizers, such as a condition variable or on file I/O, this action will cause the waited-on method to exit with an InterruptedException.
+(Unfortunately lock acquisition, except under certain cases such as using lockInterruptibly on the underlying Java lock, is not interruptible.)
+Although Pythonâs threading module does not itself support interruption, it is available through the standard Java thread API.
+First, letâs import this class (we will rename it to JThread so it doesnât conflict with Pythonâs version).
+So logically you should be able to do the converse: use Python threads as if they are Java threads.
+ Incidentally, this formulation, instead of obj.interrupt(), looks like a static method on a class, as long as we pass in the object as the first argument.
+As of the latest released version (Jython 2.5.1), we forgot to include an appropriate __tojava__ method on the Thread class! So this looks like you canât do this trick after all.
+Or can you? What if you didnât have to wait until we fix this bug? You could explore the source code -- or look at the class with dir.
+We can *monkey patch* the Thread class such that it has an appropriate __tojava__ method, but only if it doesnât exist.
+So this patching is likely to work with a future version of Jython because we are going to fix this missing method before we even consider changing its implementation and removing _thread.
+But again, you shouldnât worry too much when you keep such fixes to a minimum, especially when itâs essentially a bug fix like this one.
+In our case, we will use a variant, the monkeypatch_method_if_not_set decorator, to ensure we only patch if it has not been fixed by a later version.
+You can also use the standard Python threading constructs, which in most cases just wrap the corresponding Java functionality.
+The standard mutable Python collection types have been implemented in Jython with concurrency in mind; and Pythonâs sequential consistency removes some potential bugs.
+However, they are all very similar and usually allow deployment of WAR file or exploded directory web applications.
+Some cloud environments have typical Java application servers available for hosting, while others such as the Google App Engine run a bit differently.
+In this chapter, weâll discuss how to deploy web-based Jython applications to a few of the more widely used Java application servers.
+We will also cover deployment of Jython web applications to the Google App Engine and mobile devices.
+Although many of the deployment scenarios are quite similar, this chapter will walk through some of the differences from container to container.
+In the end, one of the most important things to remember is that we need to make Jython available to our application.
+There are different ways to do this: either by ensuring that the *jython.jar* file is included with the application server, or by packaging the JAR directly into each web application.
+Placing the *jython.jar* directly into each web application is a good idea because it allows the web application to follow the Java paradigm of âdeploy anywhere.â You do not need to worry whether you are deploying to Tomcat or Glassfish because the Jython runtime is embedded in your application.
+Lastly, this section will briefly cover some of the reasons why mobile deployment is not yet a viable option for Jython.
+While a couple of targets exist in the mobile world, namely Android and JavaFX, both environments are still very new and Jython has not yet been optimized to run on either.
+As with any Java web application, the standard web archive (WAR) files are universal throughout the Java application servers available today.
+This is good because it makes things a bit easier when it comes to the âwrite once run everywhereâ philosophy that has been brought forth with the Java name.
+The great part of using Jython for deployment to application servers is just that, we can harness the technologies of the JVM to make our lives easier and deploy a Jython web application to any application server in the WAR format with very little tweaking.
+If you have not yet used Django or Pylons on Jython, then you may not be aware that the resulting application to be deployed is in the WAR format.
+This section will discuss how to deploy a WAR file on each of the three most widely used Java application servers.
+Now, all application servers are not covered in this section mainly due to the number of servers available today.
+However, you should be able to follow similar deployment instructions as those discussed here for any of the application servers available today for deploying Jython web applications in the WAR file format.
+Arguably the most widely used of all Java application servers, Tomcat offers easy management and a small footprint compared to some of the other options available.
+Tomcat will plug into most IDEs that are in use today, so you can manage the web container from within your development environment.
+For the purposes of this section, weâve used Netbeans 6.7, so there may be some references to it.
+To get started, download the Apache Tomcat server from the site at http://tomcat.apache.org/. Tomcat is constantly evolving, so weâll note that when writing this book the deployment procedures were targeted for the 6.0.20 release.
+Once you have downloaded the server and placed it into a location on your hard drive, you may have to change permissions.
+We had to use the *chmod +x* command on the entire apache-tomcat-6.0.20 directory before we were able to run the server.
+You will also need to configure an administrative account by going into the */conf/tomcat-users.xml* file and adding one.
+After this has been done, you can add the installation to an IDE environment of your choice if youâd like.
+For instance, if you wish to add to Netbeans 6.7 you will need to go to the âServicesâ tab in the navigator, right-click on servers, choose âTomcat 6.xâ option, and then fill in the appropriate information pertaining to your environment.
+Deploying a web start application is as easy as copying the necessary files to a location on the web server that is accessible via the web.
+In the case of Tomcat, you will need to copy the contents of your web start application to a single directory contained within the â<tomcat-root>/webapps/ROOTâ directory.
+For instance, if you have a web-start application entitled , then you would package the JAR file along with the JNLP and HTML file for the application into a directory entitled and then place that directory into the â<tomcat-root>/webapps/ROOTâ directory.
+Once the application has been copied to the appropriate locations, you should be able to access it via the web if Tomcat is started.
+The URL should look something like the following: *http://your-server:8080/JythonWebStart/launch.jnlp*.
+Of course, you will need to use the server name and the port that you are using along with the appropriate JNLP name for your application.
+You can either use a WAR file including all content for your entire web application, or you can deploy an exploded directory application which is basically copy-and-paste for your entire web application directory structure into the â<tomcat-root>/webapps/ROOTâ directory.
+For manual deployment of a web application, you can copy either your exploded directory web application or your WAR file into the â<tomcat-root>/webappsâ directory.
+This means that you can have Tomcat started when you copy your WAR or exploded directory into the âwebappsâ location.
+Once youâve done this, you should see some feedback from the Tomcat server if you have a terminal open (or from within the IDE).
+The bonus to deploying exploded directory applications is that you can take any file within the application and change it at will.
+If you do not wish to have autodeploy enabled (perhaps in a production environment), then you can deploy applications on startup of the server.
+This process is basically the same as âautodeploy,â except any new applications that are copied into the âwebappsâ directory are not deployed until the server is restarted.
+To do this, open your web browser to the index of Tomcat, usually http://localhost:8080/index.html, and then click on the âManagerâ link in the left-hand menu.
+You will need to authenticate at that point using your administrator password, but once you are in the console deployment is quite easy.
+In an effort to avoid redundancy, we will once again redirect you to the Tomcat documentation for more information on deploying a web application via the Tomcat manager console.
+The Glassfish V3 server was still in preview mode, but showed a lot of potential for Jython application deployment.
+In this section, we will cover WAR and web start deployment to Glassfish V2, because it is the most widely used version.
+We will also discuss deployment for Django on Glassfish V3, because this version has added support for Django (and more Python web frameworks soon).
+Glassfish is very similar to Tomcat in terms of deployment, but there are a couple of minor differences which will be covered in this section.
+To start out, you will need to download a glassfish distribution from the site at https://glassfish.dev.java.net/. Again, we recommend downloading V2, because it is the most widely used at the time of this writing.
+The installation of Glassfish will not be covered in this text, because it varies depending upon which version you are using.
+There are detailed instructions for each version located on the Glassfish website, so we will redirect you there for more information.
+Once you have Glassfish installed, you can utilize the server via the command-line or terminal, or you can use an IDE just like Tomcat.
+To register a Glassfish V2 or V3 installation with Netbeans 6.7, just go to the âServicesâ tab in the Netbeans navigator and right-click on âServersâ and then add the version you are planning to register.
+Once the âAdd Server Instanceâ window appears, simply fill in the information depending upon your environment.
+There is an administrative user named âadminâ that is set up by default with a Glassfish installation.
+In order to change the default password, it is best to startup Glassfish and log into the administrative console.
+Deploying a web start application is basically the same as any other web server, you simply make the web start JAR, JNLP, and HTML file accessible via the web.
+On Glassfish, you need to traverse into your âdomainâ directory and you will find a âdocrootâ inside.
+The path should be similar to â<glassfish-install-loc>/domains/domain1/docrootâ. Anything placed within the docroot area is visible to the web, so of course this is where you will place any web-start application directories.
+Again, a typical web start application will consist of your application JAR file, a JNLP file, and an HTML page used to open the JNLP.
+All of these files should typically be placed inside a directory appropriately named per your application, and then you can copy this directory into docroot.
+Letâs assume that you are using V2, you have the option to âhot deployâ or use the Glassfish Admin Console to deploy your application.
+By default, the Glassfish âautodeployâ option is turned on, so it is quite easy to either copy your WAR or exploded directory application into the autodeploy location to deploy.
+If the application server is started, it will automatically start your application (if it runs without issues).
+The autodeploy directory for Glassfish V2 resides in the location â<glassfish-install-loc>/domains/domain1/autodeploy.â
+The Glassfish V3 server has some capabilities built into it to help facilitate the process of deploying a Django application.
+If you have read through the information contained in the previous sections, then you have a fairly good idea of what it is like to deploy a Jython web application to a Java application server.
+There is no difference between deploying Jython web applications and Java web applications for the most part.
+You must be sure that you include as mentioned in the introduction, but for the most part deployment is the same.
+However, we have run into cases with some application servers such as JBoss where it wasnât so cut-and-dry to run a Jython application.
+For instance, we have tried to deploy a Jython servlet application on JBoss application server 5.1.0 GA and had lots of issues.
+For one, we had to manually add to the application because we were unable to compile the application in Netbeans without doing so...this was not the case with Tomcat or Glassfish.
+Similarly, we had issues trying to deploy a Jython web application to JBoss as there were several errors that had incurred when the container was scanning for some reason.
+All in all, with a bit of tweaking and perhaps an additional XML configuration file in the application, Jython web applications will deploy to *most* Java application servers.
+The bonus to deploying your application on a Java application server is that you are in complete control of the environment.
+For instance, you could embed the *jython.jar* file into the application server lib directory so that it was loaded at startup and available for all applications running in the environment.
+Likewise, you are in control of other necessary components such as database connection pools and so forth.
+If you deploy to another service that lives in âthe cloud,â you have very little control over the environment.
+In the next section, weâll study one such environment by Google which is known as the Google App Engine.
+While this âcloudâ service is an entirely different environment than your basic Java web application server, it contains some nice features that allow one to test applications prior to deployment in the cloud.
+Fresh to the likes of the Java platform, the Google App Engine can be used for deploying applications written in just about any language that runs on the JVM, Jython included.
+The App Engine went live in April of 2008, allowing Python developers to begin using its services to host Python applications and libraries.
+Along with support of the Java language, most other languages that run on the JVM will also deploy and run on the Google App Engine, including Jython.
+It has been mentioned that more programming languages will be supported at some point in the future, but at the time of this writing Python and Java were the only supported languages.
+You must download and develop using the Google App Engine SDK for Java in order to ensure that your application will run in the environment.
+You can download the SDK by visiting this link: http://code.google.com/appengine/downloads.html along with viewing the extensive documentation available on the Google App Engine site.
+The SDK comes complete with a development web server that can be used for testing your code before deploying, and several demo applications ranging from easy JSP programs to sophisticated demos that use Google authentication.
+No doubt about it, Google has done a good job at creating an easy learning environment for the App Engine so that developers can get up and running quickly.
+In this section you will learn how to get started using the Google App Engine SDK, and how to deploy some Jython web applications.
+You will learn how to deploy a Jython servlet application as well as a WSGI application utilizing modjy.
+Once youâve learned how to develop and use a Jython Google App Engine program using the development environment, you will learn a few specifics about deploying to the cloud.
+If you have not done so already, be sure to visit the link mentioned in the previous paragraph and download the SDK so that you can follow along in the sections to come.
+Entire books could be written on the subject of developing Jython applications to run on the App Engine.
+With that said, we will cover the basics to get you up and running with developing Jython applications for the App Engine.
+Once youâve read through this section, we suggest going to the Google App Engine documentation for further details.
+We will start by running the demo application known as âguestbookâ that comes with the Google App Engine SDK.
+This is a very simple Java application that allows one to sign in using an email address and post messages to the screen.
+In order to start the SDK web server and run the âguestbookâ application, open up a terminal and traverse into the directory where you expanded the Google App Engine .zip file and run the following command:
+Of course, if you are running on windows there is a corresponding .bat script for you to run that will start the web server.
+Once youâve issued the preceding command it will only take a second or two before the web server starts.
+You can then open a browser and traverse to *http://localhost:8080* to invoke the âguestbookâ application.
+This is a basic JSP-based Java web application, but we can deploy a Jython application and use it in the same manner as we will see in a few moments.
+Prior to deploying your application to the cloud, you must of course set up an account with the Google App Engine.
+If you have another account with Google such as GMail, then you can easily activate your App Engine account using that same username.
+To do so, go to the Google App Engine link: http://code.google.com/appengine/ and click âSign Up.â Enter your existing account information or create a new account to get started.
+After your account has been activated you will need to create an application by clicking on the âCreate Applicationâ button.
+You have a total of 10 available application slots to use if you are making use of the free App Engine account.
+The Google App Engine provides project templates to get you started developing using the correct directory structure.
+Eclipse has a plug-in that makes it easy to generate Google App Engine projects and deploy them to the App Engine.
+If interested in making use of the plug-in, please visit http://code.google.com/appengine/docs/java/tools/eclipse.html to read more information and download the plug-in.
+Similarly, Netbeans has an App Engine plug-in that is available on the Kenai site appropriately named (http://kenai.com/projects/nbappengine).
+In this text we will cover the use of Netbeans 6.7 to develop a simple Jython servlet application to deploy on the App Engine.
+You can either download and use the template available with one of these IDE plug-ins, or simply create a new Netbeans project and make use of the template provided with the App Engine SDK (<app-engine-base-directory/demos/new_project_template>) to create your project directory structure.
+If you are using Eclipse you will find a section following this tutorial that provides some Eclipse plug-in specifics.
+In order to install the nbappengine plug-in, you add the âApp Engineâ update center to the Netbeans plug-in center by choosing the Settings tab and adding the update center using http://deadlock.netbeans.org/hudson/job/nbappengine/lastSuccessfulBuild/artifact/build/updates/updates.xml.gz as the URL.
+Once youâve added the new update center you can select the Available Plugins tab and add all of the plug-ins in the âGoogle App Engineâ category, then choose Install.
+After doing so, you can add the âApp Engineâ as a server in your Netbeans environment using the âServicesâ tab.
+Once you have added the App Engine server to Netbeans, it will become an available deployment option for your web applications.
+For the deployment server, choose âGoogle App Engine,â and you will notice that when your web application is created an additional file will be created within the WEB-INF directory named appengine-web.xml.
+Any of the .py files that we wish to use in our application must be mapped in this file so that they will not be treated as static files by the Google App Engine.
+By default, Google App Engine treats all files outside of the WEB-INF directory as static unless they are JSP files.
+Our application is going to make use of three Jython servlets, namely NewJythonServlet.py, AddNumbers.py and AddToPage.py.
+In our appengine-web.xml file we can exclude all .py files from being treated as static by adding the suffix to the exclusion list as follows.
+At this point we will need to create a couple of additional directories within our WEB-INF project directory.
+We should create a *lib* directory and place *jython.jar* and *appengine-api-1.0-sdk-1.2.2.jar* into the directory.
+In a traditional Jython servlet application we need to ensure that the *PyServlet* class is initialized at startup and that all files ending in *.py* are passed to it.
+We found some inconsistencies while deploying against the Google App Engine development server and deploying to the cloud.
+For this reason, we will show you the way that we were able to get the application to function as expected in both the production and development Google App Engine environments.
+If this same pattern is applied to Jython servlet applications, then we can use the factories to coerce our Jython servlet into Java byte code at runtime.
+We then map the resulting coerced class to a servlet mapping in the applicationâs web.xml deployment descriptor.
+We can also deploy our Jython applets and make use of *PyServlet* mapping to the *.py* extension in the *web.xml*.
+In order to use object factories to coerce our code, we must use an object factory along with a Java interface, and once again we will use the PlyJy project to make this happen.
+Please note that if you choose to not use the object factory pattern and instead use PyServlet you can safely skip forward to the next subsection.
+The first step is to add to the directory that we created previously to ensure it is bundled with our application.
+There is a Java servlet contained within the PlyJy project named , and what this Java servlet does is essentially use the class to coerce a named Jython servlet and then invoke its resulting and methods.
+There is also a simple Java interface named in the project, and it must be implemented by our Jython servlet in order for the coercion to work as expected.
+When we use the PyServlet mapping implementation, there is no need to coerce objects using factories.
+You simply set up a servlet mapping within and use your Jython servlets directly with the .py extension in the URL.
+However, weâve seen issues while using PyServlet on the App Engine in that this implementation will deploy to the development App Engine server environment, but when deployed to the cloud you will receive an error when trying to invoke the servlet.
+It is because of these inconsistencies that we chose to implement the object factory solution for Jython servlet to App Engine deployment.
+In this example, weâll make use of a simple servlet that displays some text as well as the same example that was used in Chapter 13 with JSP and Jython.
+The first servlet simply displays some output, the next two perform some mathematical logic, and then there is a JSP to display the results for the mathematical servlets.
+As mentioned previously, it is important that all of the Jython servlets reside within your classpath somewhere.
+If using Netbeans, you can either place the servlets into the source root of your project (not inside a package), or you can place them in the web folder that contains your JSP files.
+If doing the latter, we have found that you may have to tweak your CLASSPATH a bit by adding the web folder to your list of libraries from within the project properties.
+Next, we need to ensure that the deployment descriptor includes the necessary servlet definitions and mappings for the application.
+Now, if you are using the object factory implementation and the *JythonServletFacade* servlet, you would have noticed that there is a variable named *PyServletName* which the JythonObjectFactory is using as the name of our Jython servlet.
+Well, within the *web.xml* we must pass an *<init-param>* using *PyServletName* as the *<param-name>* and the name of our Jython servlet as the *<param-value>*.
+This will basically pass the name of the Jython servlet to the *JythonServletFacade* servlet so that it can be used by the object factory.
+Note that when using the PyServlet implementation you should exclude those portions in the *web.xml* above that are used for the object factory implementation.
+Thatâs it, now you can deploy the application to your Google App Engine development environment, and it should run without any issues.
+You can deploy directly to the cloud by right-clicking the application and choosing the âDeploy to App Engineâ option.
+If you wish to use the Eclipse IDE for development, you should definitely download the Google App Engine plug-in using the link provided earlier in the chapter.
+You should also use the PyDev plug-in which is available at http://pydev.sourceforge.net/. For the purposes of this section, we used Eclipse Galileo and started a new project named âJythonGAEâ as a Google Web Application.
+When creating the project, make sure you check the box for using Google App Engine and uncheck the Google Web Toolkit option.
+You will find that Eclipse creates a directory structure for your application that is much the same as the project template that is included with the Google App Engine SDK.
+If you follow through the code example from the previous section, you can create the same code and set up the *web.xml* and *appengine-web.xml* the same way.
+The key is to ensure that you create a *lib* directory within the *WEB-INF* and you place the files in the appropriate location.
+You will need to ensure that your Jython servlets are contained in your CLASSPATH by either adding them to the source root for your project, or by going into the project properties and adding the *war* directory to your *Java Build Path*.
+When you are ready to deploy the application, you can choose to use the Google App Engine development environment or deploy to the cloud.
+You can run the application by right-clicking on the project and choosing *Run As* option and then choose the Google Web Application option.
+If you are ready to deploy to the cloud, you can right-click on the project and choose the *Google* -> *Deploy to App Engine* option.
+According to the modjy web site, you need to obtain the source for Jython, then zip the directory and place it into another directory along with a file that will act as a pointer to the zip archive.
+The modjy site names the directory and names the pointer file . This pointer file can be named anything as long as the suffix is . Inside the pointer file you need to explicitly name the zip archive that you had created for the directory contents.
+Letâs assume you named it lib.zip, in this case we will put the text âlib.zipâ without the quotes into the file.
+Now if we add the modjy demonstration application to the project then our directory structure should look as follows:
+Likewise, we can run it using the Google App Engine SDK web server and it should provide the expected results.
+Google offers free hosting for smaller applications, and they also base account pricing on bandwidth.
+Most importantly, you can deploy Django, Pylons, and other applications via Jython to the App Engine by setting up your App Engine applications like the examples we had shown in this chapter.
+Another deployment target that is hot off the presses at the time of this book is the Java Store or Java Warehouse.
+This is a new concept brought to market by Sun Microsystems in order to help Java software developers market their applications via a single shop that is available online via a web start application.
+Similar to other application venues, The Java Store is a storefront application where people can go to search for applications that have been submitted by developers.
+It be as easy as generating a JAR file that contains a Jython application and deploying it to the Java Store.
+Unfortunately, because the program is still in alpha mode at this time, we are unable to provide any specific details on distributing Jython applications via the Java Store.
+However, there are future plans to make alternative VM language applications easily deployable to the Java Warehouse.
+At this time, it is certainly possible to deploy a Jython application to the warehouse, but it can only deploy as a Java application.
+As of the time of this writing, only Java and JavaFX applications are directly deployable to the Java Warehouse.
+Please note that because this product is still in alpha mode, this book will not discuss such aspects of the program as memberships or fees that may be incurred for hosing your applications on the Java Store.
+- Graphic image files used for icons and to give the consumer an idea of your applicationâs look.
+When a Jython application is packaged in a JAR file then it is certainly possible to use Java Web Start to host the application via the web.
+On the other hand, if one wishes to make a Jython GUI application available for purchase or for free, the Java Store would be another way of doing so.
+One likely way to deploy applications in a single JAR is to use the method discussed in Chapter 13, but there are other solutions as well.
+For instance, one could use the *One-Jar* product to create a single JAR file containing all of the necessary Jython code as well as other JAR files essential to the application.
+In the following section, we will discuss deployment of a Jython application using One-JAR so that you can see some similarities and differences to using the Jython standalone JAR technique.
+Weâve already discussed packaging Jython applications into a JAR file using the Jython standalone method in Chapter 13. In this section, you will learn how to make use of the One-JAR (http://one-jar.sourceforge.net/) product to distribute client-based Jython applications.
+There are a few options available on the download site, but for our purposes we will package an application using the source files for One-JAR.
+Next, we need to create separate source directories for both our Jython source and our Java source.
+Lastly, weâll create a *lib* directory into which we will place all of the required JAR files for the application.
+In order to run a Jython application, weâll need to package the Jython project source into a JAR file for our application.
+The easiest way to obtain a standalone Jython JAR is to run the installer and choose the standalone option.
+As you can see from the depiction of the file structure in this example, the *src* directory will contain our Jython source files.
+He has a detailed explanation of using One-Jar on his blog, and weâve replicated some of his work in this example.
+. .including a version of the build.xml that we will put together in order to build the application.
+In this example we are using Apache Ant for the build system, but you could choose something different if youâd like.
+In this case, weâll use the *PythonInterpreter* inside of our *Main.java* to invoke our simple Jython Swing application.
+In this example we are using the same simple Jython Swing application that we wrote for Chapter 13.