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-2006 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 org.netbeans.modules.form;
043:
044: import java.beans.PropertyEditor;
045: import java.io.IOException;
046: import java.net.URL;
047: import java.util.Collection;
048: import java.util.List;
049: import org.openide.filesystems.FileObject;
050:
051: /**
052: * Interface used by the form editor to manipulate resources (property values
053: * stored externally, represented by ResourceValue). Implementation is provided
054: * by the Swing App Framework module, storing the resources in properties files.
055: * Theoretically there could be other implementors, but practically there is no
056: * need for that.
057: * @see ResourceSupport
058: *
059: * @author Tomas Pavek
060: */
061: public interface ResourceService {
062:
063: /**
064: * Called when a new form is created and opened to do some preparation work.
065: * @param srcFile the source java file just created
066: */
067: void prepareNew(FileObject srcFile);
068:
069: /**
070: * Finds ResourceValue for given key, locale and source file. If no data is
071: * available for given specific locale then a less specific or default
072: * locale data is returned.
073: * @param key the key
074: * @param type the type of the value (needed for the infrastructure to
075: * determine the right converter from String)
076: * @param localeSuffix the locale variant to be used (localization suffix
077: * including the initial underscore, e.g. _cs_CZ)
078: * @param srcFile the source java file for which the resource is obtained
079: * @return ResourceValue object with found data, or null
080: */
081: ResourceValue get(String key, Class type, String localeSuffix,
082: FileObject srcFile);
083:
084: /**
085: * Collects all available keys matching given regular expression (via
086: * String.matches - i.e. key.matches(keyRegex) must be true).
087: * @param keyRegex the regular expression that the key should match
088: * @param srcFile the source file whose resources are to be searched
089: * @return Collection of matching keys
090: */
091: Collection<String> findKeys(String keyRegex, FileObject srcFile);
092:
093: /**
094: * Creates ResourceValue object for given key and value. It is not saved
095: * to the file yet. (For that purpose 'update' method is called later.)
096: * @param key the key (not checked for uniqueness - don't care if a value
097: * already exists)
098: * @param type the type of the value (needed for the infrastructure to
099: * determine the right converter from String)
100: * @param value the value object to be stored as a resource; used as a
101: * fallback if stringValue is not valid for constructing the value
102: * @param stringValue textual representation of the value; needed if the
103: * value object itself can't be saved directly
104: * @param srcFile the source java file for which the resource is created
105: * (used to determine where to store the resource)
106: * @return initialized but not saved ResourceValue object
107: */
108: ResourceValue create(String key, Class type, Object value,
109: String stringValue, FileObject srcFile);
110:
111: /**
112: * Creates a new ResourceValue object with a new key. Does not save it to
113: * the file at this moment, just returns the changed object. (The 'update'
114: * method is called later.)
115: * @param resource the ResourceValue to be changed
116: * @param newKey the new key
117: * @return new ResourceValue instance with the new key (otherwise the same)
118: */
119: ResourceValue changeKey(ResourceValue resource, String newKey);
120:
121: /**
122: * Creates new ResourceValue object with a changed value. Does not save it to
123: * the file at this moment, just returns the changed object. (The 'update'
124: * method is called later.)
125: * @param resource the ResourceValue to be changed
126: * @param newValue the new value object; used as a fallback if the string
127: * representation is not usable for constructing the value
128: * @param newStringValue textual representation of the value; needed if the
129: * value object itself can't be saved directly
130: * @return new ResourceValue instance with the new value (otherwise the same)
131: */
132: ResourceValue changeValue(ResourceValue resource, Object newValue,
133: String newStringValue);
134:
135: /**
136: * Creates a new ResourceValue corresponding to given locale (so getValue
137: * will return the new locale specific value). If no data is available for
138: * this specific locale then a less specific or default locale data is provided.
139: * @param resource the ResourceValue to be changed
140: * @param localeSuffix the locale variant to be used (localization suffix
141: * including the initial underscore, e.g. _cs_CZ)
142: * @return new ResourceValue instance containing data for the given locale
143: */
144: ResourceValue switchLocale(ResourceValue resource,
145: String localeSuffix);
146:
147: /**
148: * Obtains all currently available locales of properties files for given
149: * source file. Returns two arrays of strings. The first one containes
150: * locale suffixes, the second one corresponding display names for the user
151: * (should be unique).
152: * @param srcFile the source java file whose resources are in question
153: * @return array of available locales (locale suffixes and display names)
154: */
155: String[][] getAvailableLocales(FileObject srcFile);
156:
157: /**
158: * Provides a visual component (modal dialog) usable as a property
159: * customizer that allows create a new locale file for default properties
160: * file belonging to given source file. It writes the created locale as
161: * a string (locale suffix) to the given propery editor.
162: * @param prEd a property editor where the component writes the created
163: * locale suffix
164: * @param srcFile the source java file whose defining the resources scope
165: * (first suitable properties file will be used for creating
166: * additional locale variant)
167: * @return visual component of the customizer
168: */
169: java.awt.Component getCreateLocaleComponent(PropertyEditor prEd,
170: FileObject srcFile);
171:
172: /**
173: * Updates properties file according to given ResourceValue objects - oldValue
174: * is removed, newValue added. Update goes into given locale - parent files
175: * are updated too if given key is not present in them. New properties file
176: * is created if needed.
177: * @param oldValue the value to be removed or null
178: * @param newValue the value to be added or null
179: * @param srcFile the source java file whose properties files are going to be
180: * modified
181: * @param localeSuffix the locale variant to be updated (localization suffix
182: * including the initial underscore, e.g. _cs_CZ)
183: * @throws java.io.IOException when there is a problem with updating.
184: */
185: void update(ResourceValue oldValue, ResourceValue newValue,
186: FileObject srcFile, String localeSuffix) throws IOException;
187:
188: /**
189: * Saves properties files edited for given source object (form). This method
190: * is called when the source is being saved - so the corresponding
191: * properties files can be saved as well.
192: * @param srcFile the source java file whose properties files should be saved
193: */
194: void autoSave(FileObject srcFile);
195:
196: /**
197: * Called when the source file (form) is closed without saving changes.
198: * The changes in corresponding properties file should be discarded as well.
199: * @param srcFile the source java file whose properties files should be closed
200: */
201: void close(FileObject srcFile);
202:
203: /**
204: * Returns whether forms in the project represented by given file should
205: * actively be set to use the resources - i.e. not only the resources
206: * are allowed, but they should even be used by default.
207: * @param fileInProject a file representing the projevt (whatever source
208: * file from the project)
209: * @return true if the given project can use resources, false if the
210: * project is not suitable for resources
211: */
212: boolean projectWantsUseResources(FileObject fileInProject);
213:
214: /**
215: * Returns whether the project represented by given file allows to use the
216: * resources infrastructure (corresponding libraries are available on
217: * projects classpath). If this method returns true, form editor will allow
218: * forms in the project to use resources.
219: * @param fileInProject a file representing the projevt (whatever source
220: * file from the project)
221: * @return true if the given project uses the resources infrastracture
222: * (corresponding libraries are on the classpath)
223: */
224: boolean projectUsesResources(FileObject fileInProject);
225:
226: // /**
227: // *
228: // * @param fileInProject a file representing the projevt (whatever source
229: // * file from the project)
230: // * @return if the update was successful (might be refused for some types of
231: // * projects)
232: // */
233: // boolean updateProjectForResources(FileObject fileInProject);
234:
235: boolean isExcludedProperty(Class componentType, String propName);
236:
237: String getInjectionCode(Object component, String variableName,
238: FileObject srcFile);
239:
240: ResourcePanel createResourcePanel(Class valueType,
241: FileObject srcFile);
242:
243: /**
244: * Returns the files that define resources for given source file.
245: * Practically this includes the properties file (resource map) and all its
246: * locale or OS variants. Other files referenced from the resource map
247: * (like icons) are not included. The returned files can be used e.g. for
248: * backup during a refactoring operation.
249: * @param srcFile the source java file for which the resource files should
250: * be returned
251: * @return list of properties files defining resources for given source file
252: */
253: List<URL> getResourceFiles(FileObject srcFile);
254: }
|