GriffonApplication.java
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 }