Skip to content

add nullability annotations #1494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gavinking wants to merge 2 commits into
base: main
Choose a base branch
from
Open

add nullability annotations #1494

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
908b0b4
add nullability annotations
gavinking Jun 19, 2026
b1955a3
fix up javadoc links to Persistence
gavinking Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion api/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,9 @@ Copyright &#169; 2024 Eclipse Foundation. All rights reserved.<br>
Use is subject to <a href="{@docRoot}/doc-files/speclicense.html" target="_top">license terms</a>.]]>
</bottom>
<docfilessubdirs>true</docfilessubdirs>
<links>
<link>https://jakarta.ee/specifications/persistence/4.0/apidocs/</link>
</links>
<groups>
<group>
<title>Jakarta Data API Documentation</title>
Expand Down Expand Up @@ -239,6 +242,9 @@ Use is subject to <a href="{@docRoot}/doc-files/speclicense.html" target="_top">
<goal>jar</goal>
</goals>
<configuration>
<links>
<link>https://jakarta.ee/specifications/persistence/4.0/apidocs/</link>
</links>
<tags>
<tag>
<name>apiNote</name>
Expand All @@ -255,4 +261,4 @@ Use is subject to <a href="{@docRoot}/doc-files/speclicense.html" target="_top">
</profile>
</profiles>

</project>
</project>
3 changes: 3 additions & 0 deletions api/src/main/java/jakarta/data/Limit.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
package jakarta.data;

import jakarta.data.page.PageRequest;
import jakarta.annotation.Nonnull;

/**
* <p>Specifies a limit on the number of results retrieved by a repository
Expand Down Expand Up @@ -122,6 +123,7 @@ public long startAt() {
* method that performs a find operation; will never be {@code null}.
* @throws IllegalArgumentException if maxResults is less than 1.
*/
@Nonnull
public static Limit of(int maxResults) {
return new Limit(maxResults, DEFAULT_START_AT);
}
Expand All @@ -144,6 +146,7 @@ public static Limit of(int maxResults) {
* {@code startAt} to {@code endAt} exceeds
* {@link Integer#MAX_VALUE}.
*/
@Nonnull
public static Limit range(long startAt, long endAt) {
if (endAt < startAt)
throw new IllegalArgumentException("startAt: " + startAt + ", endAt: " + endAt);
Expand Down
17 changes: 12 additions & 5 deletions api/src/main/java/jakarta/data/Order.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@

import jakarta.data.metamodel.StaticMetamodel;
import jakarta.data.repository.OrderBy;
import jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;

/**
* <p>Requests sorting on various entity attributes.</p>
Expand Down Expand Up @@ -83,7 +85,7 @@ public class Order<T> implements Iterable<Sort<? super T>> {
* @param sorts unmodifiable list of Sort instances, from highest precedence
* to lowest.
*/
private Order(List<Sort<? super T>> sorts) {
private Order(@Nonnull List<Sort<? super T>> sorts) {
this.sorts = sorts;
}

Expand All @@ -99,7 +101,8 @@ private Order(List<Sort<? super T>> sorts) {
* criteria. This method never returns {@code null}.
*/
@SafeVarargs
public static <T> Order<T> by(Sort<? super T>... sorts) {
@Nonnull
public static <T> Order<T> by(@Nonnull Sort<? super T>... sorts) {
return new Order<T>(List.of(sorts));
}

Expand All @@ -116,7 +119,8 @@ public static <T> Order<T> by(Sort<? super T>... sorts) {
* @return a new instance indicating the order of precedence for sort
* criteria. This method never returns {@code null}.
*/
public static <T> Order<T> by(List<? extends Sort<? super T>> sorts) {
@Nonnull
public static <T> Order<T> by(@Nonnull List<? extends Sort<? super T>> sorts) {
return new Order<T>(List.copyOf(sorts));
}

Expand All @@ -126,6 +130,7 @@ public static <T> Order<T> by(List<? extends Sort<? super T>> sorts) {
* @return the instances of {@link Sort}, from highest precedence to lowest
* precedence.
*/
@Nonnull
public List<Sort<? super T>> sorts() {
return sorts;
}
Expand All @@ -138,7 +143,7 @@ public List<Sort<? super T>> sorts() {
* same ordering of sort criteria as this instance.
*/
@Override
public boolean equals(Object other) {
public boolean equals(@Nullable Object other) {
return this == other
|| other instanceof Order s && sorts.equals(s.sorts);
}
Expand All @@ -160,6 +165,7 @@ public int hashCode() {
* @return iterator over the sort criteria.
*/
@Override
@Nonnull
public Iterator<Sort<? super T>> iterator() {
return sorts.iterator();
}
Expand All @@ -173,7 +179,8 @@ public Iterator<Sort<? super T>> iterator() {
* @return textual representation of this instance.
*/
@Override
@Nonnull
public String toString() {
return sorts.toString();
}
}
}
70 changes: 44 additions & 26 deletions api/src/main/java/jakarta/data/Sort.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
*/
package jakarta.data;

import jakarta.annotation.Nullable;
import jakarta.data.expression.ComparableExpression;
import jakarta.data.expression.TextExpression;
import jakarta.data.messages.Messages;
Expand All @@ -25,6 +26,7 @@
import jakarta.data.metamodel.StaticMetamodel;
import jakarta.data.metamodel.TextAttribute;
import jakarta.data.repository.OrderBy;
import jakarta.annotation.Nonnull;

/**
* <p>Requests sorting on a given entity attribute or expression.</p>
Expand Down Expand Up @@ -99,11 +101,11 @@
* {@link Nulls#FIRST FIRST}, {@link Nulls#LAST LAST}, or
* {@linkplain Nulls#UNSPECIFIED by the data store}.
*/
public record Sort<T>(ComparableExpression<T, ? extends Comparable<?>> expression,
String property,
public record Sort<T>(@Nullable ComparableExpression<T, ? extends Comparable<?>> expression,
@Nullable String property,
boolean isAscending,
boolean ignoreCase,
Nulls nullOrdering) {
@Nonnull Nulls nullOrdering) {

/**
* Indicates how {@code null} values are ordered.
Expand Down Expand Up @@ -202,7 +204,7 @@ public enum Nulls {
* @param ignoreCase whether or not to request case insensitive ordering
* from a database with case sensitive collation.
*/
public Sort(String property, boolean isAscending, boolean ignoreCase) {
public Sort(@Nonnull String property, boolean isAscending, boolean ignoreCase) {
this(null,
property,
isAscending,
Expand All @@ -213,25 +215,29 @@ public Sort(String property, boolean isAscending, boolean ignoreCase) {
// Override to provide method documentation:

/**
* An expression to order by. The presence of a sort expression is
* mutually exclusive with the presence of a
* {@linkplain #property() sort attribute name}.
* An expression to order by, or {@code null} if this {@code Sort}
* instance was constructed without an expression.
*
* @return The attribute name to order by, or {@code null} if this
* {@code Sort} instance pertains to a {@link #property()}
* {@code Sort} instance was constructed without an expression.
*/
@Nonnull
public ComparableExpression<T, ? extends Comparable<?>> expression() {
if ( expression == null ) {
throw new IllegalStateException(
Messages.get("013.no-expression"));
}
Comment on lines +226 to +229

@gavinking gavinking Jun 26, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👀

return expression;
}

/**
* Name of the entity attribute to order by The presence of a
* sort attribute name is mutually exclusive with the presence of a
* sort {@link #expression()}.
* Name of the entity attribute to order by.
*
* @return The attribute name to order by, or {@code null} if this
* {@code Sort} instance pertains to an {@link #expression()}
* {@code Sort} instance pertains to an {@linkplain #expression}
* which is not an {@linkplain Attribute attribute}.
*/
@Nullable
public String property() {
return property;
}
Expand Down Expand Up @@ -281,6 +287,7 @@ public boolean isDescending() {
* @return indication of how {@code null} values are ordered.
* @since 1.1
*/
@Nonnull
public Nulls nullOrdering() {
return nullOrdering;
}
Expand All @@ -295,8 +302,9 @@ public Nulls nullOrdering() {
* @return a {@link Sort} instance. Never {@code null}.
* @throws NullPointerException when there is a null parameter.
*/
public static <T> Sort<T> of(String attribute,
Direction direction,
@Nonnull
public static <T> Sort<T> of(@Nonnull String attribute,
@Nonnull Direction direction,
boolean ignoreCase) {
if (direction == null) {
throw new NullPointerException(
Expand Down Expand Up @@ -325,10 +333,11 @@ public static <T> Sort<T> of(String attribute,
* @throws NullPointerException when there is a {@code null} parameter.
* @since 1.1
*/
public static <T> Sort<T> of(String attribute,
Direction direction,
@Nonnull
public static <T> Sort<T> of(@Nonnull String attribute,
@Nonnull Direction direction,
boolean ignoreCase,
Nulls nullOrdering) {
@Nonnull Nulls nullOrdering) {
if (direction == null) {
throw new NullPointerException(
Messages.get("001.arg.required", "direction"));
Expand Down Expand Up @@ -362,8 +371,9 @@ public static <T> Sort<T> of(String attribute,
* @throws NullPointerException if the {@code expression} is {@code null}
* @since 1.1
*/
@Nonnull
public static <T, V extends Comparable<?>> Sort<T> asc(
ComparableExpression<T, V> expression) {
@Nonnull ComparableExpression<T, V> expression) {
return new Sort<>(expression, null, true, false, Nulls.UNSPECIFIED);
}

Expand All @@ -377,7 +387,8 @@ public static <T, V extends Comparable<?>> Sort<T> asc(
* @return a {@link Sort} instance. Never {@code null}.
* @throws NullPointerException when the attribute name is null.
*/
public static <T> Sort<T> asc(String attribute) {
@Nonnull
public static <T> Sort<T> asc(@Nonnull String attribute) {
return new Sort<>(null, attribute, true, false, Nulls.UNSPECIFIED);
}

Expand All @@ -390,7 +401,8 @@ public static <T> Sort<T> asc(String attribute) {
* @return a {@link Sort} instance. Never {@code null}.
* @throws NullPointerException when the attribute name is null.
*/
public static <T> Sort<T> ascIgnoreCase(String attribute) {
@Nonnull
public static <T> Sort<T> ascIgnoreCase(@Nonnull String attribute) {
return new Sort<>(null, attribute, true, true, Nulls.UNSPECIFIED);
}

Expand All @@ -414,7 +426,8 @@ public static <T> Sort<T> ascIgnoreCase(String attribute) {
* @throws NullPointerException if the {@code expression} is {@code null}
* @since 1.1
*/
public static <T> Sort<T> ascIgnoreCase(TextExpression<T> expression) {
@Nonnull
public static <T> Sort<T> ascIgnoreCase(@Nonnull TextExpression<T> expression) {
return new Sort<>(expression, null, true, true, Nulls.UNSPECIFIED);
}

Expand All @@ -440,7 +453,7 @@ public static <T> Sort<T> ascIgnoreCase(TextExpression<T> expression) {
* @since 1.1
*/
public static <T, V extends Comparable<?>> Sort<T> desc(
ComparableExpression<T, V> expression) {
@Nonnull ComparableExpression<T, V> expression) {
return new Sort<>(expression, null, false, false, Nulls.UNSPECIFIED);
}

Expand All @@ -454,7 +467,8 @@ public static <T, V extends Comparable<?>> Sort<T> desc(
* @return a {@link Sort} instance. Never {@code null}.
* @throws NullPointerException when the attribute name is null.
*/
public static <T> Sort<T> desc(String attribute) {
@Nonnull
public static <T> Sort<T> desc(@Nonnull String attribute) {
return new Sort<>(null, attribute, false, false, Nulls.UNSPECIFIED);
}

Expand All @@ -468,7 +482,8 @@ public static <T> Sort<T> desc(String attribute) {
* @return a {@link Sort} instance. Never {@code null}.
* @throws NullPointerException when the attribute name is null.
*/
public static <T> Sort<T> descIgnoreCase(String attribute) {
@Nonnull
public static <T> Sort<T> descIgnoreCase(@Nonnull String attribute) {
return new Sort<>(null, attribute, false, true, Nulls.UNSPECIFIED);
}

Expand All @@ -492,7 +507,8 @@ public static <T> Sort<T> descIgnoreCase(String attribute) {
* @throws NullPointerException if the {@code expression} is {@code null}
* @since 1.1
*/
public static <T> Sort<T> descIgnoreCase(TextExpression<T> expression) {
@Nonnull
public static <T> Sort<T> descIgnoreCase(@Nonnull TextExpression<T> expression) {
return new Sort<>(expression, null, false, true, Nulls.UNSPECIFIED);
}

Expand All @@ -516,6 +532,7 @@ public static <T> Sort<T> descIgnoreCase(TextExpression<T> expression) {
* @return a sort with {@link #nullOrdering} set to {@link Nulls#FIRST}.
* @since 1.1
*/
@Nonnull
public Sort<T> nullsFirst() {
return new Sort<>(expression,
expression == null ? property : null,
Expand Down Expand Up @@ -544,11 +561,12 @@ public Sort<T> nullsFirst() {
* @return a sort with {@link #nullOrdering} set to {@link Nulls#LAST}.
* @since 1.1
*/
@Nonnull
public Sort<T> nullsLast() {
return new Sort<>(expression,
expression == null ? property : null,
isAscending,
ignoreCase,
Nulls.LAST);
}
}
}
8 changes: 6 additions & 2 deletions api/src/main/java/jakarta/data/constraint/AtLeast.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
import jakarta.data.repository.Is;
import jakarta.data.restrict.Restriction;
import jakarta.data.spi.expression.literal.ComparableLiteral;
import jakarta.annotation.Nonnull;

/**
* <p>A constraint that imposes a minimum value.</p>
Expand Down Expand Up @@ -86,8 +87,9 @@ public interface AtLeast<V extends Comparable<?>> extends Constraint<V> {
* @return an {@code AtLeast} constraint.
* @throws NullPointerException if the minimum is {@code null}.
*/
@Nonnull
static <V extends Comparable<?>> AtLeast<V> min(
V minimum) {
@Nonnull V minimum) {
return new AtLeastRecord<>(ComparableLiteral.of(minimum));
}

Expand All @@ -106,8 +108,9 @@ static <V extends Comparable<?>> AtLeast<V> min(
* @return an {@code AtLeast} constraint.
* @throws NullPointerException if the minimum is {@code null}.
*/
@Nonnull
static <V extends Comparable<?>> AtLeast<V> min(
ComparableExpression<?, V> minimum) {
@Nonnull ComparableExpression<?, V> minimum) {
return new AtLeastRecord<>(minimum);
}

Expand All @@ -117,5 +120,6 @@ static <V extends Comparable<?>> AtLeast<V> min(
*
* @return an expression representing the minimum value.
*/
@Nonnull
ComparableExpression<?, V> bound();
}
Loading