Module jakarta.data

Package jakarta.data.expression

Interface Expression<T,V>

Type Parameters:

T - entity type.

V - expression type.

All Known Subinterfaces:

BasicAttribute<T,V>, BooleanAttribute<T>, BooleanExpression<T>, BooleanLiteral, BooleanPath<T,U>, ComparableAttribute<T,V>, ComparableExpression<T,V>, ComparableLiteral<V>, ComparablePath<T,U,C>, CurrentDate<T>, CurrentDateTime<T>, CurrentTime<T>, FunctionExpression<T,V>, Literal<V>, NumericAttribute<T,N>, NumericCast<T,N>, NumericExpression<T,N>, NumericFunctionExpression<T,N>, NumericLiteral<N>, NumericOperatorExpression<T,N>, NumericPath<T,U,N>, StringLiteral, TemporalAttribute<T,V>, TemporalExpression<T,V>, TemporalLiteral<V>, TemporalPath<T,U,V>, TextAttribute<T>, TextExpression<T>, TextFunctionExpression<T>, TextPath<T,U>

All Known Implementing Classes:

TextAttributeRecord

public interface Expression<T,V>

An expression represents an entity attribute, function, or literal value.

Expressions are used to compose restrictions that allow applications to supply query criteria at runtime. For example,

 List<Car> affordableVehicles =
         cars.search(make,
                     model,
                     _Car.price.plus(fees).lessThan(25000));
 

The entity and static metamodel for the code examples within this class are shown in the Attribute Javadoc.

Expressions are immutable and do not change after they are created.

Attribute expressions

All subtypes of Attribute obtained from the static metamodel are expressions. For example,

 _Car.vin
 _Car.price
 

Function expressions

Function expressions can be obtained from attribute expressions. For example,

 _Car.price.minus(discount)
 _Car.model.upper()
 _Car.vin.length()
 

Function expressions can also be obtained from other function expressions. For example, the following expression represents the second through third digits of a Vehicle Id Number,

 _Car.vin.left(3).right(2)
 

Some function expressions are available via static methods. For example,

 CurrentDateTime.now()
 

Literal expressions

Literal expressions are used indirectly when literal values are supplied to methods that create other expressions and restrictions. For example, the value 1000 in

 _Car.price.minus(1000)
 

Since:

1.1

Method Summary

Modifier and Type	Method	Description
default Restriction<T>	equalTo(Expression<? super T,V> expression)	Obtains a Restriction that requires that this expression and the specified expression evaluate to values that are equal.
default Restriction<T>	equalTo(V value)	Obtains a Restriction that requires that this expression evaluate to a value that is equal to the specified value.
default Restriction<T>	in(Expression<? super T,V>... expressions)	Obtains a Restriction that requires that this expression and at least one of the specified expressions evaluate to values that are equal.
default Restriction<T>	in(Collection<V> values)	Obtains a Restriction that requires that this expression evaluate to a value that is equal to one of the values within the specified collection.
default Restriction<T>	in(V... values)	Obtains a Restriction that requires that this expression evaluate to a value that is equal to one of the specified values.
default Restriction<T>	isNull()	Obtains a Restriction that requires that this expression evaluate to a null value.
default Restriction<T>	notEqualTo(Expression<? super T,V> expression)	Obtains a Restriction that requires that this expression and the specified expression evaluate to values that are not equal to each other.
default Restriction<T>	notEqualTo(V value)	Obtains a Restriction that requires that this expression evaluate to a value that is not equal to the specified value.
default Restriction<T>	notIn(Expression<? super T,V>... expressions)	Obtains a Restriction that requires that this expression evaluate to a value that is not equal to any of the values to which the specified expressions evaluate.
default Restriction<T>	notIn(Collection<V> values)	Obtains a Restriction that requires that this expression evaluate to a value that is not equal to any of the values within the specified collection.
default Restriction<T>	notIn(V... values)	Obtains a Restriction that requires that this expression evaluate to a value that is not equal to any of the specified values.
default Restriction<T>	notNull()	Obtains a Restriction that requires that this expression does not evaluate to a null value.
default Restriction<T>	satisfies(Constraint<V> constraint)	Obtains a Restriction that requires that this expression evaluate to a value that satisfies the specified Constraint.
Class<? extends V>	type()	The type of the expression.

Method Details

type

Class<? extends V> type()

The type of the expression.

equalTo

default Restriction<T> equalTo(V value)

Obtains a Restriction that requires that this expression evaluate to a value that is equal to the specified value.

Example:

     newCars = cars.search(make, model, _Car.year.equalTo(Year.now().getValue()));
 

Parameters:

value - value against which to compare. Must not be null.

Returns:

the restriction.

Throws:

NullPointerException - if the value is null.

equalTo

default Restriction<T> equalTo(Expression<? super T,V> expression)

Obtains a Restriction that requires that this expression and the specified expression evaluate to values that are equal.

Example:

     listedToday = cars.search(make, model, _Car.listed.equalTo(CurrentDate.now()));
 

Parameters:

expression - expression against which to compare. Must not be null.

Returns:

the restriction.

Throws:

NullPointerException - if the expression is null.

in

default Restriction<T> in(Collection<V> values)

Obtains a Restriction that requires that this expression evaluate to a value that is equal to one of the values within the specified collection.

Example:

     found = cars.search(make,
                         model,
                         _Car.year.in(Set.of(2022, 2024)));
 

Parameters:

values - values against which to compare. Must not be null, empty, or contain a null element.

Returns:

the restriction.

Throws:

IllegalArgumentException - if the values collection is empty.

NullPointerException - if the values collection is null or contains a null element.

in

default Restriction<T> in(V... values)

Obtains a Restriction that requires that this expression evaluate to a value that is equal to one of the specified values.

Example:

     found = cars.search(make,
                         model,
                         _Car.color.in(Color.BLACK, Color.BLUE, Color.GRAY));
 

Parameters:

values - values against which to compare. Must not be null, empty, or contain a null element.

Returns:

the restriction.

Throws:

IllegalArgumentException - if the values array is empty.

NullPointerException - if the values array is null or contains a null element.

in

default Restriction<T> in(Expression<? super T,V>... expressions)

Obtains a Restriction that requires that this expression and at least one of the specified expressions evaluate to values that are equal.

Example:

     found = cars.search(make,
                         model,
                         _Car.firstModelYear.in(_Car.year.minus(3),
                                                _Car.year.minus(4),
                                                _Car.year.minus(5)));
 

Parameters:

expressions - expressions against which to compare. Must not be null, empty, or contain a null element.

Returns:

the restriction.

Throws:

IllegalArgumentException - if the expressions array is empty.

NullPointerException - if the expressions array is null or contains a null element.

isNull

default Restriction<T> isNull()

Obtains a Restriction that requires that this expression evaluate to a null value.

Example:

     notListedYet = cars.search(make, model, _Car.listed.isNull());
 

Returns:

the restriction.

notEqualTo

default Restriction<T> notEqualTo(V value)

Obtains a Restriction that requires that this expression evaluate to a value that is not equal to the specified value.

Example:

     found = cars.search(make, model, _Car.color.notEqualTo(Color.RED));
 

Parameters:

value - value against which to compare. Must not be null.

Returns:

the restriction.

Throws:

NullPointerException - if the value is null.

notEqualTo

default Restriction<T> notEqualTo(Expression<? super T,V> expression)

Obtains a Restriction that requires that this expression and the specified expression evaluate to values that are not equal to each other.

Example:

     found = cars.search(make, model, _Car.listed.notEqualTo(CurrentDate.now()));
 

Parameters:

expression - expression against which to compare. Must not be null.

Returns:

the restriction.

Throws:

NullPointerException - if the expression is null.

notIn

default Restriction<T> notIn(Collection<V> values)

Obtains a Restriction that requires that this expression evaluate to a value that is not equal to any of the values within the specified collection.

Example:

     found = cars.search(make,
                         model,
                         _Car.color.notIn(Set.of(Color.GRAY, Color.WHITE)));
 

Parameters:

values - values against which to compare. Must not be null, empty, or contain a null element.

Returns:

the restriction.

Throws:

IllegalArgumentException - if the values collection is empty.

NullPointerException - if the values collection is null or contains a null element.

notIn

default Restriction<T> notIn(V... values)

Obtains a Restriction that requires that this expression evaluate to a value that is not equal to any of the specified values.

Example:

     found = cars.search(make,
                         model,
                         _Car.year.notIn(2019, 2020, 2023));
 

Parameters:

values - values against which to compare. Must not be null, empty, or contain a null element.

Returns:

the restriction.

Throws:

IllegalArgumentException - if the values array is empty.

NullPointerException - if the values array is null or contains a null element.

notIn

default Restriction<T> notIn(Expression<? super T,V>... expressions)

Obtains a Restriction that requires that this expression evaluate to a value that is not equal to any of the values to which the specified expressions evaluate.

Example:

     found = cars.search(make,
                         model,
                         _Car.year.notIn(_Car.firstModelYear,
                                         _Car.firstModelYear.plus(1)));
 

Parameters:

expressions - expressions against which to compare. Must not be null, empty, or contain a null element.

Returns:

the restriction.

Throws:

IllegalArgumentException - if the expressions array is empty.

NullPointerException - if the expressions array is null or contains a null element.

notNull

default Restriction<T> notNull()

Obtains a Restriction that requires that this expression does not evaluate to a null value.

Example:

     found = cars.search(make, model, _Car.listed.notNull());
 

Returns:

the restriction.

satisfies

default Restriction<T> satisfies(Constraint<V> constraint)

Obtains a Restriction that requires that this expression evaluate to a value that satisfies the specified Constraint.

Example:

     found = cars.search(make,
                         model,
                         _Car.year.satisfies(Constraint.between(2021, 2024)));
 

Parameters:

constraint - constraint to use for comparing the value to which this expression evaluates. Must not be null.

Returns:

the restriction.

Throws:

NullPointerException - if the constraint is null.