The Griffon Guide

This guide is heavily influenced by the Grails Guide. It simply would not have been possible without the great efforts made by: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown and their sponsor: SpringSource. The Griffon team would like to thank them all (and the Grails community too!) for making such a great framework and bringing the fun back to programming applications.

The following section outlines the minimum environment requirements to get started with Griffon.

It may seem odd that in a framework that embraces "convention-over-configuration" that we tackle this topic now, but since what configuration there is typically a one off, it is best to get it out the way.

The Griffon runtime keeps track of useful metadata that can be consumed by applications. The following sections describe them with more detail.

Every Griffon application goes through the same lifecycle phases no matter in which mode they are running, with the exception of applet mode where there is an additional phase due to the intrinsic nature of applets. The application’s lifecycle has been inspired by JSR-296, the Swing Application Framework.

Every phase has an associated lifecycle class that will be invoked at the appropriate time. Class names match each phase name; you’ll find them inside griffon-app/lifecycle.

Modules define components that can be injected using the JSR-330 API. Module definitions are highly influenced by the Guice 3.x API however they do not impose a strict dependency on Guice.

Applications have the option to let particular artifacts abort the shutdown sequence and/or perform a task while the shutdown sequence is in process. Artifacts that desire to be part of the shutdown sequence should implement the ShutdownHandler interface and register themselves with the application instance.

The contract of a ShutdownHandler is very simple

ShutdownHandlers will be called on the same order as they were registered.

Command line arguments can be passed to the application and be accessed by calling getStartupArgs() on the application instance. This will return a copy of the args (if any) defined at the command line.

Here’s a typical example of this feature in development mode

Arguments must be defined in the build file if using Gradle

Running the application with run command results in an output similar to the following

This class is responsible for holding the configuration of all MVC groups no matter how they were defined, which can be either in Config.groovy or in an addon descriptor.

During the startup sequence an instance of MVCGroupManager will be created and initialized. Later the application will instruct this instance to create all startup groups as required. MVCGroupManager has a handful set of methods that deal with MVC group configuration alone; however those that deal with group instantiation come in 3 versions, with 2 flavors each (one Groovy, the other Java friendly).

Locating a group configuration is easily done by specifying the name you’re interested in finding

Once you have a configuration reference you can instantiate a group with it by calling any of the variants of the create method

Be aware that creating groups with the same name is usually not a good idea. The default MVCGroupManager will complain when this happens and will automatically spit out an exception. This behavior may be changed by setting a configuration key in Config.groovy

The manager will log a warning and destroy the previously existing group before instantiating the new one when warning is the preferred strategy .

Now, even though you can create group instances based on their configurations the preferred way is to call any of createMVCGroup(), buildMVCGroup() or withMVCGroup() methods. Any class annotated with the @griffon.transform.MVCAware will also gain access to these methods.

Groups will be available by id regardless of how they were instantiated. You can ask the MVCGroupManager for a particular group at any time, for example

It’s also possible to query all models, views, controllers and builders on their own. Say you’d want to inspect all currently instantiated models, this is how it can be done

Now that we know which are the different ways to instantiate MVC groups we can go back to customizing them.

The simplest way is to pass in new values as part of the arguments map that mvcGroupInit() receives, for example

However is you wish to use the special config key that every MVC group configuratio may have then you must instantiate the group in the following way

Note that you can still send custom arguments to the create() method.

Any component may gain the ability to create and destroy MVC groups through a MVCGroupManager instance. You only need annotate the class with @griffon.transform.MVCAware and it will automatically gain all methods exposed by MVCHandler.

This feature is just a shortcut to avoid reaching for the application instance from objects that do not hold a reference to it.

Here’s an example of a custom bean that’s able to work with MVC groups

This class can be used in the following way

Binding in Griffon is achieved by leveraging Java Beans’ java.beans.PropertyChangeEvent and their related classes, thus binding will work with any class that fires this type of event, regardless of its usage of @griffon.transform.Observable or not.

