The DomEL Syntax

Various components of a Domain need to compute values based on some expression involving constants, field values, and environment variables. The Domain Expression Language (DomEL) was created to fill this need. Currently, the following features in XML design files are expressed in DomEL:

•    The on and where clauses of derived tables

•    The on clause of join statements

•    Calculated fields

•    Filter expressions in Domains and Domain topics (equivalent to where clauses)

•    The testProfileAttribute function

•    Row-level security (see section The Domain Security File)

A DomEL expression is a shorthand way of writing a complex query. When processing a report based on a Domain, the server interprets DomEL expressions to generate parts of the SQL expression that perform the desired query. Depending on the data policy, either the augmented SQL is passed to the data source, or the server performs a simpler query and applies the DomEL expressions to the full dataset in memory.

Datatypes

The following simple datatypes may be declared as constants, used in expressions, and returned as values:

The following composite datatypes may be declared as constants and used with the in set or in range operator. The values in these composite types are not necessarily constant, they could be determined by field values:

Field References

DomEL expressions are stored in the Domain design and interpreted when the server prepares to run a query to retrieve data from the data source. Therefore, all references to field values in an expression are based on the IDs given in the Domain design. Field references have the following format, depending on where the expression appears:

Operators and Functions

DomEL provides the following operators, listed in order of precedence. Operators higher in this list are evaluated before operators lower in the list:

DomEL also defines the following operations as functions:

Profile Attributes

A profile attribute is a name-value pair inserted in a user object, such as a user or role. It is ordinarily used to extend the object’s standard access grants, but it has other uses, as well. It can be added to objects by database tools or custom code.

For example, this Groovy expression tests users for the Cities access grant in the store_city field in the store table:

<filterExpression>store.store_city in (groovy('authentication.getPrincipal().getAttributes().find{ it.attrName == "Cities" }.attrValue.split(",").collect {"''" + it + "''" }.join(",").replaceFirst("^''","").replaceFirst("''\$","")'))</filterExpression>

Using profile attributes enables you to obtain similar results with simpler expressions. The example below uses a principal expression to find all users with the Cities profile attribute, then it uses a filter expression to grant access only to the users among them whose Cities profile attribute is San Francisco:

The next example tests the same profile attribute, Cities. However, instead of granting access only to users with a specific profile attribute, you use variable substitution in the filter expression to grant access to all users according to their Cities attribute. A user with the San Francisco profile attribute gets access to that city, a user with the Denver profile attribute gets access to that city, and so on:

Finally, testProfileAttribute is a function for taking advantage of the profile attributes feature. An extension of the DomEL language, testProfileAttribute examines an object for a given profile attribute and permits access to the related data when the attribute is present.

Using the testProfileAttribute function, you can write simpler expressions than you can using Groovy. For instance, this filter expression tests users for the Cities profile attribute. Compare it to the expression in the previous example:

<filterExpression>testProfileAttribute(store.store_city, 'Cities')</filterExpression>

For more information about profile attributes, variable substitution, and testProfileAttribute, see the JasperReports Server Ultimate Guide and Jaspersoft OLAP Ultimate Guide.

SQL Functions

You may use SQL functions in a DomEL expression, but only in limited circumstances:

•    The functions must be supported by the database. See the vendor documentation for available functions and their syntax.

•    The functions must follow the convention of comma-separated parameters. For example, you can use TRIM(person.name), but not TRIM('Jr' FROM person.name)

•    The type of the return values must be appropriate, either within the expression or for the type of the calculated field.

•    The SQL context must be appropriate for the functions. For example, you cannot use aggregation functions such as COUNT in a calculated field because there is no GROUP BY clause.

Except for the comma-separated parameter pattern, the DomEL validation cannot enforce these criteria. You must ensure that any SQL functions meet these criteria, otherwise the expression causes errors when using the Domain to create a report.

Complex Expressions

Complex expressions are written by grouping any of the operators or functions above. Parentheses () may be used for grouping boolean operators, but arithmetic expressions that rely on parentheses are not supported. To compute complex arithmetic expressions, you may need to define several expressions as separate calculated fields, and then reference them in a simpler expression in another calculated field.

The following examples show complex expressions suitable for filters. This first one selects only stores in Western states of the US:

s1.store_country in ('USA') and s1.store_state in ('WA', 'OR', 'CA', 'NV')

The following filter expression uses a date range:

s1.first_opened_date in ( Date( '2000-01-01' ) : Date( '2004-12-31' )) and not( s1.closed )

As shown in these examples, field values are often compared to constant values such as 'USA'. Therefore, the author of the design file must ensure that values used in a DomEL expression exist in the data source. Otherwise, a wrong value might go undetected and impact the quality of data in reports based on the Domain. The Domain Designer determines values for comparison by accessing the data source, so if you export a design file, you can use the values it has found. Another way to reduce errors and also support future data changes is to use more general expressions such as:

s1.store_country in ('US', 'USA', 'United States')

Return Value

DomEL expressions are used in different contexts for different purposes. The expected return type depends on where the expression appears: