griffon/core/GriffonApplication.java

`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 }`