New Support for Virtual Directory Mappings

New Support for Virtual Directory Mappings

In GlassFish, every virtual server has a docroot property, which points to the local directory that will be used to serve resources for requests that cannot be mapped to any of the web contexts deployed on the virtual server.

Alternatively, a virtual server may designate one of its deployed web modules as its default web module, by specifying a default-web-module attribute whose value refers to one of the deployed web modules by its name. In this case, any requests that cannot be mapped to any of the web modules deployed on the virtual server will be mapped to the virtual server's default web module.

By default, a virtual server's docroot points to the ${com.sun.aas.instanceRoot}/docroot directory, as can be seen from this domain.xml snippet:

  <virtual-server id="server" [...]>
    <property name="docroot" value="${com.sun.aas.instanceRoot}/docroot"/>
  </virtual-server>

This means that when you access this URL:

  http://<host>:<port>/index.html

the contents of the ${com.sun.aas.instanceRoot}/docroot/index.html resource will be served.

By default, all virtual servers share the same docroot directory, but since the docroot property is configurable, each virtual server may be configured with its own, individual docroot.

As of GlassFish v2-b20, it is possible to configure a virtual server's docroot with finer granularity, based on the URL pattern of the request.

For example, it is now possible to configure a virtual server so that all requests with a URI that starts with /images/* will be served from one directory, whereas all requests whose URI ends in *.jsp will be served from a different directory. Each mapping from URL pattern to directory path constitutes an alternate docroot.

In GlassFish v2, a virtual server's alternate docroots are configured using the <property> subelement of <virtual-server> (this is mainly for historical reasons), as in the following sample domain.xml snippet:

  <virtual-server id="server" [...]>
    <property name="alternatedocroot_1" value="from=/images/* dir=/usr/gifs"/>
    <property name="alternatedocroot_2" value="from=*.jpg dir=/usr/gifs"/>
    <property name="alternatedocroot_3" value="from=*.jsp dir=/usr/jsps"/>
    <property name="docroot" value="${com.sun.aas.instanceRoot}/docroot"/>
  </virtual-server>

A future version of GlassFish will add proper configuration support for alternate docroots by defining a <virtual-directory-mapping> element under <virtual-server> in domain.xml, with <local-path> and <url-pattern> subelements. The above configuration, while still supported, could then be represented more cleanly, as follows:

  <virtual-server id="server" [...]>
    <virtual-directory-mapping>
      <local-path>/usr/gifs</local-path>
      <url-pattern>/images/*</url-pattern>
      <url-pattern>*.jpg</url-pattern>
    </virtual-directory-mapping>
    <virtual-directory-mapping>
      <local-path>/usr/jsps</local-path>
      <url-pattern>*.jsp</url-pattern>
    </virtual-directory-mapping>
    <property name="docroot" value="${com.sun.aas.instanceRoot}/docroot"/>
  </virtual-server>

If a request matches multiple alternate docroot URL patterns, the following precedence order is used:

1. Exact match
2. Longest path match
3. Extension match

Any request that cannot be mapped to any of the web modules deployed on the virtual server, and whose URI does not match any of the virtual server's alternate docroot URL patterns, will continue to be served from the directory indicated by the virtual server's docroot property.

You may use the GlassFish admingui or command-line interface (asadmin) to add alternatedocroot_ properties to a virtual server. Please note that GlassFish does not support multi-valued properties in domain.xml. Therefore, if you want to specify multiple alternate docroots for a given virtual server, you need to make sure that each alternate docroot has a distinct property name that starts with alternatedocroot_.

A future enhancement will be to support alternate docroots for web modules. This will, amongst other things, allow web modules to share certain kinds of resources available on the server, instead of requiring every web module to bundle such resources. For example, by each defining alternate docroots with URI patterns of the form /images/* and *.jpg and a target directory of /usr/gifs, web modules would be able to share any *.jpg resources available under /usr/gifs (provided they have read access to this directory).

Posted at 11:48AM Oct 05, 2006 by Jan Luehe in Sun  |  Comments[9]