Apache Struts 2 Documentation > Home > Guides > Core Developers Guide > Related Tools > QuickStart |

Apache Struts 2 Documentation
QuickStart
Edit Page Browse Space Add Page Add News
Added by Patrick Lightbody, last edited by Ted Husted on Sep 03, 2006 (view change)

Today, most web development still follows a strict `code/compile/deploy/review` development cycle. In practice, the `deploy` steps often means stopping and starting the web server, which can steal a significant amount of development time.The QuickStart feature is designed to reduce or eliminate restarting the server after changes to source code or configuration files. The goal is to allow developers to work interactively with an application as it is being developed, so that we can write better code faster. Essentially, QuickStart is a combination of technologies and conventions.

## QuickStart

The best way to get started with any new technology can be to just jump in and try it out. If you agree, download a distribution and take the WW:QuickStart feature for a spin.

QuickStart Quick Start

- Download and extract a distribution
- Open a command prompt to the root directory of the distribution
- Using a Java 5 JDK, execute:
  - `java -jar struts2-core.jar quickstart:showcase`
- Open your browser to the URL:
  - `http://localhost:8080/showcase`
- Feel free to edit any of the sources (.java, .jsp) in:
  - `webapps/showcase`
- Reload your browser to see the changes right away

## Using QuickStart

QuickStart is included in the framework distribution. Launch it opening a command window on the distribution root and running

    > java \-jar struts2-core.jar quickstart:mywebapp

With QuickStart running, you can fire up a web browser, open `http://localhost:8080/mywebapp`, and begin developing your application.

QuickStart requires Java 1.5.

| java.net.BindException: Address already in use Out of the box, QuickStart is set to use port 8080. If another service is already running at 8080 (say, Tomcat), you should stop that service before starting QuickStart.

There is a little more to using QuickStart effectively. But not much more. QuickStart assumes the a specific directory structure.

QuickStart Directory Structure

- struts2
  - lib - all your required libs, usually the ones you would put in `WEB-INF/lib`
  - webapps
    - mywebapp
      - src
        - java - your Java sources that would normally be compiled to `WEB-INF/classes`
        - webapp
          - WEB-INF
            - classes - any additional configuration if you'd like
            - web.xml
  - struts2-core.jar
  - launcher.jar

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

Once you have a starter application up and running, you are free to change your classes, JSPs, template files, and other resources 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 Struts 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:

- Apply additional command-line options
- Use a quickstart.xml configuration file

### Additional Command-line Options

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

- Context
- Webapp directory
- Source directory

Suppose your project layout is the following:

Sample Project Layout

- project
  - lib - all your required libs, usually the ones you would put in `WEB-INF/lib`*** src
    - - java - your Java sources that would normally be compiled to `WEB-INF/classes`
      - webapp
        - WEB-INF
          - classes - any additional configuration if you'd like
          - web.xml

You could launch your application using QuickStart by executing the command:

    > java \-jar lib/struts2-core.jar quickstart /project src/webapp src/java

### 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 JARs 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:

Error formatting macro: snippet: java.lang.IllegalArgumentException: Invalid url: must begin with a configured prefix.

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 combines Struts 2 with an embedded Jetty server, some advanced class loading, and the Eclipse Java compiler. (Don't worry, the Eclipse IDE is not required!)

Running `struts2-core.jar` bootstraps the classpath and includes every JAR found in the `lib` directory. It also includes `struts2-core.jar`, of course. The procss then invokes the QuickStart application. This, in turn, starts a Jetty server that is configured to the web application 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 the framework creates a new Action on every request, reloading the classes works great. You are free to change the entire class schema (methods, fields, inheritance, and so forth). 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 `struts2-core.jar` is included. Pay close attention to your working directory.

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

## Common Pitfalls

While the framework 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.

| ClassCastException 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.

### To Quickstart or not to Quickstart?

Quickstart is a handy tool for development of your applications. We recommend that you give QuickStart a try, to see if it meets your development needs. However, QuickStart is not meant to be your sole environment for web application development. QuickStart is meant to help you rapidily create proof-of-concepts and so that you can see the result. We recommend you always at least test your work under other applications servers, such as Tomcat, Resin, or even the standard, standalone version of Jetty.