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

* WTK (pivot-wtk-2.0.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-2.0.2.jar):
  The default WTK theme provider for Pivot, responsible for the look & feel of
  the user interface components.

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

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

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

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

NOTE Pivot uses the streaming API for XML (StAX) 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/a/apache-extras.org/p/pivot-jfree/

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

* SVG support requires SVG Salamander, which is licensed under a dual LGPL/BSD
  license and is available here:

  http://java.net/projects/svgsalamander/

* 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/2.0.2/docs/api/