Author's note: Pivot has moved since this article was written. The new location is http://incubator.apache.org/pivot.

Pivot is an open-source platform for building rich internet applications in Java. It combines the enhanced productivity and usability features of modern RIA toolkits such as Adobe Flex and Microsoft Silverlight with the robustness of the industry-standard Java platform. Pivot applications are written using a combination of Java and XML and can be run either as an applet or as a standalone (optionally offline) desktop application.

Like Flex and Silverlight, Pivot provides a number of features that make building modern GUI applications easier, including declarative UI, data binding, rich visual effects and transitions, and web services integration, and makes these features available to developers working with the Java progamming langauge.

This article provides a high-level introduction to the Pivot platform and the facilities it offers for building rich internet applications.

A Pivot application.

Platform Overview

Like other modern development platforms, Pivot provides a comprehensive set of foundation classes that together comprise a "framework". These classes form the building blocks upon which more complex and sophisticated applications can be built. Pivot classes are grouped into the following primary categories, which are distributed in a set of corresponding libraries:

• Core - A set of common, non-UI classes (pivot-core.jar).

• WTK - Classes for user interface development, including windows, dialogs, buttons, lists, text input, layout, drag and drop, XML markup, etc. (pivot-wtk.jar, pivot-wtk.terra.jar).

• Web - Classes to facilitate communicate with remote data services (pivot-web.jar, pivot-web.server.jar).

• Charting - Classes for adding interactive charting capabilities to Pivot applications (pivot-charts.jar).

Core

While Pivot is primarily a UI platform, it includes a number of general-purpose classes that are equally useful in other, non-UI contexts as well. These classes comprise the Core library:

• pivot.beans
  Classes that provide access to the Java bean properties of an object via a simple dictionary interface.

• pivot.collections
  A set of classes and interfaces that serve as generic collections as well as the data model for user interface components. This ensures a consistent API throughout the entire Pivot framework and reduces the overall learning curve for the platform.

• pivot.collections.adapter
  A set of collection implementations that are backed by java.util collections, allowing developers to easily re-use existing collection data in a Pivot application.

• pivot.collections.concurrent
  A set of thread-safe collection implementations.

• pivot.collections.immutable
  A set of read-only collection implementations.

• pivot.serialization
  Classes for use in data serialization. Pivot includes built-in support for popular data formats such as JavaScript Object Notation (JSON) and Comma-Separated Value (CSV) and can be also be extended to support custom serialization.

• pivot.util
  A collection of utility classes supporting event management, localization (using hierarchical, UTF-8 based JSON files rather than flat, ISO-8859 properties files), base-64 encoding, etc.

• pivot.util.concurrent
  Classes to simplify the execution of background tasks.

WTK

Most of Pivot's classes live in the WTK, or "windowing toolkit", libraries. WTK provides a complete desktop windowing environment in less than 500k.

Some WTK components.

Architecture

The design of WTK is based on the model-view-controller architecture employed by many current user interface toolkits. In WTK, model data is represented by the collection classes defined in the Core library (most commonly List and Dictionary). The component itself represents the controller, and acts as the intermediary between the model data and the component's "skin" (the view).

The skin defines the actual appearance of the component, as a component has no inherent visual representation of its own. The skin also defines how the component responds to user input including keyboard and mouse events. Components may have multiple skins (though only a single skin can be installed at a time), and skins can be dynamically changed or applied at runtime. However, the existence of the skin should be effectively transparent to most developers, as skins do not expose any public API. All interaction with the skin takes place via the skin's component.

Skins can be "styled" in a manner similar to CSS. Through the component, a skin may expose a set of style properties such as "color" and "font" that a user can change to achieve a custom application appearance without having to write a new skin. Styles are skin-specific - a skin may expose some, all, or none of the properties it uses to render itself. This allows a button skin that emulates the look and feel of a Mac OSX button to define a different set of styles than one that emulates a Windows button, for example.

The appearance of some components can be further customized using "renderers", which are essentially "lightweight components" used to paint the content of the actual component. For example, WTK buttons allow a caller to define the renderer used to paint the button's data, and list views support customized painting of list items via a renderer. Renderers allow large collections of data to be presented very efficiently, as the renderer is used to "rubber stamp" the content, instead of creating an actual component instance for each data element, which would require more memory and processor time.

Additionally, using renderers, component content is painted the same regardless of the skin that is currently applied. This allows applications to present information consistently as skins are updated or new skins are released.

Component Hierarchy

The following diagram shows the WTK component class structure:

Classes in gray are planned for a future release.

As in AWT, the original Java UI toolkit, Pivot component classes either extend Component or Container. Non-container components are used to present data, collect user input, or both; these include buttons, list views, table views, and tree views, among others.

Pivot table view components.

Container components, as their name implies, contain other components, creating a component hierarchy. Containers can be loosely grouped into three categories: layout, navigation, and composite. Layout containers are used primarily to arrange other components on the screen and include components such as FlowPane and TablePane, which offers capabilities similar to an HTML table. Navigation containers are used to maximize screen real estate, showing or hiding their children as needed, and include components such as TabPane, Accordion, and Expander. Composites are simply components that are implemented using other components. For example, a ScrollBar is a container consisting of of two button components and a "thumb", the draggable area that allows the user to scroll by clicking and dragging the mouse.

Some Pivot containers.

The root of the container hierarchy is the "display", represented by an instance of the Display class. The display effectively acts like a "desktop"; the only allowed direct descendants of Display are Windows, which serve as entry points into the user interface. Window classes can contain any type of component except other windows and the display itself. They also have an optional owner; owned windows always remain on top of their owner and are automatically hidden when their owner is hidden.

A Pivot window.

