Service Definition DSL

The Service Definition DSL defines the list of actions to perform, provides a simple mechanism to validate the properties of the message, and provides logic in the form of Groovy scripting. This DSL executes in the context of the Grails server therefore allowing the ability to inject Spring beans from the Grails container. The order in which the actions are defined determines the order in which each action are called. The file name of the DSL defines the name of the service. For example if the file name is "org.example.stockCheck.groovy" then the service name is "org.example.stockCheck". The grailsservicebus.definitions.locations key in Config.groovy defines the list of directories in which definitions can be found. The definitions are cached and if they are changed then the server will recompile the DSL without having to restart.

Example Definition

// injects the grails spring bean and the property in the script is named the same as the bean
using "myBean"

// injects the grails spring bean and renames the property used in the script
using "grailsApplication" alias "grails"

// "firstParameter" is required of type "any"
parameter name:"firstParamter"
parameter name:"secondParameter", required: true, default: "default value", type: "string"

// if parameter is not found then it is created with defaults
parameter name:"thirdParameter", default: "default value"

// specifying a type
parameter name:"fourthParameter", type: "boolean", default: true

action {
    handler "script"
    file "actionScript.groovy"
    properties {
        key = "value"
        anotherKey = "another value"
        keyFromConfig = grails.config.key.in.config
    }
}

action handler:"script", file:"secondExample.groovy", {
    foo = [[a:"b"], 2, 3, "secondExample"]
}

action file:"thirdExample.groovy", {
    foo = [[a:"b"], 2, 3, "thirdExample"]
}

action (handler:"script", file:"fourthExample.groovy") {
    foo = [[a:"b"], 2, 3, "fourthExample"]
}

action (file:"sixthExample.groovy") {
    foo = [[a:"b"], 2, 3, "sixthExample"]
}

using

Injects a Grails Spring Bean into the script. The default behaviour of the injection is to name the script's property the same name as the bean name; however, if you need to rename the property then use the alias keyword to specify the new name of the property.

using "grailsApplication"
using "dataSource" alias "ds"

def foo = grailsApplication.config.a.key.in.the.config.groovy
def foo = new Sql(ds)

grailsApplication and applicationContext are injected by default.

parameter

Verifies the message against a service interface definition. The validation will only validate the keys that are specified and all the other keys, in the message, are ignored.

Key	Type	Required	Default	Description
name	string	true	n/a	This is the name of the key in the message.
required	boolean	false	true	If the key in the message is mandatory.
default	any	false	n/a	If the key does not exists then create it with the value provided.
type	string or string[]	false	any	Validates the type of the value of the key in the message. Valid types are: 'any', 'array', 'boolean', 'double', 'integer', 'null', 'numeric', 'object', and 'string'. If 'numeric" is specified then a 'double' or an 'integer' can be used for the value.

action

Actions are the logical units of a service. The DSL builds an ordered list of the actions and then the service engine executes the actions in the order in which they are defined in the DSL file.

The complete form of an action:

action {
    handler "script"
    file "actionScript.groovy"
    properties {
        key = "value"
        anotherKey = "another value"
        keyFromConfig = grails.config.key.in.config
        valueFromClosure = { "returning a value from a closure" } ()
    }
}

The service bus provides the script handler as the default if the handler keyword is not specified. A handler is the code that knows how to execute the defined action. The Script handler executes Groovy scripts, caches, and recompiles the script if it is changed without having to reboot. The file property is mandatory for the Script handler and it is relative to the list of directories that are defined in the Config.groovy file using the grailsservicebus.actions.locations key.

properties

properties is simply just a Map which is passed to the action's handler for the instance of the action being executed. properties is optional and if it is not specified then the action's handler will have a reference to an empty Map.