1.6. Your First Project with IT Mill Toolkit

This section gives detailed instructions into creating a new project that uses IT Mill Toolkit. The task will include the following steps:

  1. Create a new project in the Eclipse IDE.
  2. Import IT Mill Toolkit library JAR into the project.
  3. Write the source code.
  4. Write the web.xml Deployment Descriptor for the web application.
  5. Configure and start Tomcat (or some other web server).
  6. Open a web browser to use the web application.

We also show you how to debug the application in the debug mode in Eclipse.

1.6.1. Creating the Project

Let us create the first application project with the tools installed in the previous section. First launch Eclipse and follow the following steps:

  1. Start creating a new project by selecting from the menu FileNewProject....
  2. From the New Project window that opens, select WebDynamic Web Project and click Next.
  3. Enter the Project name, such as "myproject", and leave Use default location selected to create the new project under the default workspace location. Check that the Target runtime, that is the web container, is correct. For example, if you installed Apache Tomcat, check that it reads here. Click Next twice.
  4. The wizard will suggest myproject for a context name. This will be the subpath in the URL, for example http://localhost:8080/myproject. The default for the application root will be / (root).

    You can just accept the defaults and click Finish. The wizard closes and creates the project.

  5. Eclipse asks to switch to J2EE perspective. A Dynamic Web Project uses an external web server and the J2EE perspective provides tools to control the server and manage application deployment. Click Yes.

Figure 1.10. A New Dynamic Web Service Project

A New Dynamic Web Service Project

Feel free to explore the contents of the newborn project. Your source code will usually go under the src folder. IT Mill Toolkit libraries and any resource files will be placed under the WebContent folder, which contains all material that is to be published to the web server.

1.6.2. Including IT Mill Toolkit Libraries

You need to include the IT Mill Toolkit library package in the project. Copy the following JAR package from the directory where you unpacked IT Mill Toolkit distribution to WebContent/WEB-INF/lib folder:

  • WebContent/itmill-toolkit-5.x.x.jar

Perhaps the easiest way to include the library is to import it.

  1. Select the WebContent/WEB-INF/lib folder in the Project Explorer, right-click on the folder and select Import....
  2. Select GeneralFile System and click Next.
  3. Click Browse to select the WebContent directory under the IT Mill Toolkit installation directory and click Ok.
  4. The Import window will show the libraries contained in the directory.

    Check the itmill-toolkit-5.x.x.jar item as shown above. Click Finish to import the selected library.

Notice that Eclipse does not show the imported library under WebContent/WEB-INF folder where you imported it, but under Java ResourcesLibrariesWeb App Libraries.

You can observe that the library has appeared in the project classpath by selecting ProjectProperties and in the Properties window selecting Java Build PathLibrariesWeb App Libraries.

1.6.3. Writing the Code

Next, we will look into how to create the application class.

  1. Right-click on the Java Resources: src folder and select NewClass.

  2. Enter the class name in the Name field, for example MyApplication.
  3. Enter a package name in the Package field or leave it empty to create the class in the default package.
  4. You can enter the superclass com.itmill.toolkit.Application to create stubs for inherited abstract methods automatically, or leave it empty to define the inheritance manually in editor.
  5. Click Finish to create the class and its source file.

The skeleton of the file will be opened in the editor and will look as follows.

import com.itmill.toolkit.Application;

public class MyApplication extends Application {

	@Override
	public void init() {
		// TODO Auto-generated method stub
	}
}

You can now write the source code. The Hello World application above provides a simple example for creating a minimal application.

We will use the Calculator demo application in the rest of this section as an example. You can import the source file into the project by right-clicking the project folder and selecting ImportImport.... From the Import dialog, select GeneralFile System, click Next. Click Browse to select the demo directory from the installation package, browse to WebContent/src/itmill/toolkit/demo, and click Ok. Check Calc.java in the list on the right. In the Into folder field, enter myproject/src/com/itmill/toolkit/demo to import the source file under the com.itmill.toolkit.demo package. Finally, click Finish.

