Chapter 4. OGNL expressions

Although OGNL expression is widely used in QuickBuild, generally, you need not know anything about it due to QuickBuild's deliberate designed user interface. For most properties that need OGNL expression, you can choose from drop down menu besides that property simply. However, knowledge of OGNL expression will give you ability to set up very complicated configurations. http://www.ognl.org is the official site for OGNL where you can learn everything about it. This chapter assumes that you have some knowledge of it, and will concentrate on properties and methods that can be used in QuickBuild.

Generally, there are two types of application of OGNL in QuickBuild. The first one is for boolean type properties, including Build necessary condition, Step necessary condition, Build success condition, Step success condition, etc. These properties expect an OGNL expression that will be evaluated to a boolean value. The second one is for string type properties. Inside this string, any number of OGNL expressions can be embedded as long as they are embedded in ${...}, and QuickBuild expects they evaluate to a value of string type. Strings outside of ${...} will simply keep the same during the evaluation. Every string-typed property in QuickBuild accepts OGNL expressions embedded within ${...} as long as there is not explicitly statement of nonsupport. Please be noted that double back slashes should be used for windows path in an OGNL expression, for example, ${"c:\\program files\\apache-ant-1.6.5\\bin\\ant.bat"}. Further more, if you assign windows path as value of a variable, and refer to that variable in OGNL expression, then that windows path should also use double back slashes. For example, in order to assign windows path of ant executable to variable pathToAnt, you may need to define it as:

pathToAnt = "c:\\program files\\apache-ant-1.6.5\\bin\\ant.bat"

The path is quoted because there are spaces inside it.

Maybe you know, every OGNL expression should have a root object in order to perform the evaluation. In QuickBuild, the root object is always current configuration object. From this configuration object, you can access its exposed methods or properties, such as name, status, variables, repositories, builders, steps, current build, current object, etc. Once you get a stuff out of the configuration object, you can recursively get other properties or methods exposed by that particular property. The definitive guide of these exposed methods or properties is the JavaDoc. There are a lot of methods or properties in the JavaDoc, you should only pay attention to methods or properties with OGNL: at the very beginning of the comment. Here are some typical OGNL expressions:

Get the build object that is running

build

Get version of the build object that is running

build.version

Get last build object

lastBuild

Get last successful build object

lastSuccessBuild

Determine if last build is successful

lastBuild.successful

Determine if last build is failed

lastBuild.failed

Determine if last build is running

lastBuild.running

Determine if contents of repository "cvs1" have been modified since last build

repository["cvs1"].modified

Get source path of first module of repository "svn1"

repository["svn1"].modules.get(0).srcPath

Get head revision number of repository "svn1"

repository["svn1"].headRevision

Get workspace directory of repository "accurev1" for current build

repository["accurev1"].getWorkspaceDir(build)

Get version of the remote build used by a QuickBuild repository

repository["quickbuild1"].remoteBuild.version

Determine if contents of all used repositories have been modified since last build

effectingRepositoriesModified

Determine if contents of repository "cvs1" have been modified since last successful build

lastSuccessBuild==null or repository["cvs1"].isModifiedSince(lastSuccessBuild.startDate, configuration)

Get string value of variable "var1"

var["var1"]

Get value of variable "var1" as integer

var["var1"].intValue

Increase value of variable "var1" as integer

var["var1"].increaseAsInt()

Set value of variable "var1" as "value1"

var["var1"].setValue("value1")

Increase value of variable "var1" as integer, and get the increased result

var["var1"].(increaseAsInt(), value)

Determine if value of variable "var1" equals "true"

var["var1"].value=="true"

Get working directory of current configuration

workingDir

Determine if execution of specified command is successful

system.execute("/path/to/my/command") == 0

Get current hour

system.calendar.hour

Get day of week

system.calendar.dayOfWeek

Determine if execution of step "step1" is successful

step["step1"].successful