Code review comment requiring to take insert and update out of the spec

api/src/main/java/module-info.java

@@ -18,7 +18,6 @@
 
 import jakarta.data.Limit;
 import jakarta.data.Sort;
-import jakarta.data.exceptions.EntityExistsException;
 import jakarta.data.exceptions.OptimisticLockingFailureException;
 import jakarta.data.page.Pageable;
 import jakarta.data.repository.CrudRepository;
@@ -171,17 +170,9 @@
  * <td>for delete operations</td>
  * <td><code>public void delete(person);</code></td></tr>
  *
- * <tr style="vertical-align: top"><td><code>insert</code></td>
- * <td>creates new entities</td>
- * <td><code>public void insertNewHires(Collection&lt;Employee&gt; newEmployees);</code></td></tr>
- *
  * <tr style="vertical-align: top"><td><code>save</code></td>
  * <td>update if exists, otherwise insert</td>
  * <td><code>Product[] saveAll(Product... products)</code></td></tr>
- *
- * <tr style="vertical-align: top"><td><code>update</code></td>
- * <td>updates an existing entity</td>
- * <td><code>public boolean update(Product modifiedProduct);</code></td></tr>
  * </table>
  *
  * <p>Repository methods following the <b>Query by Method Name</b> pattern
@@ -534,15 +525,6 @@
  * <td><code>LinkedHashMap&lt;K, E&gt;</code></td>
  * <td>Ordered map of Id attribute value to entity</td></tr>
  *
- * <tr style="vertical-align: top"><td><code>insert(E)</code></td>
- * <td><code>void</code>, <code>Void</code></td>
- * <td>For inserting a single entity.</td></tr>
- *
- * <tr style="vertical-align: top"><td><code>insert(E...)</code>,
- * <br><code>insert(Iterable&lt;E&gt;)</code></td>
- * <td><code>void</code>, <code>Void</code></td>
- * <td>For inserting multiple entities.</td></tr>
- *
  * <tr style="vertical-align: top"><td><code>save(E)</code></td>
  * <td><code>E</code>,
  * <br><code>void</code>, <code>Void</code></td>
@@ -560,52 +542,16 @@
  * <td>For saving multiple entities.
  * <br>Collection subtypes must have a public default constructor
  * and support <code>addAll</code> or <code>add</code></td></tr>
- *
- * <tr style="vertical-align: top"><td><code>update(E)</code></td>
- * <td><code>void</code>, <code>Void</code>
- * <br><code>boolean</code>, <code>Boolean</code></td>
- * <td>For updating a single entity.
- * <br>A boolean result indicates whether or not the database was updated.</td></tr>
- *
- * <tr style="vertical-align: top"><td><code>update(E...)</code>,
- * <br><code>update(Iterable&lt;E&gt;)</code></td>
- * <td><code>void</code>, <code>Void</code>,
- * <br><code>boolean</code>, <code>Boolean</code>,
- * <br><code>long</code>, <code>Long</code>,
- * <br><code>int</code>, <code>Integer</code>,
- * <br><code>short</code>, <code>Short</code>,
- * <br><code>Number</code></td>
- * <td>For updating multiple entities.
- * <br>A boolean result indicates whether or not the database was updated.
- * <br>A numeric result indicates how many entities were updated in the database.
- * <br>Jakarta Persistence providers limit the maximum to <code>Integer.MAX_VALUE</code></td></tr>
  * </table>
  *
  * <h2>Methods with Entity Parameters</h2>
  *
- * <p>You can define <i>insert</i>, <i>update</i>, <i>save</i>, and <i>delete</i>
+ * <p>You can define <i>save</i> and <i>delete</i>
  * methods that accept entity parameters.</p>
  *
- * <h3>Insert Methods</h3>
- *
- * <p>Insert methods must create new entity instances in the database.
- * If an entity already exists in the database with the same unique identifier,
- * then the <i>insert</i> method raises {@link EntityExistsException}.</p>
- *
- * <h3>Update Methods</h3>
- *
- * <p>Update methods modify existing entities in the database based on the
- * unique identifier of the entity parameter. 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. When updates are saved to the database,
- * the version is automatically incremented. If a matching entity does not exist
- * in the database, no update is made for that entity.
- * The absence of a matching entity does not cause an error to be raised.</p>
- *
  * <h3>Save Methods</h3>
  *
- * <p>Save methods are a combination of <i>update</i> and <i>insert</i>
+ * <p>Save methods are a combination of update and insert
  * where entities that are already present in the database are updated
  * and entities that are not present in the database are inserted.</p>
  *

spec/src/main/asciidoc/repository.asciidoc