1.6.4. Defining Deployment Descriptor

You need to set up the application environment as described in Section 3.7, “Application Environment” and provide a deployment descriptor WebContent/WEB-INF/web.xml for the application.

The new web project in Eclipse contains a template for the deployment descriptor. By default, Eclipse opens the file with XML editor. To use text editor, right-click on the web.xml file and select Open WithText Editor. The template contains a <welcome-file-list> block, which you can remove if you like.

The contents of the descriptor for the Calc application are given in the example below.

Example 1.3. Web.xml Deployment Descriptor for a Project

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.4" 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">

    <servlet>
        <servlet-name>myservlet</servlet-name>
        <servlet-class>com.itmill.toolkit.terminal.gwt.server.ApplicationServlet
        </servlet-class>
        <init-param>
            <param-name>application</param-name>
            <param-value>com.itmill.toolkit.demo.Calc</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>myservlet</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

The descriptor defines a servlet with the name myservlet. The servlet class, com.itmill.toolkit.terminal.gwt.server.ApplicationServlet, is provided by IT Mill Toolkit framework and it should be the same for all IT Mill Toolkit projects. The servlet takes the class name Calc of the user application class as a parameter, including the full package path to the class. If the class is in the default package the package path is obviously not used.

For a more detailed treatment of the web.xml file, see Section 3.7.3, “Deployment Descriptor web.xml.

1.6.5. Ready to Go!

Now everything should be in place and your Eclipse should look like this:

Figure 1.11. A Ready Project

A Ready Project

In a production-ready project, you should also have widget sets and themes in the WebContent/ITMILL directory. The default widget sets and themes are included in the JAR library, but accessing them from a JAR is inefficient. We recommend installing the ITMILL directory so that it can be accessed directly from the web server. You can copy the directory from under the IT Mill Toolkit installation directory to the WebContent directory in your project, or extract it from the JAR package.

1.6.6. Starting the Web Server

Eclipse IDE for Java EE Developers has the Web Standard Tools package installed, which supports control of various web servers and automatic deployment of web content to the server when changes are made to a project.

Make sure that Tomcat was installed with user permissions. Configuration of the web server in Eclipse will fail if the user does not have write permissions to the configuration and deployment directories under the Tomcat installation directory.

Follow the following steps.

  1. Switch to the Servers tab in the lower panel in Eclipse. List of servers should be empty after Eclipse is installed. Right-click on the empty area in the panel and select NewServer.
  2. Select ApacheTomcat v6.0 Server and set Server's host name as localhost, which should be the default. If you have only one Tomcat installed, Server runtime has only one choise. Click Next.
  3. Add your project to the server by selecting it on the left and clicking Add to add it to the configured projects on the right. Click Finish.
  4. The server and the project are now installed in Eclipse and are shown in the Servers tab. To start the server, right-click on the server and select Debug. To start the server in non-debug mode, select Start.
  5. The server starts and the WebContent directory of the project is published to the server.

1.6.7. Running and Debugging

If you have everything set up as described above, all the rest is easy. Just head your web browser to http://localhost:8080/myproject/.

Figure 1.12. Running an IT Mill Toolkit Application

Running an IT Mill Toolkit Application

To examine how the application works, you can insert break points in the Java code by double-clicking on the left margin bar of the source code window. A small magnifying glass will indicate the breakpoint. If you insert a breakpoint in the buttonClick() event handling method and click any button in the calculator, eclipse will ask to switch to the Debug perspective. Answer Yes and the Debug perspective will open where the execution stopped at the breakpoint. You can examine the state of the application and even make some changes and then select Resume from Run menu to continue the execution.

Figure 1.13. Debugging an IT Mill Toolkit Application

Debugging an IT Mill Toolkit Application

The procedure described above allows debugging the server-side application. If you develop client-side widgets with Google Web Toolkit (GWT), the GWT Hosted Mode Browser allows you to debug the widgets. For more information on debugging client-side widgets, see Section 8.7.6, “Hosted Mode Browser”.