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:
The sections below provide more detail, and some examples.
Example Download Sequence
By default, GWT expects to find all its files at 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:
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.
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, 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:
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.
Relocating Files Using an Absolute Location
The example above 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:
That is, the remap was relative. However, absolute remaps 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:
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" 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.
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 <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.
The sections below provide more detail, and some examples.
Example Download Sequence
By default, GWT expects to find all its files at 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:
- http://host.domain.tld/myApp/index.html
- http://host.domain.tld/myApp/gwt.js
- http://host.domain.tld/myApp/com.company.app.MyApp.nocache.html
- 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.
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, 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:
- http://host.domain.tld/index.html
- http://host.domain.tld/gwt.js
- http://host.domain.tld/gwt-files/com.company.app.MyApp.nocache.html
- 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.
Relocating Files Using an Absolute Location
The example above 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:
- http://host.domain.tld/myApp/index.html
- http://host.domain.tld/myApp/gwt.js
- http://host.domain.tld/myApp/gwt-files/com.company.app.MyApp.nocache.html
- http://host.domain.tld/myApp/gwt-files/CAFEBABE12345678DEADBEEF87654321.cache.html
That is, the remap was relative. However, absolute remaps 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:
- http://host.domain.tld/foo/index.html
- http://host.domain.tld/bar/gwt.js
- http://host.domain.tld/bar/gwt-files/com.company.app.MyApp.nocache.html
- http://host.domain.tld/bar/gwt-files/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" 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.