Util Functions

Util functions are small, general-purpose functions designed to perform simple, often repetitive tasks. They are generic and can be used in various places in Higson configuration, which helps organize, maintain, and increase the readability of configuration.

Features of Util Functions:

  • Clearly defined purpose: Util functions perform a single, specific operation, such as date formatting, string manipulation, data type conversions, validations, etc.
  • Independent of specific business logic: They are neutral and can be reused across different projects.
  • Reusable: They are created to be used multiple times in different parts of the configuration.

In summary, util functions are tools that make it easier to handle common and repetitive tasks in Higson, improving the structure and organization of configuration.

You can use util functions in Domain Configuration and Decision Tables. To call a util function in Higson configuration, use the notation $u utilFunctionName().

The following util functions are available in Higson:

  • Equals
  • Add
  • Diff
  • Exist
  • Format
  • From
  • GreaterThanEquals
  • GreaterThan
  • IsBlank
  • LessThanEquals
  • LessThan
  • NotBlank
  • Size
  • To
  • Trim
  • NotEmpty
  • Get
  • IsEmpty

Examples#

Equals#

This method checks if a value from the Higson context is equal to another value.

Function arguments (mandatory 2 arguments):

  • ctx: The HigsonContext object.
  • args: The arguments passed to the method.

Example 1: $u equals(context.path, 100)

  • The first argument should be the path to the target object in the context.
  • The second argument should be the value to compare with the target object (it can be a number or date).

Function arguments (optionally 4 arguments):

  • First argument: path to the target object.
  • Second argument: value to compare with the target object.
  • Third argument: ignoreCase for case-insensitive comparison.
  • Fourth argument: trim to ignore leading and trailing whitespace.

Example 2: $u equals(context.path, 100, ignoreCase, trim)

Return: True or false based on the comparison.

Add#

This method performs an addition operation based on the given arguments. Note: Numbers given as text in the context are interpreted by Higson as numbers

Function arguments:

  • ctx: The HigsonContext object.
  • args: The arguments passed to the method.

Example 1: $u add(ctx, arg) For numeric attributes, only two arguments are needed: context path and value to add.

Example 2: $u add(ctx, 10, d) For date type attributes, three arguments are needed: context path, value to add, and string representation of the time token (e.g., “d” for days).

The following table shows the supported time tokens.

Argument Description Applies to data type
s SECOND Local datetime, Date
m MINUTE Local datetime, Date
h HOUR Local datetime, Date
d DAY Local datetime, Local date, Date
M MONTH Local datetime, Local date, Date
Y YEAR Local datetime, Local date, Date

Return: The result of the addition operation, or null if the value is blank.

Example 3: $u add(ctx.path1, ctx.path2) - adds two elements provided by the HigsonContext

Return: The result of the addition operation, or null if the value is blank.

Diff#

Calculates the difference based on the given arguments and the target object.

Function arguments:

  • ctx: The HigsonContext object.
  • args: The arguments passed to the method.

Example: $u diff(ctx, arg)

  • The first argument is the path to the target object.
  • The second argument is the value to subtract from the target object.
  • The third argument (optional) is the string representation of the time token (for date formats).

Return: The result of the difference calculation, or:

  • If the target object and the diff value are both numbers, the method returns the subtraction of the two values.
  • If the target object is a Date or LocalDateTime, and the diff value is a number, the method returns the difference in time based on the provided time token.
  • If the target object is a String, the method returns the modified string after applying the difference operation.
  • If none of the above conditions match, the method returns the target object as is.

Throws: HigsonRuntimeException if the target object is a number and the diff value is not a number, an exception is thrown.

Exist#

Checks if a value exists in the given context.

Function arguments:

  • ctx: The HigsonContext object.

Example: $u exist(ctx.path)

Return: True if the context value exists. False if the ctx.path is an empty string.

Format#

Formats data according to a given pattern. Applies to the following data types:

  • Number/Integer
  • String
  • Date

Function arguments:

  • ctx: The HigsonContext object.
  • args: The arguments passed to the method.
