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-incubating.jar):
  A set of common, non-UI-specific classes.

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

* Web (pivot-web-incubating.jar, pivot-web-incubating.server.jar):
  Classes to facilitate communication with and implementation of remote data
  services.

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

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

* StAX (stax-1.2.0.jar, stax-api-1.0.jar)
  Streaming API for XML reference implementation.*

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

* Pivot includes a repackaged version of the StAX libraries, which includes a
service descriptor for the javax.xml.stream.XMLInputFactory class (the code is
otherwise unchanged). An external StAX library is required when using Java 5;
however, this modified version is also recommended for web deployment in Java 6
or above to avoid needless requests to the web server: the service resolution
process employed by many JDK factory methods looks on the classpath for a
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.

Another alternative is to set the codebase_lookup applet parameter to false.
However, this parameter requires Java 6 or later and also precludes the use
of dynamically generated WTKX on the server.

These libraries are not necessary or recommended for desktop deployment in
Java 6+.


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

Pivot requires Java 5 or greater.

* WTKX support in Java 5 requires a compatible StAX 1.0 implementation. A
  modified version of the StAX reference implementation is included with the
  Pivot distribution, as described above. The original version of this library
  is available from http://stax.codehaus.org.

* 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.1 of this provider is compatible with Pivot 1.2. 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://incubator.apache.org/pivot
Wiki:            http://cwiki.apache.org/PIVOT/
Javadoc:         http://incubator.apache.org/pivot/1.2/docs/api/index.html