001: package wicket.settings;
002:
003: import java.util.List;
004: import java.util.Locale;
005:
006: import wicket.IResourceFactory;
007: import wicket.Localizer;
008: import wicket.markup.html.IPackageResourceGuard;
009: import wicket.markup.html.PackageResourceGuard;
010: import wicket.model.IModel;
011: import wicket.resource.IPropertiesFactory;
012: import wicket.resource.loader.IStringResourceLoader;
013: import wicket.util.file.IResourceFinder;
014: import wicket.util.resource.locator.IResourceStreamLocator;
015: import wicket.util.time.Duration;
016: import wicket.util.watch.ModificationWatcher;
017:
018: /**
019: * Interface for resource related settings
020: * <p>
021: * <i>resourcePollFrequency </i> (defaults to no polling frequency) - Frequency
022: * at which resources should be polled for changes.
023: * <p>
024: * <i>resourceFinder </i> (classpath) - Set this to alter the search path for
025: * resources.
026: * <p>
027: * <i>useDefaultOnMissingResource </i> (defaults to true) - Set to true to
028: * return a default value if available when a required string resource is not
029: * found. If set to false then the throwExceptionOnMissingResource flag is used
030: * to determine how to behave. If no default is available then this is the same
031: * as if this flag were false
032: * <p>
033: * <i>A ResourceStreamLocator </i>- An Application's ResourceStreamLocator is
034: * used to find resources such as images or markup files. You can supply your
035: * own ResourceStreamLocator if your prefer to store your application's
036: * resources in a non-standard location (such as a different filesystem
037: * location, a particular JAR file or even a database) by overriding the
038: * getResourceLocator() method.
039: * <p>
040: * <i>Resource Factories </i>- Resource factories can be used to create
041: * resources dynamically from specially formatted HTML tag attribute values. For
042: * more details, see {@link IResourceFactory},
043: * {@link wicket.markup.html.image.resource.DefaultButtonImageResourceFactory}
044: * and especially
045: * {@link wicket.markup.html.image.resource.LocalizedImageResource}.
046: * <p>
047: * <i>A Localizer </i> The getLocalizer() method returns an object encapsulating
048: * all of the functionality required to access localized resources. For many
049: * localization problems, even this will not be required, as there are
050: * convenience methods available to all components:
051: * {@link wicket.Component#getString(String key)} and
052: * {@link wicket.Component#getString(String key, IModel model)}.
053: * <p>
054: * <i>stringResourceLoaders </i>- A chain of <code>IStringResourceLoader</code>
055: * instances that are searched in order to obtain string resources used during
056: * localization. By default the chain is set up to first search for resources
057: * against a particular component (e.g. page etc.) and then against the
058: * application.
059: * </p>
060: *
061: * @author Igor Vaynberg (ivaynberg)
062: */
063: public interface IResourceSettings {
064: /**
065: * Adds a resource factory to the list of factories to consult when
066: * generating resources automatically
067: *
068: * @param name
069: * The name to give to the factory
070: * @param resourceFactory
071: * The resource factory to add
072: */
073: void addResourceFactory(final String name,
074: final IResourceFactory resourceFactory);
075:
076: /**
077: * Convenience method that sets the resource search path to a single folder.
078: * use when searching for resources. By default, the resources are located
079: * on the classpath. If you want to configure other, additional, search
080: * paths, you can use this method
081: *
082: * @param resourceFolder
083: * The resourceFolder to set
084: */
085: void addResourceFolder(final String resourceFolder);
086:
087: /**
088: * Add a string resource loader to the chain of loaders. If this is the
089: * first call to this method since the creation of the application settings
090: * then the existing chain is cleared before the new loader is added.
091: *
092: * @param loader
093: * The loader to be added
094: */
095: void addStringResourceLoader(final IStringResourceLoader loader);
096:
097: /**
098: * @return Returns the defaultLocale.
099: */
100: Locale getDefaultLocale();
101:
102: /**
103: * Get the application's localizer.
104: *
105: * @see IResourceSettings#addStringResourceLoader(wicket.resource.loader.IStringResourceLoader)
106: * for means of extending the way Wicket resolves keys to localized
107: * messages.
108: *
109: * @return The application wide localizer instance
110: */
111: Localizer getLocalizer();
112:
113: /**
114: * Gets the {@link PackageResourceGuard package resource guard}.
115: *
116: * @return The package resource guard
117: */
118: IPackageResourceGuard getPackageResourceGuard();
119:
120: /**
121: * Get the property factory which will be used to load property files
122: *
123: * @return PropertiesFactory
124: */
125: IPropertiesFactory getPropertiesFactory();
126:
127: /**
128: * @param name
129: * Name of the factory to get
130: * @return The IResourceFactory with the given name.
131: */
132: IResourceFactory getResourceFactory(final String name);
133:
134: /**
135: * Gets the resource finder to use when searching for resources.
136: *
137: * @return Returns the resourceFinder.
138: * @see IResourceSettings#setResourceFinder(IResourceFinder)
139: */
140: IResourceFinder getResourceFinder();
141:
142: /**
143: * @return Returns the resourcePollFrequency.
144: * @see IResourceSettings#setResourcePollFrequency(Duration)
145: */
146: Duration getResourcePollFrequency();
147:
148: /**
149: * @return Resource locator for this application
150: */
151: IResourceStreamLocator getResourceStreamLocator();
152:
153: /**
154: * @return Resource watcher with polling frequency determined by setting, or
155: * null if no polling frequency has been set.
156: */
157: ModificationWatcher getResourceWatcher();
158:
159: /**
160: * @return an unmodifiable list of all available string resource loaders
161: */
162: List getStringResourceLoaders();
163:
164: /**
165: * @see wicket.settings.IExceptionSettings#getThrowExceptionOnMissingResource()
166: *
167: * @return boolean
168: */
169: boolean getThrowExceptionOnMissingResource();
170:
171: /**
172: * @return Whether to use a default value (if available) when a missing
173: * resource is requested
174: */
175: boolean getUseDefaultOnMissingResource();
176:
177: /**
178: * @param defaultLocale
179: * The defaultLocale to set.
180: */
181: void setDefaultLocale(Locale defaultLocale);
182:
183: /**
184: * Sets the {@link PackageResourceGuard package resource guard}.
185: *
186: * @param packageResourceGuard
187: * The package resource guard
188: */
189: void setPackageResourceGuard(
190: IPackageResourceGuard packageResourceGuard);
191:
192: /**
193: * Set the property factory which will be used to load property files
194: *
195: * @param factory
196: */
197: void setPropertiesFactory(IPropertiesFactory factory);
198:
199: /**
200: * Sets the finder to use when searching for resources. By default, the
201: * resources are located on the classpath. If you want to configure other,
202: * additional, search paths, you can use this method.
203: *
204: * @param resourceFinder
205: * The resourceFinder to set
206: */
207: void setResourceFinder(final IResourceFinder resourceFinder);
208:
209: /**
210: * Sets the resource polling frequency. This is the duration of time between
211: * checks of resource modification times. If a resource, such as an HTML
212: * file, has changed, it will be reloaded. Default is for no resource
213: * polling to occur.
214: *
215: * @param resourcePollFrequency
216: * Frequency at which to poll resources
217: * @see IResourceSettings#setResourceFinder(IResourceFinder)
218: */
219: void setResourcePollFrequency(final Duration resourcePollFrequency);
220:
221: /**
222: * Sets the resource stream locator for this application
223: *
224: * @param resourceStreamLocator
225: * new resource stream locator
226: */
227: void setResourceStreamLocator(
228: IResourceStreamLocator resourceStreamLocator);
229:
230: /**
231: * @see wicket.settings.IExceptionSettings#setThrowExceptionOnMissingResource(boolean)
232: *
233: * @param throwExceptionOnMissingResource
234: */
235: void setThrowExceptionOnMissingResource(
236: final boolean throwExceptionOnMissingResource);
237:
238: /**
239: * @param useDefaultOnMissingResource
240: * Whether to use a default value (if available) when a missing
241: * resource is requested
242: */
243: void setUseDefaultOnMissingResource(
244: final boolean useDefaultOnMissingResource);
245:
246: }
|