Project

General

Profile

ModjyConfiguration » History » Version 7

Alan Kennedy, 2016-08-27 02:57 PM
Fixed some broken links

1 1 Alan Kennedy
h1. Configuration reference
2
3 4 Alan Kennedy
{{toc}}
4
5 1 Alan Kennedy
h2(#configuring). Configuring Modjy with context and servlet parameters.
6
7 4 Alan Kennedy
Modjy is configured through a set of parameters in the *web.xml* file, contained in the *WEB-INF* sub-directory of every java web application.
8 1 Alan Kennedy
9 4 Alan Kennedy
Under J2EE, there are two main mechanisms that can be used to specify configuration values for a servlet or group of servlets, in web.xml.
10
11 1 Alan Kennedy
 # *Context Parameters*, which are defined at the top level scope of the *web.xml*, and are shared between all servlets configured in that servlet context.
12
 # *Servlet Parameters*, which are defined at servlet level scope, and are specific to a given servlet.
13
14
Modjy can be configured with both context and servlet parameters. At runtime, modjy starts with an empty parameter set. It then reads the values of all context parameters, and adds them to the set of configured values. It then reads all of the servlet parameters, and adds them to the set. This means that *servlet-scope parameters take precedence over context-scope parameters*. Consider the following configuration:
15
16
<pre>
17
<web-app>
18
19
  <context-param>
20
    <param-name>log_level</param-name>
21
    <param-value>info</param-value>
22
  </context-param>
23
24
  <servlet>
25
    <servlet-name>modjy</servlet-name>
26
      <servlet-class>com.xhaus.modjy.ModjyJServlet</servlet-class>
27
      <init-param>
28
        <param-name>log_level</param-name>
29
        <param-value>debug</param-value>
30
      </init-param>
31
  </servlet>
32
33
</web-app>
34
</pre>
35
36
In the above example, the value *log_level=info* is configured as a context parameter, which means that all servlets in that context (i.e. defined in that *web.xml* file) will inherit that value for *log_level*, if it is not specifically overwritten. In the <servlet> definition, the value *log_level=debug* is specified, meaning that this specific servlet (which may be one of many in the servlet context) will be configured with a value of *debug*, over-riding the context-level value *info*.
37
38
h2(#relative_paths). Configuring Modjy with relative pathnames
39
40 5 Alan Kennedy
When configuring modjy with file and directory names, you will sometimes need to configure paths that are *relative* to the [[ModjyServletContextRoot|servlet context root]]. The context root is a standard directory hierarchy for J2EE servlets, which is used to contain support resources for the servlet context.
41 1 Alan Kennedy
42
If you wish to specify a relative path to modjy, then place a *$* symbol at the beginning of the path. For example, if you want to configure the *app_directory* parameter to be a directory *my_apps_dir*, contained within the context root (i.e. at the same level as WEB-INF), then configure the value as follows.
43
44
<pre>
45
<servlet>
46
  <servlet-name>modjy</servlet-name>
47
    <servlet-class>com.xhaus.modjy.ModjyJServlet</servlet-class>
48
    <init-param>
49
      <param-name>app_directory</param-name>
50
      <param-value>$/my_apps_dir</param-value>
51
    </init-param>
52
</servlet>
53
</pre>
54
55
56
h2(#modjy_parameters). Modjy parameters and their meanings.
57
58
Modjy servlet parameters are set as either *<context-param>* or *<init-param>* name-value pairs in the servlet configuration, e.g. in *web.xml*. The following is the list of parameters that modjy understands.
59
60 5 Alan Kennedy
Note that the values of all modjy initialisation parameters are provided to the application in the WSGI environment, under keys named *modjy.param.param-name*.
61 1 Alan Kennedy
62
|Param-name|Value|Description|Default|
63 5 Alan Kennedy
|=.python.home|A string giving the pathname to the local jython installation.|This is used to indicate to the jython interpreter embedded in modjy where to find the jython installation on the local machine. For more detail on why this property should be set, and how the value is used, see "The Jython Registry":http://wiki.python.org/jython/UserGuide#the-jython-registry .|None|
64 7 Alan Kennedy
|=.python.*|A string giving a value for the relevant jython property.|Any parameter whose name begins with "python." is set in the java.util.Properties used to initialize the jython interpreter inside modjy. For example, values can be set for the following jython parameters: *python.path*, *python.cachedir*, etc. For more detail on the jython properties that can be set and what they mean, see "The Jython Registry":http://www.jython.org/jythonbook/en/1.0/appendixA.html .|None|
65 4 Alan Kennedy
|=.app_import_name|A string giving a name which can be imported to give an application callable|This parameter specifies the python importable name of a WSGI application, including a fully qualified package name. This can be used, for example, to import WSGI handlers from web frameworks. If you specify a name such as *some_framework.web.handlers.WSGIHandler*, then *some_framework* will be imported, *web* will be imported from *some_framework*, *handlers* will be import from *web*, and finally *WSGIHandler* will be imported from *handlers*. Being last in the path *WSGIHandler* will then be treated as the WSGI *application callable*. If a value is specified for this parameter, it will used in preference to the app_directory/app_filename/app_callable_name triplet mechanism described below. See the documentation for [[ModjyLocateCallables|how modjy locates application callable objects]] for further details.|None|
66 5 Alan Kennedy
|=.app_directory|A string giving a path to the directory where application source files are located.|You may wish to keep your application source files outside the modjy servlet/context directory. In that case, you should specify the name of the application directory with this parameter. If you do not specify a value for this parameter, it defaults to the [[ModjyServletContextRoot|servlet context root directory]]. *If a value is provided for the app_import_name, described above, then this parameter will be ignored*.|[[ModjyServletContextRoot|servlet context root directory]]|
67
|=.app_filename|A string giving the python filename which contains the callable.|This parameter can be used to change the filename which modjy uses to locate the file which contains the definition of the application callable. For example, this parameter could be set to '__wsgi_app__.py', in which case all application objects will need to be contained in files called '__wsgi_app__.py'. This process of locating callables is described under [[ModjyLocateCallables|how modjy locates application callable objects]]. *If a value is provided for the app_import_name, described above, then this parameter will be ignored*.|application.py|
68
|=.app_callable_name|A string giving the name of python callable which is the WSGI application object.|This parameter tells modjy the name of the application callable object inside the application source file. For more information, see "How modjy locates application callable objects":ModjyLocateCallables. *If a value is provided for the app_import_name, described above, then this parameter will be ignored*.|handler|
69 2 Alan Kennedy
|=.callable_query_name|A string giving the name of the query parameter from which the callable name for this request should be taken.|This parameter tells modjy to extract the name of the application callable object from a query parameter in the request URI. For more information, see [[ModjyLocateCallables|how modjy locates application callable objects]]. If the value of this parameter is not changed from its default value of None, callable names will never be extracted from the request query string. Example: if the value of this parameter was set to *python_object*, then a request for a URI like this <pre>/index?python_object=my_callable</pre> will tell modjy to look for a callable named *my_callable* as the application callable.|None|
70 1 Alan Kennedy
|=.cache_callables|0 == no caching, 1 == cache callables|This parameter tells modjy whether or not it should cache any callables it creates. Caching of callable objects is described under [[ModjyLocateCallables|how modjy locates application callable objects]].|1|
71 6 Alan Kennedy
|=.reload_on_mod|0 == do not reload source, 1 == reload when source has been modified|This parameter tells modjy whether or not it should check to see if the python source file containing the application callable has been modified since the last time it was loaded. This is a useful flag for interactive development purposes. However, enabling the flag comes at a cost, which is that modjy must check the modification time of the application source file on *every single request*. When your application has been fully debugged and running in production, you will probably want to disable this flag. This flag has no effect when the 'cache_callables' parameter is false, i.e. caching is disabled, since a disabled cache means that application source is reloaded for every single request.|0|
72 1 Alan Kennedy
|=.multithread|0 == access to callables should be synchronized, 1 == application may be called more than once simultaneously from multiple threads.|This parameter has an identical meaning to the WSGI variable 'wsgi.multithread'. If your application object is not thread-safe, you should set this flag to zero, thus ensuring that the application will only ever be called from one thread at a time. This is achieved by exclusively locking and unlocking the application callable before and after each request, so that the application services only one request at a time. This could cause considerable slowdown in a situation where multiple simultaneous calls are received for the same application.|1|
73 6 Alan Kennedy
|=.log_class|The name of the class which should be used for logging.|If you wish to write your own logger class, create a new class in modjy_log, and change the value of this configuration parameter to its name.|modjy_logger|
74 1 Alan Kennedy
|=.initial_env|This parameter is used to set initial environment variables in the WSGI environment. |A single name value pair is set by separating the name and value with a colon i.e. *:*. Multiple name value pairs can be set by separating them with a semi-colon, i.e. *;*. For example, if you wish to set the variable *myAppString* to *STRING_VAL* and *myAppInteger* to *42*, then use the following value for this parameter: *myAppString: STRING_VAL ; myAppInteger: 42*. All names values are stored in the environment as *strings*.|None|
75 2 Alan Kennedy
|=.log_level|debug, info, warn, error, fatal|The level of diagnostic output that should be logged. There is currently only one type of logger supported in modjy: the *modjy_logger* class. This class provides very basic logging functionality, sending all messages to the J2EE ServletContext.log method.|info|
76 1 Alan Kennedy
|=.exc_handler|standard, testing|The name of the class which be used to handle exceptions that occur while running applications. The *standard* handler simply re-raises the exception to be caught by the servlet container. The *testing* handler is there for two reasons: 1. To provide debugging information in development and testing phases, and 2. To illustrate how to create customised exception handlers.|standard|
77 7 Alan Kennedy
|=.load_site_packages|0 == don't imply 'import site', 1 == imply 'import site'|Controls whether or not 'import site' is executed on interpreter startup. See the docs on "the python site module":https://docs.python.org/2/library/site.html for further information|1|
78 3 Alan Kennedy
|=.packages|semicolon-separated list of java package names to be added.|See below under [[ModjyConfiguration#add_package|Using external java packages]].|None|
79 1 Alan Kennedy
|=.classdirs|semicolon-separated list of directories containing java packages and classes.|Adds each of the named directories to the list of places checked by jython for java packages and classes.|None|
80
|=.extdirs|semicolon-separated list of directories containing java packages and classes.|Forces jython to scan all *.jar* and *.zip* files in each of the named directories for java packages and classes.|None|
81
82
h2(#add_package). Using external java packages
83
84
When using an external java package, it is not sufficient to simply add the package jar to the classpath. The name of the package must also be declared to jython. This can be done in one of two ways
85
86
h3. By configuration
87
88
By specifying the java package names in the *packages* configuration parameter, e.g. *org.apache.xerces ; org.apache.xalan*.
89
90
h3. In your code
91
92
By explicitly adding the package name in your own code, using the *sys* module, e.g.
93
<pre>
94
import sys
95
sys.add_package('org.apache.xerces')
96
sys.add_package('org.apache.xalan')
97
</pre>
98 2 Alan Kennedy
99
An example of this usage can be seen in the the source for org.python.util.PyServlet.java: it explicitly adds the necessary *javax.servlet* packages.