1 Preparing the Application
2 =========================
3
4 Use the webstack_java_build.py script (installed by setup.py but also found in the
5 tools/JavaServlet directory) to create a Web application directory. Then,
6 deploy the directory in the servlet container. For example:
7
8 jython webstack_java_build.py examples/JavaServlet/SimpleApp.py \
9 examples/Common/Simple/ \
10 . \
11 web.xml \
12 $CATALINA_HOME/common/lib/activation.jar \
13 $CATALINA_HOME/common/lib/mail.jar
14
15 This identifies the handler (SimpleApp.py), the application package (Simple),
16 the directory where the WebStack package is found (.), and the name of the
17 template for the deployment descriptor (web.xml); it also specifies the
18 library files which must also be deployed with the application (activation.jar
19 and mail.jar from the Tomcat libraries in this case); it produces a directory
20 called SimpleApp in the current directory. To deploy the Web application into
21 a servlet container like Tomcat, a command like the following can be
22 performed:
23
24 mv SimpleApp/ $CATALINA_HOME/webapps/
25
26 Upon starting or restarting the servlet container, an URL such as the following
27 can be used to visit the application:
28
29 http://localhost:8080/SimpleApp/
30
31 Authentication/Authorisation with Apache Tomcat
32 ===============================================
33
34 In Apache Tomcat, it is not typically possible to use an authenticator with a
35 WebStack resource without additional configuration being performed first:
36
37 * The web.xml template should be replaced with the protected-web.xml
38 template in the webstack_java_build.py command. This alternative template
39 produces a special deployment descriptor which introduces role-based
40 authentication for the application. Consequently, upon seeing that the
41 application requires a user with a given role, Tomcat will prompt for the
42 username/password details of a user with that role, and once such a user
43 has been authenticated, the resulting user identity is then made available
44 via the API to the application.
45
46 * The server.xml configuration file in Tomcat should declare the protected
47 application as a privileged context; for example:
48
49 <Context path="/AuthApp" docBase="AuthApp" privileged="true"/>
50
51 * The tomcat-users.xml configuration file should define suitable users and
52 roles; for example:
53
54 <role rolename="webstack"/>
55 <user username="badger" password="abc" roles="webstack"/>
56
57 Note that it is still possible for an authenticator to reject access to
58 users even if they have the role stated in the special deployment
59 descriptor.