Package org.neo4j.ogm.session

Interface Session

All Known Implementing Classes:
Neo4jSession
public interface Session
A Session serves as the main point of integration for the Neo4j OGM. All the publicly-available capabilities of the framework are defined by this interface. Instances of Session are not thread safe. In a typical application scenario there should be a Session instance per thread. A broader scope may be chosen, but the access to the Session must be synchronized externally.

Load methods

Methods load(java.lang.Class, java.io.Serializable) load single instance of class by id.
Methods loadAll(java.lang.Class, java.util.Collection) load multiple instances of same class by ids. Note that if an entity with id is not found it is simply omitted from the results.
Methods loadAll(java.lang.Class, org.neo4j.ogm.cypher.Filter) queries multiple instances of class by filter

Load and save depth parameter

The depth parameter tells OGM how many steps to follow when loading or saving entities. Each relationship counts as one step (regardless type - simple relationship or RelationshipEntity). When loading entities the depth parameter is reflected by the query (also see LoadStrategy). When saving entities the depth parameter defines a horizon from root entity for checking for modified entities.

Session cache

When loading entities already present in Session following happens:
  • cached instance of the entity is returned
  • all property fields are set to original values - even when loaded entity is updated
  • relationship fields are merged with loaded relationships - new relationships may be added to existing relationship collections
