From b70209030b1b93c47786646d5da26173ffdb400e Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Wed, 4 Oct 2023 05:55:06 +0100 Subject: [PATCH 01/41] feat: create insert annotation Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Insert.java | 31 ++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 api/src/main/java/jakarta/data/Insert.java diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java new file mode 100644 index 000000000..752a98062 --- /dev/null +++ b/api/src/main/java/jakarta/data/Insert.java @@ -0,0 +1,31 @@ +/* + * Copyright (c) 2023 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 + */ +package jakarta.data; + + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Documented +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface Insert { +} From f4822ced1588f7417284e3b827ecaf4d0886e93b Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Wed, 4 Oct 2023 05:57:11 +0100 Subject: [PATCH 02/41] feat: create delete annotation Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Delete.java | 31 ++++++++++++++++++++++ api/src/main/java/jakarta/data/Update.java | 31 ++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 api/src/main/java/jakarta/data/Delete.java create mode 100644 api/src/main/java/jakarta/data/Update.java diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java new file mode 100644 index 000000000..d726d817d --- /dev/null +++ b/api/src/main/java/jakarta/data/Delete.java @@ -0,0 +1,31 @@ +/* + * Copyright (c) 2023 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 + */ +package jakarta.data; + + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Documented +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface Delete { +} diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java new file mode 100644 index 000000000..752a98062 --- /dev/null +++ b/api/src/main/java/jakarta/data/Update.java @@ -0,0 +1,31 @@ +/* + * Copyright (c) 2023 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 + */ +package jakarta.data; + + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Documented +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface Insert { +} From b6e83640ff6a48b571db46ff9a99334b5b713a98 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Wed, 4 Oct 2023 05:57:30 +0100 Subject: [PATCH 03/41] feat: create updaste annotation Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Update.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index 752a98062..a6ccef4c4 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -27,5 +27,5 @@ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) -public @interface Insert { +public @interface Update { } From 4b390089610a86dd6cc19939557400acedcd4aa9 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Wed, 4 Oct 2023 05:58:20 +0100 Subject: [PATCH 04/41] feat: create save annotation Signed-off-by: Otavio Santana --- .../java/jakarta/data/repository/Save.java | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 api/src/main/java/jakarta/data/repository/Save.java diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java new file mode 100644 index 000000000..549cbbe7e --- /dev/null +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -0,0 +1,31 @@ +/* + * Copyright (c) 2023 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 + */ +package jakarta.data.repository; + + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Documented +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface Save { +} From 601da7d7e1bae775aef64dc5c46a902f9c704926 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Wed, 4 Oct 2023 09:35:51 +0100 Subject: [PATCH 05/41] docs: create documentaion to those new annotations Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Delete.java | 22 ++++++++++ api/src/main/java/jakarta/data/Insert.java | 34 ++++++++++++++++ api/src/main/java/jakarta/data/Update.java | 37 +++++++++++++++++ .../java/jakarta/data/repository/Save.java | 40 +++++++++++++++++++ 4 files changed, 133 insertions(+) diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java index d726d817d..2922a44c4 100644 --- a/api/src/main/java/jakarta/data/Delete.java +++ b/api/src/main/java/jakarta/data/Delete.java @@ -24,6 +24,28 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + *

The {@code Delete} annotation indicates to dynamic templates or repositories that the annotated method + * will perform a delete operation. This method should have a unique parameter whose type can be one of the following: + *

+ *
    + *
  • The entity to be deleted.
    • + *
  • An {@code Iterable} of entities to be deleted.
    • + *
  • An array of entities to be deleted.
    • + *
+ *

The return type of the annotated method should be {@code void}, as the delete operation does not return a value. + *

+ *

Deletion of a given entity is performed by matching the entity's Id. If the entity is versioned (e.g., + * with {@code jakarta.persistence.Version}), the version is also checked for consistency during deletion. + * Properties other than the Id and version do not need to match for deletion. + *

+ * + * @throws OptimisticLockingFailureException if the entity is not found in the database for deletion + * or has a version for optimistic locking that is inconsistent with the version in the database. + * @throws NullPointerException when the entity is null. + * + * @see OptimisticLockingFailureException + */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index 752a98062..5fbab1497 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -24,6 +24,40 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + *

The {@code Insert} annotation indicates to dynamic templates or repositories that the annotated method + * will perform an insert operation. This method should have a unique parameter whose type can be one of the following: + *

+ *
    + *
  • The entity to be inserted.
    • + *
  • An {@code Iterable} of entities to be inserted.
    • + *
  • An array of entities to be inserted.
    • + *
+ *

The return type of the annotated method should match the type of the parameter. For example, if the method is + * annotated with {@code @Insert} and takes a parameter of type {@code Car car}, the return type should be {@code Car}. + * Similarly, if the parameter is an {@code Iterable} or an array of {@code Car}, the return type should be the + * corresponding type. + *

+ *

After invoking this method, it is recommended not to use the entity value supplied as a parameter, as this method + * makes no guarantees about the state of the entity value after insertion. + *

+ *

If the entity uses optimistic locking, and the version differs from the version in the database, an + * {@link OptimisticLockingFailureException} may be thrown. + *

+ *

For example, consider an interface representing a garage:

+ * 
+ * @Repository
+ * interface Garage {
+ *     {@literal @}Insert
+ *     Car parking(Car car);
+ * }
+ *
+ *

The {@code @Insert} annotation can be used to indicate that the {@code parkCar} method is responsible for inserting + * a car entity into a database. + *

+ * + * @see OptimisticLockingFailureException + */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index a6ccef4c4..9638b325f 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -24,6 +24,43 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; + +/** + *

The {@code Update} annotation indicates to dynamic templates or repositories that the annotated method + * will perform an update operation. This method should have a unique parameter whose type can be one of the following: + *

+ *
    + *
  • The entity to be updated.
    • + *
  • An {@code Iterable} of entities to be updated.
    • + *
  • An array of entities to be updated.
    • + *
+ *

The return type of the annotated method should be the same as the parameter type, ensuring consistency + * with the updated entity or entities. + *

+ *

Updating an entity involves modifying its existing data in the database. The method will search for the entity + * in the database using its ID or key, and then update the corresponding record with the new data. After invoking + * this method, do not continue to use the entity value that is supplied as a parameter, as it may not accurately + * reflect the changes made during the update process. + *

+ *

If the entity uses optimistic locking and its version differs from the version in the database, + * an {@link OptimisticLockingFailureException} will be thrown. + *

+ * + *

For example, consider an interface representing a garage:

+ * * 
+ *  * @Repository
+ *  * interface Garage {
+ *  *     {@literal @}Update
+ *  *     Car update(Car car);
+ *  * }
+ *  *
+ * @return The updated entity; never {@literal null}. + * @throws OptimisticLockingFailureException If the entity uses optimistic locking and the version in the + * database differs from the version in the entity. + * @throws NullPointerException If the provided entity is {@literal null}. + * + * @see OptimisticLockingFailureException + */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 549cbbe7e..4897daea1 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -24,6 +24,46 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + *

The {@code Save} annotation indicates to dynamic templates or repositories that the annotated method + * will perform a save operation. This method should have a unique parameter whose type can be one of the following: + *

+ *
    + *
  • The entity to be saved.
    • + *
  • An {@code Iterable} of entities to be saved.
    • + *
  • An array of entities to be saved.
    • + *
+ *

The return type of the annotated method should be the same as the parameter type, ensuring consistency + * with the saved entity or entities. + *

+ *

Saving an entity involves persisting it in the database. If the entity has an ID or key that already exists + * in the database, the method will update the existing record. If the entity does not exist in the database or has a + * null ID, this method will insert a new record. The entity instance returned by this method will be updated with + * any automatically generated or incremented values that changed due to the save operation. + *

+ *

After invoking this method, avoid using the entity value that was supplied as a parameter, as it may not accurately + * reflect the changes made during the save process. If the entity uses optimistic locking and its version differs from + * the version in the database, an {@link OptimisticLockingFailureException} will be thrown. + *

+ * + *

For example, consider an interface representing a garage:

+ * 
+ * @Repository
+ * interface Garage {
+ *     {@literal @}Save
+ *     Car parking(Car car);
+ * }
+ *
+ *

The {@code @Insert} annotation can be used to indicate that the {@code parkCar} method is responsible for inserting + * a car entity into a database. + *

+ * + * @throws OptimisticLockingFailureException If the entity uses optimistic locking and the version in the + * database differs from the version in the entity. + * @throws NullPointerException If the provided entity is {@literal null}. + * + * @see OptimisticLockingFailureException + */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) From 1b3bedab8bd9636435d5afc290aa8b55affa051f Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Wed, 4 Oct 2023 15:11:28 +0100 Subject: [PATCH 06/41] docs: update annotation documentationl Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Delete.java | 4 ++-- api/src/main/java/jakarta/data/Insert.java | 4 ++-- api/src/main/java/jakarta/data/Update.java | 6 +++--- api/src/main/java/jakarta/data/repository/Save.java | 6 +++--- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java index 2922a44c4..437ba2fc0 100644 --- a/api/src/main/java/jakarta/data/Delete.java +++ b/api/src/main/java/jakarta/data/Delete.java @@ -40,11 +40,11 @@ * Properties other than the Id and version do not need to match for deletion. *

* - * @throws OptimisticLockingFailureException if the entity is not found in the database for deletion + * @throws jakarta.data.exceptions.OptimisticLockingFailureException if the entity is not found in the database for deletion * or has a version for optimistic locking that is inconsistent with the version in the database. * @throws NullPointerException when the entity is null. * - * @see OptimisticLockingFailureException + * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index 5fbab1497..13cdf2d7e 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -42,7 +42,7 @@ * makes no guarantees about the state of the entity value after insertion. *

*

If the entity uses optimistic locking, and the version differs from the version in the database, an - * {@link OptimisticLockingFailureException} may be thrown. + * {@link jakarta.data.exceptions.OptimisticLockingFailureException} may be thrown. *

*

For example, consider an interface representing a garage:

* 
@@ -56,7 +56,7 @@
  * a car entity into a database.
  * 

  *
- * @see OptimisticLockingFailureException
+ * @see jakarta.data.exceptions.OptimisticLockingFailureException
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java
index 9638b325f..e791ff3fa 100644
--- a/api/src/main/java/jakarta/data/Update.java
+++ b/api/src/main/java/jakarta/data/Update.java
@@ -43,7 +43,7 @@
  * reflect the changes made during the update process.
  * 

  * 
If the entity uses optimistic locking and its version differs from the version in the database,
- * an {@link OptimisticLockingFailureException} will be thrown.
+ * an {@link jakarta.data.exceptions.OptimisticLockingFailureException} will be thrown.
  * 

  *
  * 
For example, consider an interface representing a garage:

@@ -55,11 +55,11 @@
  *  * }
  *  *
* @return The updated entity; never {@literal null}. - * @throws OptimisticLockingFailureException If the entity uses optimistic locking and the version in the + * @throws jakarta.data.exceptions.OptimisticLockingFailureException If the entity uses optimistic locking and the version in the * database differs from the version in the entity. * @throws NullPointerException If the provided entity is {@literal null}. * - * @see OptimisticLockingFailureException + * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 4897daea1..e2ed2a6a7 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -43,7 +43,7 @@ *

*

After invoking this method, avoid using the entity value that was supplied as a parameter, as it may not accurately * reflect the changes made during the save process. If the entity uses optimistic locking and its version differs from - * the version in the database, an {@link OptimisticLockingFailureException} will be thrown. + * the version in the database, an {@link jakarta.data.exceptions.OptimisticLockingFailureException} will be thrown. *

* *

For example, consider an interface representing a garage:

@@ -58,11 +58,11 @@ * a car entity into a database. *

* - * @throws OptimisticLockingFailureException If the entity uses optimistic locking and the version in the + * @throws jakarta.data.exceptions.OptimisticLockingFailureException If the entity uses optimistic locking and the version in the * database differs from the version in the entity. * @throws NullPointerException If the provided entity is {@literal null}. * - * @see OptimisticLockingFailureException + * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented @Retention(RetentionPolicy.RUNTIME) From 2ef630504054191e7a13d9274412da19be8154cf Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Wed, 4 Oct 2023 15:22:50 +0100 Subject: [PATCH 07/41] docs: remove unecessary information at javavdoc Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Delete.java | 3 --- api/src/main/java/jakarta/data/Update.java | 4 ---- api/src/main/java/jakarta/data/repository/Save.java | 4 ---- 3 files changed, 11 deletions(-) diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java index 437ba2fc0..58fb49656 100644 --- a/api/src/main/java/jakarta/data/Delete.java +++ b/api/src/main/java/jakarta/data/Delete.java @@ -40,9 +40,6 @@ * Properties other than the Id and version do not need to match for deletion. *

* - * @throws jakarta.data.exceptions.OptimisticLockingFailureException if the entity is not found in the database for deletion - * or has a version for optimistic locking that is inconsistent with the version in the database. - * @throws NullPointerException when the entity is null. * * @see jakarta.data.exceptions.OptimisticLockingFailureException */ diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index e791ff3fa..054f93cb9 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -54,10 +54,6 @@ * * Car update(Car car); * * } * * - * @return The updated entity; never {@literal null}. - * @throws jakarta.data.exceptions.OptimisticLockingFailureException If the entity uses optimistic locking and the version in the - * database differs from the version in the entity. - * @throws NullPointerException If the provided entity is {@literal null}. * * @see jakarta.data.exceptions.OptimisticLockingFailureException */ diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index e2ed2a6a7..4d9e26f9b 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -58,10 +58,6 @@ * a car entity into a database. *

* - * @throws jakarta.data.exceptions.OptimisticLockingFailureException If the entity uses optimistic locking and the version in the - * database differs from the version in the entity. - * @throws NullPointerException If the provided entity is {@literal null}. - * * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented From 2a172ab5bde2fb6117fea7052dbfb666d4a54393 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Thu, 5 Oct 2023 05:00:06 +0100 Subject: [PATCH 08/41] Update api/src/main/java/jakarta/data/Delete.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/Delete.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java index 58fb49656..a4ea2fdde 100644 --- a/api/src/main/java/jakarta/data/Delete.java +++ b/api/src/main/java/jakarta/data/Delete.java @@ -33,7 +33,7 @@ *
  • An {@code Iterable} of entities to be deleted.
    • *
  • An array of entities to be deleted.
    • * - *

    The return type of the annotated method should be {@code void}, as the delete operation does not return a value. + *

    The return type of the annotated method must be {@code void}, {@code boolean}, a numeric primitive type (such as {@code int}), or a corresponding primitive wrapper type (such as {@link Integer}). A boolean return type indicates whether or not an entity was deleted from the database. A numeric return type indicates how many entities were deleted from the database. *

    *

    Deletion of a given entity is performed by matching the entity's Id. If the entity is versioned (e.g., * with {@code jakarta.persistence.Version}), the version is also checked for consistency during deletion. From a21376f54e9fbd936170e931be1db5fc3825bae0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Thu, 5 Oct 2023 05:00:12 +0100 Subject: [PATCH 09/41] Update api/src/main/java/jakarta/data/Delete.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/Delete.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java index a4ea2fdde..7842b6b2d 100644 --- a/api/src/main/java/jakarta/data/Delete.java +++ b/api/src/main/java/jakarta/data/Delete.java @@ -41,7 +41,7 @@ *

    * * - * @see jakarta.data.exceptions.OptimisticLockingFailureException + *

    If the unique identifier of an entity is not found in the database or its version does not match, and the return type of the annotated method is {@code void} or {@code Void}, the method must raise {@link jakarta.data.exceptions.OptimisticLockingFailureException}. */ @Documented @Retention(RetentionPolicy.RUNTIME) From d7482106a65de948f1626b7699ac7e86be9e69ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Thu, 5 Oct 2023 05:00:17 +0100 Subject: [PATCH 10/41] Update api/src/main/java/jakarta/data/Insert.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/Insert.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index 13cdf2d7e..a7b09559f 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -25,8 +25,8 @@ import java.lang.annotation.Target; /** - *

    The {@code Insert} annotation indicates to dynamic templates or repositories that the annotated method - * will perform an insert operation. This method should have a unique parameter whose type can be one of the following: + *

    The {@code Insert} annotation indicates that the annotated repository method requests that one or more entities + * be inserted into the database. This method must have a single parameter whose type must be one of the following: *

    *
      *
    • The entity to be inserted.
      • From b4bd653abbb43f9a77debd4ef6aba8807a0a564c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Thu, 5 Oct 2023 05:00:23 +0100 Subject: [PATCH 11/41] Update api/src/main/java/jakarta/data/Update.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/Update.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index 054f93cb9..db8428a50 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -26,8 +26,8 @@ /** - *

      The {@code Update} annotation indicates to dynamic templates or repositories that the annotated method - * will perform an update operation. This method should have a unique parameter whose type can be one of the following: + *

      The {@code Update} annotation indicates that the annotated repository method requests that one or more entities + * be updated if found in the database. This method must have a single parameter whose type must be one of the following: *

      *
        *
      • The entity to be updated.
        • From dcfdb96e0624a4cf414999314e4213835b6a48a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Thu, 5 Oct 2023 05:00:28 +0100 Subject: [PATCH 12/41] Update api/src/main/java/jakarta/data/repository/Save.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/repository/Save.java | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 4d9e26f9b..90939cfe3 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -25,8 +25,10 @@ import java.lang.annotation.Target; /** - *

        The {@code Save} annotation indicates to dynamic templates or repositories that the annotated method - * will perform a save operation. This method should have a unique parameter whose type can be one of the following: + *

        The {@code Save} annotation indicates that the annotated repository method + * updates one or more entities if found in the database + * and inserts entities into the database that are not found. + * This method must have a single parameter whose type must be one of the following: *

        *
          *
        • The entity to be saved.
          • From c6c24a6d0418d20b51082ee4dec43e3cc20d7c90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Thu, 5 Oct 2023 05:00:43 +0100 Subject: [PATCH 13/41] Update api/src/main/java/jakarta/data/repository/Save.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/repository/Save.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 90939cfe3..b642420d0 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -35,7 +35,7 @@ *
        • An {@code Iterable} of entities to be saved.
          • *
        • An array of entities to be saved.
          • *
        - *

        The return type of the annotated method should be the same as the parameter type, ensuring consistency + *

        The return type of the annotated method must be the same as the parameter type, ensuring consistency * with the saved entity or entities. *

        *

        Saving an entity involves persisting it in the database. If the entity has an ID or key that already exists From 0043b196e130b37c0fa12c73668f978f09de14ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Thu, 5 Oct 2023 05:00:50 +0100 Subject: [PATCH 14/41] Update api/src/main/java/jakarta/data/repository/Save.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/repository/Save.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index b642420d0..31a8c74d4 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -53,10 +53,10 @@ * @Repository * interface Garage { * {@literal @}Save - * Car parking(Car car); + * Car park(Car car); * } * - *

        The {@code @Insert} annotation can be used to indicate that the {@code parkCar} method is responsible for inserting + *

        The {@code @Insert} annotation can be used to indicate that the {@code park(Car)} method is responsible for updating the entity in database if it already exists there and otherwise inserting * a car entity into a database. *

        * From b5dd41fb1a46831a6d86bf507a1942b443d0f3bb Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Thu, 5 Oct 2023 05:16:53 +0100 Subject: [PATCH 15/41] feat: update annotations with exception Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Delete.java | 3 ++- api/src/main/java/jakarta/data/Insert.java | 3 +++ api/src/main/java/jakarta/data/Update.java | 3 ++- api/src/main/java/jakarta/data/repository/Save.java | 1 + 4 files changed, 8 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java index 7842b6b2d..32a107629 100644 --- a/api/src/main/java/jakarta/data/Delete.java +++ b/api/src/main/java/jakarta/data/Delete.java @@ -40,7 +40,8 @@ * Properties other than the Id and version do not need to match for deletion. *

        * - * + * *

        If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Update}, + * * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

        *

        If the unique identifier of an entity is not found in the database or its version does not match, and the return type of the annotated method is {@code void} or {@code Void}, the method must raise {@link jakarta.data.exceptions.OptimisticLockingFailureException}. */ @Documented diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index a7b09559f..02e9b4bca 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -56,6 +56,9 @@ * a car entity into a database. *

        * + *

        If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete}, + * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

        + * * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index db8428a50..e96e7c17d 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -54,7 +54,8 @@ * * Car update(Car car); * * } * * - * + *

        If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Delete}, + * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

        * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 31a8c74d4..24be022ff 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -60,6 +60,7 @@ * a car entity into a database. *

        * + * * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented From b3dfaea30a3489c0fb46ffc2a5320f6bab077ea5 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Thu, 5 Oct 2023 05:20:14 +0100 Subject: [PATCH 16/41] style: update style avoiding extra line Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Delete.java | 9 +++++++-- api/src/main/java/jakarta/data/repository/Save.java | 3 ++- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java index 32a107629..2921db0a8 100644 --- a/api/src/main/java/jakarta/data/Delete.java +++ b/api/src/main/java/jakarta/data/Delete.java @@ -33,7 +33,10 @@ *
      • An {@code Iterable} of entities to be deleted.
        • *
      • An array of entities to be deleted.
        • *
      - *

      The return type of the annotated method must be {@code void}, {@code boolean}, a numeric primitive type (such as {@code int}), or a corresponding primitive wrapper type (such as {@link Integer}). A boolean return type indicates whether or not an entity was deleted from the database. A numeric return type indicates how many entities were deleted from the database. + *

      The return type of the annotated method must be {@code void}, {@code boolean}, a numeric primitive type + * (such as {@code int}), or a corresponding primitive wrapper type (such as {@link Integer}). + * A boolean return type indicates whether or not an entity was deleted from the database. + * A numeric return type indicates how many entities were deleted from the database. *

      *

      Deletion of a given entity is performed by matching the entity's Id. If the entity is versioned (e.g., * with {@code jakarta.persistence.Version}), the version is also checked for consistency during deletion. @@ -42,7 +45,9 @@ * * *

      If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Update}, * * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

      - *

      If the unique identifier of an entity is not found in the database or its version does not match, and the return type of the annotated method is {@code void} or {@code Void}, the method must raise {@link jakarta.data.exceptions.OptimisticLockingFailureException}. + *

      If the unique identifier of an entity is not found in the database or its version does not match, and the return + * type of the annotated method is {@code void} or {@code Void}, the method must + * raise {@link jakarta.data.exceptions.OptimisticLockingFailureException}. */ @Documented @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 24be022ff..1171ad863 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -56,7 +56,8 @@ * Car park(Car car); * } * - *

      The {@code @Insert} annotation can be used to indicate that the {@code park(Car)} method is responsible for updating the entity in database if it already exists there and otherwise inserting + *

      The {@code @Insert} annotation can be used to indicate that the {@code park(Car)} method is responsible + * for updating the entity in database if it already exists there and otherwise inserting * a car entity into a database. *

      * From e33218dc45b314d13469a0977dd9b38af08113bc Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Thu, 5 Oct 2023 05:37:27 +0100 Subject: [PATCH 17/41] docs: update documentation Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Delete.java | 9 ++++++++- api/src/main/java/jakarta/data/Insert.java | 2 +- api/src/main/java/jakarta/data/Update.java | 14 +++++++------- .../main/java/jakarta/data/repository/Save.java | 2 +- 4 files changed, 17 insertions(+), 10 deletions(-) diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java index 2921db0a8..3b1d04e87 100644 --- a/api/src/main/java/jakarta/data/Delete.java +++ b/api/src/main/java/jakarta/data/Delete.java @@ -42,7 +42,14 @@ * with {@code jakarta.persistence.Version}), the version is also checked for consistency during deletion. * Properties other than the Id and version do not need to match for deletion. *

      - * + *

      For example, consider an interface representing a garage:

      + * 
      + * {@literal @}Repository
+ * interface Garage {
+ *     {@literal @}Save
+ *     Car unpark(Car car);
+ * }
+ *
      * *

      If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Update}, * * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

      *

      If the unique identifier of an entity is not found in the database or its version does not match, and the return diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index 02e9b4bca..4138b7c78 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -46,7 +46,7 @@ *

      *

      For example, consider an interface representing a garage:

      * 
      - * @Repository
+ * {@literal @}Repository
  * interface Garage {
  *     {@literal @}Insert
  *     Car parking(Car car);
diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java
index e96e7c17d..e2d20c1b6 100644
--- a/api/src/main/java/jakarta/data/Update.java
+++ b/api/src/main/java/jakarta/data/Update.java
@@ -47,13 +47,13 @@
  * 
      
  *
  * 
      For example, consider an interface representing a garage:
      
- *  * 
      - *  * @Repository
- *  * interface Garage {
- *  *     {@literal @}Update
- *  *     Car update(Car car);
- *  * }
- *  * 
      
+ * 
      + * @Repository
+ * interface Garage {
+ *     {@literal @}Update
+ *     Car update(Car car);
+ * }
+ * 
      
  * 
      If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Delete},
  * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.
      
  * @see jakarta.data.exceptions.OptimisticLockingFailureException
diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java
index 1171ad863..c3f6b6f3b 100644
--- a/api/src/main/java/jakarta/data/repository/Save.java
+++ b/api/src/main/java/jakarta/data/repository/Save.java
@@ -50,7 +50,7 @@
  *
  * 
      For example, consider an interface representing a garage:
      
  * 
      - * @Repository
+ * {@literal @}Repository
  * interface Garage {
  *     {@literal @}Save
  *     Car park(Car car);

From 94bc06da665d13610d755087ad6a0f6c3efdfc3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= 
Date: Thu, 5 Oct 2023 15:11:06 +0100
Subject: [PATCH 18/41] Update api/src/main/java/jakarta/data/Delete.java

Co-authored-by: Nathan Rauh 
---
 api/src/main/java/jakarta/data/Delete.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java
index 3b1d04e87..7edf94db0 100644
--- a/api/src/main/java/jakarta/data/Delete.java
+++ b/api/src/main/java/jakarta/data/Delete.java
@@ -46,7 +46,7 @@
  * 
        * {@literal @}Repository
  * interface Garage {
- *     {@literal @}Save
+ *     {@literal @}Delete
  *     Car unpark(Car car);
  * }
  * 
      

From 7f99437f806ab2540351ba4c982116998e583ca6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= 
Date: Thu, 5 Oct 2023 15:11:19 +0100
Subject: [PATCH 19/41] Update
 api/src/main/java/jakarta/data/repository/Save.java

Co-authored-by: Nathan Rauh 
---
 api/src/main/java/jakarta/data/repository/Save.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java
index c3f6b6f3b..c4fb2f233 100644
--- a/api/src/main/java/jakarta/data/repository/Save.java
+++ b/api/src/main/java/jakarta/data/repository/Save.java
@@ -57,7 +57,7 @@
  * }
  * 
      
  * 
      The {@code @Insert} annotation can be used to indicate that the {@code park(Car)} method is responsible
- * for updating the entity in database if it already exists there and otherwise inserting
+ * for updating the entity in the database if it already exists there and otherwise inserting
  * a car entity into a database.
  * 
      
  *

From 725f4ae64cad9a8f28a989ca4131e67d49dd6fe2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= 
Date: Thu, 5 Oct 2023 15:11:35 +0100
Subject: [PATCH 20/41] Update api/src/main/java/jakarta/data/Delete.java

Co-authored-by: Nathan Rauh 
---
 api/src/main/java/jakarta/data/Delete.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java
index 7edf94db0..35178f979 100644
--- a/api/src/main/java/jakarta/data/Delete.java
+++ b/api/src/main/java/jakarta/data/Delete.java
@@ -25,8 +25,8 @@
 import java.lang.annotation.Target;
 
 /**
- * 
      The {@code Delete} annotation indicates to dynamic templates or repositories that the annotated method
- * will perform a delete operation. This method should have a unique parameter whose type can be one of the following:
+ * 
      The {@code Delete} annotation indicates that the annotated repository method requests one or more
+ * entities to be removed from the database. This method must have a single parameter whose type must be one of the following:
  * 
      
  * 
        
  *     
      • The entity to be deleted.
        • 

From dcd77f5d5ceee21f0ddcef378cf4568b3abd9de0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= 
Date: Thu, 5 Oct 2023 15:18:06 +0100
Subject: [PATCH 21/41] Update api/src/main/java/jakarta/data/Insert.java

Co-authored-by: Nathan Rauh 
---
 api/src/main/java/jakarta/data/Insert.java | 2 --
 1 file changed, 2 deletions(-)

diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java
index 4138b7c78..f288c4d47 100644
--- a/api/src/main/java/jakarta/data/Insert.java
+++ b/api/src/main/java/jakarta/data/Insert.java
@@ -58,8 +58,6 @@
  *
  * 
        If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete},
  *  {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.
        
- *
- * @see jakarta.data.exceptions.OptimisticLockingFailureException
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

From b6f9bf2b1abe07e310b499abf8113dd870062b31 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= 
Date: Thu, 5 Oct 2023 15:18:31 +0100
Subject: [PATCH 22/41] Update api/src/main/java/jakarta/data/Update.java

Co-authored-by: Nathan Rauh 
---
 api/src/main/java/jakarta/data/Update.java | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java
index e2d20c1b6..3c17ea94d 100644
--- a/api/src/main/java/jakarta/data/Update.java
+++ b/api/src/main/java/jakarta/data/Update.java
@@ -34,8 +34,7 @@
  *     
      • An {@code Iterable} of entities to be updated.
        • 
  *     
      • An array of entities to be updated.
        • 
  * 
      
- * 
      The return type of the annotated method should be the same as the parameter type, ensuring consistency
- * with the updated entity or entities.
+ * 
      The return type of the annotated method must be {@code void}, {@code boolean}, a numeric primitive type (such as {@code int}), or a corresponding primitive wrapper type (such as {@link Integer}). A boolean return type indicates whether a matching entity was found in the database to update. A numeric return type indicates how many matching entities were found in the database to update.
  * 
      
  * 
      Updating an entity involves modifying its existing data in the database. The method will search for the entity
  * in the database using its ID or key, and then update the corresponding record with the new data. After invoking

From 51c266cb645a7e4e59f3dc1c06797df080da46ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= 
Date: Thu, 5 Oct 2023 15:18:43 +0100
Subject: [PATCH 23/41] Update api/src/main/java/jakarta/data/Update.java

Co-authored-by: Nathan Rauh 
---
 api/src/main/java/jakarta/data/Update.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java
index 3c17ea94d..16a06cd33 100644
--- a/api/src/main/java/jakarta/data/Update.java
+++ b/api/src/main/java/jakarta/data/Update.java
@@ -37,7 +37,7 @@
  * 
      The return type of the annotated method must be {@code void}, {@code boolean}, a numeric primitive type (such as {@code int}), or a corresponding primitive wrapper type (such as {@link Integer}). A boolean return type indicates whether a matching entity was found in the database to update. A numeric return type indicates how many matching entities were found in the database to update.
  * 
      
  * 
      Updating an entity involves modifying its existing data in the database. The method will search for the entity
- * in the database using its ID or key, and then update the corresponding record with the new data. After invoking
+ * in the database using its ID (and version, if versioned) and then update the corresponding record with the new data. After invoking
  * this method, do not continue to use the entity value that is supplied as a parameter, as it may not accurately
  * reflect the changes made during the update process.
  * 
      

From 886fd529392ec99b9eeffa19c1225544a8d1ea40 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= 
Date: Sat, 7 Oct 2023 05:30:39 +0100
Subject: [PATCH 24/41] Update api/src/main/java/jakarta/data/Delete.java

Co-authored-by: Nathan Rauh 
---
 api/src/main/java/jakarta/data/Delete.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/Delete.java
index 35178f979..978cf57ef 100644
--- a/api/src/main/java/jakarta/data/Delete.java
+++ b/api/src/main/java/jakarta/data/Delete.java
@@ -51,7 +51,7 @@
  * }
  *
      * *

      If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Update}, - * * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

      + * * {@code @Save}), it will throw an {@link UnsupportedOperationException} as only one operation type can be specified.

      *

      If the unique identifier of an entity is not found in the database or its version does not match, and the return * type of the annotated method is {@code void} or {@code Void}, the method must * raise {@link jakarta.data.exceptions.OptimisticLockingFailureException}. From b7cf591372a1de66a312a7b896cdc1bfe2beba23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Sat, 7 Oct 2023 05:31:02 +0100 Subject: [PATCH 25/41] Update api/src/main/java/jakarta/data/Insert.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/Insert.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index f288c4d47..d81017ee0 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -57,7 +57,7 @@ *

      * *

      If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete}, - * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

      + * {@code @Save}), it will throw an {@link UnsupportedOperationException} as only one operation type can be specified.

      */ @Documented @Retention(RetentionPolicy.RUNTIME) From e0807270fded00c59c3b0f3dcee87b095709f172 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Sat, 7 Oct 2023 05:31:19 +0100 Subject: [PATCH 26/41] Update api/src/main/java/jakarta/data/Update.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/Update.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index 16a06cd33..c1bf4eb2a 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -54,7 +54,7 @@ * } * *

      If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Delete}, - * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

      + * {@code @Save}), it will throw an {@link UnsupportedOperationException} as only one operation type can be specified.

      * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented From ae297c7dd597ec42f431b81e1ae6cd0f45efa168 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Mon, 9 Oct 2023 13:34:13 +0100 Subject: [PATCH 27/41] style: create break line in update annotation Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Update.java | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index c1bf4eb2a..84153e436 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -34,7 +34,10 @@ *
    • An {@code Iterable} of entities to be updated.
      • *
    • An array of entities to be updated.
      • *
    - *

    The return type of the annotated method must be {@code void}, {@code boolean}, a numeric primitive type (such as {@code int}), or a corresponding primitive wrapper type (such as {@link Integer}). A boolean return type indicates whether a matching entity was found in the database to update. A numeric return type indicates how many matching entities were found in the database to update. + *

    The return type of the annotated method must be {@code void}, {@code boolean}, a numeric primitive type + * (such as {@code int}), or a corresponding primitive wrapper type (such as {@link Integer}). + * A boolean return type indicates whether a matching entity was found in the database to update. + * A numeric return type indicates how many matching entities were found in the database to update. *

    *

    Updating an entity involves modifying its existing data in the database. The method will search for the entity * in the database using its ID (and version, if versioned) and then update the corresponding record with the new data. After invoking From cf60d689ad68e150b7584dff6d244b39d1bc6795 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Mon, 9 Oct 2023 13:43:11 +0100 Subject: [PATCH 28/41] docs: update documentation about exception Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Insert.java | 2 +- api/src/main/java/jakarta/data/Update.java | 2 +- api/src/main/java/jakarta/data/repository/Save.java | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index d81017ee0..f288c4d47 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -57,7 +57,7 @@ *

    * *

    If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete}, - * {@code @Save}), it will throw an {@link UnsupportedOperationException} as only one operation type can be specified.

    + * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

    */ @Documented @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index 84153e436..918cda162 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -57,7 +57,7 @@ * } * *

    If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Delete}, - * {@code @Save}), it will throw an {@link UnsupportedOperationException} as only one operation type can be specified.

    + * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

    * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index c4fb2f233..18ed3a4f8 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -56,12 +56,13 @@ * Car park(Car car); * } * - *

    The {@code @Insert} annotation can be used to indicate that the {@code park(Car)} method is responsible + *

    The {@code @Update} annotation can be used to indicate that the {@code park(Car)} method is responsible * for updating the entity in the database if it already exists there and otherwise inserting * a car entity into a database. *

    * - * + *

    If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete}, + * {@code @Insert}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

    * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented From 24774b852ea94ff086530b146d7bbfc79e2c1c6f Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Mon, 9 Oct 2023 13:57:34 +0100 Subject: [PATCH 29/41] docs: update documentation to be valid also at build time Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/Insert.java | 3 ++- api/src/main/java/jakarta/data/Update.java | 3 ++- api/src/main/java/jakarta/data/repository/Save.java | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index f288c4d47..63376a040 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -57,7 +57,8 @@ *

    * *

    If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete}, - * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

    + * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified, where + * a Jakarta Data provider implementation choose to detect (and report) this error at compile time or at runtime..

    */ @Documented @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index 918cda162..01a2ecd10 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -57,7 +57,8 @@ * } * *

    If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Delete}, - * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

    + * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified, where + * a Jakarta Data provider implementation choose to detect (and report) this error at compile time or at runtime.

    * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 18ed3a4f8..d317293f4 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -62,7 +62,8 @@ *

    * *

    If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete}, - * {@code @Insert}), it will throw an {@link IllegalStateException} as only one operation type can be specified.

    + * {@code @Insert}), it will throw an {@link IllegalStateException} as only one operation type can be specified, where + * a Jakarta Data provider implementation choose to detect (and report) this error at compile time or at runtime.

    * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented From f83f081445dd6c4d27ab93ec269faa50c869855f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Wed, 11 Oct 2023 21:07:29 +0300 Subject: [PATCH 30/41] Update api/src/main/java/jakarta/data/repository/Save.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/repository/Save.java | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index d317293f4..0567ce760 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -35,8 +35,11 @@ *
  • An {@code Iterable} of entities to be saved.
    • *
  • An array of entities to be saved.
    • * - *

    The return type of the annotated method must be the same as the parameter type, ensuring consistency - * with the saved entity or entities. + *

    The return type of an annotated method that requires a single entity as the parameter + * must have a return type that is {@code void}, {@code Void}, or the same type as the parameter. + * The return type of an annotated method that accepts an {@code Iterable} or array of entities + * as the parameter must have a return type that is {@code void}, {@code Void}, + * or an {@code Iterable} or array of the entity. *

    *

    Saving an entity involves persisting it in the database. If the entity has an ID or key that already exists * in the database, the method will update the existing record. If the entity does not exist in the database or has a From 39d0497d4613ce2b47ecceb23f094f7d7a066e2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Wed, 11 Oct 2023 21:08:11 +0300 Subject: [PATCH 31/41] Update api/src/main/java/jakarta/data/Insert.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/Insert.java | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index 63376a040..a1c3caaf4 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -33,10 +33,16 @@ *

  • An {@code Iterable} of entities to be inserted.
    • *
  • An array of entities to be inserted.
    • * - *

    The return type of the annotated method should match the type of the parameter. For example, if the method is - * annotated with {@code @Insert} and takes a parameter of type {@code Car car}, the return type should be {@code Car}. - * Similarly, if the parameter is an {@code Iterable} or an array of {@code Car}, the return type should be the - * corresponding type. + *

    The return type of an annotated method that requires a single entity as the parameter must have a return type that is {@code void}, {@code Void}, or the same type as the parameter. + * The return type of an annotated method that accepts an {@code Iterable} or array of entities as the parameter must have a return type that is {@code void}, {@code Void}, or an {@code Iterable} or array of the entity. + * For example, if the method is + * annotated with {@code @Insert} and takes a parameter of type {@code Car car}, the return type can be {@code Car}. + * Similarly, if the parameter is an {@code Iterable} or an array of {@code Car}, the return type can be + * {@code Iterable}. + * Entities that are returned by the annotated method must include all values that were + * written to the database, including all automatically generated values and incremented values + * that changed due to the insert. The position of entities within an {@code Iterable} or array return value + * must correspond to the position of entities in the parameter based on the unique identifier of the entity. *

    *

    After invoking this method, it is recommended not to use the entity value supplied as a parameter, as this method * makes no guarantees about the state of the entity value after insertion. From 7c50b27a7a7ca12725ccf97bc7875ca96126df03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Wed, 11 Oct 2023 21:12:01 +0300 Subject: [PATCH 32/41] Update api/src/main/java/jakarta/data/repository/Save.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/repository/Save.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 0567ce760..524afeb4c 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -59,7 +59,7 @@ * Car park(Car car); * } * - *

    The {@code @Update} annotation can be used to indicate that the {@code park(Car)} method is responsible + *

    The {@code @Save} annotation can be used to indicate that the {@code park(Car)} method is responsible * for updating the entity in the database if it already exists there and otherwise inserting * a car entity into a database. *

    From 9c8491bde14aae81ca93f19d6c2bc7a2de144a5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Wed, 11 Oct 2023 21:12:22 +0300 Subject: [PATCH 33/41] Update api/src/main/java/jakarta/data/repository/Save.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/repository/Save.java | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 524afeb4c..2e4cc917e 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -46,7 +46,11 @@ * null ID, this method will insert a new record. The entity instance returned by this method will be updated with * any automatically generated or incremented values that changed due to the save operation. *

    - *

    After invoking this method, avoid using the entity value that was supplied as a parameter, as it may not accurately + *

    Entities that are returned by the annotated method must include all values that were + * written to the database, including all automatically generated values and incremented values + * that changed due to the save. The position of entities within an {@code Iterable} or array return value + * must correspond to the position of entities in the parameter based on the unique identifier of the entity.

    + *

    After invoking this method, avoid using the entity value that was supplied as a parameter, because it might not accurately * reflect the changes made during the save process. If the entity uses optimistic locking and its version differs from * the version in the database, an {@link jakarta.data.exceptions.OptimisticLockingFailureException} will be thrown. *

    From a5ad3064764a549b4b8e701f273a0df9feb9f5d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Wed, 11 Oct 2023 21:38:15 +0300 Subject: [PATCH 34/41] Update api/src/main/java/jakarta/data/Update.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/Update.java | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/Update.java index 01a2ecd10..ea9559cd0 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/Update.java @@ -57,9 +57,8 @@ * } * *

    If this annotation is combined with other operation annotations (e.g., {@code @Insert}, {@code @Delete}, - * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified, where - * a Jakarta Data provider implementation choose to detect (and report) this error at compile time or at runtime.

    - * @see jakarta.data.exceptions.OptimisticLockingFailureException + * {@code @Save}), it will throw an {@link UnsupportedOperationException} because only one operation type can be specified. + * A Jakarta Data provider implementation must detect (and report) this error at compile time or at runtime.

    */ @Documented @Retention(RetentionPolicy.RUNTIME) From 69334d9fb895f9372fee0317ab04e7adcd8e34cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Wed, 11 Oct 2023 21:39:02 +0300 Subject: [PATCH 35/41] Update api/src/main/java/jakarta/data/Insert.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/Insert.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/Insert.java index a1c3caaf4..7ab346307 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/Insert.java @@ -63,8 +63,8 @@ *

    * *

    If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete}, - * {@code @Save}), it will throw an {@link IllegalStateException} as only one operation type can be specified, where - * a Jakarta Data provider implementation choose to detect (and report) this error at compile time or at runtime..

    + * {@code @Save}), it will throw an {@link UnsupportedOperationException} because only one operation type can be specified. + * A Jakarta Data provider implementation must detect (and report) this error at compile time or at runtime.

    */ @Documented @Retention(RetentionPolicy.RUNTIME) From 772d83eca7846b6cb4dfab74b0194a14109d7452 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Wed, 11 Oct 2023 21:39:10 +0300 Subject: [PATCH 36/41] Update api/src/main/java/jakarta/data/repository/Save.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/repository/Save.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/Save.java b/api/src/main/java/jakarta/data/repository/Save.java index 2e4cc917e..e1338ca81 100644 --- a/api/src/main/java/jakarta/data/repository/Save.java +++ b/api/src/main/java/jakarta/data/repository/Save.java @@ -69,8 +69,8 @@ *

    * *

    If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete}, - * {@code @Insert}), it will throw an {@link IllegalStateException} as only one operation type can be specified, where - * a Jakarta Data provider implementation choose to detect (and report) this error at compile time or at runtime.

    + * {@code @Insert}), it will throw an {@link UnsupportedOperationException} because only one operation type can be specified. + * A Jakarta Data provider implementation must detect (and report) this error at compile time or at runtime.

    * @see jakarta.data.exceptions.OptimisticLockingFailureException */ @Documented From cb01577c762ed854c75e6500cc8f215d8c177bb3 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Wed, 11 Oct 2023 21:41:17 +0300 Subject: [PATCH 37/41] feat: move the operation annotations to repositoryl Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/{ => repository}/Delete.java | 2 +- api/src/main/java/jakarta/data/{ => repository}/Insert.java | 2 +- api/src/main/java/jakarta/data/{ => repository}/Update.java | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename api/src/main/java/jakarta/data/{ => repository}/Delete.java (98%) rename api/src/main/java/jakarta/data/{ => repository}/Insert.java (99%) rename api/src/main/java/jakarta/data/{ => repository}/Update.java (98%) diff --git a/api/src/main/java/jakarta/data/Delete.java b/api/src/main/java/jakarta/data/repository/Delete.java similarity index 98% rename from api/src/main/java/jakarta/data/Delete.java rename to api/src/main/java/jakarta/data/repository/Delete.java index 978cf57ef..1007d7a46 100644 --- a/api/src/main/java/jakarta/data/Delete.java +++ b/api/src/main/java/jakarta/data/repository/Delete.java @@ -15,7 +15,7 @@ * * SPDX-License-Identifier: Apache-2.0 */ -package jakarta.data; +package jakarta.data.repository; import java.lang.annotation.Documented; diff --git a/api/src/main/java/jakarta/data/Insert.java b/api/src/main/java/jakarta/data/repository/Insert.java similarity index 99% rename from api/src/main/java/jakarta/data/Insert.java rename to api/src/main/java/jakarta/data/repository/Insert.java index 7ab346307..0c720c714 100644 --- a/api/src/main/java/jakarta/data/Insert.java +++ b/api/src/main/java/jakarta/data/repository/Insert.java @@ -15,7 +15,7 @@ * * SPDX-License-Identifier: Apache-2.0 */ -package jakarta.data; +package jakarta.data.repository; import java.lang.annotation.Documented; diff --git a/api/src/main/java/jakarta/data/Update.java b/api/src/main/java/jakarta/data/repository/Update.java similarity index 98% rename from api/src/main/java/jakarta/data/Update.java rename to api/src/main/java/jakarta/data/repository/Update.java index ea9559cd0..8fc2deaf3 100644 --- a/api/src/main/java/jakarta/data/Update.java +++ b/api/src/main/java/jakarta/data/repository/Update.java @@ -15,7 +15,7 @@ * * SPDX-License-Identifier: Apache-2.0 */ -package jakarta.data; +package jakarta.data.repository; import java.lang.annotation.Documented; From ed94956461d23c0a624d6453ec6c3e98f2bc2139 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Wed, 11 Oct 2023 21:43:50 +0300 Subject: [PATCH 38/41] style: limite the line to 180 at Insert annotation Signed-off-by: Otavio Santana --- api/src/main/java/jakarta/data/repository/Insert.java | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/Insert.java b/api/src/main/java/jakarta/data/repository/Insert.java index 0c720c714..864264a15 100644 --- a/api/src/main/java/jakarta/data/repository/Insert.java +++ b/api/src/main/java/jakarta/data/repository/Insert.java @@ -33,10 +33,12 @@ *
  • An {@code Iterable} of entities to be inserted.
    • *
  • An array of entities to be inserted.
    • * - *

    The return type of an annotated method that requires a single entity as the parameter must have a return type that is {@code void}, {@code Void}, or the same type as the parameter. - * The return type of an annotated method that accepts an {@code Iterable} or array of entities as the parameter must have a return type that is {@code void}, {@code Void}, or an {@code Iterable} or array of the entity. - * For example, if the method is - * annotated with {@code @Insert} and takes a parameter of type {@code Car car}, the return type can be {@code Car}. + *

    The return type of an annotated method that requires a single entity as the parameter must have a return type + * that is {@code void}, {@code Void}, or the same type as the parameter. + * The return type of an annotated method that accepts an {@code Iterable} or array of entities as the parameter must + * have a return type that is {@code void}, {@code Void}, or an {@code Iterable} or array of the entity. + * For example, if the method is annotated with {@code @Insert} and takes a parameter of type {@code Car car}, + * the return type can be {@code Car}. * Similarly, if the parameter is an {@code Iterable} or an array of {@code Car}, the return type can be * {@code Iterable}. * Entities that are returned by the annotated method must include all values that were From 776a02bdb583eb0de2fe18d7a6d976f4a8b2b486 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Wed, 11 Oct 2023 22:07:26 +0300 Subject: [PATCH 39/41] Update api/src/main/java/jakarta/data/repository/Insert.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/repository/Insert.java | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/Insert.java b/api/src/main/java/jakarta/data/repository/Insert.java index 864264a15..45b146aee 100644 --- a/api/src/main/java/jakarta/data/repository/Insert.java +++ b/api/src/main/java/jakarta/data/repository/Insert.java @@ -49,8 +49,11 @@ *

    After invoking this method, it is recommended not to use the entity value supplied as a parameter, as this method * makes no guarantees about the state of the entity value after insertion. *

    - *

    If the entity uses optimistic locking, and the version differs from the version in the database, an - * {@link jakarta.data.exceptions.OptimisticLockingFailureException} may be thrown. + *

    If an entity of this type with the same unique identifier already exists in the database + * and the databases performs ACID (atomic, consistent, isolated, durable) transactions, + * then annotated method raises {@link jakarta.data.exceptions.EntityExistsException}. + * In databases that follow the BASE model or use an append model to write data, + * this exception is not thrown. *

    *

    For example, consider an interface representing a garage:

    * 
    
From 050096e3c9f5eeb32bc4a96d149c28f4a8cd73e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= 
Date: Wed, 11 Oct 2023 22:07:43 +0300
Subject: [PATCH 40/41] Update
 api/src/main/java/jakarta/data/repository/Insert.java

Co-authored-by: Nathan Rauh 
---
 api/src/main/java/jakarta/data/repository/Insert.java | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/api/src/main/java/jakarta/data/repository/Insert.java b/api/src/main/java/jakarta/data/repository/Insert.java
index 45b146aee..776719fea 100644
--- a/api/src/main/java/jakarta/data/repository/Insert.java
+++ b/api/src/main/java/jakarta/data/repository/Insert.java
@@ -60,11 +60,11 @@
  * {@literal @}Repository
  * interface Garage {
  *     {@literal @}Insert
- *     Car parking(Car car);
+ *     Car park(Car car);
  * }
  *
    - *

    The {@code @Insert} annotation can be used to indicate that the {@code parkCar} method is responsible for inserting - * a car entity into a database. + *

    The {@code @Insert} annotation can be used to indicate that the {@code park(Car)} method is responsible for inserting + * a {@code Car} entity into a database. *

    * *

    If this annotation is combined with other operation annotations (e.g., {@code @Update}, {@code @Delete}, From 3ef795cbf77ffdce5dd4c4d88a245fc05871c619 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ot=C3=A1vio=20Santana?= Date: Wed, 11 Oct 2023 22:08:30 +0300 Subject: [PATCH 41/41] Update api/src/main/java/jakarta/data/repository/Update.java Co-authored-by: Nathan Rauh --- api/src/main/java/jakarta/data/repository/Update.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/Update.java b/api/src/main/java/jakarta/data/repository/Update.java index 8fc2deaf3..ea416e385 100644 --- a/api/src/main/java/jakarta/data/repository/Update.java +++ b/api/src/main/java/jakarta/data/repository/Update.java @@ -44,8 +44,8 @@ * this method, do not continue to use the entity value that is supplied as a parameter, as it may not accurately * reflect the changes made during the update process. *

    - *

    If the entity uses optimistic locking and its version differs from the version in the database, - * an {@link jakarta.data.exceptions.OptimisticLockingFailureException} will be thrown. + *

    If the entity does not exist in the database or it is versioned and its version differs from the version in the database, + * no update is made and no error is raised. *

    * *

    For example, consider an interface representing a garage: