Merge pull request #283 from njr-11/insert-and-update-on-BasicRepository

insert and update methods on built-in repository

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);
+    }
+}

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<T, K> extends DataRepository<T, K> {
      */
     <S extends T> Iterable<S> saveAll(Iterable<S> entities);
 
+    /**
+     * <p>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}.</p>
+     *
+     * @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);
+
+    /**
+     * <p>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}.</p>
+     *
+     * @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<T> entities);
+
+    /**
+     * <p>Modifies an entity that already exists in the database.</p>
+     *
+     * <p>For an update to be made, a matching entity with the same unique identifier
+     * must be present in the database.</p>
+     *
+     * <p>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.</p>
+     *
+     * <p>Non-matching entities are ignored and do not cause an error to be raised.</p>
+     *
+     * @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);
+
+    /**
+     * <p>Modifies entities that already exists in the database.</p>
+     *
+     * <p>For an update to be made to an entity, a matching entity with the same unique identifier
+     * must be present in the database.</p>
+     *
+     * <p>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.</p>
+     *
+     * <p>Non-matching entities are ignored and do not cause an error to be raised.</p>
+     *
+     * @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<T> entities);
+
     /**
      * Retrieves an entity by its id.
      *