io.asyncer.r2dbc.mysql

Class MySqlConnectionConfiguration.Builder

java.lang.Object

io.asyncer.r2dbc.mysql.MySqlConnectionConfiguration.Builder

Enclosing class:

MySqlConnectionConfiguration

public static final class MySqlConnectionConfiguration.Builder
extends Object

A builder for MySqlConnectionConfiguration creation.

Method Summary

Modifier and Type	Method and Description
MySqlConnectionConfiguration.Builder	allowLoadLocalInfileInPath(@Nullable String path) Configures to allow the LOAD DATA LOCAL INFILE statement in the given path or disallow the statement.
MySqlConnectionConfiguration.Builder	autodetectExtensions(boolean enabled) Configures whether to use ServiceLoader to discover and register extensions.
MySqlConnectionConfiguration	build() Builds an immutable MySqlConnectionConfiguration with current options.
MySqlConnectionConfiguration.Builder	compressionAlgorithms(CompressionAlgorithm... compressionAlgorithms) Configures the compression algorithms.
MySqlConnectionConfiguration.Builder	connectionTimeZone(String connectionTimeZone) Configures the time zone of connection.
MySqlConnectionConfiguration.Builder	connectTimeout(@Nullable Duration connectTimeout) Configures the connection timeout.
MySqlConnectionConfiguration.Builder	createDatabaseIfNotExist(boolean enabled) Configures to create the database given in the configuration if it does not yet exist.
MySqlConnectionConfiguration.Builder	database(@Nullable String database) Configures the database.
MySqlConnectionConfiguration.Builder	extendWith(Extension extension) Registers a Extension to extend driver functionality and manually.
MySqlConnectionConfiguration.Builder	forceConnectionTimeZoneToSession(boolean enabled) Configures to force the connection time zone to session time zone.
MySqlConnectionConfiguration.Builder	host(String host) Configures the host.
MySqlConnectionConfiguration.Builder	localInfileBufferSize(int localInfileBufferSize) Configures the buffer size for LOAD DATA LOCAL INFILE statement.
MySqlConnectionConfiguration.Builder	lockWaitTimeout(@Nullable Duration lockWaitTimeout) Configures the lock wait timeout.
MySqlConnectionConfiguration.Builder	loopResources(reactor.netty.resources.LoopResources loopResources) Configures the LoopResources for the driver.
MySqlConnectionConfiguration.Builder	password(@Nullable CharSequence password) Configures the password.
MySqlConnectionConfiguration.Builder	passwordPublisher(Publisher<String> passwordPublisher) Registers a password publisher function.
MySqlConnectionConfiguration.Builder	port(int port) Configures the port.
MySqlConnectionConfiguration.Builder	prepareCacheSize(int prepareCacheSize) Configures the maximum size of the server-preparing cache.
MySqlConnectionConfiguration.Builder	preserveInstants(boolean enabled) Configures the time zone conversion.
MySqlConnectionConfiguration.Builder	queryCacheSize(int queryCacheSize) Configures the maximum size of the Query parsing cache.
MySqlConnectionConfiguration.Builder	serverZoneId(@Nullable ZoneId serverZoneId) Deprecated. since 1.1.2, use connectionTimeZone(String) instead.
MySqlConnectionConfiguration.Builder	sessionVariables(String... sessionVariables) Configures the session variables, used to set session variables immediately after login.
MySqlConnectionConfiguration.Builder	sslCa(@Nullable String sslCa) Configures SSL root certification for server certificate validation.
MySqlConnectionConfiguration.Builder	sslCert(@Nullable String sslCert) Configures client SSL certificate for client authentication.
MySqlConnectionConfiguration.Builder	sslContextBuilderCustomizer(Function<io.netty.handler.ssl.SslContextBuilder,io.netty.handler.ssl.SslContextBuilder> customizer) Configures a SslContextBuilder customizer.
MySqlConnectionConfiguration.Builder	sslHostnameVerifier(HostnameVerifier sslHostnameVerifier) Configures SSL HostnameVerifier, it is available only set sslMode(SslMode) as SslMode.VERIFY_IDENTITY.
MySqlConnectionConfiguration.Builder	sslKey(@Nullable String sslKey) Configures client SSL key for client authentication.
MySqlConnectionConfiguration.Builder	sslKeyPassword(@Nullable CharSequence sslKeyPassword) Configures the password of SSL key file for client certificate authentication.
MySqlConnectionConfiguration.Builder	sslMode(SslMode sslMode) Configures ssl mode.
MySqlConnectionConfiguration.Builder	statementTimeout(@Nullable Duration statementTimeout) Configures the statement timeout.
MySqlConnectionConfiguration.Builder	tcpKeepAlive(boolean enabled) Configures TCP KeepAlive.
MySqlConnectionConfiguration.Builder	tcpNoDelay(boolean enabled) Configures TCP NoDelay.
MySqlConnectionConfiguration.Builder	tlsVersion(String... tlsVersion) Configures TLS versions, see TlsVersions.
MySqlConnectionConfiguration.Builder	unixSocket(String unixSocket) Configures the Unix Domain Socket to connect to.
MySqlConnectionConfiguration.Builder	useClientPrepareStatement() Configures the protocol of parameterized statements to the text protocol.
MySqlConnectionConfiguration.Builder	user(String user) Configures the user for login the database.
MySqlConnectionConfiguration.Builder	username(String user) An alias of user(String).
MySqlConnectionConfiguration.Builder	useServerPrepareStatement() Configures the protocol of parameterized statements to the binary protocol.
MySqlConnectionConfiguration.Builder	useServerPrepareStatement(Predicate<String> preferPrepareStatement) Configures the protocol of parameterized statements and prepare-preferred simple statements to the binary protocol.
MySqlConnectionConfiguration.Builder	zeroDateOption(ZeroDateOption zeroDate) Configures the ZeroDateOption.
MySqlConnectionConfiguration.Builder	zstdCompressionLevel(int level) Configures the zstd compression level.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

