001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package com.sun.rave.designtime;
043:
044: import java.beans.BeanInfo;
045: import java.beans.EventSetDescriptor;
046: import java.beans.MethodDescriptor;
047: import java.beans.PropertyDescriptor;
048: import com.sun.rave.designtime.event.DesignBeanListener;
049:
050: /**
051: * <P>A DesignBean represents an instance of a JavaBean class at design-time. There is one
052: * DesignBean instance 'wrapping' each instance of a component class in a bean design tool. All
053: * access to properties and events should be done via the DesignBean interface at design-time, so
054: * that the tool is able to track changes and persist them. Think of the "DesignBean" as the
055: * design-time proxy for an instance of a JavaBean.</p>
056: *
057: * <P><B>IMPLEMENTED BY CREATOR</B> - This interface is implemented by Creator for use by the
058: * component (bean) author.</P>
059: *
060: * @author Joe Nuxoll
061: * @version 1.0
062: */
063: public interface DesignBean {
064:
065: /**
066: * Returns the BeanInfo descriptor for this bean instance's type.
067: *
068: * @return The BeanInfo descriptor for this bean instance's type.
069: */
070: public BeanInfo getBeanInfo();
071:
072: /**
073: * Returns the DesignInfo instance for this bean instance.
074: *
075: * @return The DesignInfo instance for this bean instance.
076: */
077: public DesignInfo getDesignInfo();
078:
079: /**
080: * Returns the instance that this DesignBean is marshalling.
081: *
082: * @return The instance of the wrapped bean instance.
083: */
084: public Object getInstance();
085:
086: /**
087: * Returns the instance name of this bean - as declared in source code.
088: *
089: * @return The source code instance name of this bean.
090: */
091: public String getInstanceName();
092:
093: /**
094: * Returns <code>true</code> if this instance can be renamed via this interface.
095: *
096: * @return <code>true</code> if this instance can be renamed via this interface, or
097: * <code>false</code> if not.
098: */
099: public boolean canSetInstanceName();
100:
101: /**
102: * Renames the instance variable for this bean instance in the source code. If successful,
103: * this method returns <code>true</code>, if there is a problem, including the existance of a
104: * duplicate instance variable name, this method returns <code>false</code>.
105: *
106: * @param name The desired source code instance name for this bean.
107: * @return <code>true</code> if the rename was successful, or <code>false</code> if not.
108: */
109: public boolean setInstanceName(String name);
110:
111: /**
112: * Renames the instance variable for this bean instance in the source code, and appends an
113: * auto-incremented number. For example: setInstanceName("button", true) --> button1 -->
114: * button2 --> button3, etc. If successful, this method returns <code>true</code>, if there is
115: * a problem, this method returns <code>false</code>.
116: *
117: * @param name The desired source code instance name (base) for this bean.
118: * @param autoNumber <code>true</code> to auto-number the instance name, <code>false</code> to
119: * strictly attempt the specified name.
120: * @return <code>true</code> if the rename was successful, or <code>false</code> if not.
121: */
122: public boolean setInstanceName(String name, boolean autoNumber);
123:
124: /**
125: * Returns the DesignContext that 'owns' this bean instance.
126: *
127: * @return The DesignContext 'owner' of this bean instance.
128: */
129: public DesignContext getDesignContext();
130:
131: /**
132: * Returns the DesignBean parent of this bean instance, or null if this is a top-level bean.
133: *
134: * @return The DesignBean parent of this bean instance, or null if this is a top-
135: * level bean.
136: */
137: public DesignBean getBeanParent();
138:
139: /**
140: * Returns an array of DesignProperty objects representing the properties of this DesignBean.
141: *
142: * @return An array of DesignProperty objects representing the properties of this DesignBean.
143: */
144: public DesignProperty[] getProperties();
145:
146: /**
147: * Returns a single DesignProperty object representing the specified property (by name).
148: *
149: * @param propertyName The name of the desired DesignProperty to retrieve.
150: * @return The DesignProperty representing the desired property, or null if the specified
151: * property does not exist in this DesignBean.
152: */
153: public DesignProperty getProperty(String propertyName);
154:
155: /**
156: * Returns a single DesignProperty object representing the specified property (by descriptor).
157: *
158: * @param property The PropertyDescriptor of the desired DesignProperty to retrieve.
159: * @return The DesignProperty representing the desired property, or null if the specified
160: * property does not exist in this DesignBean.
161: */
162: public DesignProperty getProperty(PropertyDescriptor property);
163:
164: /**
165: * Returns an array of DesignEvent objects representing the events of this DesignBean.
166: *
167: * @return An array of DesignEvent objecst representing the events of this DesignBean.
168: */
169: public DesignEvent[] getEvents();
170:
171: /**
172: * Returns the DesignEvent objects for a particular event set.
173: *
174: * @param eventSet The EventSetDescriptor containing the desired events.
175: * @return An array of DesignEvent objects representing the events contained in the specified
176: * event set.
177: */
178: public DesignEvent[] getEvents(EventSetDescriptor eventSet);
179:
180: /**
181: * Returns the DesignEvent from within the specified event set and having the specified
182: * MethodDescriptor.
183: *
184: * @param eventSet The desired EventSetDescriptor
185: * @param event The desired MethodDescriptor
186: * @return The DesignEvent representing the event desired, or null if none matched criteria
187: */
188: public DesignEvent getEvent(EventSetDescriptor eventSet,
189: MethodDescriptor event);
190:
191: /**
192: * Returns a DesignEvent with the specified EventDescriptor.
193: *
194: * @param event The desired event's EventDescriptor
195: * @return The DesignEvent representing the event desired, or null if none matched criteria
196: */
197: public DesignEvent getEvent(EventDescriptor event);
198:
199: /**
200: * Returns <code>true</code> if this DesignBean can be a logical container for other
201: * DesignBeans, or <code>false</code> if not. For example, if a DesignBean is representing a
202: * HtmlCommandButton instance, it will return <code>false</code> from this method, whereas a
203: * DesignBean representing an HtmlDataTable will return <code>true</code>. You can only add
204: * children to a DesignBean that returns <code>true</code> from this method.
205: *
206: * @return <code>true</code> if this DesignBean is a container, and <code>false</code> if it is
207: * not
208: */
209: public boolean isContainer();
210:
211: /**
212: * Returns the count of child DesignBeans contained in this DesignBean. Children are "logical"
213: * children in that they represent the sub-components contained inside of another component in
214: * the markup (JSP) or containership hiearchy.
215: *
216: * @return The count of DesignBean children contained by this DesignBean
217: */
218: public int getChildBeanCount();
219:
220: /**
221: * Returns the child DesignBean at the specified cardinal index (zero-based).
222: *
223: * @param index The zero-based cardinal index for the desired DesignBean child
224: * @return the DesignBean at the specified index
225: */
226: public DesignBean getChildBean(int index);
227:
228: /**
229: * Returns an array of DesignBean children of this DesignBean
230: *
231: * @return An array of DesignBean children of this DesignBean
232: */
233: public DesignBean[] getChildBeans();
234:
235: /**
236: * Adds a DesignBeanListener event listener to this DesignBean
237: *
238: * @param beanListener the event listener to add
239: */
240: public void addDesignBeanListener(DesignBeanListener beanListener);
241:
242: /**
243: * Removes a DesignBeanListener event listener from this DesignBean
244: *
245: * @param beanListener the event listener to remove
246: */
247: public void removeDesignBeanListener(DesignBeanListener beanListener);
248:
249: /**
250: * Returns an array of DesignBeanListener currently listening to this DesignBean
251: * @return An array of DesignBeanListener currently listening to this DesignBean
252: */
253: public DesignBeanListener[] getDesignBeanListeners();
254: }
|