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