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

Class Config.ConfigBuilder

java.lang.Object
org.neo4j.driver.Config.ConfigBuilder
Enclosing class:
Config
public static final class Config.ConfigBuilder extends Object
Used to build new config instances

  • Method Details

    • withLogging

      public Config.ConfigBuilder withLogging(Logging logging)
      Provide a logging implementation for the driver to use. Java logging framework java.util.logging with Level.INFO is used by default. Callers are expected to either implement Logging interface or provide one of the existing implementations available from static factory methods in the Logging interface.

      Please see documentation in Logging for more information.

      Parameters:
      logging - the logging instance to use
      Returns:
      this builder
      See Also:

    • withLeakedSessionsLogging

      public Config.ConfigBuilder withLeakedSessionsLogging()
      Enable logging of leaked sessions.

      Each session is associated with a network connection and thus is a resource that needs to be explicitly closed. Unclosed sessions will result in socket leaks and could cause OutOfMemoryErrors.

      Session is considered to be leaked when it is finalized via Object.finalize() while not being closed. This option turns on logging of such sessions and stacktraces of where they were created.

      Note: this option should mostly be used in testing environments for session leak investigations. Enabling it will add object finalization overhead.

      Returns:
      this builder

    • withConnectionLivenessCheckTimeout

      public Config.ConfigBuilder withConnectionLivenessCheckTimeout(long value, TimeUnit unit)
      Pooled connections that have been idle in the pool for longer than this timeout will be tested before they are used again, to ensure they are still live.

      If this option is set too low, an additional network call will be incurred when acquiring a connection, which causes a performance hit.

      If this is set high, you may receive sessions that are backed by no longer live connections, which will lead to exceptions in your application. Assuming the database is running, these exceptions will go away if you retry acquiring sessions.

      Hence, this parameter tunes a balance between the likelihood of your application seeing connection problems, and performance.

      You normally should not need to tune this parameter. No connection liveliness check is done by default. Value 0 means connections will always be tested for validity and negative values mean connections will never be tested.

      Parameters:
      value - the minimum idle time
      unit - the unit in which the duration is given
      Returns:
      this builder

    • withMaxConnectionLifetime

      public Config.ConfigBuilder withMaxConnectionLifetime(long value, TimeUnit unit)
      Pooled connections older than this threshold will be closed and removed from the pool. Such discarding happens during connection acquisition so that new session is never backed by an old connection.

      Setting this option to a low value will cause a high connection churn and might result in a performance hit.

      It is recommended to set maximum lifetime to a slightly smaller value than the one configured in network equipment (load balancer, proxy, firewall, etc. can also limit maximum connection lifetime).

      Setting can also be used in combination with withConnectionLivenessCheckTimeout(long, TimeUnit). In this case, it is recommended to set liveness check to a value smaller than network equipment has and maximum lifetime to a reasonably large value to "renew" connections once in a while.

      Default maximum connection lifetime is 1 hour. Zero and negative values result in lifetime not being checked.

      Parameters:
      value - the maximum connection lifetime
      unit - the unit in which the duration is given
      Returns:
      this builder

    • withMaxConnectionPoolSize

      public Config.ConfigBuilder withMaxConnectionPoolSize(int value)
      Configure maximum amount of connections in the connection pool towards a single database. This setting limits total amount of connections in the pool when used in direct driver, created for URI with 'bolt' scheme. It will limit amount of connections per cluster member when used with routing driver, created for URI with 'neo4j' scheme.

      Acquisition will be attempted for at most configured timeout withConnectionAcquisitionTimeout(long, TimeUnit) when limit is reached.

      Default value is 100. Negative values are allowed and result in unlimited pool. Value of 0 is not allowed.

      Parameters:
      value - the maximum connection pool size.
      Returns:
      this builder
      See Also:

    • withConnectionAcquisitionTimeout

      public Config.ConfigBuilder withConnectionAcquisitionTimeout(long value, TimeUnit unit)
      Configure maximum amount of time connection acquisition will attempt to acquire a connection from the connection pool. This timeout only kicks in when all existing connections are being used and no new connections can be created because maximum connection pool size has been reached.

      Exception is raised when connection can't be acquired within configured time.

      Default value is 60 seconds. Negative values are allowed and result in unlimited acquisition timeout. Value of 0 is allowed and results in no timeout and immediate failure when connection is unavailable.

      Parameters:
      value - the acquisition timeout
      unit - the unit in which the duration is given
      Returns:
      this builder
      See Also:

    • withEncryption

      public Config.ConfigBuilder withEncryption()
      Set to use encrypted traffic.
      Returns:
      this builder

    • withoutEncryption

      public Config.ConfigBuilder withoutEncryption()
      Set to use unencrypted traffic.
      Returns:
      this builder

    • withTrustStrategy

      public Config.ConfigBuilder withTrustStrategy(Config.TrustStrategy trustStrategy)
      Specify how to determine the authenticity of an encryption certificate provided by the Neo4j instance we are connecting to. This defaults to Config.TrustStrategy.trustSystemCertificates(). See Config.TrustStrategy.trustCustomCertificateSignedBy(File...) for using certificate signatures instead to verify trust.

      This is an important setting to understand, because unless we know that the remote server we have an encrypted connection to is really Neo4j, there is no point to encrypt at all, since anyone could pretend to be the remote Neo4j instance.

      For this reason, there is no option to disable trust verification. However, it is possible to turn off encryption using the withoutEncryption() option.

      Parameters:
      trustStrategy - TLS authentication strategy
      Returns:
      this builder

    • withRoutingTablePurgeDelay

      public Config.ConfigBuilder withRoutingTablePurgeDelay(long delay, TimeUnit unit)
      Specify how long to wait before purging stale routing tables.

      When a routing table is timed out, the routing table will be marked ready to remove after the delay specified here. Driver keeps a routing table for each database seen by the driver. The routing table of a database get refreshed if the database is used frequently. If the database is not used for a long time, the driver use the timeout specified here to purge the stale routing table.

      After a routing table is removed, next time when using the database of the purged routing table, the driver will fall back to use seed URI for a new routing table.

      Parameters:
      delay - the amount of time to wait before purging routing tables
      unit - the unit in which the duration is given
      Returns:
      this builder

    • withFetchSize

      public Config.ConfigBuilder withFetchSize(long size)
      Specify how many records to fetch in each batch. This config is only valid when the driver is used with servers that support Bolt V4 (Server version 4.0 and later).

      Bolt V4 enables pulling records in batches to allow client to take control of data population and apply back pressure to server. This config specifies the default fetch size for all query runs using Session and AsyncSession. By default, the value is set to 1000. Use -1 to disables back pressure and config client to pull all records at once after each run.

      This config only applies to run results obtained via Session and AsyncSession. As with the reactive sessions the batch size is managed by the subscription requests instead.

      Parameters:
      size - the default record fetch size when pulling records in batches using Bolt V4.
      Returns:
      this builder

    • withConnectionTimeout

      public Config.ConfigBuilder withConnectionTimeout(long value, TimeUnit unit)
      Specify socket connection timeout.

      A timeout of zero is treated as an infinite timeout and will be bound by the timeout configured on the operating system level. The connection will block until established or an error occurs.

      Timeout value should be greater or equal to zero and represent a valid int value when converted to milliseconds.

      The default value of this parameter is 30 SECONDS.

      Parameters:
      value - the timeout duration
      unit - the unit in which duration is given
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when given value is negative or does not fit in int when converted to milliseconds.

    • withMaxTransactionRetryTime

      public Config.ConfigBuilder withMaxTransactionRetryTime(long value, TimeUnit unit)
      Specify the maximum time managed transactions are allowed to retry.

      Managed transactions are available via methods like Session.executeRead(TransactionCallback), Session.executeWrite(TransactionCallback, TransactionConfig) and some other variations available under similar naming.

      Default value is 30 seconds.

      Parameters:
      value - the timeout duration
      unit - the unit in which duration is given
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when given value is negative

    • withResolver

      public Config.ConfigBuilder withResolver(ServerAddressResolver resolver)
      Specify a custom server address resolver used by the routing driver to resolve the initial address used to create the driver. Such resolution happens:
      • during the very first rediscovery when driver is created
      • when all the known routers from the current routing table have failed and driver needs to fallback to the initial address
      By default driver performs a DNS lookup for the initial address using InetAddress.getAllByName(String).
      Parameters:
      resolver - the resolver to use.
      Returns:
      this builder.
      Throws:
      NullPointerException - when the given resolver is null.

    • withDriverMetrics

      public Config.ConfigBuilder withDriverMetrics()
      Enable driver metrics backed by internal basic implementation. The metrics can be obtained afterwards via Driver.metrics().
      Returns:
      this builder.

    • withoutDriverMetrics

      public Config.ConfigBuilder withoutDriverMetrics()
      Disable driver metrics. When disabled, driver metrics cannot be accessed via Driver.metrics().
      Returns:
      this builder.

    • withMetricsAdapter

      @Experimental public Config.ConfigBuilder withMetricsAdapter(MetricsAdapter metricsAdapter)
      Enable driver metrics with given MetricsAdapter.

      MetricsAdapter.MICROMETER enables implementation based on Micrometer. The metrics can be obtained afterwards via Micrometer means and Driver.metrics(). Micrometer must be on classpath when using this option.

      Parameters:
      metricsAdapter - the metrics adapter to use. Use MetricsAdapter.DEV_NULL to disable metrics.
      Returns:
      this builder.

    • withEventLoopThreads

      public Config.ConfigBuilder withEventLoopThreads(int size)
      Configure the event loop thread count. This specifies how many threads the driver can use to handle network I/O events and user's events in driver's I/O threads. By default, 2 * NumberOfProcessors amount of threads will be used instead.
      Parameters:
      size - the thread count.
      Returns:
      this builder.
      Throws:
      IllegalArgumentException - if the value of the size is set to a number that is less than 1.

    • withUserAgent

      public Config.ConfigBuilder withUserAgent(String userAgent)
      Configure the user_agent field sent to the server to identify the connected client.
      Parameters:
      userAgent - the string to configure user_agent.
      Returns:
      this builder.

    • withNotificationConfig

      public Config.ConfigBuilder withNotificationConfig(NotificationConfig notificationConfig)
      Sets notification config.

      Any configuration other than the NotificationConfig.defaultConfig() requires a minimum Bolt protocol version 5.2. Otherwise, an UnsupportedFeatureException will be emitted when the driver comes across a Bolt connection that does not support this feature. For instance, when running a query.

      Parameters:
      notificationConfig - the notification config
      Returns:
      this builder
      Since:
      5.7

    • withTelemetryDisabled

      public Config.ConfigBuilder withTelemetryDisabled(boolean telemetryDisabled)
      Sets if telemetry is disabled on the driver side.

      By default, the driver sends anonymous telemetry data to the server it connects to if the server has telemetry enabled. This can be explicitly disabled on the driver side by setting this setting to true.

      At present, the driver sends which API type is used, like:

      Parameters:
      telemetryDisabled - true if telemetry is disabled or false otherwise
      Returns:
      this builder
      Since:
      5.13

    • build

      public Config build()
      Create a config instance from this builder.
      Returns:
      a new Config instance.