package.html revision 3909
a180a41bba1d50822df23fff0099e90b86638b89vboxsync Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync This code is free software; you can redistribute it and/or modify it
a180a41bba1d50822df23fff0099e90b86638b89vboxsync under the terms of the GNU General Public License version 2 only, as
a180a41bba1d50822df23fff0099e90b86638b89vboxsync published by the Free Software Foundation. Oracle designates this
a180a41bba1d50822df23fff0099e90b86638b89vboxsync particular file as subject to the "Classpath" exception as provided
a180a41bba1d50822df23fff0099e90b86638b89vboxsync by Oracle in the LICENSE file that accompanied this code.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync This code is distributed in the hope that it will be useful, but WITHOUT
a180a41bba1d50822df23fff0099e90b86638b89vboxsync ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
a180a41bba1d50822df23fff0099e90b86638b89vboxsync FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
a180a41bba1d50822df23fff0099e90b86638b89vboxsync version 2 for more details (a copy is included in the LICENSE file that
a180a41bba1d50822df23fff0099e90b86638b89vboxsync accompanied this code).
a180a41bba1d50822df23fff0099e90b86638b89vboxsync You should have received a copy of the GNU General Public License version
a180a41bba1d50822df23fff0099e90b86638b89vboxsync 2 along with this work; if not, write to the Free Software Foundation,
a180a41bba1d50822df23fff0099e90b86638b89vboxsync Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
a180a41bba1d50822df23fff0099e90b86638b89vboxsync or visit www.oracle.com if you need additional information or have any
a180a41bba1d50822df23fff0099e90b86638b89vboxsync<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncContains classes related to developing
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncbased on the JavaBeans™ architecture.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncA few of the
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncclasses are used by beans while they run in an application.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncFor example, the event classes are
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncused by beans that fire property and vetoable change
a180a41bba1d50822df23fff0099e90b86638b89vboxsync{@link java.beans.PropertyChangeEvent}). However, most of the classes in this
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncpackage are meant to be used by a bean editor (that is, a development environment
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncfor customizing and putting together beans to create an application). In
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncparticular, these classes help the bean editor create a user
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncinterface that the user can use to customize the bean. For example, a bean may
a180a41bba1d50822df23fff0099e90b86638b89vboxsynccontain a property of a special type that a bean editor may not know how to handle.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncBy using the <code>PropertyEditor</code> interface, a bean developer can
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncprovide an editor for this special type.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncTo minimize the resources used by a bean, the classes used by bean editors are loaded only
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncwhen the bean is being edited. They are not needed while the bean is running in an application
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncand therefore not loaded. This information is kept in what's called a bean-info (see {@link java.beans.BeanInfo}).
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncUnless explicitly stated, null values or empty Strings are not valid
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncparameters for the methods in this package. You may expect to see
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncexceptions if these parameters are used.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncthe <code>java.beans</code> package provides support for
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncwriting a bean as a textual representation of its property values.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncThe property values are treated as beans,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncand are recursively read or written to capture
a180a41bba1d50822df23fff0099e90b86638b89vboxsynctheir publicly available state.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncThis approach is suitable for long-term storage
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncbecause it relies only on public API,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncrather than the likely-to-change private implementation.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync<blockquote>
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncThe persistence scheme cannot automatically instantiate
a180a41bba1d50822df23fff0099e90b86638b89vboxsynccustom inner classes, such as you might use for event handlers.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncinstead of inner classes for custom event handlers,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncyou can avoid this problem.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync</blockquote>
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncYou read and write beans in XML format using the
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncclasses, respectively.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncOne notable feature of the persistence scheme is that
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncreading in a bean requires no special knowledge of the bean.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncWriting out a bean, on the other hand,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncsometimes requires special knowledge of the bean's type.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncIf the bean's state can be
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncexpressed using only the no-argument constructor and
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncpublic getter and setter methods for properties,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncno special knowledge is required.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncOtherwise, the bean requires a custom <em>persistence delegate</em> --
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncan object that is in charge of writing out beans of a particular type.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncAll classes provided in the JDK that descend
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncas well as all their properties,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncautomatically have persistence delegates.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncIf you need (or choose) to provide a persistence delegate for a bean,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncyou can do so either by using a
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncor by creating your own subclass of <code>PersistenceDelegate</code>.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncIf the only reason a bean needs a persistence delegate
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncis because you want to invoke the bean's constructor with
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncproperty values as arguments,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncyou can create the bean's persistence delegate
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncwith the one-argument
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncconstructor.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncyou need to implement your own persistence delegate,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncfor which you're likely to need the following classes:
a180a41bba1d50822df23fff0099e90b86638b89vboxsync<dd> The abstract class from which all persistence delegates descend.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync Your subclass should use its knowledge of the bean's type to provide
a180a41bba1d50822df23fff0099e90b86638b89vboxsync whatever <code>Statement</code>s and <code>Expression</code>s
a180a41bba1d50822df23fff0099e90b86638b89vboxsync are necessary to create the bean
a180a41bba1d50822df23fff0099e90b86638b89vboxsync and restore its state.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync<dd> Represents the invocation of a single method on an object.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync Includes a set of arguments to the method.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync used for methods that return a value.
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncOnce you create a persistence delegate,
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncyou register it using the
a180a41bba1d50822df23fff0099e90b86638b89vboxsyncFor overview, architecture, and tutorial documentation, please see:
a180a41bba1d50822df23fff0099e90b86638b89vboxsync <li><a href="http://java.sun.com/docs/books/tutorial/javabeans/">JavaBeans</a>, a trail in <em>The Java Tutorial</em>.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync <li><a href="http://java.sun.com/products/jfc/tsc/articles/persistence2/">Long-Term Persistence</a>, an article in <em>The Swing Connection</em>.