Introduction

Groovy is a standard, dynamic scripting language for the Java platform for which Visual Builder provides deep support. This document explains the basics of how you will use the Groovy scripting language to enhance your applications. This section provides a brief overview of the different contexts in which you can use Groovy scripts. The second section covers the basics of Groovy. The third section gives a concrete example of each type of Groovy script you can write. The fourth section offers a compendium of tips and techniques for getting the most out of Groovy in your applications, and the final section documents the supported classes and methods you are allowed to use in your Groovy code.

Note: Please read Supported Classes and Methods for Use in Groovy Scripts that documents the only classes and methods you may use in your Groovy scripts. Using any other class or method will raise a security violation error.

Terminology

Throughout the document the term script is used to describe one or more lines of Groovy code that your application using Oracle business objects executes at runtime. Often a very-short script is all that is required. For example, to validate that a CommissionPercentage field's value does not exceed 40%, you might use a one-line script like:

return CommissionPercentage < 0.40

In fact, this one-liner can be conveniently shortened by dropping the return keyword since the return keyword is always implied on the last line of a script:

CommissionPercentage < 0.40

For slightly more complicated logic, your script might require some conditional handling. For example, suppose the maximum commission percentage is 40% if the salesperson's job grade is less than or equal to 3, but 60% if the job grade is higher. Your script would grow a little to look like this:

if (JobGrade <= 3) {
  return CommissionPercentage < 0.40
}
else {
  return CommissionPercentage < 0.60
}

Scripts that you'll write for other purposes like complex validation rules or reusable functions may span multiple pages, depending on your needs.

When a context requiring a Groovy script will typically use a short (often, one-line) script, we emphasize that fact by calling it an expression, however technically the terms script and expression are interchangeable. Anywhere you can provide a one-line expression is also a valid context for providing a multi-line script if the need arises. Whether you provide a short expression or a multi-line script, the syntax and features at your disposal are the same. You need only pay attention that your code returns a value of the appropriate type for the context in which you use it. Each section below highlights the expected return type for the script in question.

Where You'll Use Groovy in Your Application

There are a number of different contexts where you will use Groovy scripts as you customize existing objects or create new custom ones. You will write shorter scripts to provide an expression to:

calculate a formula field's value
calculate a field's default value

You will generally write somewhat longer scripts to define:

a field-level validation rule
an object-level validation rule
a trigger to complement default processing
reusable behavior in an object function

If you anticipate calling the same code from multiple different contexts, any of your scripts can call the reusable code you write in object functions.

After exploring the Groovy basic techniques needed to understand the examples, see Examples of Each Context Where You Can Use Groovy for a concrete example of each of these usages, and Groovy Tips and Techniques for additional tips and techniques on getting the most out of Groovy in your application.

Ensuring Your Scripts Are Easy to Maintain

When writing a script, your first instinct is to get your business logic working correctly. Over time, as you iteratively add functionality, the script for a complex business process can grow very long. However, Oracle recommends limiting each script to 400 lines. Since one script can invoke other functions, in practice this restriction does not hamper your ability to solve business problems. It is always possible to decompose a lengthy script into a shorter alternative that invokes other object functions as needed.

For example, instead of writing a 600–line trigger script, create a shorter trigger that invokes other object functions. In turn, if one of these functions starts getting long, reorganize its code into additional, smaller functions that the original function can invoke. For each function you create, choose a meaningful name that describes the task it performs.

Suppose you have written a “Before Insert” trigger that executes before each new PurchaseOrder object is created. Imagine it contains a large amount of code that conditionally creates a default set of LineItem child objects for new orders. To avoid exceeding the 400–line limit and improve readability of your code, reorganize it into two object functions named requiresDefaultLineItems() and createDefaultLineItems(). Then rewrite the original trigger to be:

// Before Insert Trigger on PurchaseOrder
if (requiresDefaultLineItems()) {
  createDefaultLineItems()
}

By following these recommendations, your code will avoid “Code too large!” errors and will become much easier for colleagues to understand and maintain as well.