10.1 Connection Compression Using X DevAPI

Connector/J supports data compression for X DevAPI connections when working with MySQL Server 8.0.19 and later. General details about this feature can be found in Connection Compression with X Plugin. For details on how to configure connection compression for Connector/J, see the descriptions for the connection properties xdevapi.compression, xdevapi.compression-algorithms, and xdevapi.compression-extensions in Section 6.3, “Configuration Properties”. The following is a summary of the feature:

The compression algorithms to be negotiated with the server and the priority of negotiation can be specified using the connection property xdevapi.compression-algorithms. It accepts a list of [algorithm-name]_[operation-mode], separated by commas (,). If the property is not set, the default value of “zstd_stream,lz4_message,deflate_stream” is used. The priority for negotiation follows the order the algorithms appear in the list. Setting an empty string explicitly for the property means compression should be disabled for the connection.

Note

When specifying compression algorithms with xdevapi.compression-algorithms, the aliases zstd, lz4, and deflate can be used in place of zstd_stream, lz4_message, and deflate_stream, respectively.

Out of all the compression algorithms now supported by MySQL Server for X DevAPI connections, Connector/J provides out-of-the-box support for Deflate only; this is because none of the other compression algorithms (LZ4 and zstd, for now) are natively supported by the existing JREs. To support those algorithms, the client application must provide implementations for the corresponding deflate and inflate operations in the form of an OutputStream and an InputStream object, respectively. The easiest way to accomplish this is by using a third-party library such as the Apache Commons Compress library, which supports LZ4 and zstd. The connection option xdevapi.compression-extensions allows users to configure Connector/J to use any compression algorithm that is supported by MySQL Server, as long as there is a Java implementation for that algorithm. The option takes a list of triplets separated by commas (,), and each triplet in turn contains the following elements, separated by colons (:):

• The compression algorithm name, indicated by the identifier used by the server (see Connection Compression with X Plugin; aliases mentioned in the Note above can be used).

• A fully-qualified name of a class implementing the interface java.io.InputStream that will be used to inflate data compressed with the named algorithm.

• A fully-qualified name of a class implementing the interface java.io.OutputStream that will be used to deflate data using the named algorithm.

Here is an example that sets up the support for the algorithms lz4_message and zstd_stream using the Apache Commons Compress library:

String connStr = "jdbc:mysql://johndoe:secret@localhost:33060/mydb?" 
    + "xdevapi.compression-extensions=" 
    + "lz4_message"+":" // LZ4 triplet 
    + FramedLZ4CompressorInputStream.class.getName() + ":" 
    + FramedLZ4CompressorOutputStream.class.getName() + "," 
    + "zstd_stream"+":" // zstd triplet 
    + ZstdCompressorInputStream.class.getName() + ":" 
    + ZstdCompressorOutputStream.class.getName(); 
SessionFactory sessFact = new SessionFactory(); 
Session sess = sessFact.getSession(connStr); 
Collection col = sess.getDefaultSchema().getCollection("myCollection"); 
// (...) 
sess.close();

Note

For Connector/J 8.0.21 and earlier: The connection property xdevapi.compression-extensions described above is named xdevapi.compression-algorithm for Connector/J 8.0.21 and earlier, and the elements in each triplet should be separated by commas (,) instead of colons (:).

Negotiation for a compression algorithm is attempted by default (xdevapi.compression=Preferred by default), unless the connection property xdevapi.compression is set to DISABLED. The final choice of compression algorithm depends on what algorithms are enabled on the server. By default, because compression is not required, if the negotiation fails, the connection will not be compressed, but the client will still be able to communicate with the server; however, if the connection property xdevapi.compression is set to REQUIRED, the connection attempt fails with an error if no algorithm can be negotiated for successfully.