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