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