Platform

This section answers questions related to the Pivot platform.

What is Apache Pivot?

Apache Pivot™ is an open-source platform for building installable Internet applications (IIAs). It combines the enhanced productivity and usability features of a modern user interface toolkit with the robustness of the Java platform.

Pivot allows developers to easily construct visually-engaging, cross-platform, connected applications in Java or any other JVM language, such as JavaScript, Groovy, or Scala. Pivot is also the only truly open IIA framework: it is completely open source, and is driven entirely by the software development community.

Pivot enables developers to build solutions using the tools they already know, decreasing delivery time and reducing technology sprawl.

What is an "Installable Internet Application (IIA)"?

An "installable Internet application" is an application that takes advantage of the internet but does not require a web browser. A simple example is an email or IM client. A more sophisticated one is Apple's iTunes. Pivot and Java are a great alternative for building these types of applications, especially for projects that don't have the budget or resources to produce multiple native ports.

Note that, although it is not required, Pivot applications can still run in a web browser via the Java plugin. In this case, the "installation" is handled by the plugin, which downloads the application's source code and stores it in a local cache, whereas in most other deployment scenarios it is generally managed explicitly by the user.

Why IIA?

The web has become the defacto standard method for application delivery. However, functional requirements for many web applications have begun to scale beyond the capabilities of the browser. Even with the addition of scripting support, dynamic element manipulation, and asynchronous server communication, it is still difficult to create a user experience in HTML that is truly on par with that of a desktop application.

Installable Internet application development platforms are a means of bridging the gap between the web and desktop experiences. These platforms allow developers to build applications that offer the user experience of a desktop application but take advantage of services and data available via the Internet.

Who is Pivot's target audience?

Pivot was designed to be familiar to web developers who have experience building AJAX applications using HTML, CSS, and JavaScript. However, it provides a much richer set of standard widgets than HTML, and allows developers to create sophisticated user experiences much more quickly and easily. Pivot will also seem familiar to Swing developers, as both Swing and Pivot are based on Java2D and employ a model-view-controller (MVC) architecture to separate component data from presentation. However, Pivot includes additional features that make building modern GUI applications much easier, including declarative UI, data binding, effects and transitions, and web services integration.

Where did Pivot come from?

Pivot began as an R&D effort in the Web UI group at VMware in 2007, and was released as an open-source project in June, 2008 under the Apache 2.0 license. Pivot joined the Apache Incubator in January, 2009 and graduated as a top-level Apache project in December, 2009.

What platforms does Pivot support?

Pivot applications run on any operating system with a Java Runtime Environment (JRE) version 6 or greater (though Java 6 update 14 or later is recommended). They can be run locally as desktop applications or via the web using the Java plugin or Java Web Start.

How does Pivot compare to Swing?

While it is technically feasible to build an IIA in Java using the Swing toolkit, Pivot offers a number of advantages that make it a more compelling, modern alternative:

• Pivot provides an XML markup language called BXML for simplifying user interface construction. Other IIA platforms including Adobe Flex and Microsoft Silverlight offer a similar feature; web developers are comfortable with the markup metaphor, and it can considerably reduce overall development time.

• Components are not limited to an "atomic" preferred size; they are allowed to report a preferred size as constrained by either width or height - this facilitates such features as label wrapping, which Swing does not support.

• Pivot employs a consistent data model that is used throughout the entire framework; for example, JSON data returned from a REST service is serialized into the same data structures used by a table view component to present data. No additional translation is necessary, which can significantly improve performance. A common data model also reduces the learning curve for new developers.

• Pivot includes built-in support for REST-based data services, which Pivot calls "web queries". This provides parity with Flex, which comes with out-of-the-box support for RPC via the AMF protocol, and Silverlight, which supports both SOAP and REST-style services. Swing does not include any built-in facilities for server communication, making it less convenient to work with. Note, however, that Pivot is not limited to REST for server communication. Because it runs in a JRE, a Pivot application can take advantage of any client/server protocol that has a Java API; for example SOAP-based services via Axis or Flex RPC using the BlazeDS AMF client.

• Pivot includes built-in data binding support, which allows data returned from web queries (as well as other types of data services) to easily be mapped to form contents.

• Pivot includes (and takes advantage of) platform-level support for visual effects and transitions (i.e. animations).

• Pivot applications are inherently resolution independent. Bitmapped and vector images are interchangeable, and the entire user interface can be scaled to take advantage of high-resolution displays or for accessibility purposes.

• Pivot defines a single Application inteface that is used for launching both desktop and web-based applications - multiple codebases for applets and applications are not required.

• Because it requires Java 6, Pivot is able to take advantage of newer Java language features such as generics, enums, for..each loops, varargs, and annotations.

How does Pivot compare to JavaFX?

Pivot primarily differentiates itself from the current version of JavaFX by allowing developers to build applications in Java rather than the JavaFX scripting language. However, at the Java One conference in September, 2010, Oracle announced that it would be dropping support for JavaFX Script in future versions. JavaFX 2.0 is scheduled for release in late 2011.

How does Pivot compare to the Google Widget Toolkit (GWT)?

While GWT allows developers to use the Java language to write web-based applications, the runtime enviroment for a GWT application is the browser itself, not a JVM. This has a number of drawbacks:

• The compiled code executes as interpreted JavaScript, not bytecode. While browser vendors have made great strides recently in improving JavaScript performance, there are still many layers between the application code and the actual runtime environment. There are far fewer layers in a Pivot application - this results in less code to execute and translates to better overall performance.

• The only language features and APIs available are those that can be supported by the browser and have been ported to GWT by Google. For example, there is no support for multi-threading, network, or I/O operations. Pivot applications have access to the full feature set of the Java Virtual Machine, including all standard Java libraries and APIs as well as any third-party libraries.

• All presentation must be done via CSS and DOM manipulation. Fundamentally, HTML is a page layout language and is not optimized for general-purpose drawing. Pivot uses Java2D for presentation and can also take advantage of 3D APIs including Java3D and JOGL.

• GWT's native means of server communication, GWT RPC, is a closed protocol, which limits options for sharing back-end functionality. REST services are not natively supported, and SOAP/AMF services are not supported at all.

Pivot allows developers to efficiently construct applications that can truly take advantage of the Java platform.

Features

This section answers questions related to Pivot features.

Where can I find information on how to use Pivot?

Javadoc for Pivot is available online, and a complete tutorial list is available here.

Readers who want a quicker introduction to the platform may prefer to jump directly to the final section of the tutorial, which walks through the implementation of a simple but practical sample application called "Stock Tracker". Stock Tracker demonstrates a number of key features used by many "real world" applications, including UI markup, event handling, web queries, data binding, and localization, among others.

Readers may also find it helpful to review the BXML Primer, which provides an introduction to Pivot's markup language, before browsing the tutorials themsevles.

Where can I find documentation on what BXML attributes and styles a component supports?

Component attributes are simply the Java bean properties of the component class itself. Styles are the bean properties of the currently installed skin. So, you can simply refer to the Javadoc for the component (in org.apache.pivot.wtk) to identify the supported attributes, and for the skin (generally either in org.apache.pivot.skin or org.apache.pivot.skin.terra) to identify the supported styles.
For a live preview, use the Component Explorer Demo

How Java classes map to BXML is discussed in more detail in the BXML Primer.

How can I create a Pivot project in Eclipse?

It is very easy to set up a Pivot project using Eclipse (the Pivot platform itself is actually built using Eclipse):

• Create a new Java project (File > New Java Project).

• Add a lib folder to the project.

• Copy the Pivot JARs you need to the lib folder. At a minimum, you'll need pivot-core-2.0.jar, pivot-wtk-2.0.jar, and pivot-wtk-terra-2.0.jar. The contents of all the Pivot JARs are discussed in the Platform Overview section of the tutorial.

• Right-click on the project in Eclipse and select Properties. Click on Java Build Path.

• Select the Libraries tab and click Add JARs.

• Navigate to the lib directory in your newly created project, select the Pivot JARs, and click OK.

You can now create your main application class (the one that implements org.apache.pivot.wtk.Application). The Hello World tutorial page discusses this interface in more detail and provides information on how to deploy as a desktop application or in a browser.

An Eclipse plugin is also available that simplifies the task of creating launch configurations for Pivot applications. When the plugin is installed, a Pivot application can be launched simply by right-clicking on the name of the implementing class in the source tree.

How can I reference the Pivot source code in Eclipse?

Assuming you have followed the previous steps for setting up a Pivot project in Eclipse, you can do the following to link the source code from the source distribution the libraries in Eclipse:

• Expand the Pivot source distribution, available from the Downloads page.

• In Eclipse, expand the Referenced Libraries node in the tree view and right-click on the library name (e.g. pivot-core-2.0.jar).

• Select Java Source Attachment.

• Click External Folder.

Browse to the location of the source folder in the expanded source distribution (e.g. core/src) and click OK. Repeat this process for all Pivot libraries.

How do I associate BXML files with the XML editor in Eclipse?

• Open Eclipse Preferences.

• Select General > Content Types from the tree navigation on the left.

• Select Text > XML from the "Content types" list on the right.

• Click "Add" and enter "*.bxml" in the popup to create a new file association.

• Select General > Editors > File Assocations from the tree navigation on the left.

• Click "Add" and enter "*.bxml" in the popup to add the "*.bxml" assocation to the list.

Why does Pivot include its own collection classes?

The short answer is that they make the API easier to use, and provide a consistent API across all classes that require indexed or keyed access.

The longer answer:

• Pivot's collection classes fire events that notify listeners when collections are modified. This makes it very easy to wire an application data structure directly into a UI.

• Pivot's collection interfaces enable construction of arbitrary object hierarchies using XML. Any class that implements the Sequence or Dictionary interface can be instantiated and configured completely in markup.

Note, however, that developers aren't required to use these collection classes. Pivot includes various wrapper classes that allow existing model and collection data to be incorporated directly into a Pivot user interface.

Why doesn't copy/paste work in Pivot?

Copy/paste does work in Pivot. However, untrusted Java applets aren't allowed to interact with the system clipboard for security reasons. Trusted (signed) applets and applications running locally have full access to the system clipboard and can share data with native applications as well as other Pivot applications.

Belorussian translation of this document (Беларускі пераклад)