Interface EntityList

All Superinterfaces:
Iterable<Entity>
All Known Subinterfaces:
Relation
All Known Implementing Classes:
AbstractEntityList, AbstractEntityListWrapper, AbstractLazyEntityList, AbstractRelationAdapter, AbstractSortedEntityList, EmptyEntityList, EntityListImpl, FilteredEntityList, KeyListSortedEntityList, KeySortedEntityList, LazyEntityList, MemoryEfficientLazyEntityList, MultiEntityList, OffsetEntityList, PrimaryKeyEntityList, SingletonEntityList, ToManyRelationAdapter, ToOneRelationAdapter, ValueSortedEntityList

public interface EntityList extends Iterable<Entity>
A list of (possibly hollow) entities.

The list is either the result from Queries, or from one of the wrapper creators in EntityLists.

Implementations may be of fixed size and immutable, or resizable and modifiable. They may contain entities of state conception, or not.

  • Method Details

    • size

      int size()
      Get the number of entities this list contains.
      Returns:
      The number of entities.
    • isEmpty

      boolean isEmpty()
      Same as size() == 0
      Returns:
      If the list is empty.
    • getKeys

      PrimaryKey[] getKeys()
      Read in subclasses if this array can contain null values or not.
      Returns:
      A defensive copy of the array. The size matches the size() method.
    • get

      Entity get(int index)
      Get the entity at the specified index with eager loading.

      This method will load a full page if the entity is currently hollow.

      Parameters:
      index - The index.
      Returns:
      The entity at the specified index potentially in unusable state, or null.
    • get

      Entity get(PrimaryKey key)
      Get the entity with the specified key in that list with eager loading.
      Returns:
      The entity potentially in unusable state, or null.
      See Also:
    • get

      Entity get(int index, boolean eager)
      Get the entity at the specified index.
      Parameters:
      index - The index.
      eager - true, if a page should be eagerly loaded, if the entity's state is hollow, false otherwise.
      Returns:
      The entity at the specified index potentially in unusable state, or null.
    • get

      Entity get(PrimaryKey key, boolean eager)
      Get the entity with the specified key in that list.
      Parameters:
      key - The key of the entity.
      eager - true, if a page should be eagerly loaded, if the entity's state is hollow, false otherwise.
      Returns:
      The entity with the specified key potentially in unusable state, or null.
    • toList

      List<Entity> toList()
      Returns the Entities of this list in a List using eager loading.
    • toList

      Deprecated.
      Returns the Entities of this list in a List using eager loading.
    • getKey

      PrimaryKey getKey(int index)
      Returns the PrimaryKey at the specified position.
      Throws:
      IndexOutOfBoundsException - Obvious.
    • indexOf

      int indexOf(PrimaryKey key)
      Get the index within the list of the entity with the specified key.
      Parameters:
      key - The primary key.
      Returns:
      The index or -1, if there's no such entity in the list.
    • contains

      boolean contains(PrimaryKey key)
      Determine, whether the list contains an entity with the specified key.
      Parameters:
      key - The primary key.
      Returns:
      true, if there's an entity with the specified key, false otherwise.
    • expect

      EntityList expect(int amount)
      Throws if the list does not contain exactly that amount.

      Example: EntityList entityList = myQuery.execute(1).expect(1);

      Parameters:
      amount - The expected amount.
      Returns:
      The list itself.
      See Also:
    • expectAtLeast

      EntityList expectAtLeast(int min)
      Throws if the list contains fewer than min items.

      Example: EntityList entityList = myQuery.execute().expectAtLeast(3);

      Parameters:
      min - The expected minimal amount, including.
      Returns:
      The list itself.
      See Also:
    • expectAtMost

      EntityList expectAtMost(int max)
      Throws if the list contains more than max items.

      Example: EntityList entityList = myQuery.execute(3).expectAtMost(3);

      Parameters:
      max - The expected maximal amount, including.
      Returns:
      The list itself.
      See Also:
    • expectOr

      default <T> T expectOr(int expectedSize, Function<EntityList,T> function, Function<EntityList,T> otherwise)
      Parameters:
      expectedSize - The expected size of the collection
      function - Function to run if the size is as expected
      otherwise - Function to run if the size is different
      Returns:
      result of the executed function
    • getOnlyResult

      default Entity getOnlyResult()
      Returns:
      the only result of this EntityList
      Throws:
      PermanentPersistException - If the result count is not one
    • getOptionalOnlyResult

      default Optional<Entity> getOptionalOnlyResult()
      Returns:
      the only result or an empty Optional if there are no results
      Throws:
      PermanentPersistException - if there are multiple results
    • getOptionalOnlyResult

      default <T extends Exception> Optional<Entity> getOptionalOnlyResult(Supplier<T> exceptionSupplier) throws T
      Parameters:
      exceptionSupplier - Exception Supplier for the exception to be thrown if there are multiple results
      Returns:
      the only result or an empty Optional if there are no results
      Throws:
      T - if there are multiple results
    • expectOrThrow

      default <T extends Exception> EntityList expectOrThrow(int expectedSize, Supplier<T> exceptionSupplier) throws T
      Parameters:
      expectedSize - The expected size of the collection
      exceptionSupplier - Supplier which creates the exception to be thrown if the size is different
      Returns:
      the EntityList if the size is as expected
      Throws:
      T
    • doWithSingleResult

      default <T> T doWithSingleResult(Function<Entity,T> function)
      execute given function if there is exactly one result, otherwise throw an exception
      Parameters:
      function - Function to execute
      Returns:
      result of the given function
    • doWithSingleResultOr

      default <T> T doWithSingleResultOr(Function<Entity,T> function, Function<EntityList,T> otherwise)
      execute a given function if there is only one result or another function otherwise
      Parameters:
      function - Function to run if there is only one result
      otherwise - Function to run otherwise
      Returns:
      the result of the executed Function
    • expectAtMostOrThrow

      default <T extends Exception> EntityList expectAtMostOrThrow(int max, Supplier<T> exception) throws T
      Parameters:
      max - Maximum expected rows
      exception - Exception Supplier which creates an exception to be thrown otherwise
      Returns:
      the EntityList
      Throws:
      T
    • getModel

      EntityModel getModel()
      Get the model of the entity type contained in this list.
      Returns:
      The model of the entity type contained in this list.
    • getManager

      EntityManager getManager()
      Get the entity manager.
      Returns:
      The entity manager.
    • unwrap

      EntityList unwrap()
      Unwrap to the underlying entity list.

      Wrappers of entity lists should delegate this to the list they're wrapping, implementations return this. It may be that they cannot, and then return themselves (MultiEntityList).

      Returns:
      The underlying entity list implementation.
    • setPageSize

      @Deprecated void setPageSize(int pageSize)
      Deprecated.
      Set the page size. The page size determines how many objects will be loaded, once a hollow entity has been accessed.
      Parameters:
      pageSize - The new page size.
    • getPageSize

      @Deprecated int getPageSize()
      Deprecated.
      Get the current page size.
      Returns:
      The current page size.
    • getPageCount

      @Deprecated int getPageCount()
      Deprecated.
      Get the number of pages in this list.
      Returns:
      The number of pages in this list (size/pageSize + (size%pageSize>0 ? 1 : 0)).
    • spliterator

      default Spliterator<Entity> spliterator()
      Specified by:
      spliterator in interface Iterable<Entity>
    • stream

      default Stream<Entity> stream()
      Important note: Please do *not* use methods like: * Stream.filter(Predicate) * Stream.sorted(java.util.Comparator) for things which can be done with query (on database).
    • getFirstEntity

      @Nullable default @Nullable Entity getFirstEntity()
      Returns:
      the first entity or null
    • requireFirstEntity

      default Entity requireFirstEntity()
      Returns:
      the first entity