How do I change the location of my cache/nocache HTML files?

The bootstrap process of a Google Web Toolkit application involves a <Module Name>.nocache.html file, and a number of .cache.html files. In the hosted mode environment, these applications are automatically placed at a URL path based on the name of the module. For instance, if your GWT module is com.company.app.MyApp, then in hosted mode the URL path will be /com.company.app.MyApp/MyApp.html.

When a GWT application is deployed, however, it must coexist with the rest of the web site. To correctly integrate a GWT application into a web site's file structure, the site administrator must understand how GWT applications bootstrap. Otherwise, the files may not be at the locations where the GWT infrastructure expects to find them, and the application will not load.

To begin, it's useful to list the basic facts and constraints. There are minor differences in these details between GWT 1.3 and GWT 1.4, so we'll explain them separately here.

For GWT 1.3:

• The application's host HTML file (that is, the file containing the <meta> and <script> tags) may exist anywhere on a web site. There are no constraints on this URL.
• By default, GWT expects all its files to be at the same path as the host HTML file.
• It is possible to override the default, and instruct GWT to load its files from a path other than the host page's path.
• The location of the gwt.js file relative to the host HTML page is not significant; gwt.js attempts to locate files relative to the host HTML's URL, not the URL from which gwt.js was loaded.
• The .nocache.html file and .cache.html files must be located at the same path.
• It is not possible to instruct GWT to load files from a different site than where the host page was loaded.

For GWT 1.4, these facts and constraints are slightly different due to a newer, more efficient bootstrapping model. However, keep in mind that GWT 1.4 still supports the 1.3 bootstrap model, so the information above holds if you are using the 1.3 model. If you are instead using the 1.4 bootstrap model, here is how those details change:

• The application's host HTML file (that is, the file containing the <script> tag referencing the <module>.nocache.js file) may exist anywhere on a web site. There are no constraints on this URL.
• The location of the <module>.nocache.js file relative to the host HTML page is not significant; the .nocache.js file attempts to locate files relative to the URL from which it was loaded, not relative to the URL of the host HTML page.
• The .cache.html and other files generated by the GWT compiler must be located at the same path as the .nocache.js file.
• It is possible to instruct GWT to load files from a different site than where the host page was loaded using the GWT 1.4 bootstrap process in cross-site mode. This involves using the <module>-xs.nocache.js file generated by the GWT compiler.

The sections below provide more detail, and some examples.

Example Download Sequence using the GWT 1.3 bootstrap model

By default, GWT expects to find all its files in the same path as the host HTML file. For example, suppose your GWT Module's name is com.company.app.MyApp, and that the host HTML file is at http://host.domain.tld/myApp/index.html. By default, this sequence of requests will occur:

1. http://host.domain.tld/myApp/index.html
2. http://host.domain.tld/myApp/gwt.js
3. http://host.domain.tld/myApp/com.company.app.MyApp.nocache.html
4. http://host.domain.tld/myApp/CAFEBABE12345678DEADBEEF87654321.cache.html

Note that this sequence -- except of course for #2 -- will be true even if you move the gwt.js file to another location (such as to /gwt.js instead of /myApp/gwt.js so that you can share a single gwt.js file among several applications.) The nocache and cache files are located relative to the host HTML page (/myApp/index.html in this example), not the URL of gwt.js.

Example download sequence using the GWT 1.4 bootstrap model

In the GWT 1.4 bootstrap model, GWT expects to find all its files in the same path as the <module>.nocache.js file. For example, let's again suppose your GWT Module's name is com.company.app.MyApp, and that the host HTML file is at http://host.domain.tld/myApp/index.html. Further suppose that the <module>.nocache.js and other files generated by the GWT compiler are in the same path as the host HTML file. With this setup, the following sequence of requests will occur:

1. http://host.domain.tld/myApp/index.html
2. http://host.domain.tld/myApp/com.company.app.MyApp.nocache.js
3. http://host.domain.tld/myApp/CAFEBABE12345678DEADBEEF87654321.cache.html

Relocating the Files

The configuration above may not work in your own case. For example, for organizational reasons you might want to place the host HTML page at the root path, but place the GWT-related files at a different location, such as /gwt-files.

To do this using the GWT 1.3 bootstrap model, you must alter the format of the <meta> tag.

Again supposing that your GWT Module is com.company.app.MyApp, the default <meta> tag in /index.html would be:

<meta name="gwt:module" content="com.company.app.MyApp"/>

To instruct GWT to load files from the /gwt-files/ path instead of the root (/) path, you would use an alternate form of the content attribute:

<meta name="gwt:module" content="gwt-files=com.company.app.MyApp"/>

The syntax of the content attribute's value is "<path containing the module's files>=<module name>". The example above would result in the following file download sequence:

1. http://host.domain.tld/index.html
2. http://host.domain.tld/gwt.js
3. http://host.domain.tld/gwt-files/com.company.app.MyApp.nocache.html
4. http://host.domain.tld/gwt-files/CAFEBABE12345678DEADBEEF87654321.cache.html

