Wiring Tapestry to the servlet container

Tapestry doesn't just magically appear but it comes close. All you have to do is tell your servlet container to run the Tapestry ApplicationServlet or a subclass of it.

All Java web applications need a web.xml to define what servlets are used, resources, security settings etc. What we need to do for your web container is to define what the Tapestry application servlet is. You can use the default Tapestry class ApplicationServlet but typically you'll want to use your own servlet...but it must extend the Tapestry ApplicationServlet.

A web application that uses Cayenne will want to initialise it in here, so that is why we extend ApplicationServlet with our own. If you are familiar with Java web app's at all the next line should be familiar

    <servlet>
        <servlet-name>crud-web</servlet-name>
        <servlet-class>org.crud.engine.CrudApplicationServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>crud-web</servlet-name>
        <url-pattern>/app</url-pattern>
    </servlet-mapping>

This tells Tomcat that it should look for on the classpath and load upon startup a class called CrudApplicationServlet. When this servlet runs it will initialise Tapestry and the Hivemind engine.

An extra option that can be helpful to include is a Listener to listen for servlet container events such as a http session being created or destroyed.

    <listener>
        <listener-class>org.crud.engine.CrudEngine</listener-class>
    </listener>

In this case I've set the Tapestry Engine class to implement one or more of the Servlet API listener classes such as: HttpSessionListener, HttpSessionBindingListener, ServletContextListener

In our Maven web projects the web.xml should reside in the folder:

  src\main\webapp\WEB-INF

...then it will be automatically included in the web application build and deploy.

That is it Tapestry will now be wired to the app server.

Tapestry application definition

Each Tapestry application can have it own descriptor that tells the Tapestry engine some further configuration information such as extra component libraries, ASO (Application State Objects - Session, Application level objects), locales and where to look for the classes for a HTML template (page).

    <!-- Highly recommended -->
    <library id="contrib" specification-path="/org/apache/tapestry/contrib/Contrib.library"/>
    <meta key="org.apache.tapestry.visit-class" value="org.crud.aso.Visit"/> 
    <meta key="org.apache.tapestry.global-class" value="org.crud.aso.Global"/>
    
    <!-- Optional -->
    <meta key="org.apache.tapestry.accepted-locales" value="en,fr"/>
    <meta key="org.apache.tapestry.page-class-packages" value="org.crud.pages"/>
    <meta key="org.apache.tapestry.component-class-packages" value="org.crud.components"/>
    
    <page name="Home" specification-path="Home.page"/>

The application file should reside under: your-web-application\src\main\webapp\WEB-INF<your-web-application-name>.application

It is very wise to carry the same name for your application everywhere, the places are:

  • The above application file name
  • The web.xml:
        <servlet>
            <servlet-name>macata</servlet-name>
        ....
    
        <servlet-mapping>
            <servlet-name>macata</servlet-name>
        ...
    
  • The web applications pom.xml:
       <build>
            <finalName>macata</finalName>
            <resources>
                <resource>
                    <directory>src/main/resources</directory>
                    <targetPath>../macata</targetPath>
                </resource>
        .....
    

...if you don't you may end up with some strange errors such as application components or resources not being found.

*** For a continuation of the Tapestry setup see the HiveMind setup page ***