001 /*
002 * Copyright 2009-2013 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package griffon.core;
017
018 import griffon.core.controller.GriffonControllerActionManager;
019 import griffon.core.i18n.MessageSource;
020 import griffon.core.resources.ResourceResolver;
021 import griffon.util.GriffonNameUtils;
022 import griffon.util.Metadata;
023 import griffon.util.RunnableWithArgs;
024 import groovy.lang.Binding;
025 import groovy.lang.Closure;
026 import groovy.util.ConfigObject;
027 import groovy.util.FactoryBuilderSupport;
028 import org.slf4j.Logger;
029
030 import java.util.List;
031 import java.util.Locale;
032 import java.util.Map;
033
034 /**
035 * Defines the basic contract of a Griffon application.<p>
036 *
037 * @author Danno Ferrin
038 * @author Andres Almiray
039 */
040 public interface GriffonApplication extends Observable, ThreadingHandler, MVCHandler, ResourceHandler, MessageSource, ResourceResolver {
041 /**
042 * Defines the names of the configuration scripts.
043 *
044 * @author Andres Almiray
045 * @since 0.9.2
046 */
047 public enum Configuration {
048 APPLICATION, CONFIG, BUILDER, EVENTS;
049
050 /**
051 * Display friendly name
052 */
053 private String name;
054
055 /**
056 * Returns the capitalized String representation of this Configuration object.
057 *
058 * @return a capitalized String
059 */
060 public String getName() {
061 if (name == null) {
062 return GriffonNameUtils.capitalize(this.toString().toLowerCase(Locale.getDefault()));
063 }
064 return name;
065 }
066 }
067
068 /**
069 * Defines the names of the lifecycle scripts.
070 *
071 * @author Andres Almiray
072 * @since 0.9.2
073 */
074 public enum Lifecycle {
075 INITIALIZE, STARTUP, READY, SHUTDOWN, STOP;
076
077 /**
078 * Display friendly name
079 */
080 private String name;
081
082 /**
083 * Returns the capitalized String representation of this Lifecycle object.
084 *
085 * @return a capitalized String
086 */
087 public String getName() {
088 if (name == null) {
089 return GriffonNameUtils.capitalize(this.toString().toLowerCase(Locale.getDefault()));
090 }
091 return name;
092 }
093 }
094
095 /**
096 * Defines all the events triggered by the application.
097 *
098 * @author Andres Almiray
099 * @since 0.9.2
100 */
101 public enum Event {
102 UNCAUGHT_EXCEPTION_THROWN,
103 LOAD_ADDONS_START, LOAD_ADDONS_END, LOAD_ADDON_START, LOAD_ADDON_END,
104 BOOTSTRAP_START, BOOTSTRAP_END,
105 STARTUP_START, STARTUP_END,
106 READY_START, READY_END,
107 STOP_START, STOP_END,
108 SHUTDOWN_REQUESTED, SHUTDOWN_ABORTED, SHUTDOWN_START,
109 NEW_INSTANCE, DESTROY_INSTANCE,
110 INITIALIZE_MVC_GROUP("InitializeMVCGroup"), CREATE_MVC_GROUP("CreateMVCGroup"), DESTROY_MVC_GROUP("DestroyMVCGroup"),
111 WINDOW_SHOWN, WINDOW_HIDDEN;
112
113 /**
114 * Display friendly name
115 */
116 private String name;
117
118 Event() {
119 String name = name().toLowerCase().replaceAll("_", "-");
120 this.name = GriffonNameUtils.getClassNameForLowerCaseHyphenSeparatedName(name);
121 }
122
123 Event(String name) {
124 this.name = name;
125 }
126
127 /**
128 * Returns the capitalized String representation of this Event object.
129 *
130 * @return a capitalized String
131 */
132 public String getName() {
133 return this.name;
134 }
135 }
136
137 /**
138 * Gets the application's configuration set on 'application.properties'.<p>
139 *
140 * @return the application's metadata configuration
141 */
142 Metadata getMetadata();
143
144 /**
145 * Gets the script class that holds the MVC configuration (i.e. {@code Application.groovy})
146 */
147 Class getAppConfigClass();
148
149 /**
150 * Gets the script class that holds additional configuration (i.e. {@code Config.groovy})
151 */
152 Class getConfigClass();
153
154 /**
155 * Returns the merged runtime configuration from {@code appConfig} and {@code config}
156 */
157 ConfigObject getConfig();
158
159 void setConfig(ConfigObject config);
160
161 /**
162 * Gets the script class that holds builder configuration (i.e. {@code Builder.groovy})
163 */
164 Class getBuilderClass();
165
166 /**
167 * Returns the runtime configuration required for instantiating a {@code CompositeBuilder}
168 */
169 ConfigObject getBuilderConfig();
170
171 void setBuilderConfig(ConfigObject builderConfig);
172
173 /**
174 * Gets the script class that holds global event handler configuration (i.e. {@code Events.groovy})
175 */
176 Class getEventsClass();
177
178 /**
179 * Returns the runtime configuration for global event handlers.
180 */
181 Object getEventsConfig();
182
183 void setEventsConfig(Object eventsConfig);
184
185 Binding getBindings();
186
187 void setBindings(Binding bindings);
188
189 /**
190 * Returns all currently available model instances, keyed by group name.<p>
191 *
192 * @return a Map of all currently instantiated models.
193 */
194 Map<String, ? extends GriffonModel> getModels();
195
196 /**
197 * Returns all currently available view instances, keyed by group name.<p>
198 *
199 * @return a Map of all currently instantiated views.
200 */
201 Map<String, ? extends GriffonView> getViews();
202
203 /**
204 * Returns all currently available controller instances, keyed by group name.<p>
205 *
206 * @return a Map of all currently instantiated controllers.
207 */
208 Map<String, ? extends GriffonController> getControllers();
209
210 /**
211 * Returns all currently available builder instances, keyed by group name.<p>
212 *
213 * @return a Map of all currently instantiated builders.
214 */
215 Map<String, ? extends FactoryBuilderSupport> getBuilders();
216
217 /**
218 * Returns all currently available service instances, keyed by group name.<p>
219 *
220 * @return a Map of all currently instantiated services.
221 */
222 Map<String, ? extends GriffonService> getServices();
223
224 /**
225 * Returns all currently available groups, keyed by group name.<p>
226 *
227 * @return a Map of all currently instantiated groups.
228 */
229 Map<String, MVCGroup> getGroups();
230
231 /**
232 * Returns the application's AddonManager instance.
233 *
234 * @return the application's AddonManager
235 */
236 AddonManager getAddonManager();
237
238 /**
239 * Returns the application's MVCGroupManager instance.
240 *
241 * @return the application's MVCGroupManager
242 */
243 MVCGroupManager getMvcGroupManager();
244
245 /**
246 * Returns the application's ServiceManager instance.
247 *
248 * @return the application's ServiceManager
249 */
250 ServiceManager getServiceManager();
251
252 Object createApplicationContainer();
253
254 /**
255 * Executes the 'Initialize' life cycle phase.
256 */
257 void initialize();
258
259 /**
260 * Executes the 'Startup' life cycle phase.
261 */
262 void startup();
263
264 /**
265 * Executes the 'Ready' life cycle phase.
266 */
267 void ready();
268
269 /**
270 * Executes the 'Shutdown' life cycle phase.
271 *
272 * @return false if the shutdown sequence was aborted
273 */
274 boolean shutdown();
275
276 /**
277 * Queries any available ShutdownHandlers.
278 *
279 * @return true if the shutdown sequence can proceed, false otherwise
280 */
281 boolean canShutdown();
282
283 /**
284 * Adds an application event listener.<p>
285 * Accepted types are: Script, Map and Object.
286 *
287 * @param listener an application event listener
288 */
289 void addApplicationEventListener(Object listener);
290
291 /**
292 * Adds a closure as an application event listener.<p>
293 *
294 * @param eventName the name of the event
295 * @param listener an application event listener
296 */
297 void addApplicationEventListener(String eventName, Closure listener);
298
299 /**
300 * Adds a runnable as an application event listener.<p>
301 *
302 * @param eventName the name of the event
303 * @param listener an application event listener
304 */
305 void addApplicationEventListener(String eventName, RunnableWithArgs listener);
306
307 /**
308 * Removes an application event listener.<p>
309 * Accepted types are: Script, Map and Object.
310 *
311 * @param listener an application event listener
312 */
313 void removeApplicationEventListener(Object listener);
314
315 /**
316 * Removes a closure as an application event listener.<p>
317 *
318 * @param eventName the name of the event
319 * @param listener an application event listener
320 */
321 void removeApplicationEventListener(String eventName, Closure listener);
322
323 /**
324 * Removes a runnable as an application event listener.<p>
325 *
326 * @param eventName the name of the event
327 * @param listener an application event listener
328 */
329 void removeApplicationEventListener(String eventName, RunnableWithArgs listener);
330
331 /**
332 * Returns whether events will be published by the application's event bus or not.
333 *
334 * @return true if event publishing is enabled; false otherwise.
335 */
336 boolean isEventPublishingEnabled();
337
338 /**
339 * Sets the enabled state for event publishing.</p>
340 * Events will be automatically discarded when the enabled state is set to false.
341 *
342 * @param enabled the value fot the enabled state.
343 */
344 void setEventPublishingEnabled(boolean enabled);
345
346 /**
347 * Publishes an application event.<p>
348 *
349 * @param eventName the name of the event
350 */
351 void event(String eventName);
352
353 /**
354 * Publishes an application event.<p>
355 *
356 * @param eventName the name of the event
357 * @param params event arguments sent to listeners
358 */
359 void event(String eventName, List params);
360
361 /**
362 * Publishes an application event asynchronously off the UI thread.<p>
363 *
364 * @param eventName the name of the event
365 */
366 void eventOutsideUI(String eventName);
367
368 /**
369 * Publishes an application event asynchronously off the UI thread.<p>
370 *
371 * @param eventName the name of the event
372 * @param params event arguments sent to listeners
373 */
374 void eventOutsideUI(String eventName, List params);
375
376 /**
377 * Publishes an application event asynchronously off the publisher's thread.<p>
378 *
379 * @param eventName the name of the event
380 */
381 void eventAsync(String eventName);
382
383 /**
384 * Publishes an application event asynchronously off the publisher's thread.<p>
385 *
386 * @param eventName the name of the event
387 * @param params event arguments sent to listeners
388 */
389 void eventAsync(String eventName, List params);
390
391 /**
392 * Registers a ShutdownHandler on this application
393 *
394 * @param handler the shutdown handler to be registered; null and/or
395 * duplicated values should be ignored
396 */
397 void addShutdownHandler(ShutdownHandler handler);
398
399 /**
400 * Removes a ShutdownHandler from this application
401 *
402 * @param handler the shutdown handler to be removed; null and/or
403 * duplicated values should be ignored
404 */
405 void removeShutdownHandler(ShutdownHandler handler);
406
407 /**
408 * Gets the application locale.
409 *
410 * @return the current Locale used by the application. Never returns null.
411 */
412 Locale getLocale();
413
414 /**
415 * Sets the application locale.<p>
416 * This is a bound property.
417 *
418 * @param locale the Locale value to use
419 */
420 void setLocale(Locale locale);
421
422 /**
423 * Returns the current phase.
424 *
425 * @return returns the current ApplicationPhase. Never returns null.
426 */
427 ApplicationPhase getPhase();
428
429 // ----------------------------
430
431 /**
432 * Returns the application's ArtifactManager instance.
433 *
434 * @return the application's ArtifactManager
435 */
436 ArtifactManager getArtifactManager();
437
438 /**
439 * Creates a new instance of the specified class and type.<br/>
440 * Triggers the Event.NEW_INSTANCE with the following parameters
441 * <ul>
442 * <li>clazz - the Class of the object</li>
443 * <li>type - the symbolical type of the object</li>
444 * <li>instance -> the object that was created</li>
445 * </ul>
446 *
447 * @param clazz the Class for which an instance must be created
448 * @param type a symbolical type, for example 'controller' or 'service'. May be null.
449 * @return a newly instantiated object of type <tt>clazz</tt>. Implementations must be sure
450 * to trigger an event of type Event.NEW_INSTANCE.
451 */
452 Object newInstance(Class clazz, String type);
453
454 /**
455 * Returns the arguments set on the command line (if any).<p>
456 *
457 * @return an array of command line arguments. Never returns null.
458 * @since 0.9.2
459 */
460 String[] getStartupArgs();
461
462 /**
463 * Returns a Logger instance suitable for this application.
464 *
465 * @return a Logger instance.
466 * @since 0.9.2
467 */
468 Logger getLog();
469
470 /**
471 * Returns the application's GriffonControllerActionManager instance.
472 *
473 * @return the application's GriffonControllerActionManager
474 */
475 GriffonControllerActionManager getActionManager();
476 }
|