--- a/jdk/src/share/classes/java/beans/BeanInfo.java Tue Jan 24 18:46:36 2012 +0400
+++ b/jdk/src/share/classes/java/beans/BeanInfo.java Tue Jan 24 19:40:14 2012 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 1999, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -25,134 +25,134 @@
package java.beans;
+import java.awt.Image;
+
/**
- * A bean implementor who wishes to provide explicit information about
- * their bean may provide a BeanInfo class that implements this BeanInfo
- * interface and provides explicit information about the methods,
- * properties, events, etc, of their bean.
- * <p>
- * A bean implementor doesn't need to provide a complete set of
- * explicit information. You can pick and choose which information
- * you want to provide and the rest will be obtained by automatic
- * analysis using low-level reflection of the bean classes' methods
- * and applying standard design patterns.
+ * Use the {@code BeanInfo} interface
+ * to create a {@code BeanInfo} class
+ * and provide explicit information about the methods,
+ * properties, events, and other features of your beans.
* <p>
- * You get the opportunity to provide lots and lots of different
- * information as part of the various XyZDescriptor classes. But
- * don't panic, you only really need to provide the minimal core
- * information required by the various constructors.
- * <P>
- * See also the SimpleBeanInfo class which provides a convenient
- * "noop" base class for BeanInfo classes, which you can override
- * for those specific places where you want to return explicit info.
- * <P>
- * To learn about all the behaviour of a bean see the Introspector class.
+ * When developing your bean, you can implement
+ * the bean features required for your application task
+ * omitting the rest of the {@code BeanInfo} features.
+ * They will be obtained through the automatic analysis
+ * by using the low-level reflection of the bean methods
+ * and applying standard design patterns.
+ * You have an opportunity to provide additional bean information
+ * through various descriptor classes.
+ * <p>
+ * See the {@link SimpleBeanInfo} class that is
+ * a convenient basic class for {@code BeanInfo} classes.
+ * You can override the methods and properties of
+ * the {@code SimpleBeanInfo} class to define specific information.
+ * <p>
+ * See also the {@link Introspector} class to learn more about bean behavior.
*/
-
public interface BeanInfo {
/**
- * Gets the beans <code>BeanDescriptor</code>.
+ * Returns the bean descriptor
+ * that provides overall information about the bean,
+ * such as its display name or its customizer.
*
- * @return A BeanDescriptor providing overall information about
- * the bean, such as its displayName, its customizer, etc. May
- * return null if the information should be obtained by automatic
- * analysis.
+ * @return a {@link BeanDescriptor} object,
+ * or {@code null} if the information is to
+ * be obtained through the automatic analysis
*/
BeanDescriptor getBeanDescriptor();
/**
- * Gets the beans <code>EventSetDescriptor</code>s.
+ * Returns the event descriptors of the bean
+ * that define the types of events fired by this bean.
*
- * @return An array of EventSetDescriptors describing the kinds of
- * events fired by this bean. May return null if the information
- * should be obtained by automatic analysis.
+ * @return an array of {@link EventSetDescriptor} objects,
+ * or {@code null} if the information is to
+ * be obtained through the automatic analysis
*/
EventSetDescriptor[] getEventSetDescriptors();
/**
- * A bean may have a "default" event that is the event that will
- * mostly commonly be used by humans when using the bean.
- * @return Index of default event in the EventSetDescriptor array
- * returned by getEventSetDescriptors.
- * <P> Returns -1 if there is no default event.
+ * A bean may have a default event typically applied when this bean is used.
+ *
+ * @return index of the default event in the {@code EventSetDescriptor} array
+ * returned by the {@code getEventSetDescriptors} method,
+ * or -1 if there is no default event
*/
int getDefaultEventIndex();
/**
* Returns descriptors for all properties of the bean.
- * May return {@code null} if the information
- * should be obtained by automatic analysis.
* <p>
* If a property is indexed, then its entry in the result array
- * will belong to the {@link IndexedPropertyDescriptor} subclass
+ * belongs to the {@link IndexedPropertyDescriptor} subclass
* of the {@link PropertyDescriptor} class.
* A client of the {@code getPropertyDescriptors} method
- * can use "{@code instanceof}" to check
+ * can use the {@code instanceof} operator to check
* whether a given {@code PropertyDescriptor}
* is an {@code IndexedPropertyDescriptor}.
*
- * @return an array of {@code PropertyDescriptor}s
- * describing all properties supported by the bean
- * or {@code null}
+ * @return an array of {@code PropertyDescriptor} objects,
+ * or {@code null} if the information is to
+ * be obtained through the automatic analysis
*/
PropertyDescriptor[] getPropertyDescriptors();
/**
- * A bean may have a "default" property that is the property that will
- * mostly commonly be initially chosen for update by human's who are
- * customizing the bean.
- * @return Index of default property in the PropertyDescriptor array
- * returned by getPropertyDescriptors.
- * <P> Returns -1 if there is no default property.
+ * A bean may have a default property commonly updated when this bean is customized.
+ *
+ * @return index of the default property in the {@code PropertyDescriptor} array
+ * returned by the {@code getPropertyDescriptors} method,
+ * or -1 if there is no default property
*/
int getDefaultPropertyIndex();
/**
- * Gets the beans <code>MethodDescriptor</code>s.
+ * Returns the method descriptors of the bean
+ * that define the externally visible methods supported by this bean.
*
- * @return An array of MethodDescriptors describing the externally
- * visible methods supported by this bean. May return null if
- * the information should be obtained by automatic analysis.
+ * @return an array of {@link MethodDescriptor} objects,
+ * or {@code null} if the information is to
+ * be obtained through the automatic analysis
*/
MethodDescriptor[] getMethodDescriptors();
/**
- * This method allows a BeanInfo object to return an arbitrary collection
- * of other BeanInfo objects that provide additional information on the
- * current bean.
- * <P>
- * If there are conflicts or overlaps between the information provided
- * by different BeanInfo objects, then the current BeanInfo takes precedence
- * over the getAdditionalBeanInfo objects, and later elements in the array
- * take precedence over earlier ones.
+ * This method enables the current {@code BeanInfo} object
+ * to return an arbitrary collection of other {@code BeanInfo} objects
+ * that provide additional information about the current bean.
+ * <p>
+ * If there are conflicts or overlaps between the information
+ * provided by different {@code BeanInfo} objects,
+ * the current {@code BeanInfo} object takes priority
+ * over the additional {@code BeanInfo} objects.
+ * Array elements with higher indices take priority
+ * over the elements with lower indices.
*
- * @return an array of BeanInfo objects. May return null.
+ * @return an array of {@code BeanInfo} objects,
+ * or {@code null} if there are no additional {@code BeanInfo} objects
*/
BeanInfo[] getAdditionalBeanInfo();
/**
- * This method returns an image object that can be used to
- * represent the bean in toolboxes, toolbars, etc. Icon images
- * will typically be GIFs, but may in future include other formats.
- * <p>
- * Beans aren't required to provide icons and may return null from
- * this method.
- * <p>
- * There are four possible flavors of icons (16x16 color,
- * 32x32 color, 16x16 mono, 32x32 mono). If a bean choses to only
- * support a single icon we recommend supporting 16x16 color.
+ * Returns an image that can be used to represent the bean in toolboxes or toolbars.
* <p>
- * We recommend that icons have a "transparent" background
- * so they can be rendered onto an existing background.
+ * There are four possible types of icons:
+ * 16 x 16 color, 32 x 32 color, 16 x 16 mono, and 32 x 32 mono.
+ * If you implement a bean so that it supports a single icon,
+ * it is recommended to use 16 x 16 color.
+ * Another recommendation is to set a transparent background for the icons.
*
- * @param iconKind The kind of icon requested. This should be
- * one of the constant values ICON_COLOR_16x16, ICON_COLOR_32x32,
- * ICON_MONO_16x16, or ICON_MONO_32x32.
- * @return An image object representing the requested icon. May
- * return null if no suitable icon is available.
+ * @param iconKind the kind of icon requested
+ * @return an image object representing the requested icon,
+ * or {@code null} if no suitable icon is available
+ *
+ * @see #ICON_COLOR_16x16
+ * @see #ICON_COLOR_32x32
+ * @see #ICON_MONO_16x16
+ * @see #ICON_MONO_32x32
*/
- java.awt.Image getIcon(int iconKind);
+ Image getIcon(int iconKind);
/**
* Constant to indicate a 16 x 16 color icon.