<?xml version="1.0"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

<document>

 <properties>
  <title>URL Rewriting Howto</title>
 </properties>

<body>

<section name="Scenario and Overview">

<p>
Unaltered Turbine URLs look like this:
<code>http://www.foo.com:8080/CONTEXT/servlet/MAPPING/template/Foo.vm</code>.<br/>
But you want shorter URLs, or you don't like exposing the use of
servlets in the URL.  Maybe this url would suit you better:
<code>http://www.foo.com:8080/po/s/la/template/Foo.vm</code>
</p>

<p>
The bulk of the url is defined by the servlet api and is outside of the
control of Turbine:
<pre>
http://www.foo.com/CONTEXT/servlet/MAPPING/template/Foo.vm
                   [ servlet api defined ][ turbine       ]</pre>

This HOWTO describes how you can control the servlet part of the url
in Tomcat.  For other servlet environments you'll have to consult
their documentation.
</p>

<p>
Three parts of the url will be addresed:
<ol>
<li>the web application context (CONTEXT in the example above),</li>
<li>the servlet prefix (servlet),</li>
<li>and the servlet mapping (MAPPING).</li>
</ol>
</p>

</section>

<section name="The Context">

<p>
You need to register the context with Tomcat. If you have given your
application a short name like 'po' and placed it correctly in the
webapps directory, then you won't need to do anything special. Tomcat
will find the directory, and add a context. If you have a long
application name like 'mywonderfulapp', add the following lines to
Tomcat's server.xml file:
</p>

<source><![CDATA[
<Context
    path="/po"
    docBase="webapps/mywonderfulapp"
    reloadable="true"
    debug="0"
    trusted="false" >
</Context>
]]></source>

<p>
Everthing after the docBase= line is obviously up to you. This tells
Tomcat to add a context named 'po' with the docbase of your
application.
</p>

</section>

<section name="The Servlet Prefix">

<p>
Modifying the servlet prefix also requires editing Tomcat's server.xml
file.  Tomcat will use this prefix to determine if a given request is
for a servlet.  Edit the following lines:
</p>

<source><![CDATA[
<RequestInterceptor
    className="org.apache.tomcat.request.InvokerInterceptor"
    debug="0" prefix="/s/" />
]]></source>

<p>
With this modification, Tomcat recognize requests containing /s/ in
the url as a servlet request and will look for the servlet in the
web.xml descriptor.
</p>

</section>

<section name="The Servlet Name">
<p>
This is defined in web.xml (which you will find here:
<code>webapps/WEB-INF/web.xml</code>).  This is automatically given
the name of your application in Turbine.  To change it, simply edit the
web.xml file as follows:
</p>

<source><![CDATA[
<servlet-name>
    la
</servlet-name>
]]></source>

<p>
<strong>If you are using Tomcat standalone, then you are done and your url is
now <code>http://servername:port:/po/s/la</code></strong>
</p>

</section>

<section name="If you are running Apache and mod_jk">

<p>
... you will need to change your mod_jk.conf file to include the following:
</p>

<source><![CDATA[
#########################################################
# Auto configuration for the /po context starts.
#########################################################

#
# Make Apache aware of the location of the context
#
Alias /po "serverroot/webapps/mywonderfulapp"
<Directory "serverroot/webapps/mywonderfulapp">
     Options Indexes FollowSymLinks
</Directory>

#
# Mount all JSP files and the /servlet/ uri to Tomcat
#
JkMount /po/s/* ajp12
JkMount /po/*.jsp ajp12

#
# Prohibit users from directly accessing WEB-INF
#
<Location "/mywonderfulapp/WEB-INF/">
     AllowOverride None
     deny from all
</Location>

#
# Prohibit users from directly accessing META-INF
#
<Location "/mywonderfulapp/META-INF/">
     AllowOverride None
     deny from all
</Location>

#######################################################
# Auto configuration for the /po context ends.
#######################################################
]]></source>

<p>
document created August 14, 2001
</p>

</section>

</body>
</document>
