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