Delete user in the database. The repository also supports updates for multiple entries in batch mode by passing a - * list entities or primary keys. Alternatively, deletion can be executed in using a stream of entities. + *
Remove user from the database. The repository also supports removals for multiple entries in batch mode by passing a + * list entities or primary keys. Alternatively, removal can be executed using a stream of entities. *
{@code
* User user = ...;
- * userRepository.delete(user);
+ * userRepository.remove(user);
* }
*
* Also here, the QueryBuilder can be used to create specialized statement, for instance, to delete all users where
@@ -491,55 +491,55 @@ public interface EntityRepository This method removes an existing entity from the database. The entity must exist in the database; if it does
- * not, a {@link PersistenceException} is thrown. Unlike {@link #deleteById} and {@link #deleteByRef}, this method
+ * not, a {@link PersistenceException} is thrown. Unlike {@link #removeById} and {@link #removeByRef}, this method
* is strict rather than idempotent, because possessing the full entity implies the caller expects it to exist. This method ensures the entity with the given primary key is removed from the database. If the entity does
* not exist, the operation completes successfully without error (idempotent behavior). This method ensures the entity identified by the given reference is removed from the database. If the entity
* does not exist, the operation completes successfully without error (idempotent behavior). This method performs a bulk deletion operation, removing all instances of the entities managed by this
+ * This method performs a bulk removal operation, removing all instances of the entities managed by this
* repository from the database. This is a convenience method that delegates to {@code select().scroll(scrollable)}. It is typically used
- * with a {@link Scrollable} obtained from {@link Window#nextScrollable()} or
- * {@link Window#previousScrollable()}.
This method is useful when you need to retrieve all entity identifiers without loading the full entity data. + * The complete entity can be fetched on demand by calling {@link Ref#fetch()} on any of the returned refs.
+ * + *Note: While this method is more memory-efficient than {@link #findAll()} since it only + * loads primary keys, loading all refs into memory at once can still be memory-intensive for very large tables.
+ * + * @return a list of refs to all entities of the type supported by this repository. + * @throws PersistenceException if the selection operation fails due to underlying database issues, such as + * connectivity. + * @since 1.3 + */ + ListThis method processes the provided entities in batches to optimize performance when handling larger collections, * reducing database overhead. For each entity in the collection, the method removes the corresponding record from - * the database, if it exists. Batch processing ensures efficient handling of deletions, particularly for large data sets.
+ * the database, if it exists. Batch processing ensures efficient handling of removals, particularly for large data sets. * - * @param entities an iterable collection of entities to be deleted. Each entity in the collection must be non-null - * and represent a valid database record for deletion. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @param entities an iterable collection of entities to be removed. Each entity in the collection must be non-null + * and represent a valid database record for removal. + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ - void delete(@Nonnull IterableThis method processes the provided entities in batches to optimize performance when handling larger collections, * reducing database overhead. For each entity in the collection, the method removes the corresponding record from - * the database, if it exists. Batch processing ensures efficient handling of deletions, particularly for large data sets.
+ * the database, if it exists. Batch processing ensures efficient handling of removals, particularly for large data sets. * - * @param refs an iterable collection of entities to be deleted. Each entity in the collection must be non-null - * and represent a valid database record for deletion. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @param refs an iterable collection of entities to be removed. Each entity in the collection must be non-null + * and represent a valid database record for removal. + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ - void deleteByRef(@Nonnull IterableThis method executes queries in batches, depending on the number of primary keys in the specified ids stream. - * This optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. - * The batching strategy enhances performance, particularly when dealing with large sets of primary keys.
- * - *The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they - * are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when - * dealing with large volumes of entities.
- * - *Note: Calling this method does trigger the execution of the underlying - * query, so it should only be invoked when the query is intended to run. Since the stream holds resources open - * while in use, it must be closed after usage to prevent resource leaks. As the stream is {@code AutoCloseable}, it - * is recommended to use it within a {@code try-with-resources} block.
- * - * @param ids a stream of entity IDs to retrieve from the repository. - * @return a stream of entities corresponding to the provided primary keys. The order of entities in the stream is - * not guaranteed to match the order of ids in the input stream. If an id does not correspond to any entity - * in the database, it will simply be skipped, and no corresponding entity will be included in the returned - * stream. If the same entity is requested multiple times, it may be included in the stream multiple times - * if it is part of a separate batch. - * @throws PersistenceException if the selection operation fails due to underlying database issues, such as - * connectivity. - */ - StreamThis method executes queries in batches, depending on the number of primary keys in the specified ids stream. - * This optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. - * The batching strategy enhances performance, particularly when dealing with large sets of primary keys.
- * - *The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they - * are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when - * dealing with large volumes of entities.
- * - *Note: Calling this method does trigger the execution of the underlying - * query, so it should only be invoked when the query is intended to run. Since the stream holds resources open - * while in use, it must be closed after usage to prevent resource leaks. As the stream is {@code AutoCloseable}, it - * is recommended to use it within a {@code try-with-resources} block.
- * - * @param refs a stream of refs to retrieve from the repository. - * @return a stream of entities corresponding to the provided primary keys. The order of entities in the stream is - * not guaranteed to match the order of ids in the input stream. If an id does not correspond to any entity - * in the database, it will simply be skipped, and no corresponding entity will be included in the returned - * stream. If the same entity is requested multiple times, it may be included in the stream multiple times - * if it is part of a separate batch. - * @throws PersistenceException if the selection operation fails due to underlying database issues, such as - * connectivity. - */ - StreamThis method executes queries in batches, with the batch size determined by the provided parameter. This - * optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. The - * batching strategy enhances performance, particularly when dealing with large sets of primary keys.
- * - *The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they - * are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when - * dealing with large volumes of entities.
- * - *Note: Calling this method does trigger the execution of the underlying - * query, so it should only be invoked when the query is intended to run. Since the stream holds resources open - * while in use, it must be closed after usage to prevent resource leaks. As the stream is {@code AutoCloseable}, it - * is recommended to use it within a {@code try-with-resources} block.
- * - * @param ids a stream of entity IDs to retrieve from the repository. - * @param chunkSize the number of primary keys to include in each batch. This parameter determines the size of the - * batches used to execute the selection operation. A larger batch size can improve performance, especially when - * dealing with large sets of primary keys. - * @return a stream of entities corresponding to the provided primary keys. The order of entities in the stream is - * not guaranteed to match the order of refs in the input stream. If an id does not correspond to any entity in the - * database, it will simply be skipped, and no corresponding entity will be included in the returned stream. If the - * same entity is requested multiple times, it may be included in the stream multiple times if it is part of a - * separate batch. - * @throws PersistenceException if the selection operation fails due to underlying database issues, such as - * connectivity. - */ - StreamThis method executes queries in batches, with the batch size determined by the provided parameter. This - * optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. The - * batching strategy enhances performance, particularly when dealing with large sets of primary keys.
- * - *The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they - * are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when - * dealing with large volumes of entities.
- * - *Note: Calling this method does trigger the execution of the underlying - * query, so it should only be invoked when the query is intended to run. Since the stream holds resources open - * while in use, it must be closed after usage to prevent resource leaks. As the stream is {@code AutoCloseable}, it - * is recommended to use it within a {@code try-with-resources} block.
- * - * @param refs a stream of refs to retrieve from the repository. - * @param chunkSize the number of primary keys to include in each batch. This parameter determines the size of the - * batches used to execute the selection operation. A larger batch size can improve performance, especially when - * dealing with large sets of primary keys. - * @return a stream of entities corresponding to the provided primary keys. The order of entities in the stream is - * not guaranteed to match the order of refs in the input stream. If an id does not correspond to any entity in the - * database, it will simply be skipped, and no corresponding entity will be included in the returned stream. If the - * same entity is requested multiple times, it may be included in the stream multiple times if it is part of a - * separate batch. - * @throws PersistenceException if the selection operation fails due to underlying database issues, such as - * connectivity. - */ - StreamThis method processes the provided stream of entities in batches to optimize performance for larger - * data sets, reducing database overhead during deletion. For each entity in the stream, the method removes + * data sets, reducing database overhead during removal. For each entity in the stream, the method removes * the corresponding record from the database, if it exists. Batch processing allows efficient handling - * of deletions, particularly for large collections of entities.
+ * of removals, particularly for large collections of entities. * - * @param entities a stream of entities to be deleted. Each entity in the stream must be non-null and represent - * a valid database record for deletion. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @param entities a stream of entities to be removed. Each entity in the stream must be non-null and represent + * a valid database record for removal. + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ - void delete(@Nonnull StreamThis method processes the provided stream of entities in batches, with the size of each batch specified - * by the `batchSize` parameter. This allows for control over the number of entities deleted in each database + * by the `batchSize` parameter. This allows for control over the number of entities removed in each database * operation, optimizing performance and memory usage based on system requirements. For each entity in the * stream, the method removes the corresponding record from the database, if it exists.
* - * @param entities a stream of entities to be deleted. Each entity in the stream must be non-null and represent - * a valid database record for deletion. + * @param entities a stream of entities to be removed. Each entity in the stream must be non-null and represent + * a valid database record for removal. * @param batchSize the number of entities to process in each batch. Larger batch sizes may improve performance * but require more memory, while smaller batch sizes may reduce memory usage but increase * the number of database operations. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ - void delete(@Nonnull StreamThis method processes the provided stream of entities in batches to optimize performance for larger - * data sets, reducing database overhead during deletion. For each entity in the stream, the method removes + * data sets, reducing database overhead during removal. For each entity in the stream, the method removes * the corresponding record from the database, if it exists. Batch processing allows efficient handling - * of deletions, particularly for large collections of entities.
+ * of removals, particularly for large collections of entities. * - * @param refs a stream of entities to be deleted. Each entity in the stream must be non-null and represent - * a valid database record for deletion. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @param refs a stream of entities to be removed. Each entity in the stream must be non-null and represent + * a valid database record for removal. + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ - void deleteByRef(@Nonnull StreamThis method processes the provided stream of entities in batches, with the size of each batch specified - * by the `batchSize` parameter. This allows for control over the number of entities deleted in each database + * by the `batchSize` parameter. This allows for control over the number of entities removed in each database * operation, optimizing performance and memory usage based on system requirements. For each entity in the * stream, the method removes the corresponding record from the database, if it exists.
* - * @param refs a stream of entities to be deleted. Each entity in the stream must be non-null and represent - * valid database record for deletion. + * @param refs a stream of entities to be removed. Each entity in the stream must be non-null and represent + * valid database record for removal. * @param batchSize the number of entities to process in each batch. Larger batch sizes may improve performance * but require more memory, while smaller batch sizes may reduce memory usage but increase * the number of database operations. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ - void deleteByRef(@Nonnull StreamThis is a convenience method that delegates to {@code select().scroll(scrollable)}. It is typically used - * with a {@link Scrollable} obtained from {@link Window#nextScrollable()} or - * {@link Window#previousScrollable()}.
+ * with a {@link Scrollable} obtained from {@link Window#next()} or {@link Window#previous()}. * * @param scrollable the scroll request describing cursor position and page size. * @return a window containing the results. @@ -371,7 +370,7 @@ default Pagescroll(@Nonnull Scrollable
scrollable) { - return Window.of(select().scroll(scrollable)); + return select().scroll(scrollable); } // List based methods. @@ -389,6 +388,24 @@ default Window
scroll(@Nonnull Scrollable
scrollable) { */ List
findAll(); + /** + * Returns a list of refs to all projections of the type supported by this repository. Each element in the list + * represents a lightweight reference to a projection in the database, containing only the primary key. + * + *
This method is useful when you need to retrieve all projection identifiers without loading the full + * projection data. The complete projection can be fetched on demand by calling {@link Ref#fetch()} on any of + * the returned refs.
+ * + *Note: While this method is more memory-efficient than {@link #findAll()} since it only + * loads primary keys, loading all refs into memory at once can still be memory-intensive for very large tables.
+ * + * @return a list of refs to all projections of the type supported by this repository. + * @throws PersistenceException if the selection operation fails due to underlying database issues, such as + * connectivity. + * @since 1.3 + */ + ListThis method removes an existing entity from the database. The entity must exist in the database; if it does - * not, a {@link PersistenceException} is thrown. Unlike {@link #deleteById} and {@link #deleteByRef}, this method + * not, a {@link PersistenceException} is thrown. Unlike {@link #removeById} and {@link #removeByRef}, this method * is strict rather than idempotent, because possessing the full entity implies the caller expects it to exist.
* - * @param entity the entity to delete. The entity must exist in the database and should be correctly identified by + * @param entity the entity to remove. The entity must exist in the database and should be correctly identified by * its primary key. - * @throws PersistenceException if the deletion operation fails. Reasons for failure might include the entity not + * @throws PersistenceException if the removal operation fails. Reasons for failure might include the entity not * being found in the database, violations of database constraints, connectivity * issues, or if the entity parameter is null. */ @Override - public void delete(@Nonnull E entity) { + public void remove(@Nonnull E entity) { validateDelete(entity); fireBeforeDelete(entity); entityCache().ifPresent(cache -> { @@ -1046,7 +1046,7 @@ public void delete(@Nonnull E entity) { } }); if (model.isJoinedInheritance()) { - JoinedEntityHelper.delete(ormTemplate, model, entity); + JoinedEntityHelper.remove(ormTemplate, model, entity); fireAfterDelete(entity); return; } @@ -1057,26 +1057,26 @@ public void delete(@Nonnull E entity) { .managed() .executeUpdate(); if (result != 1) { - throw new PersistenceException("Delete of %s failed. 0 rows were affected, possibly because the entity does not exist or a foreign key constraint prevents deletion.".formatted(model.type().getSimpleName())); + throw new PersistenceException("Remove of %s failed. 0 rows were affected, possibly because the entity does not exist or a foreign key constraint prevents deletion.".formatted(model.type().getSimpleName())); } fireAfterDelete(entity); } /** - * Deletes an entity from the database based on its primary key. + * Removes an entity from the database based on its primary key. * *This method ensures the entity with the given primary key is removed from the database. If the entity does * not exist, the operation completes successfully without error (idempotent behavior).
* - * @param id the primary key of the entity to delete. - * @throws PersistenceException if the deletion operation fails due to violations of database constraints, + * @param id the primary key of the entity to remove. + * @throws PersistenceException if the removal operation fails due to violations of database constraints, * connectivity issues, or if the id parameter is null. */ @Override - public void deleteById(@Nonnull ID id) { + public void removeById(@Nonnull ID id) { entityCache().ifPresent(cache -> cache.remove(id)); if (model.isJoinedInheritance()) { - JoinedEntityHelper.deleteById(ormTemplate, model, id); + JoinedEntityHelper.removeById(ormTemplate, model, id); return; } // Don't use query builder to prevent WHERE IN clause. @@ -1088,17 +1088,17 @@ public void deleteById(@Nonnull ID id) { } /** - * Deletes an entity from the database by its reference. + * Removes an entity from the database by its reference. * *This method ensures the entity identified by the given reference is removed from the database. If the entity * does not exist, the operation completes successfully without error (idempotent behavior).
* - * @param ref the reference to the entity to delete. - * @throws PersistenceException if the deletion operation fails due to violations of database constraints, + * @param ref the reference to the entity to remove. + * @throws PersistenceException if the removal operation fails due to violations of database constraints, * connectivity issues, or if the ref parameter is null. */ @Override - public void deleteByRef(@Nonnull RefThis method performs a bulk deletion operation, removing all instances of the entities managed by this + *
This method performs a bulk removal operation, removing all instances of the entities managed by this * repository from the database.
* - * @throws PersistenceException if the bulk deletion operation fails. Failure can occur for several reasons, + * @throws PersistenceException if the bulk removal operation fails. Failure can occur for several reasons, * including but not limited to database access issues, transaction failures, or - * underlying database constraints that prevent the deletion of certain records. + * underlying database constraints that prevent the removal of certain records. */ @Override - public void deleteAll() { + public void removeAll() { entityCache().ifPresent(EntityCache::clear); // Don't use query builder to prevent WHERE IN clause. ormTemplate.query(TemplateString.raw("DELETE FROM \0", model.type())) @@ -1393,37 +1393,37 @@ public ListThis method processes the provided entities in batches to optimize performance when handling larger collections, * reducing database overhead. For each entity in the collection, the method removes the corresponding record from - * the database, if it exists. Batch processing ensures efficient handling of deletions, particularly for large data sets.
+ * the database, if it exists. Batch processing ensures efficient handling of removals, particularly for large data sets. * - * @param entities an iterable collection of entities to be deleted. Each entity in the collection must be non-null - * and represent a valid database record for deletion. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @param entities an iterable collection of entities to be removed. Each entity in the collection must be non-null + * and represent a valid database record for removal. + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ @Override - public void delete(@Nonnull IterableThis method processes the provided entities in batches to optimize performance when handling larger collections, * reducing database overhead. For each entity in the collection, the method removes the corresponding record from - * the database, if it exists. Batch processing ensures efficient handling of deletions, particularly for large data sets.
+ * the database, if it exists. Batch processing ensures efficient handling of removals, particularly for large data sets. * - * @param refs an iterable collection of entities to be deleted. Each entity in the collection must be non-null - * and represent a valid database record for deletion. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @param refs an iterable collection of entities to be removed. Each entity in the collection must be non-null + * and represent a valid database record for removal. + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ @Override - public void deleteByRef(@Nonnull IterableThis method processes the provided stream of entities in batches to optimize performance for larger - * data sets, reducing database overhead during deletion. For each entity in the stream, the method removes + * data sets, reducing database overhead during removal. For each entity in the stream, the method removes * the corresponding record from the database, if it exists. Batch processing allows efficient handling - * of deletions, particularly for large collections of entities.
+ * of removals, particularly for large collections of entities. * - * @param entities a stream of entities to be deleted. Each entity in the stream must be non-null and represent - * a valid database record for deletion. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @param entities a stream of entities to be removed. Each entity in the stream must be non-null and represent + * a valid database record for removal. + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ @Override - public void delete(@Nonnull StreamThis method processes the provided stream of entities in batches, with the size of each batch specified - * by the `batchSize` parameter. This allows for control over the number of entities deleted in each database + * by the `batchSize` parameter. This allows for control over the number of entities removed in each database * operation, optimizing performance and memory usage based on system requirements. For each entity in the * stream, the method removes the corresponding record from the database, if it exists.
* - * @param entities a stream of entities to be deleted. Each entity in the stream must be non-null and represent - * a valid database record for deletion. + * @param entities a stream of entities to be removed. Each entity in the stream must be non-null and represent + * a valid database record for removal. * @param batchSize the number of entities to process in each batch. Larger batch sizes may improve performance * but require more memory, while smaller batch sizes may reduce memory usage but increase * the number of database operations. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ @Override - public void delete(@Nonnull StreamThis method processes the provided stream of entities in batches to optimize performance for larger - * data sets, reducing database overhead during deletion. For each entity in the stream, the method removes + * data sets, reducing database overhead during removal. For each entity in the stream, the method removes * the corresponding record from the database, if it exists. Batch processing allows efficient handling - * of deletions, particularly for large collections of entities.
+ * of removals, particularly for large collections of entities. * - * @param refs a stream of entities to be deleted. Each entity in the stream must be non-null and represent - * a valid database record for deletion. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @param refs a stream of entities to be removed. Each entity in the stream must be non-null and represent + * a valid database record for removal. + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ @Override - public void deleteByRef(@Nonnull StreamThis method processes the provided stream of entities in batches, with the size of each batch specified - * by the `batchSize` parameter. This allows for control over the number of entities deleted in each database + * by the `batchSize` parameter. This allows for control over the number of entities removed in each database * operation, optimizing performance and memory usage based on system requirements. For each entity in the * stream, the method removes the corresponding record from the database, if it exists.
* - * @param refs a stream of entities to be deleted. Each entity in the stream must be non-null and represent - * valid database record for deletion. + * @param refs a stream of entities to be removed. Each entity in the stream must be non-null and represent + * valid database record for removal. * @param batchSize the number of entities to process in each batch. Larger batch sizes may improve performance * but require more memory, while smaller batch sizes may reduce memory usage but increase * the number of database operations. - * @throws PersistenceException if the deletion operation fails due to database issues, such as connectivity problems + * @throws PersistenceException if the removal operation fails due to database issues, such as connectivity problems * or constraints violations. */ @Override - public void deleteByRef(@Nonnull StreamThe Java implementation ({@code DefaultORMReflectionImpl}) handles Java records using the standard + * {@link java.lang.reflect.RecordComponent} API. The Kotlin implementation ({@code ORMReflectionImpl}) additionally + * handles Kotlin data classes using the Kotlin reflection API ({@code KClass}, {@code KProperty1}, etc.), falling back + * to the Java implementation for plain Java records.
*/ public interface ORMReflection { + /** + * Returns the primary key value of the specified {@link Data} instance. + * + *Locates the first field annotated with {@link PK} via {@link #getRecordType(Class)} and invokes its accessor + * to retrieve the value. The result is cached per class for subsequent lookups.
+ * + * @param data the data instance to extract the primary key from. + * @return the primary key value. + * @throws PersistenceException if no {@code @PK}-annotated field is found. + */ Object getId(@Nonnull Data data); + /** + * Returns the value of the record component at the specified index. + * + *Uses {@link #getRecordType(Class)} to obtain the field list, then invokes the accessor for the field at the + * given position. For Java records this is the record component accessor; for Kotlin data classes it is the + * Kotlin property getter.
+ * + * @param record the record instance (Java record or Kotlin data class). + * @param index the zero-based index of the component. + * @return the component value. + * @throws PersistenceException if the type is not a recognized record type or the index is out of bounds. + */ Object getRecordValue(@Nonnull Object record, int index); + /** + * Returns an {@link Optional} containing the {@link RecordType} descriptor for the specified class if it is a + * recognized record type, or an empty {@code Optional} otherwise. + * + *The Java implementation recognizes Java {@code record} classes and builds the descriptor from + * {@link java.lang.reflect.RecordComponent} metadata. The Kotlin implementation additionally recognizes Kotlin + * data classes (detected via the {@code @Metadata} annotation and {@code KClass.isData()}) and builds the + * descriptor from the primary constructor parameters and corresponding property accessors.
+ * + *Results are cached per class.
+ * + * @param type the class to inspect. + * @return the record type descriptor, or empty if the class is not a recognized record type. + */ OptionalThe Java implementation returns {@code true} for {@link Class} instances. The Kotlin implementation + * additionally returns {@code true} for {@code KClass} instances.
+ * + * @param o the object to test. + * @return {@code true} if this implementation can resolve the object to a Java class. + */ boolean isSupportedType(@Nonnull Object o); + /** + * Resolves a type reference to its corresponding Java {@link Class}. + * + *The Java implementation expects a {@link Class} that implements {@link Data} and returns it directly. The + * Kotlin implementation additionally handles {@code KClass} instances by mapping them to their Java class via + * {@code JvmClassMappingKt.getJavaClass}.
+ * + * @param o the type reference ({@link Class} or {@code KClass}). + * @return the resolved Java class. + * @throws PersistenceException if the object is not a supported type reference or is not a {@link Data} type. + */ Class getType(@Nonnull Object o); + /** + * Resolves a type reference to its corresponding Java {@link Class}, cast to {@code Class}. + * + *Behaves like {@link #getType(Object)} but returns a {@code Data}-bounded type. Throws if the resolved class + * does not implement {@link Data}.
+ * + * @param o the type reference ({@link Class} or {@code KClass}). + * @return the resolved Java class as a {@code Data} subtype. + * @throws PersistenceException if the object is not a supported type reference or is not a {@link Data} type. + */ Class getDataType(@Nonnull Object o); + /** + * Returns whether the specified object is a default value for its type. + * + *Returns {@code true} for: {@code null}; primitive wrappers with their default value ({@code 0}, + * {@code false}, {@code '\u0000'}); and record instances whose every component is itself a default value + * (checked recursively).
+ * + * @param o the value to test, may be {@code null}. + * @return {@code true} if the value is considered a default. + */ boolean isDefaultValue(@Nullable Object o); /** * Returns the permitted subclasses of the specified sealed class. * + *The Java implementation delegates to {@link Class#getPermittedSubclasses()}. The Kotlin implementation uses + * {@code KClass.getSealedSubclasses()} to also handle Kotlin sealed classes.
+ * * @param sealedClass the sealed class to get the permitted subclasses for. * @return a list of permitted subclasses of the specified sealed class. */The Java implementation checks {@link Method#isDefault()}. The Kotlin implementation additionally returns + * {@code true} for methods declared on classes annotated with {@code @Metadata} (indicating Kotlin default + * implementations compiled into a {@code DefaultImpls} companion class).
+ * + * @param method the method to test. + * @return {@code true} if the method is a default method. + */ boolean isDefaultMethod(@Nonnull Method method); + /** + * Invokes the accessor for the specified {@link RecordField} on the given record instance and returns the result. + * + *Uses {@link java.lang.invoke.MethodHandle}-based invocation for performance, falling back to reflective + * invocation when the method handle cannot be obtained (e.g., due to module restrictions).
+ * + * @param field the record field whose accessor should be invoked. + * @param record the record instance. + * @return the field value. + * @throws PersistenceException if the invocation fails. + */ Object invoke(@Nonnull RecordField field, @Nonnull Object record); + /** + * Invokes a default or Kotlin-compiled default method on a proxy instance. + * + *The Java implementation uses {@link java.lang.invoke.MethodHandles} to call the default method via + * {@code findSpecial}. The Kotlin implementation locates the static {@code DefaultImpls} companion class and + * invokes the corresponding static method, passing the proxy as the first argument.
+ * + * @param proxy the proxy instance on which the method was called. + * @param method the default method to invoke. + * @param args the method arguments. + * @return the return value of the method. + * @throws Throwable if the invocation fails. + */ Object execute(@Nonnull Object proxy, @Nonnull Method method, @Nonnull Object... args) throws Throwable; } diff --git a/storm-core/src/main/java/st/orm/core/template/QueryBuilder.java b/storm-core/src/main/java/st/orm/core/template/QueryBuilder.java index 6e665647b..cdbb970f7 100644 --- a/storm-core/src/main/java/st/orm/core/template/QueryBuilder.java +++ b/storm-core/src/main/java/st/orm/core/template/QueryBuilder.java @@ -30,7 +30,6 @@ import java.util.stream.Stream; import st.orm.Data; import st.orm.JoinType; -import st.orm.MappedWindow; import st.orm.Metamodel; import st.orm.NoResultException; import st.orm.NonUniqueResultException; @@ -758,21 +757,21 @@ public final PageBecause this method has no key or sort information, the returned window does not carry navigation tokens - * ({@code nextScrollable} and {@code previousScrollable} are {@code null}).
+ * ({@code next()} and {@code previous()} return {@code null}). * * @param size the maximum number of results to include in the window (must be positive). * @return a window containing the results and a flag indicating whether more results exist. * @throws IllegalArgumentException if {@code size} is not positive. * @since 1.11 */ - public final MappedWindowPhase 1 deletes from extension tables first (FK constraints), partitioned by concrete subtype. * Phase 2 deletes all entities from the base table.
* * @param queryTemplate the query template for executing SQL. * @param model the model describing the sealed entity. - * @param entities the entities to delete (already validated). + * @param entities the entities to remove (already validated). * @paramWhen the concrete type is unknown, attempts DELETE from all extension tables for all IDs * (at most one will match per entity), then deletes from the base table.
* * @param queryTemplate the query template for executing SQL. * @param model the model describing the sealed entity. - * @param refs the entity references to delete. + * @param refs the entity references to remove. * @paramThis allows {@code Ref
This method validates contextual correctness, such as preventing records from being used - * next to operators.
+ *This method transforms known template value types into their corresponding internal representations + * (e.g., {@link Subqueryable} to {@link Subquery}, column-level {@link Metamodel} to {@link Column}), and rejects + * invalid types such as {@link TemplateString} and {@link Stream}.
* - * @param value the value to resolve. - * @param previousFragment the preceding SQL fragment. - * @param nextFragment the following SQL fragment. + *{@link Data} and {@link Ref} instances pass through unchanged and are handled by the caller's switch + * (compiled via {@code ObjectExpression}, which resolves columns through the model). Other values (scalars, + * {@link Element} instances, etc.) also pass through unchanged and are compiled or bound by the caller.
+ * + * @param value the value to resolve. * @return the resolved value. * @throws SqlTemplateException if the value is invalid in this context. */ - private Object resolveElements(@Nullable Object value, @Nonnull String previousFragment, @Nonnull String nextFragment) throws SqlTemplateException { + private Object resolveElements(@Nullable Object value) throws SqlTemplateException { return switch (value) { case TemplateString ignore -> throw new SqlTemplateException("TemplateString is not allowed as a string template value."); case Stream ignore -> throw new SqlTemplateException("Stream is not supported as a string template value. Collect the Stream into a List before passing it."); case Subqueryable t -> new Subquery(t.getSubquery(), true); case Metamodel m when m.isColumn() -> new st.orm.core.template.impl.Elements.Column(m, CASCADE); case Metamodel ignore -> throw new SqlTemplateException("Metamodel does not reference a column. Use a column-level metamodel (e.g., User_.name) rather than a table-level metamodel."); - case null, default -> { - if (!(value instanceof Element) && value instanceof Record) { - String previous = removeComments(previousFragment, template.dialect()).stripTrailing().toUpperCase(); - if (ENDS_WITH_OPERATOR.matcher(previous).find()) { - throw new SqlTemplateException("Record is not allowed directly next to a comparison operator in an expression. Use a specific field value or metamodel reference instead."); - } - String next = removeComments(nextFragment, template.dialect()).stripLeading().toUpperCase(); - if (STARTS_WITH_OPERATOR.matcher(next).find()) { - throw new SqlTemplateException("Record is not allowed directly next to a comparison operator in an expression. Use a specific field value or metamodel reference instead."); - } - } - yield value; - } + case null, default -> value; }; } diff --git a/storm-core/src/test/java/st/orm/core/BuilderPreparedStatementIntegrationTest.java b/storm-core/src/test/java/st/orm/core/BuilderPreparedStatementIntegrationTest.java index d48fbd2a9..eb59b24a3 100644 --- a/storm-core/src/test/java/st/orm/core/BuilderPreparedStatementIntegrationTest.java +++ b/storm-core/src/test/java/st/orm/core/BuilderPreparedStatementIntegrationTest.java @@ -598,7 +598,7 @@ public void testScrollNavigationForwardThenBackward() { // Navigate forward: vets 4, 5, 6. var nextWindow = ORMTemplate.of(dataSource) .selectFrom(Vet.class) - .scroll(firstWindow.nextScrollable()); + .scroll(firstWindow.next()); assertEquals(3, nextWindow.content().size()); assertFalse(nextWindow.hasNext()); assertEquals(4, nextWindow.content().get(0).id()); @@ -608,7 +608,7 @@ public void testScrollNavigationForwardThenBackward() { // Navigate backward: should return the same vets as the first window, but in descending order (3, 2, 1). var backWindow = ORMTemplate.of(dataSource) .selectFrom(Vet.class) - .scroll(nextWindow.previousScrollable()); + .scroll(nextWindow.previous()); assertEquals(3, backWindow.content().size()); assertEquals(3, backWindow.content().get(0).id()); assertEquals(2, backWindow.content().get(1).id()); @@ -642,7 +642,7 @@ public void testScrollWindowNextCursorRoundTrip() { // Scroll using the navigation token for comparison. var tokenWindow = ORMTemplate.of(dataSource) .selectFrom(Vet.class) - .scroll(firstWindow.nextScrollable()); + .scroll(firstWindow.next()); // Both approaches should yield the same results. assertEquals(tokenWindow.content().size(), cursorWindow.content().size()); @@ -666,10 +666,10 @@ public void testScrollBackwardNavigation() { assertEquals(5, firstWindow.content().get(1).id()); assertEquals(4, firstWindow.content().get(2).id()); - // Navigate further back using previousScrollable: vets 3, 2, 1. + // Navigate further back using next(): vets 3, 2, 1. var previousWindow = ORMTemplate.of(dataSource) .selectFrom(Vet.class) - .scroll(firstWindow.nextScrollable()); + .scroll(firstWindow.next()); assertEquals(3, previousWindow.content().size()); assertFalse(previousWindow.hasNext()); assertEquals(3, previousWindow.content().get(0).id()); diff --git a/storm-core/src/test/java/st/orm/core/CursorSerializationTest.java b/storm-core/src/test/java/st/orm/core/CursorSerializationTest.java index 4a9d562f7..cb8eec189 100644 --- a/storm-core/src/test/java/st/orm/core/CursorSerializationTest.java +++ b/storm-core/src/test/java/st/orm/core/CursorSerializationTest.java @@ -16,9 +16,9 @@ import java.util.UUID; import org.junit.jupiter.api.Test; import st.orm.Data; -import st.orm.MappedWindow; import st.orm.Metamodel; import st.orm.Scrollable; +import st.orm.Window; /** * Tests cursor serialization (toCursor/fromCursor) which requires storm-core on the classpath. @@ -244,7 +244,7 @@ void toCursorProducesUrlSafeString() { void windowNextCursorProducesStringFromScrollable() { var key = Metamodel.key(Metamodel.of(StubEntity.class, "id")); var next = new Scrollable<>(key, 42, null, null, 20, true); - var window = new MappedWindow<>(java.util.List.of("a"), true, false, next, null); + var window = new Window<>(java.util.List.of("a"), true, false, next, null); String cursor = window.nextCursor(); assertNotNull(cursor); var restored = Scrollable.fromCursor(key, cursor); @@ -257,7 +257,7 @@ void windowNextCursorProducesStringFromScrollable() { void windowPreviousCursorProducesStringFromScrollable() { var key = Metamodel.key(Metamodel.of(StubEntity.class, "id")); var prev = new Scrollable<>(key, 5, null, null, 10, false); - var window = new MappedWindow<>(java.util.List.of("a"), false, true, null, prev); + var window = new Window<>(java.util.List.of("a"), false, true, null, prev); String cursor = window.previousCursor(); assertNotNull(cursor); var restored = Scrollable.fromCursor(key, cursor); diff --git a/storm-core/src/test/java/st/orm/core/EntityCallbackIntegrationTest.java b/storm-core/src/test/java/st/orm/core/EntityCallbackIntegrationTest.java index ffb257bc1..b5555ae5d 100644 --- a/storm-core/src/test/java/st/orm/core/EntityCallbackIntegrationTest.java +++ b/storm-core/src/test/java/st/orm/core/EntityCallbackIntegrationTest.java @@ -95,7 +95,7 @@ public void beforeDelete(@Nonnull City entity) { }); // Insert a city with no FK references, then delete it. var id = orm.entity(City.class).insertAndFetchId(City.builder().name("Deletable").build()); - orm.entity(City.class).delete(City.builder().id(id).name("Deletable").build()); + orm.entity(City.class).remove(City.builder().id(id).name("Deletable").build()); assertEquals(List.of("before:Deletable"), log); } @@ -110,7 +110,7 @@ public void afterDelete(@Nonnull City entity) { }); // Insert a city with no FK references, then delete it. var id = orm.entity(City.class).insertAndFetchId(City.builder().name("Deletable").build()); - orm.entity(City.class).delete(City.builder().id(id).name("Deletable").build()); + orm.entity(City.class).remove(City.builder().id(id).name("Deletable").build()); assertEquals(List.of("after:Deletable"), log); } diff --git a/storm-core/src/test/java/st/orm/core/EntityRepositoryAdditionalIntegrationTest.java b/storm-core/src/test/java/st/orm/core/EntityRepositoryAdditionalIntegrationTest.java index 55f3b471b..71d8e8e01 100644 --- a/storm-core/src/test/java/st/orm/core/EntityRepositoryAdditionalIntegrationTest.java +++ b/storm-core/src/test/java/st/orm/core/EntityRepositoryAdditionalIntegrationTest.java @@ -71,12 +71,12 @@ public void testUpdateWithDefaultPrimaryKeyThrows() { } @Test - public void testDeleteWithDefaultPrimaryKeyThrows() { + public void testRemoveWithDefaultPrimaryKeyThrows() { var orm = ORMTemplate.of(dataSource); var cities = orm.entity(City.class); // Deleting with null PK should throw. assertThrows(PersistenceException.class, - () -> cities.delete(City.builder().name("NoPK").build())); + () -> cities.remove(City.builder().name("NoPK").build())); } // insert with ignoreAutoGenerate @@ -92,7 +92,7 @@ public void testInsertWithIgnoreAutoGenerateExplicitPrimaryKey() { City fetched = cities.getById(9990); assertEquals("ExplicitPK", fetched.name()); // Clean up. - cities.deleteById(9990); + cities.removeById(9990); } @Test @@ -107,7 +107,7 @@ public void testInsertWithIgnoreAutoGenerateNullPrimaryKeyThrows() { // deleteAll @Test - public void testDeleteAllRemovesAllEntities() { + public void testRemoveAllRemovesAllEntities() { var orm = ORMTemplate.of(dataSource); // Use pet_extension to avoid FK constraint issues (it's a leaf table). // Insert some cities that are not referenced by anything else. @@ -123,7 +123,7 @@ public void testDeleteAllRemovesAllEntities() { var visits = orm.entity(Visit.class); long visitCountBefore = visits.count(); assertTrue(visitCountBefore > 0); - visits.deleteAll(); + visits.removeAll(); assertEquals(0, visits.count()); } @@ -342,7 +342,7 @@ public void testNoCallbacksRegistered() { Integer insertedId = cities.insertAndFetchId(City.builder().name("NoCb").build()); assertNotNull(insertedId); cities.update(City.builder().id(insertedId).name("NoCbUpdated").build()); - cities.delete(City.builder().id(insertedId).name("NoCbUpdated").build()); + cities.remove(City.builder().id(insertedId).name("NoCbUpdated").build()); } // Batch update with joined entities and callbacks diff --git a/storm-core/src/test/java/st/orm/core/EntityRepositoryBatchIntegrationTest.java b/storm-core/src/test/java/st/orm/core/EntityRepositoryBatchIntegrationTest.java index 596e6de48..70fbe3eab 100644 --- a/storm-core/src/test/java/st/orm/core/EntityRepositoryBatchIntegrationTest.java +++ b/storm-core/src/test/java/st/orm/core/EntityRepositoryBatchIntegrationTest.java @@ -106,32 +106,32 @@ public void testBatchUpdatePersistsAllChanges() { // Delete @Test - public void testDeleteEntityRemovesIt() { + public void testRemoveEntityRemovesIt() { var orm = ORMTemplate.of(dataSource); var cities = orm.entity(City.class); var insertedId = cities.insertAndFetchId(City.builder().name("ToDelete").build()); long countBefore = cities.count(); - cities.delete(City.builder().id(insertedId).name("ToDelete").build()); + cities.remove(City.builder().id(insertedId).name("ToDelete").build()); assertEquals(countBefore - 1, cities.count()); // Verify the deleted city is actually gone. assertFalse(cities.findById(insertedId).isPresent()); } @Test - public void testDeleteByRefRemovesEntity() { + public void testRemoveByRefRemovesEntity() { var orm = ORMTemplate.of(dataSource); var cities = orm.entity(City.class); var insertedId = cities.insertAndFetchId(City.builder().name("RefDelete").build()); - cities.deleteByRef(Ref.of(City.class, insertedId)); + cities.removeByRef(Ref.of(City.class, insertedId)); assertFalse(cities.findById(insertedId).isPresent()); } @Test - public void testBatchDeleteRemovesAllSpecified() { + public void testBatchRemoveRemovesAllSpecified() { var orm = ORMTemplate.of(dataSource); var cities = orm.entity(City.class); @@ -139,7 +139,7 @@ public void testBatchDeleteRemovesAllSpecified() { var id2 = cities.insertAndFetchId(City.builder().name("BatchDel2").build()); long countBefore = cities.count(); - cities.delete(List.of( + cities.remove(List.of( City.builder().id(id1).name("BatchDel1").build(), City.builder().id(id2).name("BatchDel2").build() )); @@ -149,14 +149,14 @@ public void testBatchDeleteRemovesAllSpecified() { } @Test - public void testBatchDeleteByRefRemovesAllSpecified() { + public void testBatchRemoveByRefRemovesAllSpecified() { var orm = ORMTemplate.of(dataSource); var cities = orm.entity(City.class); var id1 = cities.insertAndFetchId(City.builder().name("RefBatchDel1").build()); var id2 = cities.insertAndFetchId(City.builder().name("RefBatchDel2").build()); - cities.deleteByRef(List.of( + cities.removeByRef(List.of( Ref.of(City.class, id1), Ref.of(City.class, id2) )); diff --git a/storm-core/src/test/java/st/orm/core/EntityRepositoryIntegrationTest.java b/storm-core/src/test/java/st/orm/core/EntityRepositoryIntegrationTest.java index 40c4374ee..96804a5da 100644 --- a/storm-core/src/test/java/st/orm/core/EntityRepositoryIntegrationTest.java +++ b/storm-core/src/test/java/st/orm/core/EntityRepositoryIntegrationTest.java @@ -51,48 +51,48 @@ public class EntityRepositoryIntegrationTest { // deleteById @Test - public void testDeleteById() { + public void testRemoveById() { var orm = ORMTemplate.of(dataSource); var cities = orm.entity(City.class); // Insert a new city so we can delete it without FK constraint issues. var id = cities.insertAndFetchId(City.builder().name("ToDelete").build()); long before = cities.count(); - cities.deleteById(id); + cities.removeById(id); assertEquals(before - 1, cities.count()); } @Test - public void testDeleteByIdNonExistent() { + public void testRemoveByIdNonExistent() { var orm = ORMTemplate.of(dataSource); var cities = orm.entity(City.class); - assertDoesNotThrow(() -> cities.deleteById(99999)); + assertDoesNotThrow(() -> cities.removeById(99999)); } // deleteByRef @Test - public void testDeleteByRef() { + public void testRemoveByRef() { var orm = ORMTemplate.of(dataSource); var cities = orm.entity(City.class); var id = cities.insertAndFetchId(City.builder().name("RefDelete").build()); long before = cities.count(); RefThis is used for queries where the result type {@code R} is not the same as the data type {@code T}, such as
- * ref queries ({@code R = Ref
{@code
- * MappedWindow, User> window = userRepository.selectRef().scroll(Scrollable.of(User_.id, 20));
- * if (window.hasNext()) {
- * MappedWindow, User> next = userRepository.selectRef().scroll(window.nextScrollable());
- * }
- * }
- *
- * The {@code nextScrollable} and {@code previousScrollable} navigation tokens are always provided when the window - * has content, regardless of whether {@code hasNext} or {@code hasPrevious} is {@code true}. This allows developers - * to follow the cursor even when no more results were detected at query time, which is useful for polling scenarios - * where new data may appear after the initial query. The {@code hasNext} and {@code hasPrevious} flags are - * informational: they indicate whether more results existed at the time of the query, but the decision to follow - * the cursor is left to the developer.
- * - * @param content the list of results in this window; never contains {@code null} elements. - * @param hasNext {@code true} if more results existed beyond this window in the scroll direction at query time. - * @param hasPrevious {@code true} if this window was fetched with a cursor position (i.e., not the first page). - * @param nextScrollable the scrollable to fetch the next window, or {@code null} if the window is empty. - * @param previousScrollable the scrollable to fetch the previous window, or {@code null} if the window is empty. - * @paramThis method is a convenience for REST APIs that want to include a cursor only when more results were - * detected. For polling or streaming use cases where you want to follow the cursor regardless, use - * {@link #nextScrollable()} directly.
- * - * @return the cursor string, or {@code null}. - * @see Scrollable#toCursor() - * @see Scrollable#fromCursor(Metamodel.Key, String) - */ - @Nullable - public String nextCursor() { - return hasNext && nextScrollable != null ? nextScrollable.toCursor() : null; - } - - /** - * Returns an opaque cursor string for fetching the previous window, or {@code null} if this is the first window - * according to {@link #hasPrevious()}. - * - *This method is a convenience for REST APIs that want to include a cursor only when previous results exist. - * For use cases where you want to follow the cursor regardless, use {@link #previousScrollable()} directly.
- * - * @return the cursor string, or {@code null}. - * @see Scrollable#toCursor() - * @see Scrollable#fromCursor(Metamodel.Key, String) - */ - @Nullable - public String previousCursor() { - return hasPrevious && previousScrollable != null ? previousScrollable.toCursor() : null; - } -} diff --git a/storm-foundation/src/main/java/st/orm/Page.java b/storm-foundation/src/main/java/st/orm/Page.java index 5a0c3b1a7..4fb47142d 100644 --- a/storm-foundation/src/main/java/st/orm/Page.java +++ b/storm-foundation/src/main/java/st/orm/Page.java @@ -35,7 +35,7 @@ * @paramA {@code Scrollable} is the scrolling counterpart of {@link Pageable}. While a {@code Pageable} navigates by * page number, a {@code Scrollable} navigates by cursor position. Scrollable instances are typically obtained from - * {@link Window#nextScrollable()} or {@link Window#previousScrollable()}, but can also be created directly using + * {@link Window#next()} or {@link Window#previous()}, but can also be created directly using * the factory methods.
* *The serialized cursor is opaque and URL-safe, but it is not tamper-proof. If the cursor is exposed to @@ -203,7 +203,7 @@ public boolean isComposite() { * *
{@code
* // Server: include cursor in response
- * String cursor = window.nextScrollable().toCursor();
+ * String cursor = window.nextCursor();
*
* // Client sends cursor back as query parameter
* // Server: reconstruct scrollable
diff --git a/storm-foundation/src/main/java/st/orm/Slice.java b/storm-foundation/src/main/java/st/orm/Slice.java
new file mode 100644
index 000000000..8b931dfb0
--- /dev/null
+++ b/storm-foundation/src/main/java/st/orm/Slice.java
@@ -0,0 +1,54 @@
+/*
+ * Copyright 2024 - 2026 the original author or authors.
+ *
+ * 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
+ *
+ * https://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.
+ */
+package st.orm;
+
+import jakarta.annotation.Nonnull;
+import java.util.List;
+
+/**
+ * Represents a slice of query results — a chunk of data with informational navigation flags.
+ *
+ * A {@code Slice} is the common base for both {@link Window} (cursor-based scrolling) and {@link Page}
+ * (offset-based pagination). It provides access to the result content and flags indicating whether adjacent
+ * results exist, without prescribing a specific navigation mechanism.
+ *
+ * @param the result type of the slice content.
+ * @since 1.11
+ */
+public interface Slice {
+
+ /**
+ * Returns the list of results in this slice. The list is immutable and never contains {@code null} elements.
+ *
+ * @return the results.
+ */
+ @Nonnull
+ List content();
+
+ /**
+ * Returns {@code true} if more results exist beyond this slice in the forward direction.
+ *
+ * @return whether more results exist.
+ */
+ boolean hasNext();
+
+ /**
+ * Returns {@code true} if results exist before this slice.
+ *
+ * @return whether previous results exist.
+ */
+ boolean hasPrevious();
+}
diff --git a/storm-foundation/src/main/java/st/orm/Window.java b/storm-foundation/src/main/java/st/orm/Window.java
index 96a32d032..a8d0bf7f3 100644
--- a/storm-foundation/src/main/java/st/orm/Window.java
+++ b/storm-foundation/src/main/java/st/orm/Window.java
@@ -22,27 +22,20 @@
import java.util.List;
/**
- * Represents a window of query results from a scrolling operation where the result type matches the data type.
+ * Represents a window of query results from a scrolling operation with {@link Scrollable} navigation tokens.
*
- * A {@code Window} is the scrolling counterpart of {@link Page}. While a {@code Page} contains total counts and
- * page numbers for offset-based navigation, a {@code Window} contains cursor-based navigation tokens that allow
- * sequential traversal through large result sets.
- *
- * This is the common case for entity and projection queries where the result type is the same as the data type.
- * For queries where the result type differs from the data type (e.g., ref queries), see {@link MappedWindow}.
- *
- * Use {@link #hasNext()} and {@link #nextScrollable()} to move forward, and {@link #hasPrevious()} and
- * {@link #previousScrollable()} to move backward. Pass the returned {@link Scrollable} to the repository's
- * {@code scroll} method to fetch the adjacent window.
+ * A {@code Window} implements {@link Slice} and provides cursor-based navigation for sequential traversal
+ * through large result sets. Use {@link #next()} and {@link #previous()} for typed programmatic navigation,
+ * or {@link #nextCursor()} and {@link #previousCursor()} for serialized cursor strings suitable for REST APIs.
*
* {@code
* Window window = userRepository.scroll(Scrollable.of(User_.id, 20));
* if (window.hasNext()) {
- * Window next = userRepository.scroll(window.nextScrollable());
+ * Window next = userRepository.scroll(window.next());
* }
* }
*
- * The {@code nextScrollable} and {@code previousScrollable} navigation tokens are always provided when the window
+ *
The {@link #next()} and {@link #previous()} navigation tokens are always provided when the window
* has content, regardless of whether {@code hasNext} or {@code hasPrevious} is {@code true}. This allows developers
* to follow the cursor even when no more results were detected at query time, which is useful for polling scenarios
* where new data may appear after the initial query. The {@code hasNext} and {@code hasPrevious} flags are
@@ -54,16 +47,17 @@
* @param hasPrevious {@code true} if this window was fetched with a cursor position (i.e., not the first page).
* @param nextScrollable the scrollable to fetch the next window, or {@code null} if the window is empty.
* @param previousScrollable the scrollable to fetch the previous window, or {@code null} if the window is empty.
- * @param the data type of both the results and the {@link Scrollable} navigation tokens.
+ * @param the result type (e.g., {@code User} for entity queries, {@code Ref} for ref queries).
* @since 1.11
*/
-public record Window(
- @Nonnull List content,
+public record Window(
+ @Nonnull List content,
boolean hasNext,
boolean hasPrevious,
- @Nullable Scrollable nextScrollable,
- @Nullable Scrollable previousScrollable
-) {
+ @Nullable Scrollable nextScrollable,
+ @Nullable Scrollable previousScrollable
+) implements Slice {
+
public Window {
content = copyOf(content);
}
@@ -71,23 +65,49 @@ public record Window(
/**
* Returns an empty window with no content and no navigation tokens.
*
- * @param the data type.
+ * @param the result type.
* @return an empty window.
*/
- public static Window empty() {
+ public static Window empty() {
return new Window<>(List.of(), false, false, null, null);
}
/**
- * Creates a {@code Window} from a {@link MappedWindow} where the result type matches the data type.
+ * Returns a typed scrollable for fetching the next window, or {@code null} if the window is empty.
+ *
+ * The type parameter {@code T} is inferred from the call-site context, typically from the
+ * {@code scroll(Scrollable)} method parameter:
+ *
+ * {@code
+ * Window next = userRepository.scroll(window.next());
+ * }
+ *
+ * @param the data type, inferred from context.
+ * @return the scrollable for the next window, or {@code null}.
+ */
+ @SuppressWarnings("unchecked")
+ @Nullable
+ public Scrollable next() {
+ return (Scrollable) nextScrollable;
+ }
+
+ /**
+ * Returns a typed scrollable for fetching the previous window, or {@code null} if the window is empty.
*
- * @param mappedWindow the mapped window to convert.
- * @param the data type.
- * @return a window with the same content and navigation tokens.
+ * The type parameter {@code T} is inferred from the call-site context, typically from the
+ * {@code scroll(Scrollable)} method parameter:
+ *
+ * {@code
+ * Window prev = userRepository.scroll(window.previous());
+ * }
+ *
+ * @param the data type, inferred from context.
+ * @return the scrollable for the previous window, or {@code null}.
*/
- public static Window of(@Nonnull MappedWindow mappedWindow) {
- return new Window<>(mappedWindow.content(), mappedWindow.hasNext(), mappedWindow.hasPrevious(),
- mappedWindow.nextScrollable(), mappedWindow.previousScrollable());
+ @SuppressWarnings("unchecked")
+ @Nullable
+ public Scrollable previous() {
+ return (Scrollable) previousScrollable;
}
/**
@@ -96,7 +116,7 @@ public static Window of(@Nonnull MappedWindow