|
2
|
1 |
<!--
|
|
5506
|
2 |
Copyright (c) 1998, 2004, Oracle and/or its affiliates. All rights reserved.
|
|
2
|
3 |
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
|
4 |
|
|
|
5 |
This code is free software; you can redistribute it and/or modify it
|
|
|
6 |
under the terms of the GNU General Public License version 2 only, as
|
|
5506
|
7 |
published by the Free Software Foundation. Oracle designates this
|
|
2
|
8 |
particular file as subject to the "Classpath" exception as provided
|
|
5506
|
9 |
by Oracle in the LICENSE file that accompanied this code.
|
|
2
|
10 |
|
|
|
11 |
This code is distributed in the hope that it will be useful, but WITHOUT
|
|
|
12 |
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
|
13 |
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
|
14 |
version 2 for more details (a copy is included in the LICENSE file that
|
|
|
15 |
accompanied this code).
|
|
|
16 |
|
|
|
17 |
You should have received a copy of the GNU General Public License version
|
|
|
18 |
2 along with this work; if not, write to the Free Software Foundation,
|
|
|
19 |
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
|
20 |
|
|
5506
|
21 |
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
|
22 |
or visit www.oracle.com if you need additional information or have any
|
|
|
23 |
questions.
|
|
2
|
24 |
-->
|
|
|
25 |
|
|
|
26 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
|
27 |
<html>
|
|
|
28 |
<body bgcolor="white">
|
|
|
29 |
|
|
|
30 |
Contains classes related to developing
|
|
|
31 |
<em>beans</em> -- components
|
|
|
32 |
based on the JavaBeans<sup><font size=-2>TM</font></sup> architecture.
|
|
|
33 |
A few of the
|
|
|
34 |
classes are used by beans while they run in an application.
|
|
|
35 |
For example, the event classes are
|
|
|
36 |
used by beans that fire property and vetoable change
|
|
|
37 |
events (see
|
|
|
38 |
{@link java.beans.PropertyChangeEvent}). However, most of the classes in this
|
|
|
39 |
package are meant to be used by a bean editor (that is, a development environment
|
|
|
40 |
for customizing and putting together beans to create an application). In
|
|
|
41 |
particular, these classes help the bean editor create a user
|
|
|
42 |
interface that the user can use to customize the bean. For example, a bean may
|
|
|
43 |
contain a property of a special type that a bean editor may not know how to handle.
|
|
|
44 |
By using the <code>PropertyEditor</code> interface, a bean developer can
|
|
|
45 |
provide an editor for this special type.
|
|
|
46 |
|
|
|
47 |
<p>
|
|
|
48 |
To minimize the resources used by a bean, the classes used by bean editors are loaded only
|
|
|
49 |
when the bean is being edited. They are not needed while the bean is running in an application
|
|
|
50 |
and therefore not loaded. This information is kept in what's called a bean-info (see {@link java.beans.BeanInfo}).
|
|
|
51 |
|
|
|
52 |
<p>
|
|
|
53 |
Unless explicitly stated, null values or empty Strings are not valid
|
|
|
54 |
parameters for the methods in this package. You may expect to see
|
|
|
55 |
exceptions if these parameters are used.
|
|
|
56 |
|
|
|
57 |
|
|
|
58 |
<h2>Long-Term Persistence</h2>
|
|
|
59 |
|
|
|
60 |
As of v1.4,
|
|
|
61 |
the <code>java.beans</code> package provides support for
|
|
|
62 |
<em>long-term persistence</em> -- reading and
|
|
|
63 |
writing a bean as a textual representation of its property values.
|
|
|
64 |
The property values are treated as beans,
|
|
|
65 |
and are recursively read or written to capture
|
|
|
66 |
their publicly available state.
|
|
|
67 |
This approach is suitable for long-term storage
|
|
|
68 |
because it relies only on public API,
|
|
|
69 |
rather than the likely-to-change private implementation.
|
|
|
70 |
|
|
|
71 |
<blockquote>
|
|
|
72 |
<hr>
|
|
|
73 |
<b>Note:</b>
|
|
|
74 |
The persistence scheme cannot automatically instantiate
|
|
|
75 |
custom inner classes, such as you might use for event handlers.
|
|
|
76 |
By using the {@link java.beans.EventHandler} class
|
|
|
77 |
instead of inner classes for custom event handlers,
|
|
|
78 |
you can avoid this problem.
|
|
|
79 |
<hr>
|
|
|
80 |
</blockquote>
|
|
|
81 |
|
|
|
82 |
<p>
|
|
|
83 |
|
|
|
84 |
You read and write beans in XML format using the
|
|
|
85 |
{@link java.beans.XMLDecoder}
|
|
|
86 |
and
|
|
|
87 |
{@link java.beans.XMLEncoder}
|
|
|
88 |
classes, respectively.
|
|
|
89 |
One notable feature of the persistence scheme is that
|
|
|
90 |
reading in a bean requires no special knowledge of the bean.
|
|
|
91 |
|
|
|
92 |
<p>
|
|
|
93 |
Writing out a bean, on the other hand,
|
|
|
94 |
sometimes requires special knowledge of the bean's type.
|
|
|
95 |
If the bean's state can be
|
|
|
96 |
expressed using only the no-argument constructor and
|
|
|
97 |
public getter and setter methods for properties,
|
|
|
98 |
no special knowledge is required.
|
|
|
99 |
Otherwise, the bean requires a custom <em>persistence delegate</em> --
|
|
|
100 |
an object that is in charge of writing out beans of a particular type.
|
|
|
101 |
All classes provided in the JDK that descend
|
|
|
102 |
from <code>java.awt.Component</code>,
|
|
|
103 |
as well as all their properties,
|
|
|
104 |
automatically have persistence delegates.
|
|
|
105 |
|
|
|
106 |
<p>
|
|
|
107 |
|
|
|
108 |
If you need (or choose) to provide a persistence delegate for a bean,
|
|
|
109 |
you can do so either by using a
|
|
|
110 |
{@link java.beans.DefaultPersistenceDelegate}
|
|
|
111 |
instance
|
|
|
112 |
or by creating your own subclass of <code>PersistenceDelegate</code>.
|
|
|
113 |
If the only reason a bean needs a persistence delegate
|
|
|
114 |
is because you want to invoke the bean's constructor with
|
|
|
115 |
property values as arguments,
|
|
|
116 |
you can create the bean's persistence delegate
|
|
|
117 |
with the one-argument
|
|
|
118 |
<code>DefaultPersistenceDelegate</code>
|
|
|
119 |
constructor.
|
|
|
120 |
Otherwise,
|
|
|
121 |
you need to implement your own persistence delegate,
|
|
|
122 |
for which you're likely to need the following classes:
|
|
|
123 |
|
|
|
124 |
<dl>
|
|
|
125 |
<dt> {@link java.beans.PersistenceDelegate}
|
|
|
126 |
<dd> The abstract class from which all persistence delegates descend.
|
|
|
127 |
Your subclass should use its knowledge of the bean's type to provide
|
|
|
128 |
whatever <code>Statement</code>s and <code>Expression</code>s
|
|
|
129 |
are necessary to create the bean
|
|
|
130 |
and restore its state.
|
|
|
131 |
<dt> {@link java.beans.Statement}
|
|
|
132 |
<dd> Represents the invocation of a single method on an object.
|
|
|
133 |
Includes a set of arguments to the method.
|
|
|
134 |
<dt> {@link java.beans.Expression}
|
|
|
135 |
<dd> A subclass of <code>Statement</code>
|
|
|
136 |
used for methods that return a value.
|
|
|
137 |
</dl>
|
|
|
138 |
|
|
|
139 |
<p>
|
|
|
140 |
Once you create a persistence delegate,
|
|
|
141 |
you register it using the
|
|
|
142 |
<code>setPersistenceDelegate</code> method of
|
|
|
143 |
<code>XMLEncoder</code>.
|
|
|
144 |
|
|
|
145 |
|
|
|
146 |
<h2>Related Documentation</h2>
|
|
|
147 |
|
|
|
148 |
For overview, architecture, and tutorial documentation, please see:
|
|
|
149 |
<ul>
|
|
|
150 |
<li><a href="http://java.sun.com/docs/books/tutorial/javabeans/">JavaBeans</a>, a trail in <em>The Java Tutorial</em>.
|
|
|
151 |
<li><a href="http://java.sun.com/products/jfc/tsc/articles/persistence2/">Long-Term Persistence</a>, an article in <em>The Swing Connection</em>.
|
|
|
152 |
</ul>
|
|
|
153 |
<p>
|
|
|
154 |
|
|
|
155 |
</body>
|
|
|
156 |
</html>
|