Argument Description Applies to data type
2 Rounding to two decimal places number/integer
lower Format string to lowercase string
upper Format string to uppercase string
capitalize Format string to capitalize string
reverse Reverse string string
yyyy.MM.dd G ‘at’ HH:mm:ss Format date according to pattern: 2001.07.04 AD at 12:08:56 date
EEE, MMM d, ‘‘yy Format date according to pattern: Wed, Jul 4, ‘01 date
h:mm a Format date according to pattern: 12:08 PM date
hh ‘o’‘clock’ a Format date according to pattern: 12 o’clock PM date
K:mm a Format date according to pattern: 0:08 PM date
yyyyy.MMMMM.dd GGG hh:mm aaa Format date according to pattern: 02001.July.04 AD 12:08 PM date
EEE, d MMM yyyy HH:mm:ss Format date according to pattern: Wed, 4 Jul 2001 12:08:56 date
yyMMddHHmmss Format date according to pattern: 010704120856 date
yyyy-MM-dd’T’HH:mm:ss.SSS Format date according to pattern: 2001-07-04T12:08:56.235 date
yyyy-MM-dd’T’HH:mm:ss.SSSXXX Format date according to pattern: 2001-07-04T12:08:56.235-07:00 date
YYYY-‘W’ww-u" 2001-W27-3 Format date according to pattern: 2001-W27-3 date

Example: $u format(ctx, arg) $u format(1.2345, 2) → 1.23 Return: The formatted output based on the type of the object retrieved from the context.

Throws: HigsonRuntimeException if the format utility function is missing the format argument or if the type is unsupported.

From#

This function is used to extract a substring from a string or extract some elements from a list.

  • if object is String then function will return part of string after indexed passed in the second argument
  • if object is List then function will return part of list after indexed passed in the second argument
  • in other cases function will throw exception with unsupported type

Function arguments:

  • ctx: The HigsonContext object.
  • args: The arguments passed to the ‘from’ util function.

Example: $u from(ctx, arg) $u from(abcdef, 5) → f

Return: The result of the ‘from’ util function or null if the target is null or of an unsupported type.

Throws: HigsonRuntimeException if a required argument is missing, or if the target is of an unsupported type.

Greater Than Equals#

Checks if a value from the Higson context is greater than or equal to another value.

Function arguments:

  • ctx: The HigsonContext object.
  • args: The arguments passed to the method.

Example: $u gte(ctx, arg)

The method supports comparing various types, including:

  • Strings: Compares lexicographically.
  • Numbers: Compares numerically.
  • Dates (java.util.Date, LocalDate, LocalDateTime): Compares chronologically.

Return: True if the target object is greater than or equal to the given value, otherwise false.

Throws: HigsonRuntimeException if fewer than two arguments are provided.

Greater Than#

Checks if a value from the Higson context is greater than another value.

Function arguments:

  • ctx: The HigsonContext object.
  • args: The arguments passed to the method.

Example: $u gt(ctx, arg)

  • The first argument should be the path to the target object in the context.
  • The second argument should be the value to compare with the target object.

The method supports comparing various types, including:

  • Strings: Compares lexicographically.
  • Numbers: Compares numerically.
  • Dates (java.util.Date, LocalDate, LocalDateTime): Compares chronologically.

Return: True if the target object is greater than the given value, otherwise false.

Is Blank#

Checks if a value from the Higson context is blank.

This method considers an object blank if it meets one of the following conditions:

  • It is null
  • It is the string “undefined”
  • It is an instance of ParamValue and its isBlank method returns true
  • It is an instance of MultiValue and its isBlank method returns true
  • It is an instance of ValueHolder and its isBlank method returns true
  • It is an instance of Collection and it is empty or all its elements are blank
  • It is an array and all its elements are blank
  • It is an instance of Map and all its values are blank
  • It is a CharSequence (like String, StringBuffer, etc.) and is blank, that is when text has no characters or there is no other character than whitespace.
  • It is an instance of Iterable and it is empty or all its elements are blank

Function arguments:

  • ctx: The HigsonContext object.

Example: $u isBlank(ctx.path)

Return: True if the object is blank, false otherwise.

Is Empty#

Checks if a value from the Higson context is empty.

Function arguments:

  • ctx: The HigsonContext object.

Example: $u isEmpty(ctx)

Return: It retrieves the value from the context using the given path and returns:

  • false: if value is not string, collection, map, array, ParamValue
  • false: if value is not empty string
  • false: if value is collection or map, array but it is not empty
  • true: if value is empty string or is null
  • true: if value is collection, map or array but it is empty
  • true: if value is null
  • true: if value is ParamValue but it is empty, meaning does not contains any value inside of it

Less Than Equals#

Checks if a value from the Higson context is less than or equal to another value.

Function arguments:

  • ctx: The HigsonContext object.
  • args: The arguments passed to the method.

Example: $u lte(ctx, arg)

  • The first argument should be the path to the target object in the context.
  • The second argument should be the value to compare with the target object.

The method supports comparing various types, including:

  • Strings: Compares lexicographically.
  • Numbers: Compares numerically.
  • Dates (java.util.Date, LocalDate, LocalDateTime): Compares chronologically.

Return: True if the target object is less than or equal to the given value, otherwise false.

Throws: HigsonRuntimeException if fewer than two arguments are provided.

Less Than#

Checks if a value from the Higson context is less than another value.

Function arguments:

  • ctx: The HigsonContext object.
  • args: The arguments passed to the method.

Example: $u lt(ctx, arg)

  • The first argument should be the path to the target object in the context.
  • The second argument should be the value to compare with the target object.

The method supports comparing various types, including:

  • Strings: Compares lexicographically.
  • Numbers: Compares numerically.
  • Dates (java.util.Date, LocalDate, LocalDateTime): Compares chronologically.

Return: True if the target object is less than the given value, otherwise false.

Throws: HigsonRuntimeException if fewer than two arguments are provided.

Not Blank#

Checks if a value from the Higson context is not blank.

Function arguments:

  • ctx: The HigsonContext object.

Example: $u notBlank(ctx)

Return: It retrieves the value from the context using the given path and returns:

  • false: if value is null
  • false: if value is not string, collection or map , array, ParamValue
  • false: if value is string, collection or map , array, ParamValue but it is blank
  • true: if value is blank string
  • true: if value is collection or map but it is empty

Size#

Retrieves the length of a string attribute from context.

Function arguments:

  • ctx: The HigsonContext object.

Example: $u size(ctx)

Return: The length of the string or collection, or null if the object is null or of an unsupported type.

Throws: HigsonRuntimeException If the object is of unsupported type.

To#

Calls the ’to’ util function with the given context and arguments.

  • if object is String then function will return part of string to indexed passed in the second argument
  • if object is collection then function will return part of list to indexed passed in the second argument
  • in other cases function will throw exception with unsupported type
  • if object is a null then returned value is a null

Function arguments:

  • ctx: The HigsonContext object.
  • args: The arguments passed to the method.

Example: $u to(ctx, arg) $u to(abcdef, 5) → abcde Return: Part of the string or collection up to the indexed position passed in the second argument or null if the target is null or of an unsupported type.

Throws: HigsonRuntimeException if a required argument is missing, or if the target is of an unsupported type.

Trim#

Trims values in a given context, removing leading and trailing whitespaces.

Function arguments:

  • ctx: The HigsonContext object.

Example: $u trim(ctx)

  • If the value is null, returns null.
  • If the value is a Number, returns its decimal representation.
  • If the value is a Boolean, returns its boolean representation If the value is a Number, returns its decimal representation.
  • If the value is a Date, returns its Date representation.
  • If the value is a LocalDate, returns its LocalDate representation.
  • If the value is a LocalDateTime, returns its LocalDateTime representation.
  • If the value is a collection, filters out null values and returns the filtered array.
  • If the value is a CharSequence, trims it and returns the trimmed String.

Return: The trimmed value, or the original value if no trimming is possible.

Not Empty#

Checks if a given object is not empty.

Function arguments:

  • ctx: The HigsonContext object.

Example: $u notEmpty(ctx)

Return: True if the context object is not empty, false if it is empty.

Get#

Retrieves a value from the Higson context.

Function arguments:

  • ctx: The HigsonContext object.

Example: $u get(ctx, arg)

Return: The value from the context using the provided path.