In order to locate WSGI application callables, modjy needs three pieces of information.

1. The directory in which to look for the application's python source file.
2. The name of the application source file in that directory.
3. The name of the callable application object in that source file.

Modjy can be configured to find each of these things in a couple of ways. All modjy parameters, what they mean, and their permitted and default values, are described in a separate document: the modjy configuration reference.

A - The application directory

The application directory was either directly configured by you, by setting the app_directory parameter to modjy, or was chosen by the J2EE container, and is the servlet context root directory. Whichever directory that is, this is where modjy will look for application source files.

Note also that modjy currently adds the value of the app_directory to sys.path as well, in order for relative imports to work. This will changed when the A better Import mechanism is implemented.

B - The application filename

Once it has located the application directory, modjy then looks for an application source file. Modjy uses the same filename for all application source files. The default value for this filename is application.py. You can change this value by setting the modjy configuration variable app_filename.

C - The callable object name

Lastly, having loaded and executed the application source file in response to a request, modjy needs to find a python callable object within the resulting python namespace. There are two different ways to set the name of the callable used for a request. They are

1. By configuration. The configuration parameter app_callable_name can be used to set the name of the callable in the python namespace. By default, modjy always uses the value of this parameter, whose default value is handler. So if you don't change callable name configuration, all WSGI application objects should called "handler".
2. From the request query string. Modjy can be configured to extract the callable name from the query string of each request. This is done by specifying the name of the query field to be used in the configuration variable callable_query_name. If a value is given for this parameter, it will be used to search the query string of every request for a query parameter of that name. If the named query parameter is present, its value will be used as the name of the callable object. If the named query parameter is not found, the value configured for the app_callable_name configuration parameter (described above) will be used instead. Searching for callable names in query parameters is disabled by default. Security conscious deployers will probably wish to leave it disabled, since it provides a mechanism for the client to obtain access to the application's python objects.

Now modjy knows the pathname and callable name for the application. It now needs to decide whether it needs to load and compile the application source code, to find a definition of the application object, or whether it already has a usable instance of the application object in its cache.

D - The application object cache

You can configure modjy to cache application objects for reuse for multiple requests. Application objects are stored in a cache, keyed under (pathname, callablename). If a request arrives which maps to an application object that is in the cache, then the cached object will be reused. Thus (unless the source file has been modified and reload_on_mod is true) the application source file will not be reloaded and recompiled.

Conversely, if caching is disabled, this means that a fresh application object will be created for every new request. This will have the effect of causing the reloading and recompilation of the application source file for every request, which may be less efficient than you would like. So use this option carefully.

Lastly, note that the cache_callables parameter has implications for the wsgi.run_once environment variable. Therefore, when caching is disabled, modjy sets the value of wsgi.run_once to true (thus essentially making cache disablement almost equivalent to running as a CGI script).

E - Reloading source on modification

You can configure modjy to reload application objects when their containing source file has been modified. See under reload_on_mod in the Configuration reference for more information.

Obviously, this parameter only takes effect when caching is enabled. Disabled caching means that the application source code is reloaded and recompiled for every request. If reload_on_mod is enabled, then cached objects will only be discarded when their containing source file has been modified. This is obviously a useful facility during a testing/debugging cycle. Also obviously, checking the access time on application source files comes at a small but finite resource cost for every single request, so you may want to disable it in production scenarios.

F - Multi-threading

You can configure modjy to run your application objects in either multi-threaded or single-threaded mode. See under multithread in the Configuration reference for more information.

For a discussion of why the modjy object publishing algorithm is so basic, see the Overview of modjy.

At the moment, the exception reporting from modjy is not very good. This is because of the nature of the import mechanism I've implemented (I think). I will endeavour to improve it soon.

In the meantime, it is probably best to use the standard exception handler, which simply raises all exceptions to the servlet container, e.g. Tomcat, and let's it deal with them. A containers usual way of dealing with this should be to write a full stack trace in the container logs: so you should keep an eye on those logs if you have to do any form of debugging.