JWt User Guide

The +WWidget+ class represents a widget, which provides an abstraction of a visual entity. The entire user interface is specified by creating a hierarchical structure of widgets, rooted at +WApplication.getRoot()+. By reacting to events related to these widgets, you can perform business logic, and manipulate the widget hierarchy to update the user interface.

Any descendent class of +WWidget+ is a self-contained (reusable) class that encapsulates both the look and behavior, enabling the design of the user interface in an orthogonal way.

A JWt application, like any other servlet, is deployed at a specific location (URL) within your servlet container. This location is configured through the +url-pattern+ defined in the +servlet-mapping+ within your +web.xml+ deployment descriptor, and the context at which the application is deployed. In this mode, a JWt application is a single page web application: the URL does not change.

A JWt application may also manage internal paths, which are URLs inside your application URL. To allow the servlet to handle all internal paths too, you need to set an +url-pattern+ that ends with +"/*"+. Then, the internal path may be set and read using +WApplication.setInternalPath()+ and +WApplication.getInternalPath()+. When the internal path changes, this is reflected in the browser URL and an entry is added to the browser history, allowing the user to use the back and forward buttons to navigate through your application.

When AJAX is available, the library will always avoid rerendering the entire widget tree. For a plain HTML session, the session ID is appended to the URL to avoid the session from reloading when the user navigates using a +WAnchor+ to a new internal URL.

To effectively change the internal path and obtain consistent behavior with or without JavaScript, you should use a +WAnchor+ to let the user navigate to a new internal path. The easiest way to do this is by supplying a +WLink+ with +LinkType.InternalPath+. This refers the anchor to a URL generated by +WApplication.getBookmarkUrl()+ for the new internal path (handling the plain HTML case), and binds a JavaScript listener to its +clicked()+ signal, which changes the internal path (handling the AJAX case).

Finally, you can listen for path changes using the +WApplication.internalPathChanged()+ event to react to the user navigating through his history.

When your applications uses internal URLs, this has consequences for relative URLs to external resources (style sheets, images, JavaScript files, etc.), since these are resolved taking into account the current relative URL. All relative URLs that are known to the application are automatically replaced by JWt with an absolute URL that resolves these directly within the deployment location. You should use absolute URLs in CSS or XHTML for them to work within each internal path, since these cannot be fixed by JWt.

JWt provides the abstract +WtServlet+ class which implements the controller for an application. Every JWt application must extend this class and implement its +createApplication()+ to return a new +WApplication+ instance. This method is invoked by the library for every new session (which corresponds to a new user accessing your web application). The request arguments (as part of the +WEnvironment+ object) are passed to this +createApplication()+ function, and may be used to customize the application or authenticate the user. See also Application bootstrap for details on the application bootstrap method.

At all times, the current +WApplication+ instance is accessible using the static method +WApplication.getInstance()+, and is useful to inspect startup arguments and settings using +getEnvironment()+, to set or change the application title using +setTitle()+, to specify a locale using +setLocale()+, and many other application-wide settings. Access to this instance is implemented using thread local storage.

A session exits when the user browses away from the application, when +WApplication.quit()+ is called, or when the servlet container is shut down. From this moment on, your widget tree will be waiting to be garbage collected. Therefore, you should release auxiliary resources held by your widgets or application in the +finalize()+ method of these objects.

During the lifetime of a session, the controller implemented by +WtServlet+ will handle and interpret requests, invoke event handling code, and render updates and changes to your widget tree. This is strictly an internal affair of the library, except that it allows you to scope the use of resources to a single request. To that extent, the library provides a central entry point for doing things like acquiring and releasing database connections and transactions, or have a single place for handling internal application errors. Each request is handled from within +WApplication.notify()+, and by reimplementing this method you may control resource usage during each request.

By default, servlet containers are configured to use cookies for session tracking. This configuration disables a user to have multiple concurrent sessions of the same application running in the same browser. In order to achieve such behavior, you should configure your servlet container to use URL session tracking instead. The +ServletInit+ +ServletContextListener+ should take care of this, and can be configured as a listener with the following XML in your +web.xml+:

