1 Jython and the Java API
2 =======================
3
4 For WebStack to function properly, the underlying Java API classes must be
5 available. Although this seems like an obvious prerequisite, some
6 distributions of Jython, notably the jython package provided with Ubuntu
7 Feisty (7.04), do provide a version of Jython that runs, but do not provide
8 the underlying class libraries for the Java APIs such as the java.net package.
9 Consequently, WebStack will fail when importing modules such as urllib.
10
11 The solution to such problems is to choose packages which provide the Java API
12 functionality such as the jython-gcj package for Ubuntu Feisty (7.04).
13 Alternatives include installing a full Java runtime environment and persuading
14 Jython to run on that environment, or even to install a completely separate
15 Jython from a different source such as jython.org.
16
17 Preparing the Application for Deployment
18 ----------------------------------------
19
20 Use the webstack_java_build.py script (installed by setup.py but also found in
21 the tools/JavaServlet directory) to create a Web application directory. Then,
22 deploy the directory in the servlet container. For example:
23
24 jython webstack_java_build.py examples/JavaServlet/SimpleApp.py \
25 examples/Common/Simple/ \
26 . \
27 /tmp/jython-cache \
28 web.xml \
29 $CATALINA_HOME/common/lib/activation.jar \
30 $CATALINA_HOME/common/lib/mail.jar
31
32 This identifies the handler (SimpleApp.py), the application package (Simple),
33 the directory where the WebStack package is found (.), the directory to be
34 used for caching imported classes, and the name of the template for the
35 deployment descriptor (web.xml); it also specifies the library files which
36 must also be deployed with the application (activation.jar and mail.jar from
37 the Tomcat libraries in this case); it produces a directory called SimpleApp
38 in the current directory.
39
40 Important
41 ---------
42
43 Note that the cache directory is a new setting from WebStack 1.2.6 which has
44 been introduced to work with environments where the default class cache
45 directory may, for some reason, be read-only.
46
47 Deploying the Application
48 -------------------------
49
50 To deploy the Web application into a servlet container like Tomcat, a command
51 like the following can be performed:
52
53 mv SimpleApp/ $CATALINA_HOME/webapps/
54
55 Upon starting or restarting the servlet container, an URL such as the following
56 can be used to visit the application:
57
58 http://localhost:8080/SimpleApp/
59
60 Authentication/Authorisation with Apache Tomcat
61 ===============================================
62
63 In Apache Tomcat, it is not typically possible to use an authenticator with a
64 WebStack resource without additional configuration being performed first:
65
66 * The web.xml template should be replaced with the protected-web.xml
67 template in the webstack_java_build.py command. This alternative template
68 produces a special deployment descriptor which introduces role-based
69 authentication for the application. Consequently, upon seeing that the
70 application requires a user with a given role, Tomcat will prompt for the
71 username/password details of a user with that role, and once such a user
72 has been authenticated, the resulting user identity is then made available
73 via the API to the application.
74
75 * The server.xml configuration file in Tomcat should declare the protected
76 application as a privileged context; for example:
77
78 <Context path="/AuthApp" docBase="AuthApp" privileged="true"/>
79
80 * The tomcat-users.xml configuration file should define suitable users and
81 roles; for example:
82
83 <role rolename="webstack"/>
84 <user username="badger" password="abc" roles="webstack"/>
85
86 Note that it is still possible for an authenticator to reject access to
87 users even if they have the role stated in the special deployment
88 descriptor.
