web application: tags

Web applications are configured with the <web-app> tag, which can occur in a number of places.

• WEB-INF/web.xml contains a top-level web-app element. It is the Servlet standard location for defining things like servlet mappings and security roles.
• WEB-INF/resin-web.xml is also used by Resin and will override and supplement the configuration in WEB-INF/web.xml. Use it to specify Resin specific configuration if you prefer to keep WEB-INF/web.xml strictly conforming to the Servlet specification.
• A web application can also be configured in the main Resin configuration, and in this context web-app is a child of <host>.

• Resources tags for beans, components, databases, @Stateless and @Stateful EJBs, JMS queues, etc.
• Security for a full description of Resin's authentication and authorization.
• Rewrite tags for Resin's rewrite-dispatch rewriting.

<access-log> configures a HTTP access log for an indivitual web-app. See access-log in the <host> tag for more information.

<active-wait-time> sets a 503 busy timeout for requests trying to access a restarting web-app. If the timeout expires before the web-app complete initialization, the request will return a 503 Busy HTTP response.

element active-wait-time {
  r_period-Type
}

The <allow-servlet-el> flag configures whether <servlet> tags allow EL expressions in the init-param.

element allow-servlet-el {
  r_boolean-Type
}

<archive-path> configures the location of the web-app's .war file. In some configurations, the .war expansion might not use the webapps/ directory, but will still want automatic war expantion.

element archive-path {
  r_path-Type
}

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <host id="">

    <web-app id="/foo"
             root-directory="/var/www/foo"
             archive-path="/var/www/wars/foo.war"/>

  </host>
</cluster>
</resin>

<cache-mapping> specifies max-age and Expires times for cacheable pages.

See caching for more information.

<cache-mapping> is intended to provide Expires times for pages that have ETags or Last-Modified specified, but do not wish to hard-code the max-age timeout in the servlet. For example, Resin's FileServlet relies on cache-mapping to set the expires times for static pages. Using cache-mapping lets cacheable pages be configured in a standard manner.

<cache-mapping> does not automatically make pages cacheable. Your servlets must already set the ETag (or Last-Modified) header to activate <cache-mapping>.

The time interval defaults to seconds, but will allow other periods:

element cache-mapping {
  (url-pattern | url-regexp)
  & expires?
  & max-age?
  & s-max-age?
}

• cache-mapping requires an enabled <cache>. If the cache is disabled, cache-mapping will be ignored.
• cache-mapping does not automatically make a page cacheable. Only cacheable pages are affected by cache-mapping, i.e. pages with an ETag or Last-Modified.

<web-app xmlns="http://caucho.com/ns/resin">

  <cache-mapping url-pattern='/*'
                 max-age='10'/>

  <cache-mapping url-pattern='*.gif'
                 max-age='15m'/>

</web-app>

Initializes application (ServletContext) variables. context-param defines initial values for application.getInitParameter("foo"). See also ServletContext.getInitParameter().

element context-param {
  (param-name, param-value)*
  | (attribute * { string })*
  | (element * { string })*
}

<web-app xmlns="http://caucho.com/ns/resin">

  <context-param>
    <param-name>baz</param-name>
    <param-value>value</param-value>
  </context-param>

  <!-- shortcut -->
  <context-param foo="bar"/>

</web-app>

The <cookie-http-only> flag configures the Http-Only attribute for all Cookies generated from the web-app. The Http-Only attribute can add security to a website by not forwarding HTTP cookies to SSL HTTPS requests.

element cookie-http-only {
  r_boolean-Type
}

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <host id="www.foo.com">
    <web-app id="" root-directory="/var/www/foo">
      <cookie-http-only>true</cookie-http-only>
    <web-app id="">
  </host>

  <host id="www.foo.com:443">
    <web-app id="" root-directory="/var/www/foo-secure">
      <secure/>
    <web-app id="">
  </host>

</cluster>
</resin>

Specifies ear expansion.

ear-deploy can be used in web-apps to define a subdirectory for ear expansion.

element ear-deploy {
  path
  & archive-directory?
  & ear-default?
  & expand-cleanup-fileset?
  & expand-directory?
  & expand-path?
  & expand-prefix?
  & expand-suffix?
  & lazy-init?
  & redeploy-mode?
  & require-file*
  & url-prefix?
}

element error-page {
  (error-code | exception-type)?
  & location
}

By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages. Applications can customize the response generated for errors.

<web-app xmlns="http://caucho.com/ns/resin">
  <error-page>
    <error-code>404</error-code>
    <location>/file_not_found.jsp</location>
  </error-page>
</web-app>