TBD

TBD

The @griffon.transform.Observable transformation will inject the behavior of Observable into the annotated class. It basically injects an instance of java.beans.PropertyChangeSupport and all methods required to make the model an observable class. It will also make sure that a java.beans.PropertyChangeEvent is fired for each observable property whenever said property changes value.

The following is a list of all methods added by @griffon.transform.Observable

The @griffon.transform.Vetoable transformation will inject the behavior of Vetoable into the annotated class. It basically injects an instance of java.beans.VetoableChangeSupport and all methods required to make the model a vetoable class. It will also make sure that a java.beans.PropertyChangeEvent is fired for each vetoable property whenever said property changes value.

The following is a list of all methods added by @griffon.transform.Vetoable

The @griffon.transform.PropertyListener helps you to register PropertyChangeListeners without so much effort. The following code

is equivalent to this one

@griffon.transform.PropertyListener accepts the following values

A key aspect that you must always keep in mind is proper threading. Often times controller actions will be bound in response to an event driven by the UI. Those actions will usually be invoked in the same thread that triggered the event, which would be the UI thread. When that happens you must make sure that the executed code is short and that it quickly returns control to the UI thread. Failure to do so may result in unresponsive applications.

The following example is the typical usage one finds out there

What’s wrong with this code? It’s very likely that this action is triggered by clicking on a button, in which case its body will be executed inside the UI thread. This means the database query will be executed on the UI thread too. The model is also updated, once could assume the model is bound to an UI component. This update should happen inside the UI thread, but clearly that’s not what’s happening here.

In order to simplify things the Griffon runtime (via the ActionManager) assumes by default that all actions will be invoked outside of the UI thread. This solves the first problem, that of realizing a database operation on the wrong thread. The second problem, updating the model, can be solved in the following manner

There are other options at your disposal to make sure the code behaves properly according to the specific threading rules of a particular UI toolkit. These options are covered in the threading chapter.

Controller actions may automatically be wrapped and exposed as toolkit specific actions; this greatly simplifies how actions can be configured based on i18n concerns.

At the heart of this feature lies the ActionManager. This component is responsible for instantiating, configuring and keeping references to all actions per controller. It will automatically harvest all action candidates from a Controller once it has been instantiated. Each action has all of its properties configured following this strategy:

<action.name> should be properly capitalized. In other words, you can configure action properties specifically per Controller or application wide. Available keys are

Icon keys should point to an URL available in the classpath.

Values must be placed in resources files following the internationalization guidelines.

ActionInterceptors open a new set of possibilities by allowing developers and addon authors to define code that should be executed before and after any controller action is invoked by the framework. For example, you may want to protect the execution of a particular action given specific permissions; the shiro plugin uses annotations that are handled by an ActionInterceptor, like this

The scaffolding plugin on the other hand modifies the arguments sent to the action. Take the following snippet for example

Note that the login action requires an instance of LoginCommandObject. The scaffolding plugin is aware of this fact; it will create an instance of said class, wire up an scaffolded view in a dialog and present it to the user. The LoginCommandObject instance will be set as the action’s arguments if it validates successfully, otherwise action execution is aborted.

Services do not have a well-defined lifecycle like other MVC artifacts because they do implement the GriffonMvcArtifact interface. However you may annotate service methods with @javax.annotation.PostConstruct and @javax.annotation.PreDestroy.

The Griffon runtime guarantees that methods annotated with @javax.annotation.PostConstruct will be invoked right after the instance has been created by the Injector. Likewise it will invoke all methods annotated with @javax.annotation.PreDestroy when the Injector is closed.

Although the following API refers directly to Swing in all examples it’s possible to use the WindowManager with other toolkits such as JavaFX, Pivot and Lanterna as there are specific WindowManager implementations plus helper classes for those UI toolkits too.

The WindowManager class is responsible for keeping track of all the windows managed by the application. It also controls how these windows are displayed (via a pair of methods: show, hide). WindowManager relies on an instance of WindowDisplayHandler to actually show or hide a window. The default implementation simple shows and hide windows directly, however you can change this behavior by setting a different implementation of WindowDisplayHandler on the application instance.

Recall from the ConsoleView sample application that you can use a Groovy DSL for building View components when the main language of the application is Groovy. This DSL is configured with default nodes that are tightly coupled with the chosen UI toolkit.

Refer to the list of nodes that become available when the griffon-swing-groovy-2.0.0.RC2.jar is added as a dependency.

Refer to the list of nodes that become available when the griffon-javafx-groovy-2.0.0.RC2.jar is added as a dependency.

Lanterna is a Java library allowing you to write easy semi-graphical user interfaces in a text-only environment, very similar to the C library curses but with more functionality. Lanterna supports xterm compatible terminals and terminal emulators such as konsole, gnome-terminal, putty, xterm and many more. One of the main benefits of lanterna is that it’s not dependent on any native library but runs 100% in pure Java.

Refer to the list of nodes that become available when the griffon-lanterna-groovy-2.0.0.RC2.jar is added as a dependency.

Apache Pivot is an open-source platform for building installable Internet applications (IIAs). It combines the enhanced productivity and usability features of a modern user interface toolkit with the robustness of the Java platform.

Pivot has a deep listener hierarchy as opposed to the simple one found in Swing. This listener hierarchy does not follow the conventions set forth by the JavaBeans Conventions, thus making it difficult to extrapolate synthetic properties based on event methods when using Groovy builders, as it happens with Swing classes. However this plugin applies a convention for wiring up listeners. Take for example Button and ButtonPressListener, the following example shows how to wire up a buttonPressed event handler.

For each listener in the Pivot listener list there’s a corresponding node matching their name. For each method of such listener interface there’s a variable matching its name that may have a closure assigned to it. The closure must match the same arguments as the method.

Refer to the list of nodes that become available when the griffon-pivot-groovy-2.0.0.RC2.jar is added as a dependency.

Synchronous calls inside the UI thread are made by invoking the runInsideUISync method. This method results in the same behavior as calling SwingUtilities.invokeAndWait() when using Swing.

Similarly to synchronous calls, asynchronous calls inside the UI thread are made by invoking the runInsideUIAsync method. This method results in the same behavior as calling SwingUtilities.invokeLater() when using Swing.

Making sure a block of code is executed outside the UI thread is made by invoking the execOutsideUI method. This method is smart enough to figure out if the unit of work is already outside of the UI thread; otherwise it instructs the Griffon runtime to runt he unit in a different thread. This is usually performed by a helper java.util.concurrent.ExecutorService.

There are two additional methods that complement the generic threading facilities that Griffon exposes to the application and its artifacts

The @griffon.transform.Threading annotation can be used to alter the default behavior of executing a controller action outside of the UI thread. There are 4 possible values that can be specified for this annotation

This annotation can be usend as an AST transformation on any other component that’s not a controller. Any component may gain the ability to execute code in a particular thread, following the selected UI toolkit’s execution rules.

Here’s an example of a custom component that’s able to call its methods in different threads

You must annotate a method with @griffon.transform.Threading. Annotated methods must conform to these rules

Any component may gain the ability to execute code in a particular thread, following the selected UI toolkit’s execution rules. It injects the behavior of ThreadingHandler into the annotated class.

This feature is just a shortcut to avoid reaching for the UIThreadManager instance from objects that do not hold a reference to it.

Here’s an example of a custom component that’s able to call its methods in different threads

Any instance that obtains a reference to an EventRouter can publish events. GriffonApplication exposes the application wide EventRouter via a read-only property. You may use Dependency Injection to inject an EventRouter to any class too.

Publishing an event can be done synchronously on the current thread, asynchronously to the current thread, or asynchronously relative to the UI thread. For example, the following snippet will trigger an event that will be handled in the same thread, which could be the UI thread itself

Whereas the following snippet guarantees that all event handlers that are interested in an event of type MyEventName will be called outside of the UI thread

Finally, if you’d want event notification to be handed in a thread that is not the current one (regardless if the current one is the UI thread or not) then use the following method

Alternatively, you may specify an instance of a subclass of Event as the sole argument to any of these methods. The event instance will be the single argument sent to the event handlers when the event methods are invoked in this way.

There may be times when event publishing must be stopped for a while. If that’s the case then you can instruct the application to stop delivering events by invoking the following code

Any events sent through the application’s event bus will be discarded after that call; there’s no way to get them back or replay them. When it’s time to enable the event bus again simply call

Any artifact or class that abides to the following conventions can be registered as an application listener, those conventions are:

There is a global, per-application event handler that can be registered. If you want to take advantage of this feature you must define a class that implements the EventHandler interface. This class must be registered with a Module. Lastly both Controller and Service instances are automatically registered as application event listeners.

The following events will be triggered by the application when dealing with artifacts

These events will be triggered when dealing with MVC groups

The following events will be triggered by the application during each one of its phases

These events will be triggered when a specific condition is reached

Any component may gain the ability to publish events through an EventRouter instance. You only need annotate the class with @griffon.transform.EventPublisher and it will automatically gain all methods exposed by EventPublisher.

The following example shows a trivial usage of this feature

The application’s event router will be used by default. If you’d like your custom event publisher to use a private EventRouter then you must define a binding for it using a specific name, like this

Next specify the named EventRouter as a parameter on the @griffon.transform.EventPublisher transformation

Applications have the ability to resolve internationalizable messages by leveraging the behavior exposed by MessageSource. This interface exposes the following methods:

The first set throws NoSuchMessageException if a message could not be resolved given the key sent as argument. The following methods take and additional defaultMessage parameter that may be used if no configured message is found. If this optional parameter were to be null then the key is used as the message; in other words, these methods never throw NoSuchMessageException nor return null unless the passed in key is null.

The simplest way to resolve a message thus results like this

The set of methods that take a List as arguments are meant to be used from Groovy code whereas those that take an Object[] are meant for Java code; this leads to better idiomatic code as the following examples reveal

Of course you may also use List versions in Java, like this

Messages may be configured in either properties files or Groovy scripts. Groovy scripts have precedence over properties files should there be two files that match the same basename. The default configured basename is "messages", thus the application will search for the following resources in the classpath.

Of course Groovy scripts are only enabled if you add a dependency to the griffon-groovy module to your project. The default basename may be changed to some other value, or additional basenames may be specified too; it’s just a matter of configuring a Module override

Both properties files and Groovy scripts are subject locale aware loading mechanism described next. For a Locate set to de_CH_Basel the following resources will be searched for and loaded

Properties files and Groovy scripts used for internationalization purposes are usually placed under griffon-app/i18n The default messages.properties file is placed in this directory upon creating an application using the standard project templates.

Any component may gain the ability to resolve messages through a MessageSource instance. You only need annotate the class with @griffon.transform.MessageSourceAware and it will automatically gain all methods exposed by MessageSource.

This feature is just a shortcut to avoid reaching for the application instance from objects that do not hold a reference to it.

Here’s an example of a custom bean that’s able to resolve messages

This class can be used in the following way

The application’s MessageSource will be injected to annotated beans if no name is specified as an argument to MessageSourceAware. You may define multiple MessageSource bindings as long as you qualify them with a distinct name, such as

Then make use of any of these bindings like so

Resources can be loaded form the classpath using the standard mechanism provided by the Java runtime, that is, ask a ClassLoader instance to load a resource URL or obtain an InputStream that points to the resource.

But the code can get quite verbose, take for example the following view code that locates a text file and displays it on a text component

In order to reduce visual clutter, also to provide an abstraction over resource location, applications rely on ResourceHandler, which exposes the following contract

Thus, the previous example can be rewritten in this way

In the future Griffon may switch to a modularized runtime, this abstraction will shield you from any problems when the underlying mechanism changes, such as picking the correct ClassLoader.

Any component may gain the ability to locate resources through a ResourceHandler instance. You only need annotate the class with @griffon.transform.ResourcesAware and it will automatically gain all methods exposed by ResourceHandler.

This feature is just a shortcut to avoid reaching for the application instance from objects that do not hold a reference to it.

Here’s an example of a custom bean that’s able to locate resources

This class can be used in the following way

Applications have the ability to resolve internationalizable messages by leveraging the behavior exposed by ResourceResolver. This interface exposes the following methods:

The first set throws NoSuchResourceException if a message could not be resolved given the key sent as argument. The following methods take and additional defaultValue parameter that may be used if no configured resource is found. If this optional parameter were to be null then the key is used as the literal value of the resource; in other words, these methods never throw NoSuchResourceException nor return null unless the passed in key is null.

The simplest way to resolve a message thus results like this

The set of methods that take a List as arguments are meant to be used from Groovy code whereas those that take an Object[] are meant for Java code; this leads to better idiomatic code as the following examples reveal

Of course you may also use List versions in Java, like this

Resources may be configured in either properties files or Groovy scripts. Groovy scripts have precedence over properties files should there be two files that match the same basename. The default configured basename is "resources", thus the application will search for the following resources in the classpath.

Of course Groovy scripts are only enabled if you add a dependency to the griffon-groovy module to your project. The default basename may be changed to some other value, or additional basenames may be specified too; it’s just a matter of configuring a Module override

Both properties files and Groovy scripts are subject locale aware loading mechanism described next. For a Locate set to de_CH_Basel the following resources will be searched for and loaded

Properties files and Groovy scripts used for internationalization purposes are usually placed under griffon-app/resources The default resources.properties file is placed in this directory upon creating an application using the standard project templates.

Any component may gain the ability to resolve resources through a ResourceResolver instance. You only need annotate the class with @griffon.transform.ResourceResolverAware and it will automatically gain all methods exposed by ResourceResolver.

This feature is just a shortcut to avoid reaching for the application instance from objects that do not hold a reference to it.

Here’s an example of a custom bean that’s able to resolve resources

This class can be used in the following way

The application’s ResourceResolver will be injected to annotated beans if no name is specified as an argument to ResourceResolverAware. You may define multiple ResourceResolver bindings as long as you qualify them with a distinct name, such as

Then make use of any of these bindings like so

Resources may be automatically injected to any instance created via the application’s Injector. Injection points must be annotated with @griffon.core.resources.InjectedResource which can be set on properties (Groovy), fields (Java and Groovy) and setter methods (Java and Groovy). @InjectedResource is a perfect companion to models as the following example shows

@InjectedResource assumes a naming convention in order to determine the resource key to use. These are the rules applied by the default by ResourcesInjector:

You may also specify a default value if the resource definition is not found, however be aware that this value must be set as a String thus guaranteeing a type conversion. An optional format value may be specified as a hint to the PropertyEditor used during value conversion, for example

Resource injection makes use of the PropertyEditor mechanism provided by the java.beans package. The default ResourcesInjector queries PropertyEditorManager whenever a resource value must be transformed to a target type.

PropertyEditorManager provides methods for registering custom PropertyEditors, it also follows a class name convention to load PropertyEditors should a custom one is not programmatically registered. Griffon applications will automatically load and register PropertyEditors from the following classpath resource: /META-INF/services/java.beans.PropertyEditor. Each line follows the format

The following table enumerates the default PropertyEditors loaded by Griffon at startup.

Where the following apply

Core UI Toolkit dependencies, such as griffon-swing and griffon-javafx, deliver additional PropertyEditors. The following tables summarize these additions

Where the following apply

The following styles are supported by FontPropertyEditor