java.beans Documentation Differences

This file contains all the changes in documentation in the package java.beans as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

The EventHandler class provides support for dynamically generating event listeners whose methods execute a simple statement involving an incoming event object and a target object.

The EventHandler class is intended to be used by interactive tools such as application builders that allow developers to make connections between beans. Typically connections are made from a user interface bean (the event source) to an application logic bean (the target). The most effective connections of this kind isolate the application logic from the user interface. For example the EventHandler for a connection from a JCheckBox to a method that accepts a boolean value can deal with extracting the state of the check box and passing it directly to the method so that the method is isolated from the user interface layer.

Inner classes are another more general way to handle events from user interfaces. The EventHandler class handles only a subset of what is possible using inner classes. However EventHandler works better with the long-term persistence scheme than inner classes. Also using EventHandler in large applications in which the same interface is implemented many times can reduce the disk and memory footprint of the application.

The reason that listeners created with EventHandler have such a small footprint is that the Proxy class on which the EventHandler relies shares implementations of identical interfaces. For example if you use the EventHandler create methods to make all the ActionListeners in an application all the action listeners will be instances of a single class (one created by the Proxy class). In general listeners based on the Proxy class require one listener class to be created per listener type (interface) whereas the inner class approach requires one class to be created per listener (object that implements the interface).

You don't generally deal directly with EventHandler instances. Instead you use one of the EventHandler create methods to create an object that implements a given listener interface. This listener object uses an EventHandler object behind the scenes to encapsulate information about the event the object to be sent a message when the event occurs the message (method) to be sent and any argument to the method. The following section gives examples of how to create listener objects using the create methods.

Examples of Using EventHandler

The simplest use of EventHandler is to install a listener that calls a method on the target object with no arguments. In the following example we create an ActionListener that invokes the toFront method on an instance of javax.swing.JFrame.

 myButton.addActionListener( (ActionListener)EventHandler.create(ActionListener.class frame "toFront")); 

When myButton is pressed the statement frame.toFront() will be executed. One could get the same effect with some additional compile-time type safety by defining a new implementation of the ActionListener interface and adding an instance of it to the button:

 //Equivalent code using an inner class instead of EventHandler. myButton.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { frame.toFront(); } }); 

The next simplest use of EventHandler is to extract a property value from the first argument of the method in the listener interface (typically an event object) and use it to set the value of a property in the target object. In the following example we create an ActionListener that sets the nextFocusableComponent property of the target object to the value of the "source" property of the event.

 EventHandler.create(ActionListener.class target "nextFocusableComponent" "source") 

This would correspond to the following inner class implementation:

 //Equivalent code using an inner class instead of EventHandler. new ActionListener() { public void actionPerformed(ActionEvent e) { button.setNextFocusableComponent((Component)e.getSource()); } } 

Probably the most common use of EventHandler is to extract a property value from the source of the event object and set this value as the value of a property of the target object. In the following example we create an ActionListener that sets the "label" property of the target object to the value of the "text" property of the source (the value of the "source" property) of the event.

 EventHandler.create(ActionListener.class button "label" "source.text") 

This would correspond to the following inner class implementation:

 //Equivalent code using an inner class instead of EventHandler. new ActionListener { public void actionPerformed(ActionEvent e) { button.setLabel(((JTextField)e.getSource()).getText()); } } 

The event property may be be "qualified" with an arbitrary number of property prefixes delimited with the "." character. The "qualifying" names that appear before the "." characters are taken as the names of properties that should be applied left-most first to the event object.

For example the following action listener

 EventHandler.create(ActionListener.class target "a" "b.c.d") 

might be written as the following inner class (assuming all the properties had canonical getter methods and returned the appropriate types):

 //Equivalent code using an inner class instead of EventHandler. new ActionListener { public void actionPerformed(ActionEvent e) { target.setA(e.getB().getC().isD()); } } 

@see java.lang.reflect.Proxy @see java.util.EventObject @since 1.4 @author Mark Davidson @author Philip Milne @author Hans Muller @version 1.2 10/24/00

The Introspector class provides a standard way for tools to learn about the properties events and methods supported by a target Java Bean.

For each of those three kinds of information the Introspector will separately analyze the bean's class and superclasses looking for either explicit or implicit information and use that information to build a BeanInfo object that comprehensively describes the target bean.

For each class "Foo" explicit information may be available if there exists a corresponding "FooBeanInfo" class that provides a non-null value when queried for the information. We first look for the BeanInfo class by taking the full package-qualified name of the target bean class and appending "BeanInfo" to form a new class name. If this fails then we take the final classname component of this name and look for that class in each of the packages specified in the BeanInfo package search path.

Thus for a class such as "sun.xyz.OurButton" we would first look for a BeanInfo class called "sun.xyz.OurButtonBeanInfo" and if that failed we'd look in each package in the BeanInfo search path for an OurButtonBeanInfo class. With the default search path this would mean looking for "sun.beans.infos.OurButtonBeanInfo".

If a class provides explicit BeanInfo about itself then we add that to the BeanInfo information we obtained from analyzing any derived classes but we regard the explicit information as being definitive for the current class and its base classes and do not proceed any further up the superclass chain.

If we don't find explicit BeanInfo on a class we use low-level reflection to study the methods of the class and apply standard design patterns to identify property accessors event sources or public methods. We then proceed to analyze the class's superclass and add in the information from it (and possibly on up the superclass chain).

Because the Introspector caches BeanInfo classes for better performance take care if you use it in an application that uses multiple class loaders. In general when you destroy a ClassLoader that has been used to introspect classes you should use the Introspector.flushCaches or Introspector.flushFromCaches method to flush all of the introspected classes out of the cache.

