Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


Resin Documentation

home company docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server

web apps

Web Apps are the servlets, HTML and images that are the core HTTP application. This section shows how to configure and deploy web-apps and their resources.


  • configuration
  • Deploying with the command-line.
  • Servlets and Filters
  • resin:import app-default.xml
  • Resources: databases, queues, beans.
  • URL rewrite
  • Security

defining web-xml in resin.xml

All web-apps are defined in the resin.xml, because Resin uses explicit configuration over defaults. While this gives flexibility, most sites use one of a few basic configurations. The most common is a <web-app-deploy> which defines a dynamic directory for both command-line deployment and a place to copy .war files.


The following example shows the most minimal configuration for a web app deployment using the webapps directory.

  • The <web-app-deploy> enables both command-line and explicit jar deployment.
  • The <resin:import> of app-default.xml defines default servlet behavior like WEB-INF/web.xml, WEB-INF/lib, JSPs and the static file servlet.
  • The default <cluster> and default <host> give a place for the web-app to exist.
Example: basic web-app-deploy
<resin xmlns=""

<cluster id="">

  <resin:import path="classpath:META-INF/app-default.xml"/>

<host id="">

  <web-app-deploy path="webapps"/>



In some deployments, the web-apps are defined in the resin.xml instead of a general deployment in a webapps directory. A site might want more specific control in the resin.xml or might just prefer to have all the web-apps listed explicitly. The <web-app> tag defines a new web-application.

Example: explicit web-app
<resin xmlns=""

<cluster id="">

  <resin:import path="classpath:META-INF/app-default.xml"/>

<host id="">

  <web-app id="/my-web-app root-directory="my-root-dir"/>


Each web-app has several components: the URL path, the root directory, an archive path, the internal cloud identifier, and the internal cloud archive.

  • URL path - the context-path for servlets. It's the URL prefix that dispatches to the web-app.
  • root-directory - the expanded directory on the filesystem which contains the files and classes for the web-app.
  • archive-path - the path to a .war file with the archived web-app (optional).
  • internal id - the internal unique cloud name of the web-app, typically something like "production/webapp/".
  • internal cloud archive - an internal copy of the web-app archive which is distributed across all servers in the cloud.

web-app deployment in the cloud and the command-line

When you deploy a .war on the command-line, Resin first stores the archive in its internal cloud repository using the internal unique identifier. The <web-app> or <web-app-deploy> will look in the internal repository for that name and deploy it just as if it was a .war file.

For example, the default root web-app is named "production/webapp/default/ROOT". When you deploy the ROOT.war to the default virtual-host, Resin saves it internally as "production/webapp/default/ROOT", copies the .war to all servers in the cluster, and then expands it just like a ROOT.war file. The ROOT.war is saved in triplicate on the three triad servers for reliability.

Thinking of the command-line deployment as an internal cloud archive is an accurate model.


Web-app configuration can be shared across several web-apps using the web-app-default tag. The contents are applied to all web-apps. Resin's app-default.xml uses the web-app-default to define standard servlets like the *.jsp mapping, the WEB-INF/lib directory and the static file servlet.

If you have a shared *.jar library, you can define the shared classloaders a web-app-default. Each web-app will then use the same *.jar files without needing to copy them into each .war file.

Example: web-app-default of website-jars
<resin xmlns=""

<cluster id="">


      <library-loader path="/var/resin/website-jars"/>
<host id="">

  <web-app-deploy path="webapps"


Servlets and Filters

Resin's <web-app> includes all the standard Servlet configuration. The WEB-INF/web.xml parsing uses the same Resin code as the <web-app> or resin-web.xml configuration. So all standard Servlet configuration is possible in a <web-app> or <web-app-default>.

In fact, the web.xml is just a convention handled by the app-default.xml file. It's defined as:

Definition: web.xml in app-default.xml

  <resin:import path="WEB-INF/web.xml" optional="true"/>



Resin's standard servlet implementation is configured with a resin:import of the app-default.xml. app-default.xml defines the WEB-INF/web.xml, WEB-INF/classes, WEB-INF/lib, JSPs and the static servlet. In other words, if it's missing from the resin.xml, Resin will not behave as a standard servlet engine.

Resources: databases, queues, beans

Resources in a web-app are typically defined in the resin-web.xml file. The resin-web.xml has the same syntax as the web.xml. Using two files lets you split out the Resin-specific configuration into the resin-web.xml and keep the standard servlet configuration in the web.xml.

Common resources like <database> have their own configuration tags listed in the reference guide.. Other resources like third-party libraries and application beans can use the CDI-style XML configuration, which is general enough to configure non-CDI objects and store them in JNDI as well as configure CDI-style beans.

Example: WEB-INF/resin-web.xml database configuration
<web-app xmlns="">

<database jndi-name='jdbc/test_mysql'>
  <driver type="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource">


Third party libraries and application beans can be configured using the CDI XML configuration and saved to JNDI. The class name is given by the XML namespace and the tag name.

The following example creates a com.mycom.mylib.MyBean instance, configures a field, and saves it in JNDI at the name "java:comp/env/my-bean".

Example: WEB-INF/resin-web.xml JNDI configuration
<web-app xmlns=""

<mylib:MyBean xmlns:mylib="urn:java:com.mycom.mylib"


URL rewriting

Resin's URL rewriting tags can be configured in the resin-web.xml to conditionally rewrite URLs from a "pretty" external view to a more practical internal one and redirect pages.

Example: dispatch for a wiki
<web-app xmlns=""
<resin:Dispatch target="\.(php|gif|css|png|js)"/>

<resin:Dispatch regexp="^" target="/index.php"/>


Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.