Note that in #2, gwt.js was still loaded from the same path as the host page index.html. This is purely a function of the <script> tag used in index.html. That is, the example above still assumed the usual <script language="JavaScript" src="gwt.js"> tag. If you were to change that to src="gwt-files/gwt.js" then the request in #2 would change accordingly.

To relocate the GWT application files to the /gwt-files path using the GWT 1.4 bootstrap model, all you need to do is update the <script> tag referencing the <module>.nocache.js file to include the relative (or absolute) path to the file. The files generated by the GWT compiler, including the .cache.html files, must also reside at the same path as the <module>.nocache.js file.

Again supposing that your GWT Module is com.company.app.MyApp, the <script> tag in /index.html would be:

<script language="JavaScript" src="/gwt-files/com.company.app.MyApp.nocache.js"></script>

The example above would result in the following file download sequence:

1. http://host.domain.tld/index.html
2. http://host.domain.tld/gwt-files/com.company.app.MyApp.nocache.js
3. http://host.domain.tld/gwt-files/CAFEBABE12345678DEADBEEF87654321.cache.html

Relocating Files Using an Absolute Location using the GWT 1.3 bootstrap model

The example further above using the GWT 1.3 bootstrap model used a meta-tag remap with a relative path. As already mentioned, that is relative to the host HTML file. Suppose the host file were /myApp/index.html again; given the same <meta> tag as in the previous example, the new sequence would be:

1. http://host.domain.tld/myApp/index.html
2. http://host.domain.tld/myApp/gwt.js
3. http://host.domain.tld/myApp/gwt-files/com.company.app.MyApp.nocache.html
4. http://host.domain.tld/myApp/gwt-files/CAFEBABE12345678DEADBEEF87654321.cache.html

That is, the remap was relative. However, absolute remaps using the GWT 1.3 bootstrap model also work. For example, suppose that your host HTML is at /foo/index.html but your GWT files are at /bar/, along with your gwt.js file. In that case, you would have the following <script> and <meta> tags:

<meta name="gwt:module" content="/bar=com.company.app.MyApp"/> <script language="JavaScript" src="/bar/gwt.js"></script>

This would result in the following sequence:

1. http://host.domain.tld/foo/index.html
2. http://host.domain.tld/bar/gwt.js
3. http://host.domain.tld/bar/gwt-files/com.company.app.MyApp.nocache.html
4. http://host.domain.tld/bar/gwt-files/CAFEBABE12345678DEADBEEF87654321.cache.html

Relocating the Files to a different site using the GWT 1.4 bootstrap model

Many organizations put their host page on http://mysite.com/ but put CSS, images, JavaScript files, and other static resources on http://static.mysite.com/ because it can be more efficient to separate static content onto a server with a large memory cache that is dedicated to serving static files. For this reason, GWT 1.4 offers a way to have the bootstrap process load GWT application files from a different site. This is possible due to the new <module>-xs.nocache.js cross-site script inclusion mode.

To have the bootstrap process work in cross-site script inclusion mode, the <script> tag in the host HTML page must reference the <module>-xs.nocache.js file rather than the <module>.nocache.js file. Going back to the example, let's suppose that the GWT module is still com.company.app.MyApp and the index.html file located at the root of the application, that is http://host.domain.tld/index.html. Let's also assume that the <module>-xs.nocache.js along with the other GWT generated application files are stored at the root of another server responsible for serving static content on the domain http://static.host.domain.tld/. The <script> tag in the host HTML page would now be:

<script language="JavaScript" src="http://static.host.domain.tld/com.company.app.MyApp-xs.nocache.js"></script>

This new configuration would result in the following download sequence:

1. http://host.domain.tld/index.html
2. http://static.host.domain.tld/com.company.app.MyApp-xs.nocache.js
3. http://static.host.domain.tld/CAFEBABE12345678DEADBEEF87654321.cache.html

Additional Considerations

Usually applications will need additional content, such as images and CSS files, and of course dynamic resources such as RPC or JSON URLs. The techniques described above will change not only the path used to fetch GWT's application files, but also the value returned by the GWT.getModuleBaseURL() method. If your application uses that method to construct URLs to additional resources, be sure that the resources are located in the appropriate directory. For example, if you remap your GWT files to '/gwt-files/', but your host page is /index.html, then the code GWT.getModuleBaseURL() + "myImage.png" will result in the URL /gwt-files/myImage.png.

It's important to take care if your code refers to resources using GWT.getModuleBaseURL(). This is an especially common concern for those using Java Servlets, since the Servlet mapping must be set appropriately in the web.xml file.

Finally, note that while absolute remaps of the form content="/foo=mypackage.Module" using the GWT 1.3 bootstrap model are allowed, fully-qualified remaps of the form content="http://host.domain.tld/foo=mypackage.Module" are not allowed. In some cases, it may work anyway by sheer luck, but this is not a supported syntax and may break in a future version.