1 <!-- 2 Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved. 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 7 published by the Free Software Foundation. Oracle designates this 8 particular file as subject to the "Classpath" exception as provided 9 by Oracle in the LICENSE file that accompanied this code. 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 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. 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™ 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>