Application development

One main principle of Wheel is to maximize the speed of development. Wheel is compatible with all build environments including Ant and Maven 1/2 and will fit nicely to your build environment. However a full blown build cycle is quite a lenghty process to run every time you make a change in your UI-code which is why Wheel has strong built-in support for fast development. With a setup described in this document, you'll get a turn-over time of less than second with any servlet container that supports deploying exploded web applications.

Another important aspect of web application development with Wheel is exploiting certain IDE-features to the maximum.

Setup

Usually Java web-application development cycle consists of compiling classes, moving files from build directory to application server and then hotswapping or redeploying the application. Most application servers however support deploying exploded applications that reside outside of the server's installation directory. By exploiting this feature, we can create a development environment where the exploded application is inside the IDE workspace and classes and other resources are placed directly inside the application. In development mode Wheel will pick up all changes and refresh itself automatically and will do it fast.

The generic process of creating an optimal environment:

  1. Create a new project in your IDE.
  2. Create a subdirectory for the web application inside the project directory. (myproject/webapp for example)
  3. Add all needed static resources to the web application (WEB-INF/web.xml, WEB-INF/lib including all jar dependencies needed, css, js, etc).
  4. Configure your IDE so that it outputs compiled classes to webapp/WEB-INF/classes.
  5. Configure your servlet container so that it will deploy myproject/webapp as a web application.

Eclipse + Tomcat

First download and install latest stable Tomcat and Eclipse. You won't need any special plugins for Eclipse and no special configuration for Tomcat. For this example we'll assume that the name of your project is MyApp and your workspace root is c:\workspace (for simplicity). Desired context path for the application is /myapp.

  1. Start Eclipse and create a new project "MyApp", remember to use Java 5.0 language features.
  2. Create myapp/webapp/WEB-INF, myapp/webapp/WEB-INF/lib, myapp/webapp/WEB-INF/lib and myapp/webapp/WEB-INF/web.xml
  3. Add Wheel configuration to web.xml:
    <?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4">

    <servlet>
        <servlet-name>wheel</servlet-name>
        <servlet-class>wheel.WheelServlet</servlet-class>
        <init-param>
            <param-name>basePackageForPages</param-name>
            <param-value>myapp.pages</param-value>
        </init-param>
        <init-param>
            <param-name>applicationPackages</param-name>
            <param-value>myapp.pages</param-value>
        </init-param>
        <init-param>
            <param-name>developmentMode</param-name>
            <param-value>true</param-value>
        </init-param>
        <load-on-startup>0</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>wheel</servlet-name>
        <url-pattern>/app/*</url-pattern>
    </servlet-mapping>

</web-app>
  4. Copy at least required Wheel-dependencies to myapp/webapp/WEB-INF/lib plus all jars your application needs.
  5. Change compiler output (build path > Java Build Path > source > Default output folder) to webapp/WEB-INF/classes.
  6. Create a file myapp.xml in TOMCAT_HOME/conf/Catalina/localhost and edit it so it looks like this:
    <Context path="/myapp" docBase="C:\workspace\myapp\webapp" debug="0" reloadable="false"/>
  7. Start Tomcat.
  8. Create package myapp.pages and create class Home in it:
    package myapp.pages;

import wheel.components.StandaloneComponent;

public class Home extends StandaloneComponent{
        public void buildComponent() {
                h1("Hello World!");
        }
}
  9. Open a browser and go to address http://localhost:8080/myapp/app
  10. Try editing the class or creating a new one or whatever. All you need to do is Ctrl-S in Eclipse and Ctrl-R in your browser to see the changes. Now you're the slowest part of your development environment!
Linking Wheel javadocs

Open Build Path > Configure Build Path > Java Build Path > libraries > expand Wheel jar > Javadoc location > edit > select the directory where you've unzipped Wheel documentation and select apidocs. Now when you use Ctrl-Space, you'll get contextual help if feeling unsure what a method will do.