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 com.sun.rave.designtime.event.DesignIdeListener;
045: import java.util.Map;
046:
047: /**
048: * <p>A DesignIde is a top-level container for DesignProjects at design-time.
049: * The DesignIde represents the Creator IDE itself. Not much can be done with
050: * DesignIde in the Creator Design-Time API, except for accessing DesignProjects,
051: * listening to project-level events, and storing user-level data.</p>
052: *
053: * <P><B>IMPLEMENTED BY CREATOR</B> - This interface is implemented by Creator
054: * for use by the component (bean) author.</P>
055: *
056: * @since Mako
057: */
058: public interface DesignIde {
059:
060: // --------------------------------------------------- DesignContext Methods
061:
062: /**
063: * <p>Returns all the DesignProjects in this IDE. There will be one
064: * DesignProject for each open project in the IDE.</p>
065: *
066: * @return An array of DesignProject objects
067: */
068: public DesignProject[] getDesignProjects();
069:
070: /**
071: * <p>Creates a new DesignProject for this IDE.</p>
072: *
073: * <p>FIXME - decide on paramete3rs to createDesignContext() method</p>
074: *
075: * @param projectData A Map of project data to apply to the newly
076: * created project
077: * @return The newly created DesignProject, or null if the operation
078: * was unsuccessful
079: */
080: public DesignProject createDesignProject(Map projectData);
081:
082: /**
083: * <p>Removes an existing DesignProject from this IDE.</p>
084: *
085: * @param project The desired DesignProject to remove from the IDE
086: * @return <code>true</code> if the operation was successful,
087: * <code>false</code> if not
088: */
089: public boolean removeDesignProject(DesignProject project);
090:
091: // -------------------------------------------------------- Ide Data Methods
092:
093: /**
094: * <p>Sets a global name-value pair of data. This name-value pair will be
095: * stored in the associated user settings file (as text), so this data is
096: * retrievable in a future IDE session.</p>
097: *
098: * <p>NOTE: The 'data' Object can be a simple String or a complex
099: * (non-String) Object. Either way, it will be stored as text in IDE
100: * state and will be associated with this IDE. When the IDE state is
101: * written to disk, any complex (non-String) objects will be converted to
102: * String using the 'toString()' method. If a component author wishes to
103: * store a complex (non-String) object, they must be sure to override the
104: * 'toString()' method on their object to serialize out enough information
105: * to be able to restore the object when a subsequent call to 'getGlobalData'
106: * returns a String. Though a complex object was stored via the
107: * 'setIdeData' method, a component author *may* get back a String from
108: * 'getIdeData' if the IDE has been closed and reopened since the
109: * previous call to 'setIdeData'. It is the responsibility of the
110: * component author to reconstruct the complex object from the String,
111: * and if desired, put it back into the context using the 'setIdeData'
112: * method passing the newly constructed object in. This way, all subsequent
113: * calls to 'getIdeData' with that key will return the complex object
114: * instance - until the IDE is closed and restored.</p>
115: *
116: * @param key The String key to store the data object under
117: * @param data The data object to store - this may be a String or any
118: * complex object, but it will be stored as a string using the
119: * 'toString()' method when the user settings are written to disk.
120: * @see DesignIde#getIdeData(String)
121: */
122: public void setIdeData(String key, Object data);
123:
124: /**
125: * <p>Retrieves the value for a global name-value pair of data. This
126: * name-value pair will be stored in the associated user settings file
127: * (as text), so this data is retrievable in any IDE session once it
128: * has been set.</p>
129: *
130: * <p>NOTE: The 'data' Object can be a simple String or a complex
131: * (non-String) Object. Either way, it will be stored as text in IDE
132: * state and will be associated with this IDE. When the IDE state is
133: * written to disk, any complex (non-String) objects will be converted
134: * to String using the 'toString()' method. If a component author wishes to
135: * store a complex (non-String) object, they must be sure to override the
136: * 'toString()' method on their object to serialize out enough information
137: * to be able to restore the object when a subsequent call to 'getIdeData'
138: * returns a String. Though a complex object was stored via the
139: * 'setIdeData' method, a component author *may* get back a String from
140: * 'getIdeData' if the IDE has been closed and reopened since the previous
141: * call to 'setIdeData'. It is the responsibility of the component author
142: * to reconstruct the complex object from the String, and if desired, put
143: * it back into the context using the 'setIdeData' method passing the newly
144: * constructed object in. This way, all subsequent calls to 'getIdeData'
145: * with that key will return the complex object instance - until the
146: * IDE is closed and restored.</p>
147: *
148: * @param key The desired String key to retrieve the data object for
149: * @return The data object that is currently stored under this key -
150: * this may be a String or an Object, based on what was stored using
151: * 'setIdeData'. NOTE: This will always be a String after the user
152: * settings are read from disk, even if the stored object was not a
153: * String - it will have been converted using the 'toString()' method.
154: * @see DesignIde#setIdeData(String, Object)
155: */
156: public Object getIdeData(String key);
157:
158: // ---------------------------------------------------- IDE Listener Methods
159:
160: /**
161: * Adds a listener to this DesignIde
162: *
163: * @param listener The desired listener to add
164: */
165: public void addDesignIdeListener(DesignIdeListener listener);
166:
167: /**
168: * Removes a listener from this DesignIde
169: *
170: * @param listener The desired listener to remove
171: */
172: public void removeDesignIdeListener(DesignIdeListener listener);
173:
174: /**
175: * Returns the array of current listeners to this DesignIde
176: *
177: * @return An array of listeners currently listening to this DesignIde
178: */
179: public DesignIdeListener[] getDesignIdeListeners();
180:
181: }
|