build

public MySqlConnectionConfiguration build()

Builds an immutable MySqlConnectionConfiguration with current options.

Returns:

the MySqlConnectionConfiguration.

database

public MySqlConnectionConfiguration.Builder database(@Nullable
                                                     @Nullable String database)

Configures the database. Default no database.

Parameters:

database - the database, or null if no database want to be login.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.1

createDatabaseIfNotExist

public MySqlConnectionConfiguration.Builder createDatabaseIfNotExist(boolean enabled)

Configures to create the database given in the configuration if it does not yet exist. Default to false.

Parameters:

enabled - to discover and register extensions.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

1.0.6

unixSocket

public MySqlConnectionConfiguration.Builder unixSocket(String unixSocket)

Configures the Unix Domain Socket to connect to.

Parameters:

unixSocket - the socket file path.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if unixSocket is null.

Since:

0.8.1

host

public MySqlConnectionConfiguration.Builder host(String host)

Configures the host.

Parameters:

host - the host.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if host is null.

Since:

0.8.1

password

public MySqlConnectionConfiguration.Builder password(@Nullable
                                                     @Nullable CharSequence password)

Configures the password. Default login without password.

Note: for memory security, should not use intern String for password.

Parameters:

password - the password, or null when user has no password.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.1

port

public MySqlConnectionConfiguration.Builder port(int port)

Configures the port. Defaults to 3306.

Parameters:

port - the port.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if the port is negative or bigger than 65535.

Since:

0.8.1

connectTimeout

public MySqlConnectionConfiguration.Builder connectTimeout(@Nullable
                                                           @Nullable Duration connectTimeout)

Configures the connection timeout. Default no timeout.

Parameters:

connectTimeout - the connection timeout, or null if no timeout.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.1

user

public MySqlConnectionConfiguration.Builder user(String user)

Configures the user for login the database.

Parameters:

user - the user.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if user is null.

Since:

0.8.2

username

public MySqlConnectionConfiguration.Builder username(String user)

An alias of user(String).

Parameters:

user - the user.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if user is null.

Since:

0.8.1

preserveInstants

public MySqlConnectionConfiguration.Builder preserveInstants(boolean enabled)

Configures the time zone conversion. Default to true means enable conversion between JVM and connectionTimeZone(String).

Note: disable it will ignore the time zone of connection, and use the JVM local time zone.

Parameters:

enabled - true to preserve instants, or false to disable conversion.

Returns:

this

Since:

1.1.2

connectionTimeZone

public MySqlConnectionConfiguration.Builder connectionTimeZone(String connectionTimeZone)