If new state of the entity is required when reloading, use clear() to clear current session before reload.
Author:
Vince Bickers, Luanne Misquitta, Mark Angrish, Frantisek Hartman
See Also:

  • Method Details

    • loadAll

      <T, ID extends Serializable> Collection<T> loadAll(Class<T> type, Collection<ID> ids)
      Load entities of type by their ids, with default depth = 1.
      Parameters:
      type - type of entities
      ids - ids of entities to load
      Returns:
      collection of entities

    • loadAll

      <T, ID extends Serializable> Collection<T> loadAll(Class<T> type, Collection<ID> ids, int depth)
      Load entities of type by their ids.
      Parameters:
      type - type of entities
      ids - ids of entities to load
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T, ID extends Serializable> Collection<T> loadAll(Class<T> type, Collection<ID> ids, SortOrder sortOrder)
      Load entities of type by their ids, with default depth = 1.
      Parameters:
      type - type of entities
      ids - ids of entities to load
      sortOrder - sort order
      Returns:
      collection of entities

    • loadAll

      <T, ID extends Serializable> Collection<T> loadAll(Class<T> type, Collection<ID> ids, SortOrder sortOrder, int depth)
      Load entities of type by their ids.
      Parameters:
      type - type of entities
      ids - ids of entities to load
      sortOrder - sort order
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T, ID extends Serializable> Collection<T> loadAll(Class<T> type, Collection<ID> ids, Pagination pagination)
      Load entities of type by their ids, with default depth = 1.
      Parameters:
      type - type of entities
      ids - ids of entities to load
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T, ID extends Serializable> Collection<T> loadAll(Class<T> type, Collection<ID> ids, Pagination pagination, int depth)
      Load entities of type by their ids.
      Parameters:
      type - type of entities
      ids - ids of entities to load
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T, ID extends Serializable> Collection<T> loadAll(Class<T> type, Collection<ID> ids, SortOrder sortOrder, Pagination pagination)
      Load entities of type by their ids, with default depth = 1.
      Parameters:
      type - type of entities
      ids - ids of entities to load
      sortOrder - sort order
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T, ID extends Serializable> Collection<T> loadAll(Class<T> type, Collection<ID> ids, SortOrder sortOrder, Pagination pagination, int depth)
      Load entities of type by their ids.
      Parameters:
      type - type of entities
      ids - ids of entities to load
      sortOrder - sort order
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Collection<T> objects)
      Load entities by themselves - uses id of the entity to load it again, with default depth = 1. Note that standard session behaviour regarding entity loading an reloading applies.
      Parameters:
      objects - objects
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Collection<T> objects, int depth)
      Load entities by themselves - uses id of the entity to load it again. Note that standard session behaviour regarding entity loading an reloading applies.
      Parameters:
      objects - objects
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Collection<T> objects, SortOrder sortOrder)
      Load entities by themselves - uses id of the entity to load it again, with default depth = 1. Note that standard session behaviour regarding entity loading an reloading applies.
      Parameters:
      objects - objects
      sortOrder - sort order
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Collection<T> objects, SortOrder sortOrder, int depth)
      Load entities by themselves - uses id of the entity to load it again. Note that standard session behaviour regarding entity loading an reloading applies.
      Parameters:
      objects - objects
      sortOrder - sort order
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Collection<T> objects, Pagination pagination)
      Load entities by themselves - uses id of the entity to load it again, with default depth = 1. Note that standard session behaviour regarding entity loading an reloading applies.
      Parameters:
      objects - objects
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Collection<T> objects, Pagination pagination, int depth)
      Load entities by themselves - uses id of the entity to load it again. Note that standard session behaviour regarding entity loading an reloading applies.
      Parameters:
      objects - objects
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Collection<T> objects, SortOrder sortOrder, Pagination pagination)
      Load entities by themselves - uses id of the entity to load it again, with default depth = 1. Note that standard session behaviour regarding entity loading an reloading applies.
      Parameters:
      objects - objects
      sortOrder - sort order
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Collection<T> objects, SortOrder sortOrder, Pagination pagination, int depth)
      Load entities by themselves - uses id of the entity to load it again. Note that standard session behaviour regarding entity loading an reloading applies.
      Parameters:
      objects - objects
      sortOrder - sort order
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type)
      Load all entities of type, with default depth = 1.
      Parameters:
      type - type of entities
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, int depth)
      Load all entities of type, with depth
      Parameters:
      type - type of entities
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, SortOrder sortOrder)
      Load all entities of type, with default depth = 1
      Parameters:
      type - type of entities
      sortOrder - sort order
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, SortOrder sortOrder, int depth)
      Load all entities of type.
      Parameters:
      type - type of entities
      sortOrder - sort order
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Pagination pagination)
      Load all entities of type, with default depth = 1.
      Parameters:
      type - type of entities
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Pagination pagination, int depth)
      Load all entities of type.
      Parameters:
      type - type of entities
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, SortOrder sortOrder, Pagination pagination)
      Load all entities of type, with default depth = 1.
      Parameters:
      type - type of entities
      sortOrder - sort order
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, SortOrder sortOrder, Pagination pagination, int depth)
      Load all entities of type.
      Parameters:
      type - type of entities
      sortOrder - sort order
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filter filter)
      Load all entities of type, filtered by filter, with default depth = 1.
      Parameters:
      type - type of entities
      filter - filter
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filter filter, int depth)
      Load all entities of type, filtered by filter.
      Parameters:
      type - type of entities
      filter - filter
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filter filter, SortOrder sortOrder)
      Load all entities of type, filtered by filter, with default depth = 1.
      Parameters:
      type - type of entities
      filter - filter
      sortOrder - sort order
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filter filter, SortOrder sortOrder, int depth)
      Load all entities of type, filtered by filter.
      Parameters:
      type - type of entities
      filter - filter
      sortOrder - sort order
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filter filter, Pagination pagination)
      Load all entities of type, filtered by filter, with default depth = 1.
      Parameters:
      type - type of entities
      filter - filter
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filter filter, Pagination pagination, int depth)
      Load all entities of type, filtered by filter.
      Parameters:
      type - type of entities
      filter - filter
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filter filter, SortOrder sortOrder, Pagination pagination)
      Load all entities of type, filtered by filter, with default depth = 1.
      Parameters:
      type - type of entities
      filter - filter
      sortOrder - sort order
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filter filter, SortOrder sortOrder, Pagination pagination, int depth)
      Load all entities of type, filtered by filter.
      Parameters:
      type - type of entities
      filter - filter
      sortOrder - sort order
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filters filters)
      Load all entities of type, filtered by filters, with default depth = 1.
      Parameters:
      type - type of entities
      filters - filters
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filters filters, int depth)
      Load all entities of type, filtered by filters.
      Parameters:
      type - type of entities
      filters - filters
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filters filters, SortOrder sortOrder)
      Load all entities of type, filtered by filters, with default depth = 1.
      Parameters:
      type - type of entities
      filters - filters
      sortOrder - sort order
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filters filters, SortOrder sortOrder, int depth)
      Load all entities of type, filtered by filters.
      Parameters:
      type - type of entities
      filters - filters
      sortOrder - sort order
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filters filters, Pagination pagination)
      Load all entities of type, filtered by filters, with default depth = 1.
      Parameters:
      type - type of entities
      filters - filters
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filters filters, Pagination pagination, int depth)
      Load all entities of type, filtered by filters.
      Parameters:
      type - type of entities
      filters - filters
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filters filters, SortOrder sortOrder, Pagination pagination)
      Load all entities of type, filtered by filters, with default depth = 1.
      Parameters:
      type - type of entities
      filters - filters
      sortOrder - sort order
      pagination - pagination
      Returns:
      collection of entities

    • loadAll

      <T> Collection<T> loadAll(Class<T> type, Filters filters, SortOrder sortOrder, Pagination pagination, int depth)
      Load all entities of type, filtered by filters.
      Parameters:
      type - type of entities
      filters - filters
      sortOrder - sort order
      pagination - pagination
      depth - depth
      Returns:
      collection of entities

    • load

      <T, ID extends Serializable> T load(Class<T> type, ID id)
      Load single entity instance of type, with default depth = 1
      Returns:
      entity instance, null if not found

    • load

      <T, ID extends Serializable> T load(Class<T> type, ID id, int depth)
      Load single entity instance of type, with depth
      Returns:
      entity instance, null if not found

    • save

      <T> void save(T object)
      Save entity(or entities) into the database, up to specified depth The entities are either created or updated. When new objects are saved and the objects have a field that is mapped with Id using the internal Id-generation-strategy, those fields are modified and set to the internal graph-id.
      Parameters:
      object - object to save, may be single entity, array of entities or Iterable

    • save

      <T> void save(T object, int depth)
      Save entity(or entities) into the database, up to specified depth The objects are either created or updated. When new objects are saved and the objects have a field that is mapped with Id using the internal Id-generation-strategy, those fields are modified and set to the internal graph-id.
      Parameters:
      object - object to save, may be single entity, array of entities or Iterable

    • delete

      <T> void delete(T object)
      Delete entity (or entities)
      Parameters:
      object - object to delete, may be single entity, array of entities or Iterable

    • deleteAll

      <T> void deleteAll(Class<T> type)
      Delete all entities of type
      Parameters:
      type - type of the entities to delete

    • delete

      <T> Object delete(Class<T> type, Iterable<Filter> filters, boolean listResults)
      Delete all entities of type matching filter
      Parameters:
      type - type of the entities to delete
      filters - filters to match entities to delete
      listResults - true if ids of deleted entities should be returned, false to return count only
      Returns:
      ids or deleted entities or count of deleted entities

    • purgeDatabase

      void purgeDatabase()
      Delete all nodes in the database. The delete is performed in a single transaction so it may not be suitable for large data sets. NOTE: This will delete all data, not only nodes/relationships with matching metadata in the domain.

    • clear

      void clear()
      Clears the Session

    • getTransaction

      org.neo4j.ogm.transaction.Transaction getTransaction()
      Get the existing transaction if available
      Returns:
      an active Transaction, or null if none exists

    • beginTransaction

      org.neo4j.ogm.transaction.Transaction beginTransaction()
      Begin a new READ_WRITE transaction. If an existing transaction already exists, users must decide whether to commit or rollback. Only one transaction can be bound to a thread at any time, so active transactions that have not been closed but are no longer bound to the thread must be handled by client code.
      Returns:
      a new active Transaction

    • beginTransaction

      org.neo4j.ogm.transaction.Transaction beginTransaction(org.neo4j.ogm.transaction.Transaction.Type type)
      Begin a new transaction, passing in the required type (READ_ONLY, READ_WRITE). If an existing transaction already exists, users must decide whether to commit or rollback. Only one transaction can be bound to a thread at any time, so active transactions that have not been closed but are no longer bound to the thread must be handled by client code.
      Parameters:
      type - the Transaction.Type required for this transaction
      Returns:
      a new active Transaction

    • beginTransaction

      org.neo4j.ogm.transaction.Transaction beginTransaction(org.neo4j.ogm.transaction.Transaction.Type type, Iterable<String> bookmarks)
      Begin a new transaction, passing in the required type and bookmarks If an existing transaction already exists, users must decide whether to commit or rollback. Only one transaction can be bound to a thread at any time, so active transactions that have not been closed but are no longer bound to the thread must be handled by client code.
      Parameters:
      type - the Transaction.Type required for this transaction
      bookmarks - bookmarks that are passed to driver
      Returns:
      a new active Transaction

    • queryForObject

      <T> T queryForObject(Class<T> objectType, String cypher, Map<String,?> parameters)
      a cypher statement this method will return a domain object that is hydrated to the default level or a scalar (depending on the parametrized type).
      Type Parameters:
      T - A domain object or scalar.
      Parameters:
      objectType - The type that should be returned from the query.
      cypher - The parameterizable cypher to execute.
      parameters - Any scalar parameters to attach to the cypher.
      Returns:
      An instance of the objectType that matches the cypher and parameters. Null if no object is matched
      Throws:
      RuntimeException - If more than one object is found.

    • query

      <T> Iterable<T> query(Class<T> objectType, String cypher, Map<String,?> parameters)
      a cypher statement this method will return a collection of domain objects that is hydrated to the default level or a collection of scalars (depending on the parametrized type).
      Type Parameters:
      T - A domain object or scalar.
      Parameters:
      objectType - The type that should be returned from the query.
      cypher - The parameterizable cypher to execute.
      parameters - Any parameters to attach to the cypher.
      Returns:
      A collection of domain objects or scalars as prescribed by the parametrized type.

    • query

      org.neo4j.ogm.model.Result query(String cypher, Map<String,?> parameters)
      a cypher statement this method will return a Result object containing a collection of Map's which represent Neo4j objects as properties, along with query statistics if applicable. Each element of the query result is a map which you can access by the name of the returned field TODO: Are we going to use the neo4jOperations conversion method to cast the value object to its proper class?
      Parameters:
      cypher - The parameterisable cypher to execute.
      parameters - Any parameters to attach to the cypher.
      Returns:
      A Result containing an Iterable map representing query results and QueryStatistics if applicable.

    • queryDto

      <T> List<T> queryDto(String cypher, Map<String,?> parameters, Class<T> type)
      Map non-entities to a List of DTO objects.
      Type Parameters:
      T - Type of the expected result.
      Parameters:
      cypher - The parameterisable cypher to execute.
      parameters - Any parameters to attach to the cypher.
      type - The tyoe that should be returned from the query.
      Returns:
      A List of the resulting object.

    • query

      org.neo4j.ogm.model.Result query(String cypher, Map<String,?> parameters, boolean readOnly)
      a cypher statement this method will return a Result object containing a collection of Map's which represent Neo4j objects as properties, along with query statistics if applicable. Each element of the query result is a map which you can access by the name of the returned field TODO: Are we going to use the neo4jOperations conversion method to cast the value object to its proper class?
      Parameters:
      cypher - The parameterisable cypher to execute.
      parameters - Any parameters to attach to the cypher.
      readOnly - true if the query is readOnly, false otherwise
      Returns:
      A Result of Iterables with each entry representing a neo4j object's properties.

    • countEntitiesOfType

      long countEntitiesOfType(Class<?> entity)
      Counts all the node entities of the specified type.
      Parameters:
      entity - The Class denoting the type of entity to count
      Returns:
      The number of entities in the database of the type

    • count

      long count(Class<?> clazz, Iterable<Filter> filters)
      Counts all the node entities of the specified type which match the filters supplied
      Parameters:
      clazz - The Class denoting the type of entity to count
      filters - a collection of Filter objects used as additional parameters to the query
      Returns:
      The number of entities in the database of the type matched by the filters

    • resolveGraphIdFor

      Long resolveGraphIdFor(Object possibleEntity)
      Resolve the graph id for a possible entity.
      Parameters:
      possibleEntity - the possible entity
      Returns:
      the value of the internal graph id for the possible entity. Returns null if either the object is not an entity or the id is null.

    • detachNodeEntity

      boolean detachNodeEntity(Long id)
      Detach this node entity represented by the supplied Graph ID from the session.
      Parameters:
      id - the node id to detach.
      Returns:
      true if detached successfully.

    • detachRelationshipEntity

      boolean detachRelationshipEntity(Long id)
      Detach this relationship entity represented by the supplied Graph ID from the session.
      Parameters:
      id - the relationship id to detach.
      Returns:
      true if detached successfully.

    • register

      EventListener register(EventListener eventListener)
      Register an event listener with this session.
      Parameters:
      eventListener - The listener to register.
      Returns:
      the registered event listener.

    • dispose

      boolean dispose(EventListener eventListener)
      Remove an event listener from this session.
      Parameters:
      eventListener - The listener to deregister
      Returns:
      true if successfully registered.

    • notifyListeners

      void notifyListeners(Event event)
      Notifies listeners of this session of the supplied Event.
      Parameters:
      event - The event to inform listeners with.

    • eventsEnabled

      boolean eventsEnabled()
      Determines if events are enabled for this session.
      Returns:
      true if this session allows events.

    • getLastBookmark

      String getLastBookmark()
      Retrieves the last bookmark used in this session when used in a Neo4j Causal Cluster. This bookmark can be used to ensure the cluster is consistent before performing a read/write.
      Returns:
      The last used bookmark String on this session.

    • withBookmark

      void withBookmark(String bookmark)
      Sets the bookmark to use on this session. Useful when resuming a user session with a causal cluster.
      Parameters:
      bookmark - The last used bookmark String that this session should start from.

    • getLoadStrategy

      LoadStrategy getLoadStrategy()
      Returns current load strategy
      Returns:
      load strategy

    • setLoadStrategy

      void setLoadStrategy(LoadStrategy loadStrategy)
      Sets the LoadStrategy Will be used for all subsequent queries.