Extending the Expression Language with Custom Functions
This page contains information about extending the Expression Language to create custom functions for the Computed Fields in Codebeamer.
 |
The code snippets provided are intended as a hint and a starting point for your development.
Custom functions can have a significant performance impact when they execute database queries or call remote services.
PTC recommends testing carefully any custom implementations in a non-production environment with realistic data first.
|
You can extend the expression language by using TrackerItemFilterEL.registerFunction(String name, Method function) to register the functions.
When developing the custom functions, you must adhere to specific development principles to ensure reliability:
Custom functions must be:
• Deterministic—They should always produce the same output for the same input.
• Idempotent—They should not cause side effects when called multiple times.
• Stateless—They should not maintain any state between calls.
• Thread-safe—They should be safe to use in a multi-threaded environment.
Additionally, custom functions must not:
• Modify objects passed in as parameters.
• Modify objects in the ELContext.
You can find an example of implementation in the following section.
Implementing Custom Functions
package com.intland.codebeamer.my;
import java.util.ArrayList;
import java.util.List;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.springframework.stereotype.Component;
import com.intland.codebeamer.persistence.dto.base.ReleaseId;
@Component("my.ExpressionLanguageExtension")
public class ExpressionLanguageExtension {
public static final Logger logger = LogManager.getLogger(ExpressionLanguageExtension.class);
// Register a new custom expression function, to increment versions
static {
try {
TrackerItemFilterEL.registerFunction("incrementVersion",
ExpressionLanguageExtension.class.getMethod("incrementVersion", String.class, boolean.class));
} catch (Exception ex) {
logger.warn("Could not register TrackerItemFilterEL function \"incrementVersion\"", ex);
}
}
/**
* Increment the major or minor number of the specified {@link ReleaseId} string by 1
*
* @param version is the {@link ReleaseId} to increment
* @param minor whether to increase the major (false) or minor(true) version number
* @return the new version string
*/
public static String incrementVersion(String version, boolean minor) {
List<Integer> numbers = ReleaseId.parse(version);
if (numbers != null && numbers.size() == 2) {
numbers = new ArrayList<>(numbers);
if (minor) {
numbers.set(1, numbers.get(1).intValue() + 1);
} else {
numbers.set(0, numbers.get(0).intValue() + 1);
numbers.set(1, 0);
}
} else {
numbers = List.of(1, 0);
}
return new ReleaseId(numbers).toString();
}
}
import java.util.ArrayList;
import java.util.List;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.springframework.stereotype.Component;
import com.intland.codebeamer.persistence.dto.base.ReleaseId;
@Component("my.ExpressionLanguageExtension")
public class ExpressionLanguageExtension {
public static final Logger logger = LogManager.getLogger(ExpressionLanguageExtension.class);
// Register a new custom expression function, to increment versions
static {
try {
TrackerItemFilterEL.registerFunction("incrementVersion",
ExpressionLanguageExtension.class.getMethod("incrementVersion", String.class, boolean.class));
} catch (Exception ex) {
logger.warn("Could not register TrackerItemFilterEL function \"incrementVersion\"", ex);
}
}
/**
* Increment the major or minor number of the specified {@link ReleaseId} string by 1
*
* @param version is the {@link ReleaseId} to increment
* @param minor whether to increase the major (false) or minor(true) version number
* @return the new version string
*/
public static String incrementVersion(String version, boolean minor) {
List<Integer> numbers = ReleaseId.parse(version);
if (numbers != null && numbers.size() == 2) {
numbers = new ArrayList<>(numbers);
if (minor) {
numbers.set(1, numbers.get(1).intValue() + 1);
} else {
numbers.set(0, numbers.get(0).intValue() + 1);
numbers.set(1, 0);
}
} else {
numbers = List.of(1, 0);
}
return new ReleaseId(numbers).toString();
}
}
You can use the preceding implementation for the computed fields expressions, as in the following examples:
incrementVersion("2.2", true) // Yields "2.3"
incrementVersion("2.2", false) // Yields "3.0"
incrementVersion("2.2", false) // Yields "3.0"
Limitations
You cannot override the default Codebeamer functions using a custom function. For the list of the default Codebeamer functions, refer to Functions.