WebWork - QuickStart

WebWork provides a quick way to get started called QuickStart. QuickStart is essentially a combination of a few technologies and some general conventions for developing web applications. What it lets you do is write applications without the need to even compile your sources, let alone have to deploy and redeploy them after every change. Instead, you can now develop your web applications just like if you were writing perl or PHP - on the fly and as quickly as you can think.

How to Use It

QuickStart is included in the WebWork distribution and can be launched by simply running java -jar webwork.jar quickstart:mywebapp. At this point you can access http://localhost:8080/mywebapp and begin developing your application. At this time, QuickStart requires Java 1.5.

Is Port 8080 really free for use?

If you face problems while starting applications via quickstart mechanism, leading to output like

java.net.BindException: Address already in use

you already have a running container at IP port 8080. This may be the case if you installed a tomcat server distribution for your operating system, with autostart enabled. Please be sure to stop the application bound to port 8080 before trying to use quickstart.

OK, it's a little more work than that, but not much more. QuickStart assumes the following directory structure:

You can quickly get started by copying one of the existing webapps in the WebWork distribution.

Once you have it up and running, you are free to change your classes, JSPs, template files, and other files on the fly - all without compiling or redeploying. Some files, such as web.xml, will require that you restart QuickStart for the changes to take affect. Similarly, some frameworks, such as Hibernate, do not offer the full class-reloading support that WebWork does. Your mileage may vary, but we think no matter what you'll love developing in QuickStart.

Advanced Deployment

Don't have a directory structure like the one laid out? Want to use a port other than 8080? No problem! There are two options for you:

Additional Command-line Options

While the quickstart:xxx shorthand is nice, it often doesn't work for many people beyond the initial WebWork distribution packaging. So QuickStart allows you to specify three options from the command line:

Using the quickstart.xml File

Sometimes the command line options still aren't enough. For whatever reasons, port 8080 might not be enough, or you may need to extend other configurations. Or perhaps your libs are not in your project but instead are in some other directory (very common if you use Maven to build your project). To help out, QuickStart provides a configuration file that let's you tweak how the deployment happens and how it is configured as much as you'd like. Consider the sample quickstart.xml file:

<configuration>
    <!--
    QuickStart can be used to extend other QuickStart configurations.
    This is great for applications that have multiple "editions" and
    extend upon a base webapp or evven just a base set of classes.
    -->
    <!--<extendsConfig>../path/to/quickstart.xml</extendsConfig>-->

    <!--
    QuickStart supports reading your IDEA module configuration and
    using the libraries there. This is especially useful for maven
    users who don't have a single directory in their project that
    contains all the libraries they need.
    -->
    <!--<ideaConfig>ShowCase.iml</ideaConfig>-->

    <!-- The context in which to deploy the web application -->
    <context>/showcase</context>

    <!-- The port in which to deploy the web application -->
    <port>8080</port>

    <!--
    The libs directories can be a jar, a directory of jars, or even
    a directory of directories (searched recursively)
    -->
    <libs>
        <dir>../../lib</dir>
    </libs>

    <!--
    Optional: the location where your source files are. If this is
    not included, the auto-recompiling feature of QuickStart will
    not be enabled. You may wish to do this anyway, as this feature
    has been known to cause strange side effects. If you don't
    specify your sources, you must specify where your classes are by
    using the classDirs and libs elements
    -->
    <sources>
        <dir>src/java</dir>
    </sources>

    <!--
    The classDirs directories can be a jar or a directory of classes.
    The WEB-INF/classes directory for each webDir (below) will automatically
    be added if it exists.

    <classDirs>
        <dir>src/webapp/WEB-INF/classes</dir>
    </classDirs>
    -->

    <!--
    You can specify one or more directories where your webapp files
    are located. This is useful if you have your project split up in
    unique ways. You can also specify the path that the directory is
    mapped to, relative to the context.
    -->
    <webDirs>
        <webDir>
            <path>/</path>
            <dir>src/webapp</dir>
        </webDir>
    </webDirs>
</configuration>

If you use this deployment technique, you must remember that quickstart.xml must be in the same working directory in which you execute the java -jar webwork.jar quickstart command. You don't need to pass any additional command line arguments to QuickStart, but you must have this file in your working directory.

How It Works

QuickStart works by using the combination of WebWork's "share nothing" (or rather, "share very little") architecture, an embedded Jetty server, some advanced class loading, and the Eclipse Java compiler (don't worry, the Eclipse IDE is not required!)

Running webwork.jar bootstraps the classpath and includes every jar found in the lib directory. It also includes webwork.jar, of course. It then invokes the QuickStart application. This, in turn, starts a Jetty server that is configured to the webapp specified in the quickstart:xxx argument.

The Jetty server's context ClassLoader is specified as a custom ClassLoader that looks at the source files in webapps/xxx/src/java and compiles them on the fly. These classes are also reloaded whenever a change is detected.

Because WebWork creates a new action on every request, reloading the classes works great. You are free to change the entire class schema (methods, fields, inheritance, etc). Because none of the objects are cached or stored in long-term storage, you usually won't run into any problems here.

Running in Your IDE

Running QuickStart from your IDE is no different than running it from the command line. The only difference is that you need to set up the structure and classpath in your IDE properly. It doesn't really matter what is in the classpath as long the WebWork jar is included. Pay close attention to your working directory.

An example of what IntelliJ IDEA looks like when launching QuickStart from within the WebWork project is included for reference (click for a larger view):

Common Pitfalls

While WebWork is pretty good about making class reloading in QuickStart easy, other libraries and code are not. As a general rule of thumb, if any objects have long term state (singleton, session scope, etc), they will not be reloaded. The reloaded classes will only take affect after a new instance has been created with the new keyword or through reflection.

For example, Hibernate has been found to store references to the objects it persists for long periods of time because of it's caching mechanism. It also happens to hold a reference to the Class instance itself. This makes it very difficult, if not impossible, to allow you to change your models on the fly.

Most problems will manifest themselves through a ClassCastException, or some other weird class-related error. You may even find yourself banging your head against the wall because some Foo instance can't be cast to the Foo class. This is the biggest challenge with using QuickStart and can best be mitigated by using libraries and code that share very little state.

A final word of warning: QuickStart is not meant for production use, or even to be used as the sole environment for application development. Rather, it is meant to help you quickly develop proof-of-concepts and see results quickly. We recommend you always at least test in other applications servers, such as Tomcat, Resin, or even standalone Jetty.