For more information about introspection and design patterns please consult the JavaBeans specification.

Gets the list of package names that will be used for finding BeanInfo classes. @return The array of package names that will be searched in order to find BeanInfo classes. This is initially set to {"sun.beans.infos"}.

Reads the next object from the underlying input stream. @return the next object read @throws ArrayIndexOutOfBoundsException if the stream contains no objects (or no more objects) @see XMLEncoder#writeObject

The XMLEncoder class is a complementary alternative to the ObjectOutputStream and can used to generate a textual representation of a JavaBean in the same way that the ObjectOutputStream can be used to create binary representation of Serializable objects. For example the following fragment can be used to create a textual representation the supplied JavaBean and all its properties:

 XMLEncoder e = new XMLEncoder( new BufferedOutputStream( new FileOutputStream("Test.xml"))); e.writeObject(new JButton("Hello world")); e.close(); 

Despite the similarity of their APIs the XMLEncoder class is exclusively designed for the purpose of archiving graphs of JavaBeans as textual representations of their public properties. Like Java source files documents written this way have a natural immunity to changes in the implementations of the classes involved. The ObjectOutputStream continues to be recommended for interprocess communication and general purpose serialization.

The XMLEncoder class provides a default denotation for JavaBeans in which they are represented as XML documents complying with version 1.0 of the XML specification and the UTF-8 character encoding of the Unicode/ISO 10646 character set. The XML documents produced by the XMLEncoder class are:

• Portable and version resilient: they have no dependencies on the private implementation of any class and so like Java source files they may be exchanged between environments which may have different versions of some of the classes and between VMs from different vendors.
• Structurally compact: The XMLEncoder class uses a redundancy elimination algorithm internally so that the default values of a Bean's properties are not written to the stream.
• Fault tolerant: Non-structural errors in the file caused either by damage to the file or by API changes made to classes in an archive remain localized so that a reader can report the error and continue to load the parts of the document which were not affected by the error.

Below is an example of an XML archive containing some user interface components from the swing toolkit:

 < xml version="1.0" encoding="UTF-8" > <java version="1.0" class="java.beans.XMLDecoder"> <object class="javax.swing.JFrame"> <void property="name"> <string>frame1</string> </void> <void property="bounds"> <object class="java.awt.Rectangle"> <int>0</int> <int>0</int> <int>200</int> <int>200</int> </object> </void> <void property="contentPane"> <void method="add"> <object class="javax.swing.JButton"> <void property="label"> <string>Hello</string> </void> </object> </void> </void> <void property="visible"> <boolean>true</boolean> </void> </object> </java> 

The XML syntax uses the following conventions:

• Each element represents a method call.
• The "object" tag denotes an expression whose value is to be used as the argument to the enclosing element.
• The "void" tag denotes a statement which will be executed but whose result will not be used as an argument to the enclosing method.
• Elements which contain elements use those elements as arguments unless they have the tag: "void".
• The name of the method is denoted by the "method" attribute.
• XML's standard "id" and "idref" attributes are used to make references to previous expressions - so as to deal with circularities in the object graph.
• The "class" attribute is used to specify the target of a static method or constructor explicitly; its value being the fully qualified name of the class.
• Elements with the "void" tag are executed using the outer context as the target if no target is defined by a "class" attribute.
• Java's String class is treated specially and is written <string>Hello world</string> where the characters of the string are converted to bytes using the UTF-8 character encoding.

Although all object graphs may be written using just these three tags the following definitions are included so that common data structures can be expressed more concisely:

• The default method name is "new".
• A reference to a java class is written in the form <class>javax.swing.JButton</class>.
• Instances of the wrapper classes for Java's primitive types are written using the name of the primitive type as the tag. For example an instance of the Integer class could be written: <int>123</int>. Note that the XMLEncoder class uses Java's reflection package in which the conversion between Java's primitive types and their associated "wrapper classes" is handled internally. The API for the XMLEncoder class itself deals only with Objects.
• In an element representing a nullary method whose name starts with "get" the "method" attribute is replaced with a "property" attribute whose value is given by removing the "get" prefix and decapitalizing the result.
• In an element representing a monadic method whose name starts with "set" the "method" attribute is replaced with a "property" attribute whose value is given by removing the "set" prefix and decapitalizing the result.
• In an element representing a method named "get" taking one integer argument the "method" attribute is replaced with an "index" attribute whose value the value of the first argument.
• In an element representing a method named "set" taking two arguments the first of which is an integer the "method" attribute is replaced with an "index" attribute whose value the value of the first argument.
• A reference to an array is written using the "array" tag. The "class" and "length" attributes specify the sub-type of the array and its length respectively.

@see XMLDecoder @see java.io.ObjectOutputStream @since 1.4 @version 1.18 1220 05/03/01/02 @author Philip Milne

This method callsRecords the superclass's implementation and recordsExpression oldExp so that itthe Encoder canwill produce the actual output when the stream is flushed.

This method should only be called within the context of initializing a persistence delegate or setting up an encoder to read from a resource bundle. @param oldExp The expression tothat will be written to the stream. @see java.beans.PersistenceDelegate#initialize

This method callsRecords the superclass's implementation and recordsStatement oldStm so that itthe Encoder canwill produce the actual output when the stream is flushed.

This method should only be called within the context of initializing a persistence delegate or setting up an encoder to read from a resource bundle. @param oldStmoldExp The statement tothat will be written to the stream. @see java.beans.PersistenceDelegate#initialize