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 . \
26 /tmp/jython-cache \
27 web.xml \
28 examples/Common/Simple/ \
29 --libraries \
30 $CATALINA_HOME/common/lib/activation.jar \
31 $CATALINA_HOME/common/lib/mail.jar
32
33 This identifies the handler (SimpleApp.py), the directory where the WebStack
34 package is found (.), the directory to be used for caching imported classes,
35 and the name of the template for the deployment descriptor (web.xml); it also
36 specifies the package directories for the application (Simple), and after the
37 --libraries flag, the library files which must also be deployed with the
38 application (activation.jar and mail.jar from the Tomcat libraries in this
39 case); it produces a directory called SimpleApp in the current directory.
40
41 Important
42 ---------
43
44 Note that the cache directory is a new setting from WebStack 1.2.6 which has
45 been introduced to work with environments where the default class cache
46 directory may, for some reason, be read-only.
47
48 Deploying the Application
49 -------------------------
50
51 To deploy the Web application into a servlet container like Tomcat, a command
52 like the following can be performed:
53
54 mv SimpleApp/ $CATALINA_HOME/webapps/
55
56 Upon starting or restarting the servlet container, an URL such as the following
57 can be used to visit the application:
58
59 http://localhost:8080/SimpleApp/
60
61 Running Applications with Apache Tomcat
62 =======================================
63
64 Before starting Tomcat, make sure the following environment variables are set:
65 JAVA_HOME, CATALINA_HOME. On some systems, such as Ubuntu Feisty (7.04), even
66 if Jython is installed (see above), there is no guarantee that a suitable Java
67 development kit (JDK) will have been installed, yet Tomcat will require a JDK
68 to function. It is therefore necessary to install the Sun JDK or a suitable
69 package (eg. java-gcj-compat-dev). Then, the environment variables can be set
70 up as in this example:
71
72 export JAVA_HOME=/usr/lib/jvm/java-1.4.2-gcj-4.1-1.4.2.0
73 export CATALINA_HOME=/home/paulb/Software/Java/jakarta-tomcat-4.1.31
74
75 Generally, the contents of the directory referenced by JAVA_HOME should
76 contain bin and lib directories, with the bin directory containing javac and
77 other tools.
78
79 Authentication/Authorisation with Apache Tomcat
80 ===============================================
81
82 In Apache Tomcat, it is not typically possible to use an authenticator with a
83 WebStack resource without additional configuration being performed first:
84
85 * The web.xml template should be replaced with the protected-web.xml
86 template in the webstack_java_build.py command. This alternative template
87 produces a special deployment descriptor which introduces role-based
88 authentication for the application. Consequently, upon seeing that the
89 application requires a user with a given role, Tomcat will prompt for the
90 username/password details of a user with that role, and once such a user
91 has been authenticated, the resulting user identity is then made available
92 via the API to the application.
93
94 * The server.xml configuration file in Tomcat should declare the protected
95 application as a privileged context; for example:
96
97 <Context path="/AuthApp" docBase="AuthApp" privileged="true"/>
98
99 * The tomcat-users.xml configuration file should define suitable users and
100 roles; for example:
101
102 <role rolename="webstack"/>
103 <user username="badger" password="abc" roles="webstack"/>
104
105 Note that it is still possible for an authenticator to reject access to
106 users even if they have the role stated in the special deployment
107 descriptor.