Preparing the Application
=========================

Use the webstack_java_build.py script (installed by setup.py but also found in the
tools/JavaServlet directory) to create a Web application directory. Then,
deploy the directory in the servlet container. For example:

jython webstack_java_build.py examples/JavaServlet/SimpleApp.py \
    examples/Common/Simple/ \
    . \
    web.xml \
    $CATALINA_HOME/common/lib/activation.jar \
    $CATALINA_HOME/common/lib/mail.jar

This identifies the handler (SimpleApp.py), the application package (Simple),
the directory where the WebStack package is found (.), and the name of the
template for the deployment descriptor (web.xml); it also specifies the
library files which must also be deployed with the application (activation.jar
and mail.jar from the Tomcat libraries in this case); it produces a directory
called SimpleApp in the current directory. To deploy the Web application into
a servlet container like Tomcat, a command like the following can be
performed:

mv SimpleApp/ $CATALINA_HOME/webapps/

Upon starting or restarting the servlet container, an URL such as the following
can be used to visit the application:

http://localhost:8080/SimpleApp/

Authentication/Authorisation with Apache Tomcat
===============================================

In Apache Tomcat, it is not typically possible to use an authenticator with a
WebStack resource without additional configuration being performed first:

  * The web.xml template should be replaced with the protected-web.xml
    template in the webstack_java_build.py command. This alternative template
    produces a special deployment descriptor which introduces role-based
    authentication for the application. Consequently, upon seeing that the
    application requires a user with a given role, Tomcat will prompt for the
    username/password details of a user with that role, and once such a user
    has been authenticated, the resulting user identity is then made available
    via the API to the application.

  * The server.xml configuration file in Tomcat should declare the protected
    application as a privileged context; for example:

    <Context path="/AuthApp" docBase="AuthApp" privileged="true"/>

  * The tomcat-users.xml configuration file should define suitable users and
    roles; for example:

    <role rolename="webstack"/>
    <user username="badger" password="abc" roles="webstack"/>

    Note that it is still possible for an authenticator to reject access to
    users even if they have the role stated in the special deployment
    descriptor.
