Package ch.tocco.nice2.persist.core.api.entity

Interface Relation

All Superinterfaces:
EntityList, Iterable<Entity>
All Known Implementing Classes:
AbstractRelationAdapter, ToManyRelationAdapter, ToOneRelationAdapter
public interface Relation extends EntityList
A specialised entity list returned by RelationQueries.

This adds methods to manipulate the relation, making the list mutable. Also it may contain entities in state conception.

NOTE: The relation remains the way it is once you got it. It will not be changed magically behind your back. Updates to the relation (in persistence) do not write through to this snapshot. This is in contrast to the Entity.

WARNING: atm a commit leaves this list in an outdated state. It may still contain entries of entities that were deleted meanwhile, and entities that were in state conception and had no PK before the commit. Thus one really should re-query the relation after a commit. This will be changed at some point so that the relation will continue working after the commit the way it was before the commit.

  • Method Details

    • add

      void add(Entity entity)
      Add an entity to the relation.

      If the entity is in the relation already then the call is ignored; no exception thrown, no events fired. (i'm sure about the exception, but not about the events. -andrej)

      If this is a to-one relation then you are advised to use the set(ch.tocco.nice2.persist.core.api.entity.Entity) method. If you still decide to use add() then you also need to call remove() with the old value if there was an entity linked already. set(ch.tocco.nice2.persist.core.api.entity.Entity) takes care of all this for you.

      Parameters:
      entity - The entity to be added, may be in state conception.

    • remove

      void remove(Entity entity)
      Remove an entity from the relation.

      TODO document what happens when the entity is not in the relation.

      Parameters:
      entity - The entity to be removed, may be in state conception.

    • set

      void set(Entity entity)
      Set the relation's entities to the specified single entity. Any other entities will be removed. This method may only be called for relations to a single entity (n-1).

      NOTE: This calls remove(ch.tocco.nice2.persist.core.api.entity.Entity) and add(ch.tocco.nice2.persist.core.api.entity.Entity) internally. That's also why the interceptor does not have this.

      Parameters:
      entity - The entity to be set, may be in state conception.

    • set

      void set(Iterable<Entity> entities)
      Creates an intersection of the currently linked ones and the given ones, and then calls remove(ch.tocco.nice2.persist.core.api.entity.Entity) and add(ch.tocco.nice2.persist.core.api.entity.Entity) in a loop.
      Parameters:
      entities - The list of entities that will be the only linked ones.

    • clear

      void clear()
      Removes all entities in this relation. Does the same as calling remove() for all linked entities.

    • get

      @Nullable @Nullable Entity get()
      Get the current single target entity of this relation. This method may only be called for relations to a single entity (n-1).
      Returns:
      The current single target entity potentially in unusable state, or null.

    • get

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

    • get

      @Nullable @Nullable Entity get(PrimaryKey key, boolean eager)
      Note that this cannot be used for entities in state conception for they have a null PK.

      WARNING: Also, don't use it after a commit when the conception entities got a PK from the backend. This list won't know about the new PK, it is out of sync, see class header! (subject to change)

      Specified by:
      get in interface EntityList
      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 potentially in unusable state, or null.
      See Also:

    • expect

      Relation expect(int amount)
      Description copied from interface: EntityList
      Throws if the list does not contain exactly that amount.

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

      Specified by:
      expect in interface EntityList
      Parameters:
      amount - The expected amount.
      Returns:
      The list itself.
      See Also:

    • expectAtLeast

      Relation expectAtLeast(int min)
      Description copied from interface: EntityList
      Throws if the list contains fewer than min items.

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

      Specified by:
      expectAtLeast in interface EntityList
      Parameters:
      min - The expected minimal amount, including.
      Returns:
      The list itself.
      See Also:

    • expectAtMost

      Relation expectAtMost(int max)
      Description copied from interface: EntityList
      Throws if the list contains more than max items.

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

      Specified by:
      expectAtMost in interface EntityList
      Parameters:
      max - The expected maximal amount, including.
      Returns:
      The list itself.
      See Also:

    • expectOrThrow

      default <T extends Exception> Relation expectOrThrow(int expectedSize, Supplier<T> exceptionSupplier) throws T
      Specified by:
      expectOrThrow in interface EntityList
      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

    • expectAtMostOrThrow

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

    • getSource

      Entity getSource()

    • getRelationModel

      RelationModel getRelationModel()

    • unwrap

      Relation unwrap()
      Description copied from interface: EntityList
      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).

      Specified by:
      unwrap in interface EntityList
      Returns:
      The underlying entity list implementation.

    • getKeys

      PrimaryKey[] getKeys()
      WARNING: this impl may return null entries! This happens when entities of state conception are in the list. Also, after a commit this data is outdated, see class header.
      Specified by:
      getKeys in interface EntityList
      Returns:
      A defensive copy of the array. The size matches the EntityList.size() method.