indexdownloadinstallconfigappscompliancerelated

Installing modjy

  1. Choosing a J2EE container
  2. The steps required to install and configure modjy
  3. Installing the modjy servlet
  4. Placing the jython.jar file
  5. Configuring modjy
  6. Testing that modjy is running.
  7. The context root of the modjy servlet.
  8. Serving all requests to a container with modjy.

1: Choosing a J2EE container

[top]

In order to run modjy, you will need to have a J2EE-compliant servlet container. There are dozens of such competing containers on the market, both commercial and non-commercial, both open-source and closed-source. You can find a current and comprehensive list of them here: Java Glossary : servlet womb.

If you are already using a particular servlet container, then you've probably chosen it for good reasons, and are unlikely to change it. Since modjy was written to the J2EE standard, you should be able to run modjy without modification, and the below documentation should be sufficient to help you configure it. But you will need to know the in-and-outs of how to configure your container for modjy: I'm not going to include installation instructions for every container here.

If you are picking a servlet container for the sole purpose of running modjy, then I recommend that you use Tomcat 6, for the following reasons

  1. Because all of the modjy documentation examples relate to it
  2. Because it is one of the simplest containers to get up and running
  3. Because it is one of the most stable, most configurable, well supported and well documented containers there is.

So if you don't yet have a running J2EE servlet container, I recommend that you download the latest version of Tomcat 6, install it and get it running now, before proceeding.

2: The steps required to install and configure modjy

[top]

From here, I will assume that you already have a J2EE container up and running. You should be satisfied that your container is fully operational, i.e. by using some container-specific test mechanism, before attempting to install modjy.

You should also have jython 2.2 installed and operational on your target system.

The following are the steps that you will need to follow, in order: each is explained in detail below.

  1. Install the modjy java servlet, including it's web.xml configuration file and its modjy.jar file.
  2. Place the jython.jar file in a suitable location.
  3. Set the value of the python.home property.
  4. Test that modjy is running.
  5. Optionally configure modjy to service all requests to the container (not just requests for a subset of the URI space).

3: Installing the modjy servlet

[top]

It should be easy to install modjy as a web application. Simply take a copy of the modjy_webapp directory in the modjy distribution, and drop it in the location where your container expects to find web applications.

The default installation of Apache Tomcat 6 has a subdirectory called webapps. If you're running Tomcat 6, simply drop the modjy_webapp directory in there, (maybe) restart your container, and you should be up-and-running.

If you're using a different J2EE container, or a non-default installation of Tomcat, you'll need to read your container documentation to find out where web applications should live.

The modjy_webapp directory contains the following files and directories

Path Description
WEB-INF This standard J2EE directory contains the support resources required for a web application.
WEB-INF/web.xml This file contains configuration for this instance of the modjy servlet. The J2EE servlet <init-param> parameters are used to control the operation of modjy. Setting configuration parameters is described below. The configuration parameters which can be set are described in a separate document: Modjy parameters.
WEB-INF/lib This is the standard J2EE directory where servlet support jars, etc, should be placed. In the simple case, this is where the jython.jar file should go. See below under Placing the jython.jar file for more details.
WEB-INF/lib-python This directory is treated specially by modjy. Firstly, lib-python is added to sys.path, which means that any python libraries you wish to use can be dropped in here, and they will automatically become available to your code. Secondly, the directory is searched for python .pth files. These files are simple text files, each line of which is added directly to sys.path. So if you want to use .jar files, .zip files or .egg files containing python code, you should create a text file, whose name ends with .pth, listing each of those files, one per line, and place the file in the lib-python directory. All files in the lib-python directory whose names end with .pth are scanned.
WEB-INF/lib/modjy.jar This is the jar file which contains the single java class file for modjy, as well as several jython source (*.py) files which implement modjy. These jython files are imported directly from the jar file by modjy, so you should not need to extract them into the filesystem.

4: Placing the jython.jar file

[top]

When the modjy servlet is running, it requires access to the jython.jar file, so you must place this file in the servlet container hierarchy so that it is available when the modjy servlet class is being loaded.

Standard J2EE classloading behaviour when looking for support resources is to look first inside the WEB-INF/lib directory for a web application. So if you're just running a single instance of the modjy servlet, you can place the jython.jar file in there, and read no further in this section.

If you're running more than one instance of the servlet, you have a choice of what to do.

  1. Place multiple copies of jython.jar, one in the WEB-INF/lib directory of each instance.
  2. Place a single copy of jython.jar in a place where all instances of the modjy servlet can find it. Picking the right place requires knowing how the classloader hierarchy of your container works, so you may need to do some reading. On the standard Tomcat 6 installation, there is a directory called lib, which is shared between all web applications, so you could put it there. More information available in the Tomcat 6 documentation on classloading

If you neglect to make jython.jar available to the modjy servlet, or put it in the wrong place, then you will get messages like this in your error log: java.lang.NoClassDefFoundError: org/python/core/PyException.

5: Configuring modjy

[top]

Configuring modjy is done inside the <servlet> elements in web.xml files. You have to define a name for the servlet, and the name of the class that implements it. So the beginning of your servlet declaration for modjy will look something like this

<servlet>
    <servlet-name>modjy</servlet-name>
    <servlet-class>com.xhaus.modjy.ModjyJServlet</servlet-class>
    <!-- Parameters omitted -->
    <load-on-startup>1</load-on-startup>
</servlet>
			

After this is a series of initialization parameters, given as name/value pairs. These parameters control the operation of modjy, for example logging, caching, threading, etc, behaviour. All of those parameters, what they mean, and their permitted and default values, are described in a separate document: the modjy configuration reference.