Configures the time zone of connection. Default to LOCAL means use JVM local time zone. "SERVER" means querying the server-side timezone during initialization.

Parameters:

connectionTimeZone - "LOCAL", "SERVER", or a valid ID of ZoneId.

Returns:

this

Throws:

IllegalArgumentException - if connectionTimeZone is null or empty.

Since:

1.1.2

forceConnectionTimeZoneToSession

public MySqlConnectionConfiguration.Builder forceConnectionTimeZoneToSession(boolean enabled)

Configures to force the connection time zone to session time zone. Default to false. Used only if the connectionTimeZone(String) is not "SERVER".

Note: alter the time zone of session will affect the results of MySQL date/time functions, e.g. NOW([n]), CURRENT_TIME([n]), CURRENT_DATE(), etc. Please use with caution.

Parameters:

enabled - true to force the connection time zone to session time zone.

Returns:

this

Since:

1.1.2

serverZoneId

@Deprecated
public MySqlConnectionConfiguration.Builder serverZoneId(@Nullable
                                                                     @Nullable ZoneId serverZoneId)

Deprecated. since 1.1.2, use connectionTimeZone(String) instead.

Configures the time zone of server. Since 1.1.2, default to use JVM local time zone.

Parameters:

serverZoneId - the ZoneId, or null if query server during initialization.

Returns:

this

Since:

0.8.2

zeroDateOption

public MySqlConnectionConfiguration.Builder zeroDateOption(ZeroDateOption zeroDate)

Configures the ZeroDateOption. Default to ZeroDateOption.USE_NULL. It is a behavior option when this driver receives a value of zero-date.

Parameters:

zeroDate - the ZeroDateOption.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if zeroDate is null.

Since:

0.8.1

sslMode

public MySqlConnectionConfiguration.Builder sslMode(SslMode sslMode)

Configures ssl mode. See also SslMode.

Parameters:

sslMode - the SSL mode to use.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if sslMode is null.

Since:

0.8.1

tlsVersion

public MySqlConnectionConfiguration.Builder tlsVersion(String... tlsVersion)

Configures TLS versions, see TlsVersions.

Parameters:

tlsVersion - TLS versions.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if the array tlsVersion is null.

Since:

0.8.1

sslHostnameVerifier

public MySqlConnectionConfiguration.Builder sslHostnameVerifier(HostnameVerifier sslHostnameVerifier)

Configures SSL HostnameVerifier, it is available only set sslMode(SslMode) as SslMode.VERIFY_IDENTITY. It is useful when server was using special Certificates or need special verification.

Default is builtin HostnameVerifier which use RFC standards.

Parameters:

sslHostnameVerifier - the custom HostnameVerifier.

Returns:

this MySqlConnectionConfiguration.Builder

Throws:

IllegalArgumentException - if sslHostnameVerifier is null

Since:

0.8.2

sslCa

public MySqlConnectionConfiguration.Builder sslCa(@Nullable
                                                  @Nullable String sslCa)

Configures SSL root certification for server certificate validation. It is only available if the sslMode(SslMode) is configured for verify server certification.

Default is null, which means that the default algorithm is used for the trust manager.

Parameters:

sslCa - an X.509 certificate chain file in PEM format.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.1

sslCert

public MySqlConnectionConfiguration.Builder sslCert(@Nullable
                                                    @Nullable String sslCert)

Configures client SSL certificate for client authentication.

The sslCert and sslKey must be both non-null or both null.

Parameters:

sslCert - an X.509 certificate chain file in PEM format, or null if no SSL cert.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.2

sslKey

public MySqlConnectionConfiguration.Builder sslKey(@Nullable
                                                   @Nullable String sslKey)

Configures client SSL key for client authentication.

The sslCert and sslKey must be both non-null or both null.

Parameters:

sslKey - a PKCS#8 private key file in PEM format, or null if no SSL key.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.2

sslKeyPassword

public MySqlConnectionConfiguration.Builder sslKeyPassword(@Nullable
                                                           @Nullable CharSequence sslKeyPassword)

Configures the password of SSL key file for client certificate authentication.

It will be used only if sslKey and sslCert non-null.

Parameters:

sslKeyPassword - the password of the sslKey, or null if it's not password-protected.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.2

sslContextBuilderCustomizer

