--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/beans/package.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,156 @@
+<!--
+ Copyright 1998-2004 Sun Microsystems, Inc. All Rights Reserved.
+ DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+ This code is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License version 2 only, as
+ published by the Free Software Foundation. Sun designates this
+ particular file as subject to the "Classpath" exception as provided
+ by Sun in the LICENSE file that accompanied this code.
+
+ This code is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ version 2 for more details (a copy is included in the LICENSE file that
+ accompanied this code).
+
+ You should have received a copy of the GNU General Public License version
+ 2 along with this work; if not, write to the Free Software Foundation,
+ Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+ Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ CA 95054 USA or visit www.sun.com if you need additional information or
+ have any questions.
+-->
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<body bgcolor="white">
+
+Contains classes related to developing
+<em>beans</em> -- components
+based on the JavaBeans<sup><font size=-2>TM</font></sup> architecture.
+A few of the
+classes are used by beans while they run in an application.
+For example, the event classes are
+used by beans that fire property and vetoable change
+events (see
+{@link java.beans.PropertyChangeEvent}). However, most of the classes in this
+package are meant to be used by a bean editor (that is, a development environment
+for customizing and putting together beans to create an application). In
+particular, these classes help the bean editor create a user
+interface that the user can use to customize the bean. For example, a bean may
+contain a property of a special type that a bean editor may not know how to handle.
+By using the <code>PropertyEditor</code> interface, a bean developer can
+provide an editor for this special type.
+
+<p>
+To minimize the resources used by a bean, the classes used by bean editors are loaded only
+when the bean is being edited. They are not needed while the bean is running in an application
+and therefore not loaded. This information is kept in what's called a bean-info (see {@link java.beans.BeanInfo}).
+
+<p>
+Unless explicitly stated, null values or empty Strings are not valid
+parameters for the methods in this package. You may expect to see
+exceptions if these parameters are used.
+
+
+<h2>Long-Term Persistence</h2>
+
+As of v1.4,
+the <code>java.beans</code> package provides support for
+<em>long-term persistence</em> -- reading and
+writing a bean as a textual representation of its property values.
+The property values are treated as beans,
+and are recursively read or written to capture
+their publicly available state.
+This approach is suitable for long-term storage
+because it relies only on public API,
+rather than the likely-to-change private implementation.
+
+<blockquote>
+<hr>
+<b>Note:</b>
+The persistence scheme cannot automatically instantiate
+custom inner classes, such as you might use for event handlers.
+By using the {@link java.beans.EventHandler} class
+instead of inner classes for custom event handlers,
+you can avoid this problem.
+<hr>
+</blockquote>
+
+<p>
+
+You read and write beans in XML format using the
+{@link java.beans.XMLDecoder}
+and
+{@link java.beans.XMLEncoder}
+classes, respectively.
+One notable feature of the persistence scheme is that
+reading in a bean requires no special knowledge of the bean.
+
+<p>
+Writing out a bean, on the other hand,
+sometimes requires special knowledge of the bean's type.
+If the bean's state can be
+expressed using only the no-argument constructor and
+public getter and setter methods for properties,
+no special knowledge is required.
+Otherwise, the bean requires a custom <em>persistence delegate</em> --
+an object that is in charge of writing out beans of a particular type.
+All classes provided in the JDK that descend
+from <code>java.awt.Component</code>,
+as well as all their properties,
+automatically have persistence delegates.
+
+<p>
+
+If you need (or choose) to provide a persistence delegate for a bean,
+you can do so either by using a
+{@link java.beans.DefaultPersistenceDelegate}
+instance
+or by creating your own subclass of <code>PersistenceDelegate</code>.
+If the only reason a bean needs a persistence delegate
+is because you want to invoke the bean's constructor with
+property values as arguments,
+you can create the bean's persistence delegate
+with the one-argument
+<code>DefaultPersistenceDelegate</code>
+constructor.
+Otherwise,
+you need to implement your own persistence delegate,
+for which you're likely to need the following classes:
+
+<dl>
+<dt> {@link java.beans.PersistenceDelegate}
+<dd> The abstract class from which all persistence delegates descend.
+ Your subclass should use its knowledge of the bean's type to provide
+ whatever <code>Statement</code>s and <code>Expression</code>s
+ are necessary to create the bean
+ and restore its state.
+<dt> {@link java.beans.Statement}
+<dd> Represents the invocation of a single method on an object.
+ Includes a set of arguments to the method.
+<dt> {@link java.beans.Expression}
+<dd> A subclass of <code>Statement</code>
+ used for methods that return a value.
+</dl>
+
+<p>
+Once you create a persistence delegate,
+you register it using the
+<code>setPersistenceDelegate</code> method of
+<code>XMLEncoder</code>.
+
+
+<h2>Related Documentation</h2>
+
+For overview, architecture, and tutorial documentation, please see:
+<ul>
+ <li><a href="http://java.sun.com/docs/books/tutorial/javabeans/">JavaBeans</a>, a trail in <em>The Java Tutorial</em>.
+ <li><a href="http://java.sun.com/products/jfc/tsc/articles/persistence2/">Long-Term Persistence</a>, an article in <em>The Swing Connection</em>.
+</ul>
+<p>
+
+</body>
+</html>