1 /*
2 * Copyright (c) 1996, 2012, 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 package java.beans;
27
28 import java.awt.Image;
29
30 /**
31 * Use the {@code BeanInfo} interface
32 * to create a {@code BeanInfo} class
33 * and provide explicit information about the methods,
34 * properties, events, and other features of your beans.
35 * <p>
36 * When developing your bean, you can implement
37 * the bean features required for your application task
38 * omitting the rest of the {@code BeanInfo} features.
39 * They will be obtained through the automatic analysis
40 * by using the low-level reflection of the bean methods
41 * and applying standard design patterns.
42 * You have an opportunity to provide additional bean information
43 * through various descriptor classes.
44 * <p>
45 * See the {@link SimpleBeanInfo} class that is
46 * a convenient basic class for {@code BeanInfo} classes.
47 * You can override the methods and properties of
48 * the {@code SimpleBeanInfo} class to define specific information.
49 * <p>
50 * See also the {@link Introspector} class to learn more about bean behavior.
51 *
52 * @since 1.1
53 */
54 public interface BeanInfo {
55
56 /**
57 * Returns the bean descriptor
58 * that provides overall information about the bean,
59 * such as its display name or its customizer.
60 *
61 * @return a {@link BeanDescriptor} object,
62 * or {@code null} if the information is to
63 * be obtained through the automatic analysis
64 */
65 BeanDescriptor getBeanDescriptor();
66
67 /**
68 * Returns the event descriptors of the bean
69 * that define the types of events fired by this bean.
70 *
71 * @return an array of {@link EventSetDescriptor} objects,
72 * or {@code null} if the information is to
73 * be obtained through the automatic analysis
74 */
75 EventSetDescriptor[] getEventSetDescriptors();
76
77 /**
78 * A bean may have a default event typically applied when this bean is used.
79 *
80 * @return index of the default event in the {@code EventSetDescriptor} array
81 * returned by the {@code getEventSetDescriptors} method,
82 * or -1 if there is no default event
83 */
84 int getDefaultEventIndex();
85
86 /**
87 * Returns descriptors for all properties of the bean.
88 * <p>
89 * If a property is indexed, then its entry in the result array
90 * belongs to the {@link IndexedPropertyDescriptor} subclass
91 * of the {@link PropertyDescriptor} class.
92 * A client of the {@code getPropertyDescriptors} method
93 * can use the {@code instanceof} operator to check
94 * whether a given {@code PropertyDescriptor}
95 * is an {@code IndexedPropertyDescriptor}.
96 *
97 * @return an array of {@code PropertyDescriptor} objects,
98 * or {@code null} if the information is to
99 * be obtained through the automatic analysis
100 */
101 PropertyDescriptor[] getPropertyDescriptors();
102
103 /**
104 * A bean may have a default property commonly updated when this bean is customized.
105 *
106 * @return index of the default property in the {@code PropertyDescriptor} array
107 * returned by the {@code getPropertyDescriptors} method,
108 * or -1 if there is no default property
109 */
110 int getDefaultPropertyIndex();
111
112 /**
113 * Returns the method descriptors of the bean
114 * that define the externally visible methods supported by this bean.
115 *
116 * @return an array of {@link MethodDescriptor} objects,
117 * or {@code null} if the information is to
118 * be obtained through the automatic analysis
119 */
120 MethodDescriptor[] getMethodDescriptors();
121
122 /**
123 * This method enables the current {@code BeanInfo} object
124 * to return an arbitrary collection of other {@code BeanInfo} objects
125 * that provide additional information about the current bean.
126 * <p>
127 * If there are conflicts or overlaps between the information
128 * provided by different {@code BeanInfo} objects,
129 * the current {@code BeanInfo} object takes priority
130 * over the additional {@code BeanInfo} objects.
131 * Array elements with higher indices take priority
132 * over the elements with lower indices.
133 *
134 * @return an array of {@code BeanInfo} objects,
135 * or {@code null} if there are no additional {@code BeanInfo} objects
136 */
137 BeanInfo[] getAdditionalBeanInfo();
138
139 /**
140 * Returns an image that can be used to represent the bean in toolboxes or toolbars.
141 * <p>
142 * There are four possible types of icons:
143 * 16 x 16 color, 32 x 32 color, 16 x 16 mono, and 32 x 32 mono.
144 * If you implement a bean so that it supports a single icon,
145 * it is recommended to use 16 x 16 color.
146 * Another recommendation is to set a transparent background for the icons.
147 *
148 * @param iconKind the kind of icon requested
149 * @return an image object representing the requested icon,
150 * or {@code null} if no suitable icon is available
151 *
152 * @see #ICON_COLOR_16x16
153 * @see #ICON_COLOR_32x32
154 * @see #ICON_MONO_16x16
155 * @see #ICON_MONO_32x32
156 */
157 Image getIcon(int iconKind);
158
159 /**
160 * Constant to indicate a 16 x 16 color icon.
161 */
162 final static int ICON_COLOR_16x16 = 1;
163
164 /**
165 * Constant to indicate a 32 x 32 color icon.
166 */
167 final static int ICON_COLOR_32x32 = 2;
168
169 /**
170 * Constant to indicate a 16 x 16 monochrome icon.
171 */
172 final static int ICON_MONO_16x16 = 3;
173
174 /**
175 * Constant to indicate a 32 x 32 monochrome icon.
176 */
177 final static int ICON_MONO_32x32 = 4;
178 }