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.File;
045: import java.io.IOException;
046: import java.net.URI;
047: import java.net.URL;
048: import java.util.Map;
049: import com.sun.rave.designtime.event.DesignProjectListener;
050:
051: /**
052: * <p>A DesignProject is a top-level container for DesignContexts at design-time. The DesignProject
053: * represents the project in the Creator IDE. Not much can be done with Projects in the Creator
054: * Design-Time API, except for accessing other DesignContexts, listening to project-level events,
055: * and storing project-level data.</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: * @see DesignContext#getProject()
063: */
064: public interface DesignProject extends DisplayItem {
065:
066: //------------------------------------------------------------------------ DesignContext Methods
067:
068: /**
069: * Returns all the DesignContexts in this project. There will be one DesignContext for each
070: * designable file in the project. Note that for JSF, this means one DesignContext for each
071: * combination of "PageX.java" and "PageX.jsp" file, as well as one for each of the non-page
072: * beans, like "SessionBeanX.java", "ApplicationBeanX.java", etc.
073: *
074: * @return An array of DesignContext objects - one for each designable file in the project
075: */
076: public DesignContext[] getDesignContexts();
077:
078: /**
079: * Creates a new DesignContext (backing file) in this project.
080: *
081: * @param className The desired fully-qualified class name for the file
082: * @param baseClass The desired base class for the file
083: * @param contextData A Map of context data to apply to the newly created context file
084: * @return The newly created DesignContext, or null if the operation was unsuccessful
085: */
086: public DesignContext createDesignContext(String className,
087: Class baseClass, Map contextData);
088:
089: /**
090: * Removes an existing DesignContext (backing file) from this project.
091: *
092: * @param context The desired DesignContext to remove from the project
093: * @return <code>true</code> if the operation was successful, <code>false</code> if not
094: */
095: public boolean removeDesignContext(DesignContext context);
096:
097: //----------------------------------------------------------------------------- Resource Methods
098:
099: /**
100: * <p>Returns the set of project root relative resources in this project as an array of local
101: * resource identifiers. The returned URIs will always be paths from the project root,
102: * including folder hiearchy within the project. The specified <code>rootPath</code> is used
103: * as a filter, to allow drilling-in to directories as desired. Use
104: * <code>URI.relativize()</code> to make relative URIs when needed. Use
105: * <code>getResourceFile(URI)</code> to retrieve a File object for a particular resource in
106: * the project.</p>
107: *
108: * @param rootPath The root path to fetch resources underneath. Passing <code>null</code> will
109: * start at the root of the project.
110: * @param recurseFolders <code>true</code> to include the sub-resources inside of any folders
111: * @return A project root relative array of URIs representing all the resource files under the
112: * specified root path
113: */
114: public URI[] getResources(URI rootPath, boolean recurseFolders);
115:
116: /**
117: * Returns a File object containing the specified resource.
118: *
119: * @param resourceUri The desired project relative resource uri to fetch a file object
120: * @return A File object containing the project resource
121: */
122: public File getResourceFile(URI resourceUri);
123:
124: /**
125: * Copies a resource into this project, and converts the external URL into a local URI
126: * (resource identifier string).
127: *
128: * @param sourceUrl A URL pointing to the desired external resource
129: * @param targetUri The desired resource URI (path) within the project directory
130: * @return The resulting project relative resource uri (resourceUri)
131: * @throws IOException if the resource cannot be copied
132: */
133: public URI addResource(URL sourceUrl, URI targetUri)
134: throws IOException;
135:
136: /**
137: * Removes a resource from the project directory.
138: *
139: * @param resourceUri The desired resource to remove from the project
140: * @return boolean <code>true</code> if the resource was successfully removed,
141: * <code>false</code> if not
142: */
143: public boolean removeResource(URI resourceUri);
144:
145: //------------------------------------------------------------------------- Project Data Methods
146:
147: /**
148: * <p>Sets a name-value pair of data on this DesignProject. This name-value pair will be stored
149: * in the associated project file, so this data is retrievable in a future IDE session.</p>
150: *
151: * <p>NOTE: The 'data' Object can be a simple String or a complex (non-String) Object. Either
152: * way, it will be stored as text in the project file and will be associated with this project.
153: * When the project file is written to disk, any complex (non-String) objects
154: * will be converted to String using the 'toString()' method. If a component author wishes to
155: * store a complex (non-String) object, they must be sure to override the 'toString()' method
156: * on their object to serialize out enough information to be able to restore the object when a
157: * subsequent call to 'getProjectData' returns a String. Though a complex object was stored
158: * via the 'setProjectData' method, a component author *may* get back a String from
159: * 'getProjectData' if the project has been saved and reopened since the previous call to
160: * 'setProjectData'. It is the responsibility of the component author to reconstruct the
161: * complex object from the String, and if desired, put it back into the context using the
162: * 'setProjectData' method passing the newly constructed object in. This way, all subsequent
163: * calls to 'getProjectData' with that key will return the complex object instance - until the
164: * project is closed and restored.</p>
165: *
166: * @param key The String key to store the data object under
167: * @param data The data object to store - this may be a String or any complex object, but it
168: * will be stored as a string using the 'toString()' method when the project file is
169: * written to disk.
170: * @see #getProjectData(String)
171: */
172: public void setProjectData(String key, Object data);
173:
174: /**
175: * <p>Retrieves the value for a name-value pair of data on this DesignProject. This name-value
176: * pair is stored in the project file, so this data is retrievable in any IDE session once it
177: * has been set. Some custom pre-defined keys can be found in {@link Constants.ProjectData}.
178: * </p>
179: *
180: * <p>NOTE: The 'data' Object can be a simple String or a complex (non-String) Object. Either
181: * way, it will be stored as text in the project file and will be associated with this project.
182: * When the project file is written to disk, any complex (non-String) objects
183: * will be converted to String using the 'toString()' method. If a component author wishes to
184: * store a complex (non-String) object, they must be sure to override the 'toString()' method
185: * on their object to serialize out enough information to be able to restore the object when a
186: * subsequent call to 'getProjectData' returns a String. Though a complex object was stored
187: * via the 'setProjectData' method, a component author *may* get back a String from
188: * 'getProjectData' if the project has been saved and reopened since the previous call to
189: * 'setProjectData'. It is the responsibility of the component author to reconstruct the
190: * complex object from the String, and if desired, put it back into the context using the
191: * 'setProjectData' method passing the newly constructed object in. This way, all subsequent
192: * calls to 'getProjectData' with that key will return the complex object instance - until the
193: * project is closed and restored.</p>
194: *
195: * @param key The desired String key to retrieve the data object for
196: * @return The data object that is currently stored under this key - this may be a String or
197: * an Object, based on what was stored using 'setProjectData'. NOTE: This will always
198: * be a String after the project file is read from disk, even if the stored object was
199: * not a String - it will have been converted using the 'toString()' method.
200: * @see #setProjectData(String, Object)
201: * @see Constants.ProjectData
202: */
203: public Object getProjectData(String key);
204:
205: //-------------------------------------------------------------------------- Global Data Methods
206:
207: /**
208: * <p>Sets a global name-value pair of data. This name-value pair will be stored in the
209: * associated user settings file (as text), so this data is retrievable in a future IDE
210: * session.</p>
211: *
212: * <p>NOTE: The 'data' Object can be a simple String or a complex (non-String) Object. Either
213: * way, it will be stored as text in IDE state and will be associated with this IDE.
214: * When the IDE state is written to disk, any complex (non-String) objects
215: * will be converted to String using the 'toString()' method. If a component author wishes to
216: * store a complex (non-String) object, they must be sure to override the 'toString()' method
217: * on their object to serialize out enough information to be able to restore the object when a
218: * subsequent call to 'getGlobalData' returns a String. Though a complex object was stored
219: * via the 'setGlobalData' method, a component author *may* get back a String from
220: * 'getGlobalData' if the IDE has been closed and reopened since the previous call to
221: * 'setGlobalData'. It is the responsibility of the component author to reconstruct the
222: * complex object from the String, and if desired, put it back into the context using the
223: * 'setGlobalData' method passing the newly constructed object in. This way, all subsequent
224: * calls to 'getGlobalData' with that key will return the complex object instance - until the
225: * IDE is closed and restored.</p>
226: *
227: * @param key The String key to store the data object under
228: * @param data The data object to store - this may be a String or any complex object, but it
229: * will be stored as a string using the 'toString()' method when the project file is
230: * written to disk.
231: * @see DesignProject#getGlobalData(String)
232: *
233: * @deprecated (since Mako) Use {@link DesignIde#getIdeData(String)} instead
234: */
235: public void setGlobalData(String key, Object data);
236:
237: /**
238: * <p>Retrieves the value for a global name-value pair of data. This name-value pair will be
239: * stored in the associated user settings file (as text), so this data is retrievable in any
240: * IDE session once it has been set.</p>
241: *
242: * <p>NOTE: The 'data' Object can be a simple String or a complex (non-String) Object. Either
243: * way, it will be stored as text in IDE state and will be associated with this IDE.
244: * When the IDE state is written to disk, any complex (non-String) objects
245: * will be converted to String using the 'toString()' method. If a component author wishes to
246: * store a complex (non-String) object, they must be sure to override the 'toString()' method
247: * on their object to serialize out enough information to be able to restore the object when a
248: * subsequent call to 'getGlobalData' returns a String. Though a complex object was stored
249: * via the 'setGlobalData' method, a component author *may* get back a String from
250: * 'getGlobalData' if the IDE has been closed and reopened since the previous call to
251: * 'setGlobalData'. It is the responsibility of the component author to reconstruct the
252: * complex object from the String, and if desired, put it back into the context using the
253: * 'setGlobalData' method passing the newly constructed object in. This way, all subsequent
254: * calls to 'getGlobalData' with that key will return the complex object instance - until the
255: * IDE is closed and restored.</p>
256: *
257: * @param key The desired String key to retrieve the data object for
258: * @return The data object that is currently stored under this key - this may be a String or
259: * an Object, based on what was stored using 'setGlobalData'. NOTE: This will always
260: * be a String after the project file is read from disk, even if the stored object was
261: * not a String - it will have been converted using the 'toString()' method.
262: * @see DesignProject#setGlobalData(String, Object)
263: *
264: * @deprecated (since Mako) Use {@link DesignIde#setIdeData(String, Object)} instead
265: */
266: public Object getGlobalData(String key);
267:
268: //---------------------------------------------------------------------------- IDE Access Method
269:
270: /**
271: * Returns the IDE element, which is the top-level container for all projects.
272: *
273: * @return The DesignIde associated with this DesignProject
274: *
275: * @since Mako
276: */
277: // FIXME - cannot define getIde() until it is implemented in concrete classes
278: // public DesignIde getIde();
279:
280: //--------------------------------------------------------------------- Project Listener Methods
281: /**
282: * Adds a listener to this DesignProject
283: *
284: * @param listener The desired listener to add
285: */
286: public void addDesignProjectListener(DesignProjectListener listener);
287:
288: /**
289: * Removes a listener from this DesignProject
290: *
291: * @param listener The desired listener to remove
292: */
293: public void removeDesignProjectListener(
294: DesignProjectListener listener);
295:
296: /**
297: * Returns the array of current listeners to this DesignProject
298: *
299: * @return An array of listeners currently listening to this DesignProject
300: */
301: public DesignProjectListener[] getDesignProjectListeners();
302: }
|