To respond to user interactivity events, or in general to communicate events from one widget to any other, JWt uses a signal/listener system, which is a popular implementation of the Observer pattern.

Depending on the number of objects your signal propagates to listeners, you need to use +Signal+, +Signal1+, +Signal2+, … , +Signal6+ as a signal object.

Listeners implement the corresponding listener class, and can be added to a signal using +addListener()+. Because the listener interface only requires the implementation of a single method, it is convenient to use a lambda function or anonymous inner class to implement it. The following example is taken from the hello example.

The library defines several user event signals on various widgets, and it is easy and convenient to add signals and listeners to widget classes to communicate events and trigger callbacks.

Event signals (+EventSignal+) are signals that may be triggered internally by the library to respond to user interactivity events. The abstract base classes +WInteractWidget+ and +WFormWidget+ define most of these event signals.

By default, updates to the user interface are possible only at startup, during any event (in a signal listener), or at regular time points using +WTimer+. This is the normal JWt event loop.

In some cases, one may want to modify the user interface from a second thread, outside the event loop. While this may be worked around by the +WTimer+, in some cases, there are bandwidth and processing overheads associated which may be unnecessary, and which create a trade-off with time resolution of the updates.

When "server push" (also called "comet" in AJAX terminology) is enabled, widgets may be modified, created, or deleted outside of the event loop (e.g. in response to execution of another thread), and these changes are propagated by calling +triggerUpdate()+.

For more information, please refer to the reference documentation of +WApplication.enableUpdates()+. This function enables or disables server push.

You can find a feature example on server push and a more elaborate +simplechat+ example in the JWt source code.

By default, JWt performs all event processing server side. Every connected event signal will cause the web browser to communicate with the servlet container in order to invoke the listener’s implementation, and visual changes will be updated in the web page.

However, JWt offers several options for incorporating client-side event handling. This may in general increase responsiveness of the application since the user gets an instant feed-back and the communication delay is avoided.

JWt provides a number of mechanisms to integrate JavaScript code with Java:

A JWt application may support both plain HTML and Ajax-enabled user agents. When a first request is made for a new session, there is no way of knowing whether the agent supports Ajax (and has it enabled). The bootstrap procedure therefore has two strategies of making the choice between a plain HTML and Ajax-enabled application mode.

JWt provides a vector graphics painting system which, depending on browser support, uses one of three different methods to paint the graphics (inline SVG, HTML 5 +<canvas>+ element, or server side rendered PNG). Vector graphics has as benefit a lower bandwidth usage, which is independent of the image size and quality, and can be embedded within the HTML, avoiding an additional round trip. To use the paint system, you need to specialize +WPaintedWidget+ and use a +WPainter+ to paint the contents of the widget inside its +paintEvent()+.

The charting library is built on top of this painting infrastructure.

JWt uses the Java Servlet API, and thus JWt applications are all compatible with commonly used servlet containers (Tomcat, Jetty, …) and JEE application servers (JBoss, Glassfish, …). The most common way to deploy a JWt application is by packaging the application as a +.war+ file and deploying it into a servlet container. Because JWt applications are plain Java applications, without the need for code generation or XML editing, JWt application development can be conveniently done from your favorite Java IDE. See the Getting Started section for hints on how to create war files and develop JWt applications from within Eclipse.

JWt can be configured by changing values in the +Configuration+ object accessible via the +WtServlet.getConfiguration()+ method.

The library and all of the examples include a +.project+ file which is used by Eclipse to manage the build process. For deploying the web application during development, we recommend using the Eclipse Jetty plugin.

To build the library and examples, we will be using ant, and for deployment we will use the lightweight Jetty servlet container.

Setting up a JWt project does not involve much, since JWt acts as a Java library (on top of the Java servlet API). After running +ant+ in the JWt source distribution folder, all required jar files can be found in the +dist+ folder. To use JWt in your project, you need only to include these jar files into your project library path.

The start point of your application is defined by extending +WtServlet+ which implements a Java servlet, and provides an entry point to a JWt application. An example of this is +eu.webtoolkit.jwt.examples.hello.HelloMain+.

To deploy the web application you need to provide a +WebRoot/WEB-INF/web.xml+ configuration file which binds the servlet to a context path: