Configuration

Event-handler registration

Event handlers are registered via configuration files. The complete syntax has the following form:

/config/handlers += [{
  "events" : JSON_string or JSON_array(JSON_string),
  "handler" : JSON_string,
  "conditions" : JSON_string,
  "instanceData" : JSON_object
}]

where

• events is the name (or list of names) of the events handled by this handler
• handler is the name of the handler, including a suffix that must match a registered Interpreter type. The default list of registered types is:
  • .class for Java (the value is the fully-qualified class name with a ".class" suffix, e.g. "your.pkg.Handler.class")
  • .groovy for Groovy scripts (searched in app/scripts; use slashes for path delimiters, e.g. "foo/bar/handler.groovy")
  • .gt for Groovy templates (searched in app/views; use slashes for path delimiters, e.g. "foo/bar/handler.gt")
  • .php for PHP scripts (searched in app/scripts; use slashes for path delimiter, eg "foo/bar/handler.php")
• conditions is optional. The value of the conditions, computed at run time. If not specified, then the handler is always a match for the corresponding event.
• instanceData is optional. This data is provided to the handler in the event zone.

Condition operators

Global Context URI

true only if the Global Context contains the specified key.
Example: "conditions" : "/request/status"

==

Selector pattern match. Named groups are specified as {name}; matches may be qualified, such as {name:any}. Values of named groups are set into the event zone for the handler.
Example: "/request/path == /foo/bar/{next}]; the value of next is available to the invoked handler in the Global Context at /event/next contains value.

Qualifiers:

any

Matches to the end.
Example: If /request/path == /a/b/c, then "/request/path == /a/{remainder:any}" evaluates to true and the handler will be invoked with /event/matchedURI == /a and /event/remainder == b/c.

The pipe character | will also match to the end of the URI and, additionally, set /event/pathInfo.
Example: If /request/path == /a/b/c, then "/request/path == /a|" evaluates to true and the handler will be invoked with /event/matchedURI == /a and /event/pathInfo == /b/c.

Note: | is only valid as the last character in the selector pattern or last except for right brackets. For example, "/request/path == /a/b|" and "/request/path == /a[/b|]" are valid; "/request/path == /a|/b" is not.

element

Matches to the next slash.

digit

Matches one or more digits: [0-9].

word

Matches one or more word characters: [a-zA-Z_0-9].

=~

Regex pattern match, based upon the regular expression support in the JDK.
Example: "/request/path =~ /foo/.*"
Example: "/event/resolvingEvent =~ (GET|POST|DELETE|PUT)"

!

Negates the condition value; placed before the operator it modifies.
Example: "!(/request/status)"

!=

Not URI matches
Example: "/request/path != /a/b"

!~

Not matches
Example: "/event/resolvingEvent !~ (GET|POST)"

&&

Logical AND
Example: "(/request/path != /a/b) && (/event/resolvingEvent !~ (GET|POST))"

||

Logical OR Example: "(/request/path == /a/b) || (/event/resolvingEvent =~ (GET|POST))"

Configuration templates

A combination of @include and configuration properties can be used to build configuration templates.

For example, security support in zero.core uses configuration templates.

Configuration template example: config/security/rule.config

authType=""
users=[]
groups=[]
roles=[]
requireSSL=false
csrfProtect=true


@include "requireSSL.config"{
   "conditions": ${conditions},
   "requireSSL": ${requireSSL}
}

csrfProtect=${csrfProtect}

/config/handlers += [{
   "events" : "secure",
   "handler" : "zero.core.security.SecurityHandler.class",
   "conditions": ${conditions},
   "instanceData" : {
                  "authType" : ${authType},
                  "groups" : ${groups},
                  "users" : ${users},
                  "roles" : ${roles},
                  "csrfProtect" : ${csrfProtect}
               }
}
]

/config/handlers += [{
   "events" : "retrieveCredentials",
   "handler" : "zero.core.security.${authType}UserInfoResolver.class",
   "conditions": ${conditions}
}]

/config/handlers += [{
   "events" : "authorize",
   "handler" : "zero.core.security.authorization.AuthorizationHandler.class",
   "conditions": ${conditions}
}]

Using a configuration template

@include "security/rule.config"{
   "conditions" : "(/request/path =~ /formauth/getonly(/.*)?) && (/request/method == GET)",
   "authType" : "Form",
   "groups" : ["ALL_AUTHENTICATED_USERS"]
}

Type-handler registration

Type handlers are registered via configuration files or programmatically. Each new type handler is registered by appending it to the list. For example:

/config/typeHandlers += {
   "zero.core.context.types.commands.Command" : "zero.core.context.types.CommandTypeHandler"
}

Order of processing

Zero enforces a "first one wins" strategy with configuration processing to ensure consistency throughout the application. As a result, you might need to understand the order in which configuration files are processed in cases involving overwrites.

By default, Zero first processes <apphome>/config/zero.config, then processes config/zero.config for each dependency. The order in which dependencies are processed is described in the Virtualized directories documentation. Although the config directory is not a virtualized directory, the order of processing configuration files is identical to the search order through dependencies within a virtualized directory.

Pre- and post-configuration files

Deployers may want to override application configuration settings without modifying any of the application files. This can be accomplished with pre- and post-configuration files. (Pre- and post- refer to the main configuration processing step: pre- happens before the main configuration processing; post- occurs after.)

In Eclipse, you specify an alternate configuration file by modifying the Run profile for that Zero application to set the Program Arguments to: [-pre <preConfigFile>] [-post <postConfigFile>] <applicationRootDirectory>

From the command line:

zero run [-args "-pre <preConfigFile>"]

<configFile> may be an absolute or relative file reference. Relative file references are relative to the current working directory.