public MySqlConnectionConfiguration.Builder sslContextBuilderCustomizer(Function<io.netty.handler.ssl.SslContextBuilder,io.netty.handler.ssl.SslContextBuilder> customizer)

Configures a SslContextBuilder customizer. The customizer gets applied on each SSL connection attempt to allow for just-in-time configuration updates. The Function gets called with the prepared SslContextBuilder that has all configuration options applied. The customizer may return the same builder or return a new builder instance to be used to build the SSL context.

Parameters:

customizer - customizer function

Returns:

this MySqlConnectionConfiguration.Builder

Throws:

IllegalArgumentException - if customizer is null

Since:

0.8.1

tcpKeepAlive

public MySqlConnectionConfiguration.Builder tcpKeepAlive(boolean enabled)

Configures TCP KeepAlive.

Parameters:

enabled - whether to enable TCP KeepAlive

Returns:

this MySqlConnectionConfiguration.Builder

Since:

0.8.2

See Also:

Socket.setKeepAlive(boolean)

tcpNoDelay

public MySqlConnectionConfiguration.Builder tcpNoDelay(boolean enabled)

Configures TCP NoDelay.

Parameters:

enabled - whether to enable TCP NoDelay

Returns:

this MySqlConnectionConfiguration.Builder

Since:

0.8.2

See Also:

Socket.setTcpNoDelay(boolean)

useClientPrepareStatement

public MySqlConnectionConfiguration.Builder useClientPrepareStatement()

Configures the protocol of parameterized statements to the text protocol.

The text protocol is default protocol that's using client-preparing. See also MySQL documentations.

Returns:

this MySqlConnectionConfiguration.Builder

Since:

0.8.1

useServerPrepareStatement

public MySqlConnectionConfiguration.Builder useServerPrepareStatement()

Configures the protocol of parameterized statements to the binary protocol.

The binary protocol is compact protocol that's using server-preparing. See also MySQL documentations.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.1

useServerPrepareStatement

public MySqlConnectionConfiguration.Builder useServerPrepareStatement(Predicate<String> preferPrepareStatement)

Configures the protocol of parameterized statements and prepare-preferred simple statements to the binary protocol.

The preferPrepareStatement configures whether to prefer prepare execution on a statement-by-statement basis (simple statements). The Predicate accepts the simple SQL query string and returns a boolean flag indicating preference. true prepare-preferred, false prefers direct execution (text protocol). Defaults to direct execution.

The binary protocol is compact protocol that's using server-preparing. See also MySQL documentations.

Parameters:

preferPrepareStatement - the above Predicate.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if preferPrepareStatement is null.

Since:

0.8.1

sessionVariables

public MySqlConnectionConfiguration.Builder sessionVariables(String... sessionVariables)

Configures the session variables, used to set session variables immediately after login. Default no session variables to set. It should be a list of key-value pairs. e.g. ["sql_mode='ANSI_QUOTES,STRICT_TRANS_TABLES'", "time_zone=00:00"].

Parameters:

sessionVariables - the session variables to set.

Returns:

this

Throws:

IllegalArgumentException - if sessionVariables is null.

Since:

1.1.2

lockWaitTimeout

public MySqlConnectionConfiguration.Builder lockWaitTimeout(@Nullable
                                                            @Nullable Duration lockWaitTimeout)

Configures the lock wait timeout. Default to use the server-side default value.

Parameters:

lockWaitTimeout - the lock wait timeout, or null to use the server-side default value.

Returns:

this

Since:

1.1.3

statementTimeout

public MySqlConnectionConfiguration.Builder statementTimeout(@Nullable
                                                             @Nullable Duration statementTimeout)

Configures the statement timeout. Default to use the server-side default value.

Parameters:

statementTimeout - the statement timeout, or null to use the server-side default value.

Returns:

this

Since:

1.1.3

allowLoadLocalInfileInPath

public MySqlConnectionConfiguration.Builder allowLoadLocalInfileInPath(@Nullable
                                                                       @Nullable String path)

Configures to allow the LOAD DATA LOCAL INFILE statement in the given path or disallow the statement. Default to null which means not allow the statement.

Parameters:

path - which parent path are allowed to load file data, null means not be allowed.

Returns:

this.

Throws:

InvalidPathException - if the string cannot be converted to a Path.

Since:

1.1.0

localInfileBufferSize

