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