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