Package de.espirit.or

Interface Session

public interface Session
Session is the entry point for a connection to a database. The meta data (schema) for the session is available via getSchema(). To create new entites (i.e. database entries) call createEntity(String), providing an entity type name. To retrive existing entities use on of the 'find' methods (find(String, Object...), findNotNull(String, Object...), etc.) or use a select to execute a query to retrieve a list of entities. To delete an entity call delete(Entity).
All changes are persisted to the database when you call commit(). Prior to commit() no database locks are held with exception of read locks when an entity is explicitly or transparently (re)loaded. You may also rollback() all changes. The set of changed entities could be requested by calling getChanged(). This will return an empty collection if hasChanges() delivers false.
A session may be read-only, then every modification will be rejected.
Schema changes may be synced to the database.
Most methods may throw the (unchecked) ORException.
Since:
4.0.17

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addSessionListener(@NotNull de.espirit.or.SessionListener listener)
    Add the listener to this session.
    void
    close()
    Close the session and release all used resources.
    void
    commit()
    Make all changes since the last commit or rollback persistent.
    void
    commit(String comment)
    Make all changes since the last commit or rollback persistent with the given comment as revision comment.
    @NotNull Entity
    createEntity(@NotNull String type)
    Create a new entity of the given type
    @NotNull Select
    createSelect(@NotNull String name)
    Create a select for the entity type with the provided name.
    void
    delete(@NotNull Entity entity)
    Mark the entity as deleted.
    @NotNull EntityList
    executeQuery(@NotNull Select select)
    Execute the provided query and returns the matching entities.
    Schema
    extractSchemaFromDB(String schemaName)
    Update the assigned schema with the structure of DB schema schemaName.
    IdentifierList<UUID,Entity>
    fetchEntities(@NotNull String entityTypeName, @NotNull Collection<UUID> entityGids)
    Fetches all entities specified by given gids.
    Attention: List could contain null entries for gids no entity could be found for.
    @Nullable Entity
    find(@NotNull EntityType type, String uuid)
    Returns the entity specififed by given EntityType and uuid string
    Important: Only supported if the schema is temporal.
    @Nullable Entity
    find(@NotNull EntityType type, UUID uuid)
    Returns the entity specififed by given EntityType and uuid.
    @NotNull Entity
    find(@NotNull Identifier identifier)
    Return the entity with the given identifier.
    @Nullable Entity
    find(@NotNull KeyValue keyValue)
    Return the entity with the given keyValue.
    @Nullable Entity
    find(@NotNull String entityTypeName, @NotNull Object... key)
    Return the entity of type entityTypeName with the id key.
    @NotNull Entity
    findNotNull(@NotNull KeyValue keyValue)
    Returns an entity with the given keyValue even if it doesn't exist.
    @NotNull Entity
    findNotNull(@NotNull String entityTypeName, @NotNull Object... key)
    Returns an entity of type entityTypeName with the id key even if it doesn't exists.
    Set<Entity>
    getChanged()
    Return the set of modified and not yet committed entities in this session.
    @NotNull List<Entity>
    getDeletedEntities(@NotNull String entityTypeName)
    Get all deleted entities from type entityTypeName.
    @NotNull List<Entity>
    getHistory(@NotNull KeyValue keyValue)
    Return the history of the entity with the given keyValue.
    @NotNull List<Entity>
    getInvalidEntities(@NotNull KeyValue keyValue)
    Return a list of invalid entities of the given keyValue.
    long
    getLastChangeTime(@NotNull Select select)
    Get the timestamp of the last change of the result set of the specified select.
    long
    getLastChangeTime(@NotNull Select select, long after)
    Get the timestamp of the last change of the result set of the specified select after the specified timestamp.
    @NotNull Set<KeyValue>
    getReleasedDeleted(@NotNull String entityTypeName)
    Get the key values of all entities of the given entity type which are deleted but still released.
    @NotNull Schema
    getSchema()
    Return the schema assigned with this session.
    boolean
    hasChanges()
    Returns true if there are uncommitted changes, see commit and rollback.
    boolean
    isReadOnly()
    If the session is read only no modifications are permitted.
    boolean
    isRelease()
    Return true if this session is a release session else false.
    boolean
    refresh()
    Refresh the session if there are no uncommitted changes.
    void
    release(@NotNull Entity entity)
    Release the given entity.
    void
    removeSessionListener(@NotNull de.espirit.or.SessionListener listener)
    Remove the listener from this session.
    void
    restore(@NotNull Identifier identifier)
    Restore the deleted entity with the specified identifier.
    void
    rollback()
    Undo all changes since the last commit or rollback.
    Schema
    syncSchemaWithDB(@NotNull Schema schema, boolean createKeys)
    Update the database structure with the given schema.
    @NotNull Select
    xml2Select(@NotNull String queryXml)
    Construct a select from the xml document queryXml.

  • Method Details

    • getSchema

      @NotNull @NotNull Schema getSchema()
      Return the schema assigned with this session.
      Since:
      4.0.17

    • createEntity

      @NotNull @NotNull Entity createEntity(@NotNull @NotNull String type)
      Create a new entity of the given type
      Since:
      4.0.17

    • find

      @Nullable @Nullable Entity find(@NotNull @NotNull KeyValue keyValue)
      Return the entity with the given keyValue.
      Since:
      4.0.17

    • findNotNull

      @NotNull @NotNull Entity findNotNull(@NotNull @NotNull KeyValue keyValue)
      Returns an entity with the given keyValue even if it doesn't exist. In that case the entity's state is NOT_EXISTS.
      Since:
      4.1.2

    • find

      @Nullable @Nullable Entity find(@NotNull @NotNull String entityTypeName, @NotNull @NotNull Object... key)
      Return the entity of type entityTypeName with the id key.
      Parameters:
      entityTypeName - Name of the target entity type.
      key - Primary key values.
      Since:
      4.0.17

    • findNotNull

      @NotNull @NotNull Entity findNotNull(@NotNull @NotNull String entityTypeName, @NotNull @NotNull Object... key)
      Returns an entity of type entityTypeName with the id key even if it doesn't exists. In that case the entity's state is NOT_EXISTS.
      Parameters:
      entityTypeName - Name of the target entity type.
      key - Primary key values.
      Since:
      4.1.2

    • find

      @Nullable @Nullable Entity find(@NotNull @NotNull EntityType type, String uuid)
      Returns the entity specififed by given EntityType and uuid string
      Important: Only supported if the schema is temporal.
      Parameters:
      type - Target entity type.
      uuid - UUID as string.
      Since:
      5.0.100
      See Also:

    • find

      @Nullable @Nullable Entity find(@NotNull @NotNull EntityType type, UUID uuid)
      Returns the entity specififed by given EntityType and uuid.
      Important: Only supported if the schema is temporal.
      Parameters:
      type - Target entity type.
      uuid - UUID as object.
      Since:
      5.0.100
      See Also:

    • find

      @NotNull @NotNull Entity find(@NotNull @NotNull Identifier identifier)
      Return the entity with the given identifier.
      Important: Keep in mind the difference between an Identifier and KeyValue for a temporal schema, use find(KeyValue) if possible.
      Since:
      4.0.17

    • createSelect

      @NotNull @NotNull Select createSelect(@NotNull @NotNull String name)
      Create a select for the entity type with the provided name.
      Parameters:
      name - Enity type name.
      Since:
      4.0.17

    • xml2Select

      @NotNull @NotNull Select xml2Select(@NotNull @NotNull String queryXml)
      Construct a select from the xml document queryXml.
      Parameters:
      queryXml - Xml string describing the select statement.
      Since:
      4.0.17

    • delete

      void delete(@NotNull @NotNull Entity entity)
      Mark the entity as deleted. The state of the entity will change to Entity.PersistentState.DELETING. The change is persisted with the next commit().
      Parameters:
      entity - Entity to delete.
      Since:
      4.0.17

    • executeQuery

      @NotNull @NotNull EntityList executeQuery(@NotNull @NotNull Select select)
      Execute the provided query and returns the matching entities. The items of the result list are loaded lazy when requested.
      Parameters:
      select - Select statement.
      Returns:
      A list of entities.
      Since:
      4.0.17
      See Also:

    • fetchEntities

      IdentifierList<UUID,Entity> fetchEntities(@NotNull @NotNull String entityTypeName, @NotNull @NotNull Collection<UUID> entityGids)
      Fetches all entities specified by given gids.
      Attention: List could contain null entries for gids no entity could be found for.
      Since:
      5.0.412

    • getDeletedEntities

      @NotNull @NotNull List<Entity> getDeletedEntities(@NotNull @NotNull String entityTypeName)
      Get all deleted entities from type entityTypeName.
      Since:
      4.0.19

    • getReleasedDeleted

      @NotNull @NotNull Set<KeyValue> getReleasedDeleted(@NotNull @NotNull String entityTypeName)
      Get the key values of all entities of the given entity type which are deleted but still released.
      For a non-temporal schema this method delivers an empty set.
      Parameters:
      entityTypeName - Entity type to filter on.
      Returns:
      A collection of keys of matching entities.
      Since:
      4.0.91

    • getInvalidEntities

      @NotNull @NotNull List<Entity> getInvalidEntities(@NotNull @NotNull KeyValue keyValue)
      Return a list of invalid entities of the given keyValue.
      For a non-temporal schema this method delivers an empty list.
      Parameters:
      keyValue - Key of the entity.
      Returns:
      A history of changes for the specified entity.
      Since:
      4.0.22
      See Also:

    • getHistory

      @NotNull @NotNull List<Entity> getHistory(@NotNull @NotNull KeyValue keyValue)
      Return the history of the entity with the given keyValue. In contrast to getInvalidEntities(de.espirit.or.schema.KeyValue) the returned list includes the also the most actual value of the entity.
      For non-temporal schema this method delivers an empty list.
      Parameters:
      keyValue - Key of the entity.
      Returns:
      A history of changes for the specified entity.
      Since:
      4.2.44
      See Also:

    • restore

      void restore(@NotNull @NotNull Identifier identifier)
      Restore the deleted entity with the specified identifier.
      Important: Only supported if the schema is temporal.
      Parameters:
      identifier - Identifier of entity to restore.
      Since:
      4.0.20

    • rollback

      void rollback()
      Undo all changes since the last commit or rollback.
      Since:
      4.0.17

    • refresh

      boolean refresh()
      Refresh the session if there are no uncommitted changes. The operation itself is fast, but invalidates already loaded entities so that they are re-loaded on the next access.
      Returns:
      true if refresh was performed, false if refresh is skipped because there are uncommitted changes.
      Since:
      5.2.501
      See Also:

    • commit

      void commit()
      Make all changes since the last commit or rollback persistent.
      Since:
      4.0.17

    • commit

      void commit(String comment)
      Make all changes since the last commit or rollback persistent with the given comment as revision comment.
      Parameters:
      comment - Revision comment.
      Since:
      4.0.27

    • close

      void close()
      Close the session and release all used resources. All pending changes are be committed.
      Since:
      4.0.17

    • release

      void release(@NotNull @NotNull Entity entity)
      Release the given entity. The state of the entity will change to Entity.PersistentState.RELEASING, the operation will be made persistent with the next commit.
      Important: Only supported if the schema is temporal.
      Parameters:
      entity - Entity to release.
      Since:
      4.0.17

    • isRelease

      boolean isRelease()
      Return true if this session is a release session else false. All entities manages by a release session must be in the release state. A release session supports only the delete and find / select operations.
      All other operations e.g. like create a new entity createEntity(String), create a new schema form the database extractSchemaFromDB(String) and update the database structure syncSchemaWithDB(Schema, boolean) are not supported.
      An UnsupportedOperationException will be thrown if these methods are called in a release session.
      Important: Only supported if the schema is temporal.
      Returns:
      true if this session operates on the release state, else false.
      Since:
      4.0.17

    • extractSchemaFromDB

      Schema extractSchemaFromDB(String schemaName)
      Update the assigned schema with the structure of DB schema schemaName.
      Parameters:
      schemaName - Name of schema to extract.
      Since:
      4.0.17

    • syncSchemaWithDB

      Schema syncSchemaWithDB(@NotNull @NotNull Schema schema, boolean createKeys)
      Update the database structure with the given schema. If importMode is true then no primary and foreign keys are created during the sync.
      Parameters:
      schema - Schema containing the structure to sync with the database.
      createKeys - Create keys in the database.
      Since:
      4.0.17

    • isReadOnly

      boolean isReadOnly()
      If the session is read only no modifications are permitted.
      Returns:
      true if no changes are permitted through this session instance.
      Since:
      4.0.17

    • hasChanges

      boolean hasChanges()
      Returns true if there are uncommitted changes, see commit and rollback.
      Returns:
      true if there are pending changes.
      Since:
      4.0.17
      See Also:

    • getChanged

      Set<Entity> getChanged()
      Return the set of modified and not yet committed entities in this session.
      Returns:
      Set of modified and not yet commited entities.
      Since:
      4.0.17

    • getLastChangeTime

      long getLastChangeTime(@NotNull @NotNull Select select)
      Get the timestamp of the last change of the result set of the specified select. Only changes of the result entity type are considered.
      Important: Only supported if the schema is temporal.
      Parameters:
      select - Select statement.
      Returns:
      Time stamp of last change of all matching entities.
      Since:
      4.0.19

    • getLastChangeTime

      long getLastChangeTime(@NotNull @NotNull Select select, long after)
      Get the timestamp of the last change of the result set of the specified select after the specified timestamp. Only changes of the result entity type are considered.
      Only supported for temporal schema.
      Parameters:
      select - Select statement.
      after - Additional time stamp restriction.
      Returns:
      Time stamp of last change of all matching entities.
      Since:
      4.2.400
      See Also:

    • addSessionListener

      void addSessionListener(@NotNull @NotNull de.espirit.or.SessionListener listener)
      Add the listener to this session.
      Parameters:
      listener - Listener to add.
      Since:
      4.0.17

    • removeSessionListener

      void removeSessionListener(@NotNull @NotNull de.espirit.or.SessionListener listener)
      Remove the listener from this session.
      Parameters:
      listener - Listener to remove.
      Since:
      4.0.17