Module org.neo4j.driver
Package org.neo4j.driver

Interface Driver

All Superinterfaces:
AutoCloseable
public interface Driver extends AutoCloseable
Accessor for a specific Neo4j graph database.

Driver implementations are typically thread-safe, act as a template for session creation and host a connection pool. All configuration and authentication settings are held immutably by the Driver. Should different settings be required, a new Driver instance should be created.

A driver maintains a connection pool for each remote Neo4j server. Therefore, the most efficient way to make use of a Driver is to use the same instance across the application.

To construct a new Driver, use one of the GraphDatabase.driver methods. The URI passed to this method determines the type of Driver created.

Available schemes and drivers
URI SchemeDriver
bolt Direct driver: connects directly to the host and port specified in the URI.
neo4j Routing driver: can automatically discover members of a Causal Cluster and route sessions based on AccessMode.

  • Method Details

    • executableQuery

      ExecutableQuery executableQuery(String query)
      Creates a new ExecutableQuery instance that executes a query in a managed transaction with automatic retries on retryable errors.
      Parameters:
      query - query string
      Returns:
      new executable query instance
      Since:
      5.7

    • executableQueryBookmarkManager

      BookmarkManager executableQueryBookmarkManager()
      Returns an instance of BookmarkManager used by ExecutableQuery instances by default.
      Returns:
      bookmark manager, must not be null
      Since:
      5.7

    • isEncrypted

      boolean isEncrypted()
      Return a flag to indicate whether encryption is used for this driver.
      Returns:
      true if the driver requires encryption, false otherwise

    • session

      default Session session()
      Create a new general purpose Session with default session configuration.

      Alias to session(SessionConfig)}.

      Returns:
      a new Session object.

    • session

      default Session session(SessionConfig sessionConfig)
      Instantiate a new Session with a specified session configuration. Use SessionConfig.forDatabase(String) to obtain a general purpose session configuration for the specified database.
      Parameters:
      sessionConfig - specifies session configurations for this session.
      Returns:
      a new Session object.
      See Also:

    • session

      default <T extends BaseSession> T session(Class<T> sessionClass)
      Instantiate a new session of supported type with default session configuration.

      Supported types are:

      Sample usage: 

       
 var session = driver.session(AsyncSession.class);
      Type Parameters:
      T - session type
      Parameters:
      sessionClass - session type class, must not be null
      Returns:
      session instance
      Throws:
      IllegalArgumentException - for unsupported session types
      Since:
      5.2

    • session

      default <T extends BaseSession> T session(Class<T> sessionClass, AuthToken sessionAuthToken)
      Instantiate a new session of a supported type with the supplied AuthToken.

      This method allows creating a session with a different AuthToken to the one used on the driver level. The minimum Bolt protocol version is 5.1. An UnsupportedFeatureException will be emitted on session interaction for previous Bolt versions.

      Supported types are:

      Sample usage: 

       
 var session = driver.session(AsyncSession.class);
      Type Parameters:
      T - session type
      Parameters:
      sessionClass - session type class, must not be null
      sessionAuthToken - a token, null will result in driver-level configuration being used
      Returns:
      session instance
      Throws:
      IllegalArgumentException - for unsupported session types
      Since:
      5.8

    • session

      default <T extends BaseSession> T session(Class<T> sessionClass, SessionConfig sessionConfig)
      Create a new session of supported type with a specified session configuration.

      Supported types are:

      Sample usage: 

       
 var session = driver.session(AsyncSession.class);
      Type Parameters:
      T - session type
      Parameters:
      sessionClass - session type class, must not be null
      sessionConfig - session config, must not be null
      Returns:
      session instance
      Throws:
      IllegalArgumentException - for unsupported session types
      Since:
      5.2

    • session

      <T extends BaseSession> T session(Class<T> sessionClass, SessionConfig sessionConfig, AuthToken sessionAuthToken)
      Instantiate a new session of a supported type with the supplied session configuration and AuthToken.

      This method allows creating a session with a different AuthToken to the one used on the driver level. The minimum Bolt protocol version is 5.1. An UnsupportedFeatureException will be emitted on session interaction for previous Bolt versions.

      Supported types are:

      Sample usage: 

       
 var session = driver.session(AsyncSession.class);
      Type Parameters:
      T - session type
      Parameters:
      sessionClass - session type class, must not be null
      sessionConfig - session config, must not be null
      sessionAuthToken - a token, null will result in driver-level configuration being used
      Returns:
      session instance
      Throws:
      IllegalArgumentException - for unsupported session types
      Since:
      5.8

    • close

      void close()
      Close all the resources assigned to this driver, including open connections and IO threads.

      This operation works the same way as closeAsync() but blocks until all resources are closed.

      Since this method is intended for graceful shutdown only, it is strongly recommended to finish interaction with all driver resources (like sessions, transactions, results, etc.) before invoking this method. Not doing this may result in unspecified behaviour, including leaving driver execution unfinished indefinitely.

      Specified by:
      close in interface AutoCloseable

    • closeAsync

      CompletionStage<Void> closeAsync()
      Close all the resources assigned to this driver, including open connections and IO threads.

      This operation is asynchronous and returns a CompletionStage. This stage is completed with null when all resources are closed. It is completed exceptionally if termination fails.

      Since this method is intended for graceful shutdown only, it is strongly recommended to finish interaction with all driver resources (like sessions, transactions, results, etc.) before invoking this method. Not doing this may result in unspecified behaviour, including leaving driver execution unfinished indefinitely.

      Returns:
      a completion stage that represents the asynchronous close.

    • metrics

      Metrics metrics()
      Returns the driver metrics if metrics reporting is enabled via Config.ConfigBuilder.withDriverMetrics(). Otherwise, a ClientException will be thrown.
      Returns:
      the driver metrics if enabled.
      Throws:
      ClientException - if the driver metrics reporting is not enabled.

    • isMetricsEnabled

      boolean isMetricsEnabled()
      Returns true if the driver metrics reporting is enabled via Config.ConfigBuilder.withDriverMetrics(), otherwise false.
      Returns:
      true if the metrics reporting is enabled.

    • verifyConnectivity

      void verifyConnectivity()
      This verifies if the driver can connect to a remote server or a cluster by establishing a network connection with the remote and possibly exchanging a few data before closing the connection.

      It throws exception if fails to connect. Use the exception to further understand the cause of the connectivity problem. Note: Even if this method throws an exception, the driver still need to be closed via close() to free up all resources.

    • verifyConnectivityAsync

      CompletionStage<Void> verifyConnectivityAsync()
      This verifies if the driver can connect to a remote server or cluster by establishing a network connection with the remote and possibly exchanging a few data before closing the connection.

      This operation is asynchronous and returns a CompletionStage. This stage is completed with null when the driver connects to the remote server or cluster successfully. It is completed exceptionally if the driver failed to connect the remote server or cluster. This exception can be used to further understand the cause of the connectivity problem. Note: Even if this method complete exceptionally, the driver still need to be closed via closeAsync() to free up all resources.

      Returns:
      a completion stage that represents the asynchronous verification.

    • verifyAuthentication

      boolean verifyAuthentication(AuthToken authToken)
      Verifies if the given AuthToken is valid.

      This check works on Bolt 5.1 version or above only.

      Parameters:
      authToken - the token
      Returns:
      the verification outcome
      Since:
      5.8

    • supportsSessionAuth

      boolean supportsSessionAuth()
      Checks if session auth is supported.
      Returns:
      the check outcome
      Since:
      5.8
      See Also:

    • supportsMultiDb

      boolean supportsMultiDb()
      Returns true if the server or cluster the driver connects to supports multi-databases, otherwise false.
      Returns:
      true if the server or cluster the driver connects to supports multi-databases, otherwise false.

    • supportsMultiDbAsync

      CompletionStage<Boolean> supportsMultiDbAsync()
      Asynchronous check if the server or cluster the driver connects to supports multi-databases.
      Returns:
      a completion stage that returns true if the server or cluster the driver connects to supports multi-databases, otherwise false.