The bootstrap process of a Google Web Toolkit application involves a <Module Name>.nocache.js 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:
The sections below provide more detail, and some examples.
Example Download Sequence
GWT expects to find all its files at the same path as the <module>.nocache.js 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. 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:
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, as you may expect, 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:
Relocating the Files to a different site
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:
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. Something to keep in mind is that these resources are expected to be in the same path as the <module>.nocache.js file. Particularly, it is important to be aware that the GWT.getModuleBaseURL() method will resolve to the path where your <module>.nocache.js file is located. 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.
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:
- 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
GWT expects to find all its files at the same path as the <module>.nocache.js 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. 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:
- http://host.domain.tld/myApp/index.html
- http://host.domain.tld/myApp/com.company.app.MyApp.nocache.js
- 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, as you may expect, 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:
- http://host.domain.tld/index.html
- http://host.domain.tld/gwt-files/com.company.app.MyApp.nocache.js
- http://host.domain.tld/gwt-files/CAFEBABE12345678DEADBEEF87654321.cache.html
Relocating the Files to a different site
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:
- http://host.domain.tld/index.html
- http://static.host.domain.tld/com.company.app.MyApp-xs.nocache.js
- 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. Something to keep in mind is that these resources are expected to be in the same path as the <module>.nocache.js file. Particularly, it is important to be aware that the GWT.getModuleBaseURL() method will resolve to the path where your <module>.nocache.js file is located. 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.