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.io.IOException;
045: import java.net.URL;
046: import java.awt.datatransfer.Transferable;
047: import com.sun.rave.designtime.event.DesignContextListener;
048:
049: /**
050: * <p>A DesignContext is a 'host' for DesignBean instances at design-time. The DesignContext
051: * represents the 'source file' or 'persistence model' for a design-time session. A DesignContext
052: * is the container (instance host) for a set of DesignBeans. For example, in a JSF application,
053: * the DesignContext represents the logical backing file which is the combination of the 'Page1.jsp'
054: * and the 'Page1.java' files. In a Swing application, the DesignContext represents the
055: * 'JFrame1.java' file.</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 DesignContext extends DisplayItem {
064:
065: //-------------------------------------------------------------------- DesignBean Access Methods
066:
067: /**
068: * Returns the root container DesignBean for this DesignContext. This is typically the "this"
069: * component being designed. For example, this would be the view root in a JSF application.
070: * The children of the root container are the items you see on the page. To get all of the
071: * DesignBeans within the scope of this context (ignoring the containership hierarchy), use
072: * the getBeans() method.
073: *
074: * @return The root container DesignBean for this DesignContext
075: * @see getBeans()
076: */
077: public DesignBean getRootContainer();
078:
079: /**
080: * Returns a DesignBean (design-time proxy) to represent the specified JavaBean instance. This
081: * must be an instance that lives within the scope of this DesignContext, or the method will
082: * return null.
083: *
084: * @param beanInstance A live instance of a JavaBean
085: * @return A DesignBean (design-time proxy) representing the specified bean instance, or null if
086: * the specified Object does not represent a JavaBean within the scope of this
087: * DesignContext
088: */
089: public DesignBean getBeanForInstance(Object beanInstance);
090:
091: /**
092: * Returns a DesignBean (design-time proxy) to represent the JavaBean with the specified
093: * instance name. This must be an instance that lives within the scope of this DesignContext,
094: * or the method will return null.
095: *
096: * @param instanceName The String instance name of the desired JavaBean
097: * @return A DesignBean (design-time proxy) representing the specified bean, or null if the
098: * specified instance name does not represent a JavaBean within the scope of this
099: * DesignContext
100: */
101: public DesignBean getBeanByName(String instanceName);
102:
103: /**
104: * Returns a DesignBean array (design-time proxies) representing the JavaBeans within the scope
105: * of this DesignContext that are assignable from the specified class type. This uses
106: * Class.isAssignableFrom(...) to determine if a JavaBean satisfies the specified criteria, so
107: * subtypes of the specified type will be included.
108: *
109: * @param beanClass The desired class type
110: * @return An array of DesignBean representing the JavaBeans within the scope of this
111: * DesignContext that are assignable from the specified class type
112: * @see Class#isAssignableFrom(Class)
113: */
114: public DesignBean[] getBeansOfType(Class beanClass);
115:
116: /**
117: * Returns an array of all the DesignBeans within the scope of this DesignContext. This is a
118: * flat list of instances, ignoring the containership hierarchy. To navigate the containership
119: * hierarchy, use the getRootContainer() method.
120: *
121: * @return An array of DesignBean representing the JavaBeans within the scope of this
122: * DesignContext
123: * @see getRootContainer()
124: */
125: public DesignBean[] getBeans();
126:
127: //-------------------------------------------------------------- DesignBean Manipulation Methods
128:
129: /**
130: * Returns <code>true</code> if the specified type (classname) of JavaBean can be created as a
131: * child of the specified parent DesignBean at the specified position. This is a test call that
132: * should be performed before calling the createBean method.
133: *
134: * @param classname The fully qualified class name of the JavaBean to be created
135: * @param parent The DesignBean parent for the JavaBean to be created
136: * @param position The desired position for the JavaBean to be created
137: * @return <code>true</code> if a matching call to 'createBean' would succeed, or
138: * <code>false</code> if not
139: * @see DesignContext#createBean(String, DesignBean, Position)
140: */
141: public boolean canCreateBean(String classname, DesignBean parent,
142: Position position);
143:
144: /**
145: * Creates an instance of a JavaBean of the specified type (classname), as a child of the
146: * specified parent DesignBean at the specified position. If successful, a DesignBean
147: * representing the newly created bean is returned. Before this method is called, a test call
148: * should be performed to the canCreateBean method.
149: *
150: * @param classname The fully qualified class name of the JavaBean to be created
151: * @param parent The DesignBean parent for the JavaBean to be created
152: * @param position The desired position for the JavaBean to be created
153: * @return A DesignBean representing the JavaBean that was created, or null if the operation
154: * failed
155: * @see DesignContext#canCreateBean(String, DesignBean, Position)
156: */
157: public DesignBean createBean(String classname, DesignBean parent,
158: Position position);
159:
160: /**
161: * Returns <code>true</code> if the specified DesignBean can be can be moved to be a child of
162: * the specified parent DesignBean at the specified position. This is a test call that should
163: * be performed before calling the moveBean method.
164: *
165: * @param designBean The DesignBean to be moved
166: * @param newParent The new DesignBean parent for the DesignBean
167: * @param position The desired position for the DesignBean to be moved
168: * @return <code>true</code> if a matching call to 'moveBean' would succeed, or
169: * <code>false</code> if not
170: * @see moveBean(DesignBean, DesignBean, Position)
171: */
172: public boolean canMoveBean(DesignBean designBean,
173: DesignBean newParent, Position position);
174:
175: /**
176: * Moves a DesignBean, to become a child of the specified parent DesignBean at the specified
177: * position. Returns <code>true</code> if successful, <code>false</code> if not. Before this
178: * method is called, a test call should be performed to the canMoveBean method.
179: *
180: * @param designBean The DesignBean to move
181: * @param newParent The new DesignBean parent for the DesignBean
182: * @param position The desired position for the DesignBean to be moved
183: * @return <code>true</code> if move was succeessful, or <code>false</code> if not
184: * @see canMoveBean(DesignBean, DesignBean, Position)
185: */
186: public boolean moveBean(DesignBean designBean,
187: DesignBean newParent, Position position);
188:
189: /**
190: * Copies a set of DesignBean instances into a clipboard-like format. This returns a
191: * Transferable object that stores all the necessary data for the pasteBeans method.
192: *
193: * @param designBeans An array of desired DesignBean instances
194: * @return the resulting Transferable object representing the copied beans
195: * @see pasteBeans(java.awt.datatransfer.Transferable, DesignBean, Position)
196: */
197: public Transferable copyBeans(DesignBean[] designBeans);
198:
199: /**
200: * Pastes a set of DesignBean instances (acquired via copyBeans) into the specified parent
201: * DesignBean at the specified position. This returns an array of DesignBean(s), representing
202: * the newly pasted children.
203: *
204: * @param persistData The Transferable object acquired via 'copyBeans' that contains the data
205: * representing the DesignBean(s) to be pasted
206: * @param newParent The desired new parent DesignBean to paste the DesignBean(s) into
207: * @param position The desired new position for the pasted DesignBean(s)
208: * @return The newly created DesignBean instances
209: * @see copyBeans(DesignBean[])
210: */
211: public DesignBean[] pasteBeans(Transferable persistData,
212: DesignBean newParent, Position position);
213:
214: /**
215: * Deletes a DesignBean object (and removes all persistence). Returns <code>true</code> if the
216: * delete was successful, <code>false</code> if not.
217: *
218: * @param designBean The desired DesignBean to delete
219: * @return <code>true</code> if the delete operation was successful, <code>false</code> if not
220: */
221: public boolean deleteBean(DesignBean designBean);
222:
223: //------------------------------------------------------------------------- Context Data Methods
224:
225: /**
226: * <p>Sets a name-value pair of data on this DesignContext. This name-value pair will be stored
227: * in the associated project file (as text) that contains this DesignContext, so this data is
228: * retrievable in a future IDE session.</p>
229: *
230: * <p>NOTE: The 'data' Object can be a simple String or a complex (non-String) Object. Either
231: * way, it will be stored as text in the project file and will be associated with this
232: * DesignContext. When the project file is written to disk, any complex (non-String) objects
233: * will be converted to String using the 'toString()' method. If a component author wishes to
234: * store a complex (non-String) object, they must be sure to override the 'toString()' method
235: * on their object to serialize out enough information to be able to restore the object when a
236: * subsequent call to 'getContextData' returns a String. Though a complex object was stored
237: * via the 'setContextData' method, a component author *may* get back a String from
238: * 'getContextData' if the project has been saved and reopened since the previous call to
239: * 'setContextData'. It is the responsibility of the component author to reconstruct the
240: * complex object from the String, and if desired, put it back into the context using the
241: * 'setContextData' method passing the newly constructed object in. This way, all subsequent
242: * calls to 'getContextData' with that key will return the complex object instance - until the
243: * project is closed and restored.</p>
244: *
245: * @param key The String key to store the data object under
246: * @param data The data object to store - this may be a String or any complex object, but it
247: * will be stored as a string using the 'toString()' method when the project file is
248: * written to disk.
249: * @see getContextData(String)
250: */
251: public void setContextData(String key, Object data);
252:
253: /**
254: * <p>Retrieves the value for a name-value pair of data on this DesignContext. This name-value
255: * pair is stored in the associated project file (as text) that contains this DesignContext, so
256: * this data is retrievable in any IDE session once it has been set.</p>
257: *
258: * <p>NOTE: The 'data' Object can be a simple String or a complex (non-String) Object. Either
259: * way, it will be stored as text in the project file and will be associated with this
260: * DesignContext. When the project file is written to disk, any complex (non-String) objects
261: * will be converted to String using the 'toString()' method. If a component author wishes to
262: * store a complex (non-String) object, they must be sure to override the 'toString()' method
263: * on their object to serialize out enough information to be able to restore the object when a
264: * subsequent call to 'getContextData' returns a String. Though a complex object was stored
265: * via the 'setContextData' method, a component author *may* get back a String from
266: * 'getContextData' if the project has been saved and reopened since the previous call to
267: * 'setContextData'. It is the responsibility of the component author to reconstruct the
268: * complex object from the String, and if desired, put it back into the context using the
269: * 'setContextData' method passing the newly constructed object in. This way, all subsequent
270: * calls to 'getContextData' with that key will return the complex object instance - until the
271: * project is closed and restored.</p>
272: *
273: * @param key The desired String key to retrieve the data object for
274: * @return The data object that is currently stored under this key - this may be a String or
275: * an Object, based on what was stored using 'setContextData'. NOTE: This will always
276: * be a String after the project file is read from disk, even if the stored object was
277: * not a String - it will have been converted using the 'toString()' method.
278: * @see #setContextData(String, Object)
279: * @see Constants.ContextData
280: */
281: public Object getContextData(String key);
282:
283: //----------------------------------------------------------------------------- Resource Methods
284:
285: /**
286: * Adds a resource reference to this DesignContext, and converts the external URL into a local
287: * resource identifyer String. This may also copy (if specified) an external resource into the
288: * project.
289: *
290: * @param resource A URL pointing to the desired external resource
291: * @param copy <code>true</code> if the resource should be copied into the project,
292: * <code>false</code> if not
293: * @throws IOException if the resource cannot be copied
294: * @return The resulting relative resource identifyer String. This will be a local relative
295: * resource if the external resource was copied into the project.
296: */
297: public String addResource(URL resource, boolean copy)
298: throws IOException;
299:
300: /**
301: * Resolves a local resource identifyer String into a fully-qualified URL.
302: *
303: * @param localResource A local resource identifier string
304: * @return A fully-qualified URL
305: */
306: public URL resolveResource(String localResource);
307:
308: //----------------------------------------------------------------------- Context Method Methods
309:
310: /**
311: * Returns a set of {@link ContextMethod} objects describing the methods declared on this
312: * DesignContext (source file).
313: *
314: * @return An array of {@link ContextMethod} objects, describing the methods declared on this
315: * DesignContext (source file)
316: */
317: public ContextMethod[] getContextMethods();
318:
319: /**
320: * Returns a {@link ContextMethod} object describing the method with the specified name and
321: * parameter types. Returns <code>null</code> if no method exists on this DesignContext with
322: * the specified name and parameter types.
323: *
324: * @param methodName The method name of the desired context method
325: * @param parameterTypes The parameter types of the desired context method
326: * @return A ContextMethod object describing the requested method, or <code>null</code> if no
327: * method exists with the specified name and parameter types
328: */
329: public ContextMethod getContextMethod(String methodName,
330: Class[] parameterTypes);
331:
332: /**
333: * <p>Creates a new method in the source code for this DesignContext. The passed ContextMethod
334: * <strong>must</strong> specify at least the designContext and name, and <strong>must
335: * not</strong> describe a method that already exists in the DesignContext source. To update
336: * an existing method, use the <code>updateContextMethod()</code> method. These methods are
337: * separated to help prevent accidental method overwriting. The following table
338: * details how the specified ContextMethod is used for this method:</p>
339: *
340: * <p><table border="1">
341: * <tr><th>designContext <td><strong>REQUIRED.</strong> Must match the DesignContext that is
342: * being called. This is essentially a safety precaution to help prevent accidental
343: * method overwriting.
344: * <tr><th>name <td><strong>REQUIRED.</strong> Defines the method name.
345: * <tr><th>modifiers <td>Defines the method modifiers. Use {@link java.lang.reflect.Modifier}
346: * to define the modifier bits. If <code>0</code> is specified (no modifier bits), then
347: * a public method is created.
348: * <tr><th>returnType <td>Defines the return type. If <code>null</code> is specified, the
349: * created method will have a <code>void</code> return type.
350: * <tr><th>parameterTypes <td>Defines the parameter types. If <code>null</code> or an empty
351: * array is specified, the created method will have no arguments.
352: * <tr><th>parameterNames <td>Defines the parameter names. If <code>null</code> or an empty
353: * array is specified (or an array shorter than the parameterTypes array), default
354: * argument names will be used.
355: * <tr><th>exceptionTypes <td>Defines the throws clause exception types. If <code>null</code>
356: * is specified, the created method will have no throws clause.
357: * <tr><th>methodBodyText <td>Defines the method body Java source code. If <code>null</code> is
358: * specified, the method will have an empty body. If the value is non-null, this must
359: * represent valid (compilable) Java source code.
360: * <tr><th>commentText <td>Defines the comment text above the newly created method. If
361: * <code>null</code> is specified, no comment text will be included.
362: * </table></p>
363: *
364: * @param method A ContextMethod object representing the desired method.
365: * @return <code>true</code> if the method was created successfully, or <code>false</code> if
366: * it was not.
367: * @throws IllegalArgumentException If there was a syntax error in any of the ContextMethod
368: * settings, or if the ContextMethod represents a method that already exists on this
369: * DesignContext (<code>updateContextMethod()</code> must be used in this case to avoid
370: * accidental method overwriting)
371: */
372: public boolean createContextMethod(ContextMethod method)
373: throws IllegalArgumentException;
374:
375: /**
376: * <p>Updates an existing method in the source code for this DesignContext. The passed
377: * ContextMethod will be used to locate the desired method to update using the designContext,
378: * name, and parameterTypes. This method may only be used to update the modifiers, returnType,
379: * parameterNames, exceptionTypes, methodBodyText, or commentText. Any other changes
380: * actually constitute the creation of a new method, as they alter the method signature. To
381: * create a new method, the <code>createContextMethod()</code> method should be used. These
382: * operations are separated to help prevent accidental method overwriting. The following table
383: * details how the specified ContextMethod is used for this method:</p>
384: *
385: * <p><table border="1">
386: * <tr><th>designContext <td><strong>REQUIRED.</strong> Must match the DesignContext that is
387: * being called. This is essentially a safety precaution to help prevent accidental
388: * method overwriting.
389: * <tr><th>name <td><strong>REQUIRED.</strong> Specifies the desired method name.
390: * <tr><th>modifiers <td>Defines the method modifiers. Use {@link java.lang.reflect.Modifier}
391: * to define the modifier bits.
392: * <tr><th>returnType <td>Defines the method's return type. If <code>null</code> is specified,
393: * the method is assumed to have a <code>void</code> return type.
394: * <tr><th>parameterTypes <td><strong>REQUIRED.</strong> Specifies the desired method's
395: * parameter types (if it has any). If <code>null</code> or an empty array is
396: * specified, the desired method is assumed to have zero arguments.
397: * <tr><th>parameterNames <td>Defines the parameter names. If <code>null</code> or an empty
398: * array is specified (or an array shorter than the parameterTypes array), default
399: * argument names will be used.
400: * <tr><th>exceptionTypes <td>Defines the throws clause exception types. If <code>null</code>
401: * is specified, the resulting method will have no throws clause.
402: * <tr><th>methodBodyText <td>Defines the method body Java source code. If <code>null</code> is
403: * specified, the resulting method body will be empty. If the value is non-null, this
404: * must represent valid (compilable) Java source code. Note that a method with a
405: * non-void return type <strong>must</strong> return a value.
406: * <tr><th>commentText <td>Defines the comment text above the newly created method. If
407: * <code>null</code> is specified, no comment text will be included.
408: * </table></p>
409: *
410: * @param method The desired ContextMethod representing the method to be updated
411: * @return The resulting ContextMethod object (including any updates from the process)
412: * @throws IllegalArgumentException If there was a syntax error in any of the ContextMethod
413: * settings, or if the ContextMethod does not exist in this DesignContext.
414: */
415: public ContextMethod updateContextMethod(ContextMethod method)
416: throws IllegalArgumentException;
417:
418: /**
419: * <p>Removes an existing method from the source code for this DesignContext. The passed
420: * ContextMethod will be used to locate the desired method to remove using the designContext,
421: * name, and parameterTypes. No other portions of the ContextMethod are used. The
422: * following table details how the specified ContextMethod is used for this method:</p>
423: *
424: * <p><table border="1">
425: * <tr><th>designContext <td><strong>REQUIRED.</strong> Must match the DesignContext that is
426: * being called. This is essentially a safety precaution to help prevent accidental
427: * method removal.
428: * <tr><th>name <td><strong>REQUIRED.</strong> Specifies the desired method name.
429: * <tr><tr>modifiers <id>Ignored.
430: * <tr><th>returnType <td>Ignored.
431: * <tr><th>parameterTypes <td><strong>REQUIRED.</strong> Specifies the desired method's
432: * parameter types (if it has any). If <code>null</code> or an empty array is
433: * specified, the desired method is assumed to have zero arguments.
434: * <tr><th>parameterNames <td>Ignored.
435: * <tr><th>exceptionTypes <td>Ignored.
436: * <tr><th>methodBodyText <td>Ignored.
437: * <tr><th>commentText <td>Ignored.
438: * </table></p>
439: *
440: * @param method A ContextMethod object defining the method to be removed
441: * @return <code>true</code> if the method was successfully removed
442: * @exception IllegalArgumentException if the specified ContextMethod does not exist on this
443: * DesignContext
444: */
445: public boolean removeContextMethod(ContextMethod method);
446:
447: //------------------------------------------------------------------------ Project Access Method
448:
449: /**
450: * Returns the project, which is the top-level container for all contexts.
451: *
452: * @return The DesignProject associated with this DesignContext
453: */
454: public DesignProject getProject();
455:
456: //------------------------------------------------------------------- Event Registration Methods
457:
458: /**
459: * Adds a listener to this DesignContext
460: *
461: * @param listener The desired listener to add
462: */
463: public void addDesignContextListener(DesignContextListener listener);
464:
465: /**
466: * Removes a listener from this DesignContext
467: *
468: * @param listener The desired listener to remove
469: */
470: public void removeDesignContextListener(
471: DesignContextListener listener);
472:
473: /**
474: * Returns the array of current listeners to this DesignContext
475: *
476: * @return An array of listeners currently listening to this DesignContext
477: */
478: public DesignContextListener[] getDesignContextListeners();
479: }
|