<web-app xmlns="http://caucho.com/ns/resin">
   <error-page exception-type="java.lang.NullPointerException"
               location="/nullpointer.jsp"/>
</web-app>

The error page can use request attributes to obtain information about the request that caused the error:

<%@ page session="false" isErrorPage="true" %>

<html>
<head><title>404 Not Found</title></head>
<body>
<h1>404 Not Found</h1>

The url <code>${requestScope["javax.servlet.error.request_uri"]}</code> 
was not found.
</body>
</html>

Defines a filter name for later mapping. Because Filters are fully integrated with Resin-IoC, they can use dependency-injection, transactional aspects, custom interception with @InterceptorType, and event handling with @Observes.

element filter {
  filter-name
  & filter-class
  & init*
  & init-param*
}

The following example defines a filter alias 'image'

<web-app xmlns="http://caucho.com/ns/resin">

  <filter>
    <filter-name>image</filter-name>
    <filter-class>test.MyImage</filter-class>
    <init-param>
      <param-name>title</param-name>
      <param-value>Hello, World</param-value>
    </init-param>
  </filter>

  <filter-mapping>
    <filter-name>image</filter-name>
    <url-pattern>/images/*</url-pattern>
  </filter-mapping>

</web-app>

The full Servlet 2.3 syntax for init-param is supported as well as a simple shortcut.

<web-app id='/'>

<filter filter-name='test.HelloWorld'>
  <init-param foo='bar'/>

  <init-param>
    <param-name>baz</param-name>
    <param-value>value</param-value>
  </init-param>
</servlet>

</web-app>

Maps url patterns to filters. filter-mapping has two children, url-pattern and filter-name. url-pattern selects the urls which should execute the filter.

filter-name can either specify a servlet class directly or it can specify a servlet alias defined by filter.

element filter-mapping {
  (url-pattern | url-regexp | servlet-name)+
  & filter-name
  & dispatcher*
}

<web-app xmlns="http://caucho.com/ns/resin">

  <filter>
    <filter-name>test-filter</filter-name>
    <filter-class>test.MyFilter</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>test-filter</filter-name>
    <url-pattern>/hello/*</url-pattern>
  </filter-mapping>

  <servlet>
    <servlet-name>hello</servlet-name>
    <servlet-class>test.HelloWorld</servlet-class>
  </servlet>

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

url-regexp matches the portion of the url that follows the context path. A webapp in webapps/ROOT, and a url http://localhost/foo/hello.html will have a value of "/foo/hello.html" for the purposes of the regular expression match. A webapp in webapps/baz and a url http://localhost/baz/hello.html will have a url of "/hello.html" for the purposes of the regular expression match, because "/baz" is the context path.

The <idle-time> specifies the timeout for lazy-idle web-apps. In some configurations, web-apps are created only on demand and are closed when no requests access the web-app. The idle-time configures when those web-apps should be freed.

For example, the resin-doc web-app uses idle-time for its child web-apps because there are a large number of sub-web-apps for the individual tutorials.

element idle-time {
  r_period-Type
}

Configures JSF behavior.

element jsf {
  & fast-jsf?
}

Configures JSP behavior.

element jsp {
  auto-compile
  & deferred-syntax-allowed-as-literal?
  & dependency-check-interval?
  & el-ignored?
  & fast-jstl?
  & ide-hack?
  & ignore-el-exception?
  & is-xml?
  & page-encoding?
  & precompile?
  & print-null-as-blank?
  & recompile-on-error?
  & recycle-tags?
  & require-source?
  & scripting-invalid?
  & session?
  & static-page-generates-class?
  & tld-dir?
  & tld-file-set?
  & trim-directive-whitespaces?
  & validate-taglib-schema?
  & velocity-enabled?
}

<jsp-config> configure standard settings for JSP files.

element jsp-config {
  taglib*,
  jsp-property-group*
}

element jsp-property-group {
  url-pattern*,
  deferred-syntax-allowed-as-literal?,
  el-ignored?,
  page-encoding?
  scripting-invalid?
  trim-directive-whitespaces?
  is-xml?
  include-prelude*
  include-coda*
}

<lazy-servlet-validate> defers validation of servlet classes until the servlet is used. Some servlet libraries are bundled with web.xml files which include servlets with no available classes. Since Resin will normally send an error in this situation, <lazy-servlet-validate> lets you turn the validation off.

element lazy-servlet-validate {
  r_boolean-Type
}

<listener> configures servlet event listeners. The listeners are registered based on interfaces they implement. The listener instances are fully Resin-IoC aware, including dependency injection, observing events, and supporting aspects.

element listener {
  listener-class,
  init?
}

Maps url patterns to mime-types.

element mime-mapping {
  extension,
  mime-type
}

<web-app xmlns="http://caucho.com/ns/resin">

  <mime-mapping>
    <extension>.foo</extension>
    <mime-type>text/html</mime-type>
  </mime-mapping>

  <!-- resin shortcut syntax -->
  <mime-mapping extension='.bar'
                mime-type='text/html'/>

</web-app>

Resin has a long list of default mime types in $RESIN_HOME/conf/app-default.xml

Enables multipart-mime for forms and file uploads. multipart-mime is disabled by default.

For an uploaded file with a form name of foo, the parameter value contains the path name to a temporary file containing the uploaded file. foo.filename contains the uploaded filename, and foo.content-type contains the content-type of the uploaded file.

If the upload is larger than the limit or if multipart-form processing is disabled, Resin will not parse the request and will set an error message in the "caucho.multipart.form.error" request attribute. The "caucho.multipart.form.error.size" will contain the attempted upload size.

Requests can set the maximum by setting the request attribute "caucho.multipart.form.upload-max" with an Integer or Long value.

By default, multipart-form is disabled.

element multipart-form {
  enable?
  & upload-max?
}

Maps url patterns to real paths. If using a server like IIS, you may need to match the server's path aliases.

element path-mapping {
  (url-pattern | url-regexp)

  & real-path
}

<web-app xmlns="http://caucho.com/ns/resin">

<path-mapping url-pattern='/resin/*'
              real-path='e:\resin'/>

<path-mapping url-regexp='/~([^/]*)'
              real-path='e:\home\$1'/>

</web-app>

<protocol> configures a remoting protocol for a Java bean. The bean is configured with the <servlet> and <servlet-mapping> tags, since it will process HTTP URL requests.

Protocol drivers extend the AbstractProtocolServletFactory interface and can register a URI alias to simplify configuration.

element protocol {
  (class | uri)
  & init?
}

<web-app xmlns="http://caucho.com/ns/resin">

  <servlet-mapping url-pattern="/hello">
                    servlet-class="example.MyHello">
    <protocol uri="hessian:"/>
  </servlet-mapping>

</web-app>

<redeploy-check-interval> specifies how often Resin should check if a .war file has been updated or added to a <web-app-deploy> directory.

element redeploy-check-interval {
  r_period-Type
}

<redeploy-mode> specifies how Resin handles updates to web-apps and .war files. By default, Resin restarts web-apps when classes or configuration files change.

element redeploy-mode {
  automatic | manual
}

See the Resource tag documentation for a full list of resources available to the web-app.

All resource tags are available to the <web-app>, like databases, IoC beans and components, EJB stateful, stateless and message beans, JMS queues, remote clients, etc.

<web-app xmlns="http://caucho.com/ns/resin">
  <database jndi-name="jdbc/test">
    <driver type="org.postgresql.Driver">
      <url>jdbc:postgresql://localhost/test</url>
      <user>caucho</user>
    </driver>
  </database>
</web-app>

Or IoC-configured Beans:

<web-app xmlns="http://caucho.com/ns/resin">
  <bean jndi-name="jdbc/test" type="example.Theater>
    <init name="Balboa Theater">
      <movie title="Attack of the Killer Tomatoes"/>

      <movie title="Snakes on a Plane"/>

      <movie title="Casablanca"/>
    </init>
  </bean>
</web-app>

<rewrite-real-path> lets you rewrite the URL to physical path mapping, to allow aliasing or for filesystem organization.

element rewrite-real-path {
  element rewrite {
    regexp
    & replacement
  }*

  & element rewrite {
    regexp
    & target
  }*
}

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-real-path>
    <real-path regexp="^/foo" target="/bar"/>
  </rewrite-real-path>

</web-app>

<root-directory> configures the web-app's filesystem root.

element root-directory {
  string
}

The <secure> flag requires that the web-app only be accessed in a secure/SSL mode. Equivalent to a <security-constraint>.

element secure {
  r_boolean-Type
}

Defines a servlet to process HTTP URL requests. The servlet class can either implement javax.servlet.Servlet to handle the HTTP request directly or it can use a remoting protocol like SOAP or Hessian to handle remoting requests.

Since servlets are full Resin-IoC beans, they can use dependency injection, EJB aspects like @TransactionAttribute, custom @InterceptorType interceptors, and listen for @Observes events.

element servlet {
  servlet-name
  < (servlet-class | jsp-file)
  < init*
  < init-param*
  < load-on-startup?
  < protocol?
  < run-as?
  < run-at?
}

<web-app xmlns="http://caucho.com/ns">

  <servlet>
    <servlet-name>hello</servlet-name>
    <servlet-class>test.HelloWorld</servlet-class>
    <init-param>
      <param-name>title</param-name>
      <param-value>Hello, World</param-value>
    </init-param>
  </servlet>

  <!-- using Resin shortcut syntax -->
  <servlet servlet-name='cron'
           servlet-class='test.DailyChores'>
    <init-param title='Daily Chores'/>
    <load-on-startup/>
    <run-at>3:00</run-at>
  </servlet>

  <!-- mapping a url to use the servlet -->
  <servlet-mapping url-pattern='/hello.html'
                   servlet-name='hello'/>

</web-app>

Several servlet configurations might configure the same servlet class with different init-param values. Each will have a separate servlet-name.

<web-app xmlns="http://caucho.com/ns/resin">
  <servlet servlet-name='foo-a'>
    <servlet-class>test.FooServlet</servlet-class>
    <init-param name='foo-a sample'/>
  </servlet>

  <servlet servlet-name='foo-b'>
    <servlet-class>test.FooServlet</servlet-class>
    <init-param name='foo-b sample'/>
  </servlet>
</web-app>

load-on-startup can specify an (optional) integer value. If the value is 0 or greater, it indicates an order for servlets to be loaded, servlets with higher numbers get loaded after servlets with lower numbers.

There are a number of named servlets that are usually available to a Resin application, as defined in $RESIN_HOME/conf/app-default.xml.

  <servlet servlet-name="directory"
           servlet-class="com.caucho.servlets.DirectoryServlet"/>

  <servlet servlet-name="file"
           servlet-class="com.caucho.servlets.FileServlet"/>

  <servlet servlet-name="jsp"
           servlet-class="com.caucho.jsp.JspServlet"/>

  <servlet servlet-name="xtp"
           servlet-class="com.caucho.jsp.XtpServlet"/>

<servlet servlet-name="j_security_check"
         servlet-class="com.caucho.server.security.FormLoginServlet"/>

Maps url patterns to servlets. servlet-mapping has two children, url-pattern and servlet-name. url-pattern selects the urls which should execute the servlet.

element servlet-mapping {
  init?
  & protocol?
  & servlet-class?
  & servlet-name?
  < url-pattern*
  < url-regexp*
}

<web-app xmlns="http://caucho.com/ns/resin">

  <servlet>
    <servlet-name>hello</servlet-name>
    <servlet-class>test.HelloWorld</servlet-class>
  </servlet>

  <servlet-mapping>
    <url-pattern>/hello.html</servlet-class>
    <servlet-name>hello</servlet-class>
  </servlet-mapping>

  <!-- resin shortcut syntax -->
  <servlet-mapping url-pattern='*.xtp'
                   servlet-name='com.caucho.jsp.XtpServlet'/>

</web-app>

url-regexp matches the portion of the url that follows the context path. A webapp in webapps/ROOT, and a url http://localhost/foo/hello.html will have a value of "/foo/hello.html" for the purposes of the regular expression match. A webapp in webapps/baz and a url http://localhost/baz/hello.html will have a url of "/hello.html" for the purposes of the regular expression match, because "/baz" is the context path.

In Resin, the special servlet-name'invoker' is used to dispatch servlets by class name.

<web-app xmlns="http://caucho.com/ns/resin">

  <!-- 
    used with urls like 
    http://localhost:8080/servlets/test.HelloServlet 
  -->
  <servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/>

</web-app>

There are a number of mappings to servlets that are usually available to a Resin application, as defined in $RESIN_HOME/conf/app-default.xml.

<cluster>

<web-app-default>
  <servlet-mapping url-pattern="*.jsp" servlet-name="jsp"/>
  <servlet-mapping url-pattern="*.xtp" servlet-name="xtp"/>

  <servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/>
  <servlet-mapping url-pattern="/" servlet-name="file"/>
</web-app-default>
</cluster>

The plugins use servlet-mapping to decide which URLs to send to Resin. The following servlet-name values are used by the plugins:

Maps URL by regular expressions to custom servlets.

element servlet-regexp {
  init?
  & servlet-class?
  & servlet-name?
  & url-regexp
}

<servlet-regexp url-regexp="/([^.]*).do"
                servlet-class="qa.\${regexp[1]}Servlet">
  <init a="b"/>
</servlet-regexp>

<session-config> configures Resin's session handling, including the cookies Resin sends, the maximum sessions, and session persistence and clustering.

See also: Resin clustering for more information about distributed sessions and persistence.

element session-config {
  always-load-session?
  & always-save-session?
  & cookie-append-server-index?
  & cookie-domain?
  & cookie-length?
  & cookie-max-age?
  & cookie-port?
  & cookie-secure?
  & cookie-version?
  & enable-cookies?
  & enable-url-rewriting?
  & ignore-serialization-errors?
  & invalidate-after-listener?
  & reuse-session-id?
  & save-mode?
  & save-on-shutdown?
  & serialization-type?
  & session-max?
  & session-timeout?
  & use-persistent-store?
}

The session-timeout and session-max are usually used together to control the number of sessions. Sessions are stored in an LRU cache. When the number of sessions in the cache fills up past session-max, the oldest sessions are recovered. In addition, sessions idle for longer than session-timeout are purged.

<web-app id='/dir'>

  <session-config>
     <!-- 2 hour timeout -->
     <session-timeout>120</session-timeout>
     <session-max>4096</session-max>
  </session-config>

</web-app>

cookie-length is used to limit the maximum length for the session's generated cookie for special situations like WAP devices. Reducing this value reduces the randomness in the cookie and increases the chance of session collisions.

reuse-session-id defaults to true so that Resin can share the session id amongst different web-apps.

The class that corresponds to <session-config> is com.caucho.server.session.SessionManager

The maximum time Resin will wait for requests to finish before closing the web-app.

element shutdown-wait-max {
  r_period-Type
}

<statistics-enable> enables more detailed statistics for the WebAppMXBean administration. The statistics gathering is disabled by default for performance reasons.

element statistics-enable {
  r_boolean-Type
}

Forces servlet-mapping to follow strict Servlet 2.2, disallowing PATH_INFO. Value is true or false.

element strict-mapping {
  r_boolean-Type
}

<web-app xmlns="http://caucho.com/ns/resin">
  <strict-mapping>true</strict-mapping>
</web-app>

web-app configures a web application.

When specified by id, the application will be initialized on server start. When specified by url-regexp, the application will be initialized at the first request. This means that load-on-startup servlets may start later than expected for url-regexp applications.

The following example creates a web-app for /apache using the Apache htdocs directory to serve pages.

<host id=''>
  <web-app id='/apache' document-directory='/usr/local/apache/htdocs'>

  ...

</host>

The following example sets the root web-app to the IIS root directory.

  <web-app id='/' document-directory='C:/inetpub/wwwroot'>

When the web-app is specified with a url-regexp, document-directory can use replacement variables ($2).

In the following, each user gets his or her own independent application using ~user.

<host id=''>

  <web-app url-regexp='/~([^/]*)'
           document-directory='/home/$1/public_html'>

    ...

  </web-app>

</host>

Establishes the defaults for a web-app.

When initializing a web-app, all the tags in the web-app-defaults sections configure the web-app. In other words, the web-app-default value is essentially a macro that is cut-and-pasted before the web-app configuration.

web-app-default is used for defining server-wide behavior, like *.jsp handling, and for host-wide behavior.

<host>
  <web-app-default>
    <servlet servlet-name='test'
             servlet-class='test.MyServlet'/>

    <servlet-mapping url-pattern='*.text' servlet-class='test'/>
  </web-app-default>
</host>

Specifies war expansion.

web-app-deploy can be used in web-apps to define a subdirectory for war expansion. The tutorials in the documentation use web-app-deploy to allow servlet/tutorial/helloworld to be an independent war file.

element web-app-deploy {
  archive-directory?
  expand-cleanup-fileset?
  expand-directory?
  expand-prefix?
  expand-suffix?
  path?
  redeploy-check-interval?
  redeploy-mode?
  require-file*
  startup-mode?
  url-prefix?
  versioning?
  web-app-default*
  web-app*
}

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">
<host id="">

<web-app-deploy path="webapps">
  <web-app context-path="/wiki"
              document-directory="wiki">
    <context-param database="jdbc/wiki">
  </web-app>
</web-app-deploy>

</host>
</cluster>
</resin>

Sets the files to use as when no filename is present in url. According to the spec, each file is in a <welcome-file> element.

element welcome-file-list {
  string
  | welcome-file*
}

<web-app xmlns="http://caucho.com/ns/resin">
  <welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>index.xtp</welcome-file>
    <welcome-file>home.xtp</welcome-file>
  </welcome-file-list>
</web-app>

Resin also provides a shortcut where you can just list the files:

<web-app xmlns="http://caucho.com/ns/resin">
  <welcome-file-list>
    index.jsp, index.xtp, home.xtp
  </welcome-file-list>
</web-app>