Author: [EMAIL PROTECTED]
Date: Wed Dec 3 18:07:29 2008
New Revision: 4246
Added:
wiki/WAR_Design_1_6.wiki
Log:
Created 1.6 WAR design doc through web user interface.
Added: wiki/WAR_Design_1_6.wiki
==============================================================================
--- (empty file)
+++ wiki/WAR_Design_1_6.wiki Wed Dec 3 18:07:29 2008
@@ -0,0 +1,135 @@
+#summary Plans for changes to GWT output for 1.6.
+
+= Design Doc for 1.6 WAR structure =
+
+In 1.5, `GWTShellServlet` served resources directly off the classpath (for
public files), or generated files from a temporary location. This has the
advantage of allowing fast refresh and resource updating, and making
things "easy". However, it has the downside of not leaving the user with
something that's easy to deploy.
+
+We will rectify the deployment issue in 1.6 by standardizing GWT around
the "expanded WAR format". The two *key principles* are:
+
+ # The result of running the GWT compiler (and possibly some associated
tools/build rules) will be an expanded WAR directory structure that can be
immediately deployed to a Java Servlet Container compatible web server.
+ # Hosted mode will operate using essentially the same format, in the
same directory, to ensure that hosted and compiled web applications behave
the same.
+
+In 1.6, we always dump all resources directly into the WAR directory,
which the server serves directly out of. We automate in hosted mode what a
build process would do. This is triggered by the Hosted Browser actually
executing a selection script; the selection script (when running hosted
mode) forces a hosted mode link. Subsequent `GWT.create()` calls may cause
incremental links.
+
+== Non-Goals / Off-the-table ==
+
+ * Produce a JS library or anything other than a standard GWT application
+ * Implement server code refresh within the hosted mode servlet container
+ * Implement a more complex project structure based on the idea of
a "source" war template which is automatically copied into the output war
directory; external tools could do this.
+
+== Proposed Simple GWT project structure ==
+{{{
+MyProject/
+ build.xml <ant build file with
various targets to javac, gwtc, hosted, server, clean>
+ src/
+ <source code, GWT modules, public resources>
+ war/
+ MyProject.html <a host HTML page>
+ MyProject.jsp <another host page>
+ MyProject.css <non-GWT static resources>
+ WEB-INF/
+ web.xml <contains servlet
mappings>
+ classes/
+ <classes compiled by IDE or build rule>
+ lib/
+ gwt-servlet.jar
+ <other server-side libs>
+ qualified.ModuleName/
+ qualified.ModuleName.nocache.js <selection script>
+ public_resource.gif
+ generated_resource.png
+ <other public and generated files>
+ scripts/
+ STRONGNAME1.cache.js <compiled script>
+ STRONGNAME2.cache.js <compiled script>
+ <other compiled scripts>
+ qualified.ModuleName2/
+ <as above>
+ extra/
+ qualified.ModuleName/
+ <non-deployed linker artifacts>
+ qualified.ModuleName2/
+ <non-deployed linker artifacts>
+}}}
+
+Note: the `extra/` subfolder will not be produced by default.
+
+== Changes in Suggested Best Practices ==
+
+The most key user-facing change is that we no longer suggest that host
HTML pages live in the public path of the application module. Instead, we
suggest that many static resources, most especially the host HTML page that
includes a GWT module, should live in the `war` directory as a static
resource rather than on the classpath.
+
+== Command Line Options, old vs. new ==
+
+In 1.5, the output level options work this way:
+
+ * `-out` is respected by both GWTCompiler and GWTShell, it represents
the "root" output folder
+ * Defaults to the current working directory
+ * Deployable files go into `out/qualified.moduleName/`
+ * Non-deployed files go into `out/qualified.ModuleName-aux/`
+ * Extra cruft is created in `out/.gwt-tmp/`
+
+This situation is undesirable because it the out directory is not
immediately useful without addition build rules and processing. We propose
for 1.6 that the output be in standard expanded WAR format. We will retain
`GWTCompiler` and `GWTShell` for backwards-compatibility with 1.5, but
newly created projects will use new entry points, `Compile` and
`HostedMode`.
+
+ * `-war` is used to specify the WAR output folder
+ * The default value is <current directory>/war
+ * `-extra` is used to specify the output folder for non-deployed linker
artifacts
+ * The default value is to not produce extra output
+ * `-server` can be used to specify what server should be run
+ * The argument is the name of a class which implements a
`ServletContainerLauncher` interface; details TBD
+ * The default value is to launch a Jetty server, which will we
distribute with GWT
+ * `-noserver` can be used to run no server at all
+ * `HostedMode` requires a list of modules to serve as the default
argument
+ * `-startupUrl` is optionally (but canonically) used to launch one or
more urls in the hosted browser on startup, which is what GWTShell used to
use the default argument for
+ * `Compiler` can support a list of modules to compile, as opposed to
just a single module
+ * `-out` is no longer supported
+ * `.gwt-tmp/` is no longer created in the output folder
+
+== How Hosted Mode Will Work ==
+
+We will no longer use `GWTShellServlet` and embedded Tomcat. Instead, we
will used Jetty by default, but allow other servers to be plugged in
through a lightweight interface.
+
+ # `HostedMode` performs an initial link for each module specified on the
command line
+ # Public resources and a generated a default selection script are
copied into `war/qualified.ModuleName/`
+ # `HostedMode` starts the web server, targeting it at war/.
+ # `HostedMode` launches a hosted browser window for each -startupUrl
specified on the command line
+ # The hosted browser requests the host HTML page from the server.
+ # The host HTML page loads the generated selection script for the
included modules.
+ # The generated selection script recognizes the hosted browser
environment and takes special action
+ # The `window.external` interface is used to create a unique
debugging "session".
+ # A random (or monotonically increasing) session ID is chosen
+ # A new module-session directory,
`war/qualified.ModuleName-<sessionID>/` is created
+ # Another link is performed into the module-session directory
+ # The original selection script delegates to the new selection script
in the module-session directory
+ # The GWT module base url targets the new directory
+ # The new selection script loads `hosted.html` into an `IFRAME`, and
hosted mode continues bootstrapping as per 1.5
+ # Whenever new resources are generated from a `GWT.create(`)
resolution, an incremental link is performed into the module-session
directory.
+ # The new selection script hooks window closing, and triggers deletion
of the module-session directory when the session is complete.
+ # As a backup, a VM shutdown hook is used to delete any outstanding
module-session directories.
+ # If the user refreshes the page
+ # The old module-session directory is deleted as per above
+ # A new module-session directory is created as per above
+ # We do not provide a mechanism to reload server-side code executing
in the servlet container
+ # If the user presses "Compile/Browse"
+ # The set of modules passed in on the command line are compiled
+ # They are linked into the canonical path,
`war/qualified.ModuleName/`, not the module-session directory.
+ # A web browser then loads the host HTML page, which loads the
compiled selection script.
+ # The compiled selection script detects that it is not running in the
hosted browser, and therefore loads web mode normally.
+
+== Coordination with Eclipse Plugin ==
+Make sure that it expects to track the list of active modules for a given
project.
+
+== Open Issues ==
+ # How do we isolate the web app classloader to ensure same behavior in
deployment?
+ # What happens to the GWT `<servlet>` tag for `HostedMode`?
+ # Supported programmatically? (Can lead to deployment failure.)
+ # Deprecated?
+ # Ignored?
+ # Validate that web.xml matches and suggest the text to add? <---
this one
+ # `war/qualified.ModuleName/scripts/` is likely to change in 2.0 with
runAsync
+ # How will JUnit work?
+ # Probably can use legacy stuff for now
+ # Will this design work with Maven?
+
+== Open Tasks ==
+ # Make sure app creator and sample follow this structure.
+ # Remove the GWT module deploy-to attribute introduced in the 1.6 branch.
--~--~---------~--~----~------------~-------~--~----~
http://groups.google.com/group/Google-Web-Toolkit-Contributors
-~----------~----~----~----~------~----~------~--~---
