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 behaviour, 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/J2EE application server. 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. To avoid rerendering only to change the URL, the internal path is indicated using a name anchor (#) after the deployment URL. 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 behaviour 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 using the WAnchor.setRefInternalPath(). 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 (e.g. those set in WAnchor.setRef(), WImage.setImageRef(), WApplication.useStyleSheet(), etc…) 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 extend, 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 behaviour, you should configure your servlet container to use URL session tracking instead. This servlet container specific configuration can be found in your servlet container’s documentation. The examples distributed with JWt contain a configuration file for a number of servlet containers: Jetty (jwt-3.0.0/examples/hello/WebRoot/WEB-INF/jetty-web.xml), JBoss (jwt-3.0.0/examples/hello/WebRoot/WEB-INF/context.xml) and Tomcat (jwt-3.0.0/examples/hello/WebRoot/META-INF/context.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 an 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 slot), 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" (what is called comet in AJAX terminology) is enabled, widgets may then 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.enabledUpdates(), this function enables or disables server push.

Note that server push works only if your servlet container supports the Servlet 3.0 API. 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 the browser support uses one of three different methods to paint the graphics (inline SVG, inline VML or HTML 5 <canvas> element). Vector graphics has as benefit a lower bandwidth usage, which is indepedent 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 favourite 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().

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 run-jetty-run plugin.

To build the library and examples, we will be using ant, and for deployemt we will use the light-weight Jetty servlet container.

A JWt project is a setup 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 distrubition folder, all required jar files can be found in the jwt-3.0.0/dist folder. To use JWt in your project, you need only to include these 4 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.xml configuration file which binds the servlet to a context path:

Server push (used in the simplechat and serverpush feature example) relies on the asynchronous processing of requests, a feature which is only part of the Servlet API since version 3.0. Several servlet containers are currently implementing this new Servlet API, and no official releases exist. We were able to test our examples successfully on Tomcat 7.0.4 Beta.

A note when developing your own server push applications: make sure to include the servlet-api-3.0.jar during compilation, as demonstrated in the build.xml of the serverpush feature example (examples/features/serverpush).