XML Markup

Pivot applications can be constructed entirely in Java code, but it is often more efficient (and readable) to define a Pivot application using XML. Pivot supports an XML markup language called WTKX to help simplify user interface development. Every component has a corresponding XML element that allows a developer to create an instance of it without writing any Java code. All component properties accessible from Java are also supported in XML, and, in general, the structure of a user interface can be entirely defined in markup - only application logic and event handling needs to be written in Java. This enables project teams to delegate user interface design and development to non-technical design resources and coding tasks to developers, facilitating a clean separation of responsibility.

The following is a simple WTKX example that would create two buttons, labeled "OK" and "Cancel", arranged in a horizontal line:

<FlowPane xmlns:wtkx="http://pivot.dev.java.net/wtkx/2008" xmlns="pivot.wtk">
    <PushButton buttonData="OK"/>
    <PushButton buttonData="Cancel"/>
</FlowPane>

Note that the button text is specified using the buttonData attribute. Simple string-based data such as this is often sufficient; however, some component properties, including button data, cannot always be easily expressed using XML attributes. For example, a designer may want to create a button containing both an image and a label. WTKX supports the expression of typed data directly in XML using XML namespaces, allowing developers to pass complex data types to components without needing to write Java code to do so. XML namespace prefixes are translated to Java package names by the loader; an instance of pivot.wtk.content.ButtonData, which defines "icon" and "text" properties, is instantiated and passed as the data to each button as follows:

<FlowPane xmlns:wtkx="http://pivot.dev.java.net/wtkx/2008"
    xmlns:content="pivot.wtk.content" xmlns="pivot.wtk">
    <PushButton>
        <buttonData>

            <content:ButtonData icon="@ok.png" text="OK"/>
        </buttonData>
    </PushButton>
    <PushButton>
        <buttonData>
            <content:ButtonData icon="@cancel.png" text="Cancel"/>

        </buttonData>
    </PushButton>
</FlowPane>

The default button renderer is capable of handling this type of data and automatically draws the button appropriately.

Note that the icon values are preceded by an '@' symbol. This is a "hint" to the WTKX loader that the following string should be treated as a URL; specifically, a URL that is relative to the source WTKX file. The special syntax is required because XML does not natively support a URL data type. WTKX also supports similar hints for embedding resource values in a WTKX file as well as referring to object instances within markup.

Effects

Pivot includes support for adding visual richness to Pivot applications via "effects". Effects in Pivot are implemented primarily via two types of classes: decorators and transitions. Decorators allow a caller to attach additional rendering behavior to a component, such as blurs, fades, or drop shadows. Transitions are timed behaviors that are often used to animate elements of a user interface. Many Pivot components use animations to help improve usability and provide a more engaging user experience.

A decorator example.

Distribution

WTK is distributed in two libraries, pivot-wtk.jar and pivot-wtk.terra.jar. This allows a Pivot application to be distributed with a custom theme without incurring the download overhead of an unused default theme:

pivot-wtk.jar

Includes all WTK classes except for the Terra theme.

• pivot.wtk
  Classes that define the structure and behavior of WTK user interface components, including windows, buttons, drop-down lists, etc.

• pivot.wtk.content
  Contains default data and renderer classes for content components such as buttons, lists, and tree views.

• pivot.wtk.effects
  Classes supporting visual effects such as blurs, reflections, and drop shadows.

• pivot.wtk.effects.easing
  Contains "easing" operations for producing natural-looking transitions. Based on easing equations developed by Robert Penner.

• pivot.wtk.media
  Classes for including multimedia support in Pivot applications.

• pivot.wtk.skin
  Contains base support for component skins, which define the appearance of Pivot components.

• pivot.wtkx
  Provides support for loading constructing a user interface using XML.

pivot-wtk.terra.jar

Includes skin classes for Pivot's the default look and feel, called "Terra". Terra is a simple but modern-looking theme that looks at home next to most OS-native widgets and includes support for customizable color schemes.

Web

"Web queries" are Pivot's native means of communicating with remote data services. Fundamentally, a web query is simply an HTTP request. However, the default data format used by a web query is not HTML, but JSON. This allows a caller to effectively invoke database-like operations over the web - the HTTP methods are used in a manner that is very similar to their corresponding SQL equivalents:

These operations, sometimes referred to as "CRUD", form the basis of the Representational State Transfer (REST) model of building web services. Pivot web queries are designed primarily to facilitate interaction with JSON-based REST services. However, they are sufficiently generic to support communication with any type of HTTP-based service, using any data format (for example, XML). This renders the classes in the pivot.web package applicable to a broad range of server communication scenarios.

Web Services

In addition to the client APIs defined in pivot.web, the pivot.web.server package provides classes that simplify the task of implementing and interacting with HTTP web services. pivot.web.server.QueryServlet provides an abstract base class for implementing web query servlets, and pivot.web.server.ProxyServlet provides an HTTP proxy that allows an unsigned applet to issue web queries to services outside of its origin server.

Charts

Pivot includes a charting library based on JFreeChart. Pivot's charting components allow developers to easily incorporate interactive charting functionality into a Pivot application.

Example Pivot chart.

Pivot currently includes components for the following chart types:

• Pie charts
• Bar charts
• Line charts
• Area charts
• Candlestick/OHLC charts

The appearance of these components can be customized using style properties, just like any other Pivot component.

Summary

Pivot is a modern UI toolkit that provides an alternative to Flex, Silverlight, or AJAX for developers who want to build rich internet applications using Java. The combination of features provided by the Core, WTK, Web, and Charts libraries enable developers to easily create visually rich and highly functional modern web-based applications.

For more information, visit pivot-toolkit.org.