From 8be937e7cecfac982e2282aa12a89d1e74c43c37 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Thu, 15 Oct 2026 16:56:56 -0500 Subject: [PATCH 1/9] Add Javadoc for SPI packages --- .../jakarta/data/page/impl/package-info.java | 28 +++++++++++++++++ .../spi/expression/function/package-info.java | 30 +++++++++++++++++++ .../spi/expression/literal/package-info.java | 30 +++++++++++++++++++ .../spi/expression/path/package-info.java | 30 +++++++++++++++++++ .../java/jakarta/data/spi/package-info.java | 28 +++++++++++++++++ 5 files changed, 146 insertions(+) create mode 100644 api/src/main/java/jakarta/data/page/impl/package-info.java create mode 100644 api/src/main/java/jakarta/data/spi/expression/function/package-info.java create mode 100644 api/src/main/java/jakarta/data/spi/expression/literal/package-info.java create mode 100644 api/src/main/java/jakarta/data/spi/expression/path/package-info.java create mode 100644 api/src/main/java/jakarta/data/spi/package-info.java diff --git a/api/src/main/java/jakarta/data/page/impl/package-info.java b/api/src/main/java/jakarta/data/page/impl/package-info.java new file mode 100644 index 000000000..0da868035 --- /dev/null +++ b/api/src/main/java/jakarta/data/page/impl/package-info.java @@ -0,0 +1,28 @@ +/* + * Copyright (c) 2026 Contributors to the Eclipse Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + *

SPI related to pagination. Jakarta Data providers can use the + * implementations of {@link jakarta.data.page.Page} and + * {@link jakarta.data.page.CursoredPage} found in this package. + * Applications must not use this package directly. + * + *

The module Javadoc provides an {@linkplain jakarta.data/ overview} of + * Jakarta Data. + */ +package jakarta.data.page.impl; diff --git a/api/src/main/java/jakarta/data/spi/expression/function/package-info.java b/api/src/main/java/jakarta/data/spi/expression/function/package-info.java new file mode 100644 index 000000000..6d8b62345 --- /dev/null +++ b/api/src/main/java/jakarta/data/spi/expression/function/package-info.java @@ -0,0 +1,30 @@ +/* + * Copyright (c) 2026 Contributors to the Eclipse Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * SPI for function expressions. Jakarta Data providers can use the + * interfaces within this package to identify the type of function + * expression and the arguments supplied to it. Applications must not + * use this package directly. + * + *

The module Javadoc provides an {@linkplain jakarta.data/ overview} of + * Jakarta Data. + * + * @since 1.1 + */ +package jakarta.data.spi.expression.function; diff --git a/api/src/main/java/jakarta/data/spi/expression/literal/package-info.java b/api/src/main/java/jakarta/data/spi/expression/literal/package-info.java new file mode 100644 index 000000000..95c20cfc8 --- /dev/null +++ b/api/src/main/java/jakarta/data/spi/expression/literal/package-info.java @@ -0,0 +1,30 @@ +/* + * Copyright (c) 2026 Contributors to the Eclipse Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * SPI for literal expressions. Jakarta Data providers can use the + * interfaces within this package to identify the type of literal + * expression and its value. Applications must not use this package + * directly. + * + *

The module Javadoc provides an {@linkplain jakarta.data/ overview} of + * Jakarta Data. + * + * @since 1.1 + */ +package jakarta.data.spi.expression.literal; diff --git a/api/src/main/java/jakarta/data/spi/expression/path/package-info.java b/api/src/main/java/jakarta/data/spi/expression/path/package-info.java new file mode 100644 index 000000000..58b6051fd --- /dev/null +++ b/api/src/main/java/jakarta/data/spi/expression/path/package-info.java @@ -0,0 +1,30 @@ +/* + * Copyright (c) 2026 Contributors to the Eclipse Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * SPI for navigable expressions. Jakarta Data providers can use the + * interfaces within this package to identify the type of navigable + * expression and the attribute to which its path navigates. + * Applications must not use this package directly. + * + *

The module Javadoc provides an {@linkplain jakarta.data/ overview} of + * Jakarta Data. + * + * @since 1.1 + */ +package jakarta.data.spi.expression.path; diff --git a/api/src/main/java/jakarta/data/spi/package-info.java b/api/src/main/java/jakarta/data/spi/package-info.java new file mode 100644 index 000000000..af4347e9e --- /dev/null +++ b/api/src/main/java/jakarta/data/spi/package-info.java @@ -0,0 +1,28 @@ +/* + * Copyright (c) 2026 Contributors to the Eclipse Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * SPI for Jakarta Data providers. Applications must not use this package + * directly. + * + *

The module Javadoc provides an {@linkplain jakarta.data/ overview} of + * Jakarta Data. + * + * @since 1.1 + */ +package jakarta.data.spi; From 6d06deb41136b97049e01df2516bab353cebaaf9 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Thu, 15 Oct 2026 16:57:56 -0500 Subject: [PATCH 2/9] package-info Javadoc for deprecated and internal packages --- .../jakarta/data/messages/package-info.java | 28 +++++++++++++++++++ .../data/metamodel/impl/package-info.java | 10 ++++++- 2 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 api/src/main/java/jakarta/data/messages/package-info.java diff --git a/api/src/main/java/jakarta/data/messages/package-info.java b/api/src/main/java/jakarta/data/messages/package-info.java new file mode 100644 index 000000000..ed06575c6 --- /dev/null +++ b/api/src/main/java/jakarta/data/messages/package-info.java @@ -0,0 +1,28 @@ +/* + * Copyright (c) 2026 Contributors to the Eclipse Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + *

Internal package for messages. Do not use this package within + * applications. It is not exported by the data module. + * + *

The module Javadoc provides an {@linkplain jakarta.data/ overview} of + * Jakarta Data. + * + * @since 1.1 + */ +package jakarta.data.messages; diff --git a/api/src/main/java/jakarta/data/metamodel/impl/package-info.java b/api/src/main/java/jakarta/data/metamodel/impl/package-info.java index 2e8b65cac..cfcfbbc59 100644 --- a/api/src/main/java/jakarta/data/metamodel/impl/package-info.java +++ b/api/src/main/java/jakarta/data/metamodel/impl/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2025 Contributors to the Eclipse Foundation + * Copyright (c) 2025,2026 Contributors to the Eclipse Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,5 +16,13 @@ * SPDX-License-Identifier: Apache-2.0 */ +/** + * Deprecated - do not use. For more complete access to the static metamodel, + * use the most specific subtype of {@link jakarta.data.metamodel.Attribute} + * that applies to the entity attribute, such as + * {@link jakarta.data.metamodel.TextAttribute#of(Class, String) TextAttribute} + * or {@link jakarta.data.metamodel.NumericAttribute#of(Class, String, Class) + * NumericAttribute}. + */ @Deprecated(since = "1.1") package jakarta.data.metamodel.impl; From 4e53856242a19a7f0b5e41b67035a1924a7452ed Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Thu, 15 Oct 2026 17:00:49 -0500 Subject: [PATCH 3/9] Add more links to Javadoc --- api/src/main/java/jakarta/data/Direction.java | 5 +- api/src/main/java/jakarta/data/Limit.java | 5 +- .../jakarta/data/constraint/Constraint.java | 27 +++++++---- .../jakarta/data/constraint/package-info.java | 8 ++-- .../jakarta/data/event/LifecycleEvent.java | 5 +- .../java/jakarta/data/event/package-info.java | 48 +++++++++++++++++++ .../jakarta/data/exceptions/package-info.java | 5 +- .../jakarta/data/expression/package-info.java | 40 ++++++++++++++++ .../data/metamodel/StaticMetamodel.java | 6 +++ .../jakarta/data/metamodel/package-info.java | 6 +-- .../main/java/jakarta/data/package-info.java | 6 +-- 11 files changed, 135 insertions(+), 26 deletions(-) create mode 100644 api/src/main/java/jakarta/data/event/package-info.java create mode 100644 api/src/main/java/jakarta/data/expression/package-info.java diff --git a/api/src/main/java/jakarta/data/Direction.java b/api/src/main/java/jakarta/data/Direction.java index 956fec6d6..792785c92 100644 --- a/api/src/main/java/jakarta/data/Direction.java +++ b/api/src/main/java/jakarta/data/Direction.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2022,2023 Contributors to the Eclipse Foundation + * Copyright (c) 2022,2026 Contributors to the Eclipse Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -19,7 +19,8 @@ package jakarta.data; /** - * Represents the direction of the ordering. + * Represents the {@linkplain Sort#of(String, Direction, boolean) direction} + * of the ordering. */ public enum Direction { /** diff --git a/api/src/main/java/jakarta/data/Limit.java b/api/src/main/java/jakarta/data/Limit.java index 160197678..4b803c3da 100644 --- a/api/src/main/java/jakarta/data/Limit.java +++ b/api/src/main/java/jakarta/data/Limit.java @@ -24,9 +24,8 @@ import jakarta.data.repository.Query; /** - *

Specifies a limit on the number of results retrieved by a repository - * method. The results of a single invocation of a repository method may be - * limited to + *

Limits the number of results retrieved by a repository method. + * The results of a repository method invocation can be limited to *