paulb@658 | 1 | Jython and the Java API
|
paulb@658 | 2 | =======================
|
paulb@658 | 3 |
|
paulb@658 | 4 | For WebStack to function properly, the underlying Java API classes must be
|
paulb@658 | 5 | available. Although this seems like an obvious prerequisite, some
|
paulb@658 | 6 | distributions of Jython, notably the jython package provided with Ubuntu
|
paulb@658 | 7 | Feisty (7.04), do provide a version of Jython that runs, but do not provide
|
paulb@658 | 8 | the underlying class libraries for the Java APIs such as the java.net package.
|
paulb@658 | 9 | Consequently, WebStack will fail when importing modules such as urllib.
|
paulb@379 | 10 |
|
paulb@658 | 11 | The solution to such problems is to choose packages which provide the Java API
|
paulb@658 | 12 | functionality such as the jython-gcj package for Ubuntu Feisty (7.04).
|
paulb@658 | 13 | Alternatives include installing a full Java runtime environment and persuading
|
paulb@658 | 14 | Jython to run on that environment, or even to install a completely separate
|
paulb@658 | 15 | Jython from a different source such as jython.org.
|
paulb@658 | 16 |
|
paulb@658 | 17 | Preparing the Application for Deployment
|
paulb@658 | 18 | ----------------------------------------
|
paulb@658 | 19 |
|
paulb@658 | 20 | Use the webstack_java_build.py script (installed by setup.py but also found in
|
paulb@658 | 21 | the tools/JavaServlet directory) to create a Web application directory. Then,
|
paulb@569 | 22 | deploy the directory in the servlet container. For example:
|
paulb@178 | 23 |
|
paulb@569 | 24 | jython webstack_java_build.py examples/JavaServlet/SimpleApp.py \
|
paulb@212 | 25 | examples/Common/Simple/ \
|
paulb@212 | 26 | . \
|
paulb@658 | 27 | /tmp/jython-cache \
|
paulb@290 | 28 | web.xml \
|
paulb@212 | 29 | $CATALINA_HOME/common/lib/activation.jar \
|
paulb@212 | 30 | $CATALINA_HOME/common/lib/mail.jar
|
paulb@178 | 31 |
|
paulb@290 | 32 | This identifies the handler (SimpleApp.py), the application package (Simple),
|
paulb@658 | 33 | the directory where the WebStack package is found (.), the directory to be
|
paulb@658 | 34 | used for caching imported classes, and the name of the template for the
|
paulb@658 | 35 | deployment descriptor (web.xml); it also specifies the library files which
|
paulb@658 | 36 | must also be deployed with the application (activation.jar and mail.jar from
|
paulb@658 | 37 | the Tomcat libraries in this case); it produces a directory called SimpleApp
|
paulb@658 | 38 | in the current directory.
|
paulb@658 | 39 |
|
paulb@658 | 40 | Important
|
paulb@658 | 41 | ---------
|
paulb@658 | 42 |
|
paulb@658 | 43 | Note that the cache directory is a new setting from WebStack 1.2.6 which has
|
paulb@658 | 44 | been introduced to work with environments where the default class cache
|
paulb@658 | 45 | directory may, for some reason, be read-only.
|
paulb@658 | 46 |
|
paulb@658 | 47 | Deploying the Application
|
paulb@658 | 48 | -------------------------
|
paulb@658 | 49 |
|
paulb@658 | 50 | To deploy the Web application into a servlet container like Tomcat, a command
|
paulb@658 | 51 | like the following can be performed:
|
paulb@178 | 52 |
|
paulb@204 | 53 | mv SimpleApp/ $CATALINA_HOME/webapps/
|
paulb@178 | 54 |
|
paulb@178 | 55 | Upon starting or restarting the servlet container, an URL such as the following
|
paulb@178 | 56 | can be used to visit the application:
|
paulb@178 | 57 |
|
paulb@212 | 58 | http://localhost:8080/SimpleApp/
|
paulb@290 | 59 |
|
paulb@390 | 60 | Authentication/Authorisation with Apache Tomcat
|
paulb@390 | 61 | ===============================================
|
paulb@290 | 62 |
|
paulb@290 | 63 | In Apache Tomcat, it is not typically possible to use an authenticator with a
|
paulb@290 | 64 | WebStack resource without additional configuration being performed first:
|
paulb@290 | 65 |
|
paulb@290 | 66 | * The web.xml template should be replaced with the protected-web.xml
|
paulb@569 | 67 | template in the webstack_java_build.py command. This alternative template
|
paulb@569 | 68 | produces a special deployment descriptor which introduces role-based
|
paulb@569 | 69 | authentication for the application. Consequently, upon seeing that the
|
paulb@569 | 70 | application requires a user with a given role, Tomcat will prompt for the
|
paulb@569 | 71 | username/password details of a user with that role, and once such a user
|
paulb@569 | 72 | has been authenticated, the resulting user identity is then made available
|
paulb@569 | 73 | via the API to the application.
|
paulb@290 | 74 |
|
paulb@290 | 75 | * The server.xml configuration file in Tomcat should declare the protected
|
paulb@290 | 76 | application as a privileged context; for example:
|
paulb@290 | 77 |
|
paulb@290 | 78 | <Context path="/AuthApp" docBase="AuthApp" privileged="true"/>
|
paulb@290 | 79 |
|
paulb@290 | 80 | * The tomcat-users.xml configuration file should define suitable users and
|
paulb@290 | 81 | roles; for example:
|
paulb@290 | 82 |
|
paulb@290 | 83 | <role rolename="webstack"/>
|
paulb@290 | 84 | <user username="badger" password="abc" roles="webstack"/>
|
paulb@290 | 85 |
|
paulb@290 | 86 | Note that it is still possible for an authenticator to reject access to
|
paulb@290 | 87 | users even if they have the role stated in the special deployment
|
paulb@290 | 88 | descriptor.
|