While more and more server based frameworks, libraries, standards, and architectures for Java are invented to make the programmer's life easier, software deployment seems to get harder and harder. For example, Java Enterprise Beans tried to make the creation of persistent and networked objects easy and somewhat automatic, but the number of deployment descriptions got enormous. As IT Mill Toolkit lives in a Java Servlet container, it must follow the rules, but it tries to avoid adding extra complexity.
All IT Mill Toolkit applications are deployed as Java web applications, which can be packaged as WAR files. For a detailed tutorial on how web applications are packaged, please refer to any Java book that discusses Servlets. Sun has an excellent reference online on http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/WCC3.html .
To deploy the created application to a web server, you need to create a WAR package. Here we give the instructions for Eclipse.
Open project properties and first set the name and destination of the WAR file in Tomcat
tab. Exporting to WAR is done by selecting from in project context menu (just click calc with the right mouse button on ).The following files are required in a web application in order to run it.
Web application organization
WEB-INF/web.xml
This is the standard web application descriptor that defines how the application is organized. You can refer to any Java book about the contents of this file. Also see an example in Example 3.1, “web.xml”.
WEB-INF/lib/itmill-toolkit-5.0.0.jar
This is the IT Mill Toolkit library. It
is included in the product package in
lib
directory.
You must include your application
classes either in a JAR file in
WEB-INF/lib
or as classes in
WEB-INF/classes
If your application uses a special theme
(look and feel), you must include it in
WEB-INF/lib/themes/themename
directory.
The deployment descriptor is an XML file with the name
web.xml
in the WEB-INF
directory of
a web application. It is a standard component in Java EE describing
how a web application should be deployed. The structure of the deployment
descriptor is illustrated by the following example. You simply deploy
applications as servlets implemented by the special
com.itmill.toolkit.terminal.gwt.server.ApplicationServlet
wrapper class. The class of the actual application is specified by giving
the application
parameter with the name of the
specific application class to the servlet. The servlet is then connected
to a URL in a standard way for Java Servlets.
Example 3.1. web.xml
<?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>MyApplicationClass</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 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.
The url-pattern
is defined above as
/*
. This matches to any URL under the project
context. We defined above the project context as
myproject
so the application URL will be
http://localhost:8080/myproject/
. If the project were to have
multiple applications or servlets, they would have to be given different names to distinguish them.
For example, url-pattern
/myapp/*
would match a URL such as
http://localhost:8080/myproject/myapp/
. Notice that the slash
and the asterisk must be included at the end of the
pattern.
Notice also that if the URL pattern is other than root
/*
(such as /myapp/*
), you will also
need to make a servlet mapping to /ITMILL/*
(unless you
are serving it statically as noted below). For example:
... <servlet-mapping> <servlet-name>myservlet</servlet-name> <url-pattern>/myurl/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>myservlet</servlet-name> <url-pattern>/ITMILL/*</url-pattern> </servlet-mapping>
You do not have to provide the above /ITMILL/*
mapping
if you serve both the widget sets and (custom and default) themes
statically in WebContent/ITMILL/
directory. The
mapping simply allows serving them dynamically from the IT Mill Toolkit
JAR. Serving them statically is recommended for production environments as
it is much faster.
For a complete example on how to deploy applications, see the demos
included in the IT Mill Toolkit installation package, especially the
WebContent/WEB-INF
directory.
Deployment descriptor can have many parameters and options that
control the execution of a servlet. You can find a complete
documentation of the deployment descriptor in Java Servlet
Specification at
http://java.sun.com/products/servlet/
.
By default, IT Mill Toolkit applications run in debug
mode, which should be used during development. This enables
various debugging features. For production use, you should have put in
your web.xml
the following parameter:
<context-param> <param-name>productionMode</param-name> <param-value>true</param-value> <description>IT Mill Toolkit production mode</description> </context-param>
The parameter and the debug and production modes are described in detail in Section 9.1, “Debug and Production Mode”.
One often needed option is the session timeout. Different servlet containers use varying defaults for timeouts, such as 30 minutes for Apache Tomcat. You can set the timeout with:
<session-config> <session-timeout>30</session-timeout> </session-config>
After the timeout expires, the close()
method of the Application
class will be
called. You should implement it if you wish to handle timeout
situations.