There is only a single parameter that is always required: the python.home property, which gives the home directory of the local jython installation. Without knowing this value, modjy cannot operate, so this is the first thing you should check if things aren't working.

Specifying python.home permits jython to locate its registry file, its cache of pre-compiled packages, etc, etc. For more information on the effects of setting python.home, see the The Jython Registry documentation.

There is one final web.xml configuration value which needs to be specified: the servlet-mapping. This maps an URL pattern to the servlet declared above. Inside the web.xml file, you will need a fragment like this

<servlet-mapping>
    <servlet-name>modjy</servlet-name>
    <url-pattern>/*</url-pattern>
</servlet-mapping>
			

6: Testing that modjy is running.

[top]

First off, be sure that your container is running. Assuming that you're using the out-of-the-box configuration, and that you're running your container on port 8080 on localhost, then resolving the following URL should render proof that modjy is indeed running.

http://localhost:8080/modjy_webapp/
			

The returned page should show some version details for jython, and the JVM version in which it is running. It will also display a table showing the contents of the WSGI environment, as seen by all WSGI applications running under modjy.

7: The context root of the modjy servlet.

[top]

Any instance of the modjy servlet lives in a servlet context. This context has a related file system directory, where resources supporting the servlet are located. This directory is the default directory where modjy starts looking for application files to load.

If you are using the out-of-the-box configuration, this directory will be the modjy_webapp directory, so you should place your WSGI application files in there.

If you are mapping all URIs through modjy, as described below, then the context root directory will be different. Tomcat 6 creates a special ROOT directory under its webapps directory: the behaviour of your container may differ. Whichever directory this is for your container is the root directory in which modjy will begin the search for application source files.

8: Serving all requests to a container with modjy.

[top]

A - Changing the uri space served by modjy

If you successfully installed the modjy servlet according to the instructions above, using the suggested name modjy_webapp, then you will find that modjy will be used by the container to service all requests which look like this: /modjy_webapp/*. However, you probably don't want to use URIs like that.

If you want modjy to serve requests for a different uri subset, simply rename the web application directory to something else: e.g. my_app_uri, in which case your uris will look like /my_app_uri/*, etc.

B - Serving an entire uri space with modjy

If you want to configure modjy to serve requests for all URIs, i.e. /* then you cannot do so in the modjy_servlet web.xml file. Instead you must move the servlet up the configuration hierarchy.

Every servlet container has a container-wide configuration file where container-wide servlets are configured. Some, such as Tomcat, split this function across multiple configuration files. Under Tomcat 6, this file is located at $tomcat_home/conf/web.xml. Other containers, e.g. Caucho Resin, permit this kind of configuration directly in the main server configuration file, i.e. resin.conf.

You will need to configure a declaration for the modjy servlet in this higher level configuration file. You can probably copy this definition directly from the web.xml file that comes with modjy. After that, you will need to make the container map all URIs to the modjy servlet. The servlet definition will look something like this

<servlet>
    <servlet-name>modjy</servlet-name>
    <servlet-class>com.xhaus.modjy.ModjyJServlet</servlet-class>
    <!-- Parameters omitted -->
    <load-on-startup>1</load-on-startup>
</servlet>
			

C - Creating a mapping for the entire uri space

Possibly your container will have a default servlet to which requests are sent when they are not mapped to any other servlet. Under Tomcat, this is called the default servlet, and is implemented by the java class org.apache.catalina.servlets.DefaultServlet. The servlet-mapping for this servlet will contain a <url-pattern>/</url-pattern>. You could change this servlet-mapping to reference the modjy servlet definition you defined above, or create a new servlet mapping if one does not already exist. That mapping should look something like this.

<servlet-mapping>
    <servlet-name>modjy</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>
			

D - Placing modjy.jar

However, you're not finished yet! Because you've moved the modjy servlet up the container hierarchy, you must also move the modjy.jar file up the classloader hierarchy. Such matters tend to be container specific, and so you may need to read on the classloader hierarchy of your container to know where to place the modjy.jar file. Under the Tomcat 6 classloader hierarchy, the level that is appropriate for container-wide servlets is $tomcat_home/lib.

E - Placing jython.jar

Once you've found the right place for the modjy.jar file, that is probably also the most appropriate to place the jython.jar file.

The only reason for doing differently is if there are objects even further up the container hierarchy that also rely on jython. And if that's the situation, well, you're probably an old hand at all this stuff, aren't you ;-)

F - Telling modjy where modjy.jar is

There's one more thing you may need to do. Modjy consists of a combination of java and jython files. The J2EE container is responsible for loading the modjy java servlet class (which is the thinnest possible wrapper around the jython modjy classes). Once started, the modjy java servlet imports the jython files directly from the modjy.jar file, thus bootstrapping the real modjy servlet.

There are three different ways in which modjy locates the modjy.jar file. Each of these methods is attempted, in the order given.

  1. By looking for it inside the J2EE standard WEB-INF/lib directory.
  2. By being configured with a location, using the modjy_jar.location configuration property, as described below.
  3. By trying to find the location of the archive from which the java class ModjyJServlet.class was loaded.

You will probably not need to explicitly specify the location of the modjy.jar file. But if you do, the configuration would look something like this.

<servlet>
    <servlet-name>modjy</servlet-name>
    <servlet-class>com.xhaus.modjy.ModjyJServlet</servlet-class>
    <init-param>
        <param-name>modjy_jar.location</param-name>
        <param-value>lib/modjy.jar</param-value>
    </init-param>
</servlet>
			

So hopefully now you've got modjy/WSGI taking care of your entire URI space, i.e. SCRIPT_NAME="". Cool!