public MySqlConnectionConfiguration.Builder localInfileBufferSize(int localInfileBufferSize)

Configures the buffer size for LOAD DATA LOCAL INFILE statement. Default to 8192.

It is used only if allowLoadLocalInfileInPath(String) is set.

Parameters:

localInfileBufferSize - the buffer size.

Returns:

this.

Throws:

IllegalArgumentException - if localInfileBufferSize is not positive.

Since:

1.1.0

queryCacheSize

public MySqlConnectionConfiguration.Builder queryCacheSize(int queryCacheSize)

Configures the maximum size of the Query parsing cache. Usually it should be power of two. Default to 0. Driver will use unbounded cache if size is less than 0.

Notice: the cache is using EL model (the PACELC theorem) which provider better performance. That means it is an elastic cache. So this size is not a hard-limit. It should be over 16 in average.

Parameters:

queryCacheSize - the above size, 0 means no cache, -1 means unbounded cache.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.3

prepareCacheSize

public MySqlConnectionConfiguration.Builder prepareCacheSize(int prepareCacheSize)

Configures the maximum size of the server-preparing cache. Usually it should be power of two. Default to 256. Driver will use unbounded cache if size is less than 0. It is used only if using server-preparing parameterized statements, i.e. the useServerPrepareStatement() is set.

Notice: the cache is using EC model (the PACELC theorem) for ensure consistency. Consistency is very important because MySQL contains a hard limit of all server-prepared statements which has been opened, see also max_prepared_stmt_count. And, the cache is one-to-one connection, which means it will not work on thread-concurrency.

Parameters:

prepareCacheSize - the above size, 0 means no cache, -1 means unbounded cache.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.3

compressionAlgorithms

public MySqlConnectionConfiguration.Builder compressionAlgorithms(CompressionAlgorithm... compressionAlgorithms)

Configures the compression algorithms. Default to [CompressionAlgorithm.UNCOMPRESSED].

It will auto choose an algorithm that's contained in the list and supported by the server, preferring zstd, then zlib. If the list does not contain CompressionAlgorithm.UNCOMPRESSED and the server does not support any algorithm in the list, an exception will be thrown when connecting.

Note: zstd requires a dependency com.github.luben:zstd-jni.

Parameters:

compressionAlgorithms - the list of compression algorithms.

Returns:

this.

Throws:

IllegalArgumentException - if compressionAlgorithms is null or empty.

Since:

1.1.2

zstdCompressionLevel

public MySqlConnectionConfiguration.Builder zstdCompressionLevel(int level)

Configures the zstd compression level. Default to 3.

It is only used if zstd is chosen for the connection.

Note: MySQL protocol does not allow to set the zlib compression level of the server, only zstd is configurable.

Parameters:

level - the compression level.

Returns:

this.

Throws:

IllegalArgumentException - if level is not between 1 and 22.

Since:

1.1.2

See Also:

MySQL Connection Options --zstd-compression-level

loopResources

public MySqlConnectionConfiguration.Builder loopResources(reactor.netty.resources.LoopResources loopResources)

Configures the LoopResources for the driver. Default to global tcp resources.

Parameters:

loopResources - the LoopResources.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if loopResources is null.

Since:

1.1.2

autodetectExtensions

public MySqlConnectionConfiguration.Builder autodetectExtensions(boolean enabled)

Configures whether to use ServiceLoader to discover and register extensions. Defaults to true.

Parameters:

enabled - to discover and register extensions.

Returns:

this MySqlConnectionConfiguration.Builder.

Since:

0.8.2

extendWith

public MySqlConnectionConfiguration.Builder extendWith(Extension extension)

Registers a Extension to extend driver functionality and manually.

Notice: the driver will not deduplicate Extensions of autodetect discovered and manually extended. So if a Extension is registered by this function and autodetect discovered, it will get two Extension as same.

Parameters:

extension - extension to extend driver functionality.

Returns:

this MySqlConnectionConfiguration.Builder.

Throws:

IllegalArgumentException - if extension is null.

Since:

0.8.2

passwordPublisher

public MySqlConnectionConfiguration.Builder passwordPublisher(Publisher<String> passwordPublisher)

Registers a password publisher function.

Parameters:

passwordPublisher - function to retrieve password before making connection.

Returns:

this MySqlConnectionConfiguration.Builder.