| author | ohair |
| Wed, 06 Apr 2011 22:06:11 -0700 | |
| changeset 9035 | 1255eb81cc2f |
| parent 8760 | 83843c0b84f7 |
| child 23703 | 8f6d9fbd6834 |
| permissions | -rw-r--r-- |
| 2 | 1 |
<!-- |
|
9035
1255eb81cc2f
7033660: Update copyright year to 2011 on any files changed in 2011
ohair
parents:
8760
diff
changeset
|
2 |
Copyright (c) 1998, 2011, 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 |
|
|
8760
83843c0b84f7
7021517: java.beans code comments have issues with HTML4 compliance
malenkov
parents:
5506
diff
changeset
|
32 |
based on the JavaBeans™ architecture. |
| 2 | 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> |