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