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