@@ -44,7 +44,7 @@ Several vital characteristics define repositories:
 
 - **Built-In Interfaces:** The Jakarta Data specification provides a set of built-in interfaces from which repositories can inherit. These built-in interfaces offer a convenient way to include a variety of pre-defined methods for common operations. They also declare the entity type to use for methods where the entity type cannot otherwise be inferred.
 
-- **Data Retrieval and Modification:** Repositories facilitate data retrieval and modification operations. This includes querying for persistent instances in the data store, creating new persistent instances in the data store, removing existing persistent instances, and modifying the state of persistent instances. Conventionally, these operations are named insert, delete, and update for modifying operations and find, count, and exists for retrieval operations.
+- **Data Retrieval and Modification:** Repositories facilitate data retrieval and modification operations. This includes querying for persistent instances in the data store, creating new persistent instances in the data store, removing existing persistent instances, and modifying the state of persistent instances. Conventionally, these operations are named save and delete for modifying operations and find, count, and exists for retrieval operations.
 
 - **Subset of Data:** Repositories may expose only a subset of the full data set available in the data store, providing a focused and controlled access point to the data.
 
@@ -841,26 +841,18 @@ first20 = products.findByNameLike(name, pageable);
 
 === Methods With Entity Parameters
 
-Repository methods with a name that begins with one of the prefixes, `insert`, `save`, `update`, `delete`, can have a single entity parameter that is one of the following types, where `E` is the entity type:
+Repository methods with a name that begins with one of the prefixes, `save` or `delete`, can have a single entity parameter that is one of the following types, where `E` is the entity type:
 
 - `E` - the entity type
 - `E[]` - an array of the entity type
 - `E...` - a variable arguments array of the entity type
 - `Iterable<E>` and subtypes of `Iterable<E>` - a collection of multiple entities
 
-Note: A form of `delete` and `update` can be defined in a different manner under the Query by Parameters and Query by Method Name patterns. In those cases, the method can have multiple parameters, none of which can be the entity type.
-
-==== Insert Methods
-
-Insert methods must create new entity instances in the database. If an entity already exists in the database with the same unique identifier, then the `insert` method must raise `EntityExistsException`.
-
-==== Update Methods
-
-Update methods modify existing entities in the database based on the unique identifier of the entity parameter. 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 `version`), then the version must also match. When updates are saved to the database, the version is automatically incremented. If a matching entity does not exist in the database, no update is made for that entity. The absence of a matching entity does not cause an error to be raised.
+Note: A form of `delete` can be defined in a different manner under the Query by Parameters and Query by Method Name patterns. In those cases, the method can have multiple parameters, none of which can be the entity type.
 
 ==== Save Methods
 
-Save methods are a combination of `update` and `insert` where entities that are already present in the database are updated and entities that are not present in the database are inserted.
+Save methods are a combination of update and insert where entities that are already present in the database are updated and entities that are not present in the database are inserted.
 
 The unique identifier is used to determine if an entity exists in the database. If the entity exists in the database and 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 `version`), then the version must also match. When updates are saved to the database, the version is automatically incremented. If the version does not match, the `save` method must raise `OptimisticLockingFailureException`.
 
@@ -881,7 +873,7 @@ System.out.println("Saved version " + product.getVersion() + " of " + product);
 
 ==== Delete Methods
 
-Delete methods remove entities from the database based on the unique identifier of the entity parameter value. 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 `version`), then the version must also match. Other entity attributes do not need to match. The the unique identifier of an entity is not found in the database or its version does not match, the `delete` method must raise `OptimisticLockingFailureException`.
+Delete methods remove entities from the database based on the unique identifier of the entity parameter value. 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 `version`), then the version must also match. Other entity attributes do not need to match. The the unique identifier of an entity is not found in the database or its version does not match, a `delete` method with a return type of `void` or `Void` must raise `OptimisticLockingFailureException`.
 
 ==== Return Types
 
@@ -1055,10 +1047,13 @@ When composing repository methods in Jakarta Data, there are a several different
 | Otherwise, if the method is annotated with `@Query`, the query from the annotation is used.
 | The `@Query` annotation defines a custom query.
 
+| Otherwise, if the method has a single parameter with a type that is the entity type or array, Iterable, or Iterable subclass of the entity type, determine the operation according to the method name prefix, which can be `save` or `delete`.
+| Methods with entity parameters define operations on one or more entities.
+
 | Otherwise, if the method name contains the `By` keyword, determine the query according to the BNF for Query by Method Name.
 | Query by method name allows dynamic query generation based on method names and parameters.
 
-| Otherwise, process it as Query by Parameters, determining the query from the supplied parameters and the `save`, `insert`, `update`, `delete`, `find`, `count`, or `exists` prefix.
+| Otherwise, process it as Query by Parameters, determining the query from the supplied parameters and the `delete`, `find`, `count`, or `exists` prefix.
 | Query by parameters constructs queries based on method parameters and prefixes.
 |===