README

Welcome to Pivot
================

Apache Pivot is a platform for building rich internet applications in Java.
It combines the enhanced productivity and usability features of a modern RIA
toolkit with the robustness of the industry-standard Java platform.

Like most 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 categories and distributed
in their associated libraries:


Distribution JARs
=================

* Core (pivot-core-1.5.2.jar):
  A set of common, non-UI-specific classes.

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

* WTK Terra Theme (pivot-wtk-terra-1.5.2.jar):
  The default WTK theme provider for Pivot, responsible for the look & feel of
  the user interface components.

* Web (pivot-web-1.5.2.jar):
  Classes to facilitate communication with remote data services.

* Web Server (pivot-web-server-1.5.2.jar):
  Classes to facilitate implementation of server-side data services.

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

* Tools (pivot-tools-1.5.2.jar):
  Development tools and utility applications.

To begin developing with Pivot, simply include the necessary libraries on your
project classpath.

NOTE Pivot uses the StAX API to load and process WTKX source files. Like many
APIs in the JDK, StAX uses a service discovery mechanism to locate and
instantiate an appropriate parser. When deploying Pivot applications in a web
browser, this may incur unnecessary requests to the web server. The service
resolution process looks on the classpath for an appropriate service descriptor
file; since an applet's classpath also contains its codebase, the JRE will look
for this file on the web server if it is not found in an archive JAR. Such
requests can have a noticeable impact on runtime performance, especially for
slow or unresponsive web servers. As a result, it is recommended that all Pivot
applications deployed via the web set the codebase_lookup applet parameter to
false.


Distribution WARs
=================

Pivot also includes web archives for browsing the Pivot tutorial and demo
applications. The source for those applications can be found in the source
distribution.


Dependencies
============

* Pivot requires Java 6 or greater.

* Pivot's charting components require a compatible chart provider. No such
  provider is included in this release, but one is available here:

  http://code.google.com/p/pivot-jfree/

  Version 1.5 of this provider is compatible with Pivot 1.5.x. Please note that
  this provider has a dependency on JFreeChart, which is licensed under LGPL.

* Scripting support requires a compatible script engine. See
  http://jcp.org/en/jsr/detail?id=223 or
  http://java.sun.com/javase/6/docs/technotes/guides/scripting/index.html
  for more information.


Documentation
=============

Pivot home page: http://pivot.apache.org/
Demos:           http://pivot.apache.org/demos/
Tutorials:       http://pivot.apache.org/tutorials/
Javadoc:         http://pivot.apache.org/1.5.1/docs/api/