If you rely on URL Context Paths to differentiate sites, you must configure your environment to forward HTTP requests to the content-serving application that these sites share. Configuration largely depends on whether HTTP requests can be mapped directly to the context root of the shared application, or whether they must first be handled by the default web application. Two scenarios apply:

Configure the Content-Serving Web Application to Handle Requests

If all production site URLs contain the context root of the content-serving web application, you can configure the application’s web.xml to handle requests directly. For example, a multisite application might configure its context root as /sportswhere. It also configures its production site URLs to include /sportswhere:

/sportswhere/baseball
/sportswhere/hockey
/sportswhere/basketball

Given this configuration, HTTP requests for one of these sites always include the context root /sportswhere as in the following example:

http://sportswhere.com/sportswhere/baseball/uniforms

The non-virtual portion of this URL’s path — /sportswhere — maps directly to the context root of the content-serving application. You enable the application to handle all URLs of this type by configuring its web.xml with ForwardFilter, PageFilter, NucleusServlet and error code filtering as follows:

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                      http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
  version="2.5">
...
  <filter>
    <filter-name>ForwardFilter</filter-name>
    <filter-class>atg.servlet.ForwardFilter</filter-class>
  </filter>

  <filter>
    <filter-name>PageFilter</filter-name>
    <filter-class>atg.filter.dspjsp.PageFilter</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>ForwardFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>FORWARD</dispatcher>
  </filter-mapping>

  <filter-mapping>
    <filter-name>PageFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>

  <servlet>
    <servlet-name>NucleusServlet</servlet-name>
    <servlet-class>atg.nucleus.servlet.NucleusServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>

Note: The <dispatcher> element requires that the application’s web.xml use web-app_2_5.xsd or later.

Configure the Default Web Application to Handle Requests

If production site URLs exclude the multisite context root, you must configure the web.xml of the application server’s default web application to handle HTTP requests. For example, a multisite application might configure its production site URLs as follows:

/baseball
/hockey
/basketball

Given a request URL of http://sportswhere.com/baseball/uniforms, the non-virtual portion of the URL path is / (forward slash), which must be handled by the default web application. To do so, its web.xml must include Oracle Commerce Platform resources PageFilter, NucleusServlet and error code filtering as follows:

<filter>
  <filter-name>PageFilter</filter-name>
  <filter-class>atg.filter.dspjsp.PageFilter</filter-class>
</filter>

<filter-mapping>
  <filter-name>PageFilter</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>ERROR</dispatcher>
  <dispatcher>FORWARD</dispatcher>
</filter-mapping>

<servlet>
  <servlet-name>NucleusServlet</servlet-name>
  <servlet-class>atg.nucleus.servlet.NucleusServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>

The content-serving web application must also be configured with the ForwardFilter servlet filter:

...
<filter>
  <filter-name>ForwardFilter</filter-name>
  <filter-class>atg.servlet.ForwardFilter</filter-class>
</filter>

...

<filter-mapping>
  <filter-name>ForwardFilter</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>FORWARD</dispatcher>
  <dispatcher>ERROR</dispatcher>
</filter-mapping>

Note: The <dispatcher> element requires that the application’s web.xml use web-app_2_5.xsd or later.

Configuration of the default web application varies among application servers. The following sections describe different requirements among the various application servers that the Oracle Commerce Platform supports.

JBoss
Configure the default web application’s web.xml file as discussed above.

IBM WebSphere
You configure the default web application in IBM WebSphere in the following steps:

web.xml includes Oracle Commerce Platform resources PageFilter and NucleusServlet, it also includes the <display-name> and <description> tags, as follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                       http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
   version="2.5">

  <display-name>default-war-name</display-name>
  <description>description</description>

  <filter>
    <filter-name>PageFilter</filter-name>
    <filter-class>atg.filter.dspjsp.PageFilter</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>PageFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>ERROR</dispatcher>
    <dispatcher>FORWARD</dispatcher>
  </filter-mapping>

  <servlet>
    <servlet-name>Nucleus</servlet-name>
    <servlet-class>atg.nucleus.servlet.NucleusServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
</web-app>

The following example shows how you might set the contents of application.xml:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application
1.3//EN" "http://java.sun.com/dtd/application_1_3.dtd">

<application>
  <display-name>
    default-app-name
  </display-name>
  <module>
    <web>
      <web-uri>
        default.war
      </web-uri>
      <context-root>
        /
      </context-root>
    </web>
  </module>
</application>

Note: The <context-root> tag in application.xml must be set to / (forward slash).

Oracle WebLogic
You configure the default web application in Oracle WebLogic in the following steps:

Error Pages

If you configure error pages in the request-handling application’s web.xml, the following requirements apply:

One constraint applies when the default web application handles HTTP requests for multiple content-serving web applications. In this case, an error page that is defined in the request-handling web.xml must be in the same location within the various WAR files of the content-serving web applications.

Note: This error handing constraint differs for Oracle WebLogic. Refer to the section on Oracle WebLogic for information.

For example, you might modify the request-handling web.xml by configuring an error page as follows (changes that pertain to error handling are in bold face):

...
  <filter>
    <filter-name>ErrorFilter</filter-name>
    <filter-class>atg.servlet.ErrorFilter</filter-class>
  </filter>

  <filter>
    <filter-name>PageFilter</filter-name>
    <filter-class>atg.filter.dspjsp.PageFilter</filter-class>
  </filter>
...
  <filter-mapping>
    <filter-name>ErrorFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>ERROR</dispatcher>
  </filter-mapping>
...
  <filter-mapping>
    <filter-name>PageFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>ERROR</dispatcher>
  </filter-mapping>

<servlet>
  <servlet-name>NucleusServlet</servlet-name>
  <servlet-class>atg.nucleus.servlet.NucleusServlet</servlet-class>
  <load-on-startup>1</load-on-startup>

  <error-page>
    <error-code>404</error-code>
    <location>/globalErrors/pageNotFound.jsp</location>
  </error-page>
...

Given this configuration, any 404 errors are directed to the same location within the appropriate WAR file: context-root/pageNotFound.jsp.

Welcome Files

In order to use welcome files with virtual context roots, set the list of valid welcome files in the component /atg/dynamo/service/VirtualContextRootService, through its defaultWelcomeFiles property. This property has the following default setting:

defaultWelcomeFiles=/index.jsp,/index.html,/index.htm,/home.jsp,/main.jsp

For example, you might configure several sites with the same context root /sportswhere and assign production site URLs as follows:

/sportswhere/baseball
/sportswhere/hockey
/sportswhere/basketball

You might also configure the VirtualContextRootService.defaultWelcomeFiles property as follows:

defaultWelcomeFiles=/index.jsp,/welcome.jsp

Given this configuration and the following request:

http://www.mysports.com/baseball/

the VirtualContextRootService launches the following search under the context root /sports: