diff --git a/api/src/main/java/jakarta/data/exceptions/EntityExistsException.java b/api/src/main/java/jakarta/data/exceptions/EntityExistsException.java new file mode 100644 index 000000000..fa40fb56d --- /dev/null +++ b/api/src/main/java/jakarta/data/exceptions/EntityExistsException.java @@ -0,0 +1,55 @@ +/* + * 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.exceptions; + +/** + * Indicates that an entity cannot be inserted into the database + * because an entity with same unique identifier already exists in the database. + */ +public class EntityExistsException extends DataException { + private static final long serialVersionUID = -7275063477464065015L; + + /** + * Constructs a new {@code EntityExistsException} with the specified detail message. + * + * @param message the detail message. + */ + public EntityExistsException(String message) { + super(message); + } + + /** + * Constructs a new {@code EntityExistsException} with the specified detail message and cause. + * + * @param message the detail message. + * @param cause another exception or error that caused this exception. + * Null indicates that no other cause is specified. + */ + public EntityExistsException(String message, Throwable cause) { + super(message, cause); + } + + /** + * Constructs a new {@code EntityExistsException} with the specified cause. + * + * @param cause the cause. + */ + public EntityExistsException(Throwable cause) { + super(cause); + } +} \ No newline at end of file diff --git a/api/src/main/java/jakarta/data/repository/BasicRepository.java b/api/src/main/java/jakarta/data/repository/BasicRepository.java index 035887a4c..7e50269be 100644 --- a/api/src/main/java/jakarta/data/repository/BasicRepository.java +++ b/api/src/main/java/jakarta/data/repository/BasicRepository.java @@ -17,6 +17,7 @@ */ package jakarta.data.repository; +import jakarta.data.exceptions.EntityExistsException; import jakarta.data.exceptions.OptimisticLockingFailureException; import java.util.Optional; import java.util.stream.Stream; @@ -83,6 +84,70 @@ public interface BasicRepository extends DataRepository { */ Iterable saveAll(Iterable entities); + /** + *

Inserts an entity into the database. If an entity of this type with the same + * unique identifier already exists in the database, then this method raises + * {@link EntityExistsException}.

+ * + * @param entity the entity to insert. Must not be {@code null}. + * @throws EntityExistsException if the entity is already present in the database. + * @throws NullPointerException if the entity is null. + * @throws UnsupportedOperationException for Key-Value and Wide-Column databases + * that use an append model to write data. + */ + void insert(T entity); + + /** + *

Inserts multiple entities into the database. If an entity of this type with the same + * unique identifier as any of the given entities already exists in the database, + * then this method raises {@link EntityExistsException}.

+ * + * @param entities entities to insert. + * @throws EntityExistsException if any of the entities are already present in the database. + * @throws NullPointerException if either the iterable is null or any element is null. + * @throws UnsupportedOperationException for Key-Value and Wide-Column databases + * that use an append model to write data. + */ + void insertAll(Iterable entities); + + /** + *

Modifies an entity that already exists in the database.

+ * + *

For an update to be made, a matching entity with the same unique identifier + * must be present in the database.

+ * + *

If the entity is versioned (for example, with {@code jakarta.persistence.Version} or by + * another convention from the entity model such as having an attribute named {@code version}), + * then the version must also match. The version is automatically incremented when making + * the update.

+ * + *

Non-matching entities are ignored and do not cause an error to be raised.

+ * + * @param entity the entity to update. + * @return true if a matching entity was found in the database to update, otherwise false. + * @throws NullPointerException if the entity is null. + */ + boolean update(T entity); + + /** + *

Modifies entities that already exists in the database.

+ * + *

For an update to be made to an entity, a matching entity with the same unique identifier + * must be present in the database.

+ * + *

If the entity is versioned (for example, with {@code jakarta.persistence.Version} or by + * another convention from the entity model such as having an attribute named {@code version}), + * then the version must also match. The version is automatically incremented when making + * the update.

+ * + *

Non-matching entities are ignored and do not cause an error to be raised.

+ * + * @param entities entities to update. + * @return the number of matching entities that were found in the database to update. + * @throws NullPointerException if either the iterable is null or any element is null. + */ + int updateAll(Iterable entities); + /** * Retrieves an entity by its id. *