com.mysql.cj.protocol

## Interface Protocol<M extends Message>

Type Parameters:
  `M` - Message type

    public interface Protocol<M extends Message>

A protocol provides the facilities to communicate with a MySQL server.

### Nested Class Summary

Nested Classes
`static interface` `Protocol.ProtocolEventHandler`
`static interface` `Protocol.ProtocolEventListener`

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `afterHandshake()`
`void` `beforeHandshake()`
`void` `changeDatabase(String database)`
`void` `changeUser(String user, String password, String database)` Re-authenticates as the given user and password
`M` `checkErrorMessage()` Read one message from the MySQL server, checks for errors in it, and if none, returns the message, ready for reading
`void` `close()`
`void` `configureTimeZone()`
`void` `connect(String user, String password, String database)` Create a new session.
`AuthenticationProvider<M>` `getAuthenticationProvider()`
`ExceptionInterceptor` `getExceptionInterceptor()`
`InputStream` `getLocalInfileInputStream()` Returns the InputStream instance that will be used to send data in response to a "LOAD DATA LOCAL INFILE" statement.
`MessageBuilder<M>` `getMessageBuilder()`
`PacketReceivedTimeHolder` `getPacketReceivedTimeHolder()`
`PacketSentTimeHolder` `getPacketSentTimeHolder()`
`PropertySet` `getPropertySet()`
`String` `getQueryComment()` Returns the comment that will be prepended to all statements sent to the server.
`String` `getQueryTimingUnits()`
`ServerSession` `getServerSession()`
`SocketConnection` `getSocketConnection()`
`Supplier<ValueEncoder>` `getValueEncoderSupplier(Object obj)`
`void` `init(Session session, SocketConnection socketConnection, PropertySet propertySet, TransactionEventHandler transactionManager)` Init method takes the place of constructor.
`void` `initServerSession()`
`void` `negotiateSSLConnection()`
`<T extends ProtocolEntity> T` `read(Class<Resultset> requiredClass, int maxRows, boolean streamResults, M resultPacket, boolean isBinaryEncoded, ColumnDefinition metadata, ProtocolEntityFactory<T,M> protocolEntityFactory)` Read protocol entity.
`<T extends ProtocolEntity> T` `read(Class<T> requiredClass, ProtocolEntityFactory<T,M> protocolEntityFactory)`
`M` `readMessage(M reuse)` Read one message from the MySQL server into the reusable buffer if provided or into the new one.
`ColumnDefinition` `readMetadata()`
`<T extends QueryResult> T` `readQueryResult(ResultBuilder<T> resultBuilder)` Read messages from server and deliver them to resultBuilder.
`ServerCapabilities` `readServerCapabilities()` Retrieve ServerCapabilities from server.
`void` `reset()` Return Protocol to its initial state right after successful connect.
`void` `send(Message message, int packetLen)`
`M` `sendCommand(Message queryPacket, boolean skipCheck, int timeoutMillis)` Send a command to the MySQL server.
`void` `setLocalInfileInputStream(InputStream stream)` Sets an InputStream instance that will be used to send data to the MySQL server for a "LOAD DATA LOCAL INFILE" statement rather than a FileInputStream or URLInputStream that represents the path given as an argument to the statement.
`void` `setPacketReceivedTimeHolder(PacketReceivedTimeHolder packetReceivedTimeHolder)`
`void` `setPacketSentTimeHolder(PacketSentTimeHolder packetSentTimeHolder)`
`void` `setPropertySet(PropertySet propertySet)`
`void` `setQueryComment(String comment)` Sets the comment that will be prepended to all statements sent to the server.
`boolean` `versionMeetsMinimum(int major, int minor, int subminor)`

### Method Detail

#### init

    void init(Session session,
              SocketConnection socketConnection,
              PropertySet propertySet,
              TransactionEventHandler transactionManager)

Init method takes the place of constructor. A constructor should be used unless the encapsulation of ProtocolFactory is necessary.

Parameters:
  `session` - `Session`
  `socketConnection` - `SocketConnection`
  `propertySet` - `PropertySet`
  `transactionManager` - `TransactionEventHandler`

#### getPropertySet

    PropertySet getPropertySet()

#### setPropertySet

    void setPropertySet(PropertySet propertySet)

#### getMessageBuilder

    MessageBuilder<M> getMessageBuilder()

#### readServerCapabilities

    ServerCapabilities readServerCapabilities()

Retrieve ServerCapabilities from server.

Returns:
  `ServerCapabilities`

#### getServerSession

    ServerSession getServerSession()

#### getSocketConnection

    SocketConnection getSocketConnection()

#### getAuthenticationProvider

    AuthenticationProvider<M> getAuthenticationProvider()

#### getExceptionInterceptor

    ExceptionInterceptor getExceptionInterceptor()

#### getPacketSentTimeHolder

    PacketSentTimeHolder getPacketSentTimeHolder()

#### setPacketSentTimeHolder

    void setPacketSentTimeHolder(PacketSentTimeHolder packetSentTimeHolder)

#### getPacketReceivedTimeHolder

    PacketReceivedTimeHolder getPacketReceivedTimeHolder()

#### setPacketReceivedTimeHolder

    void setPacketReceivedTimeHolder(PacketReceivedTimeHolder packetReceivedTimeHolder)

#### connect

    void connect(String user,
                 String password,
                 String database)

Create a new session. This generally happens once at the beginning of a connection.

Parameters:
  `user` - DB user name
  `password` - DB user password
  `database` - database name

#### negotiateSSLConnection

    void negotiateSSLConnection()

#### beforeHandshake

    void beforeHandshake()

#### afterHandshake

    void afterHandshake()

#### changeDatabase

    void changeDatabase(String database)

#### changeUser

    void changeUser(String user,
                    String password,
                    String database)

Re-authenticates as the given user and password

Parameters:
  `user` - DB user name
  `password` - DB user password
  `database` - database name

#### versionMeetsMinimum

    boolean versionMeetsMinimum(int major,
                                int minor,
                                int subminor)

#### readMessage

    M readMessage(M reuse)

Read one message from the MySQL server into the reusable buffer if provided or into the new one.

Parameters:
  `reuse` - `Message` instance to read into, may be null
Returns:
  the message from the server.

#### checkErrorMessage

    M checkErrorMessage()

Read one message from the MySQL server, checks for errors in it, and if none, returns the message, ready for reading

Returns:
  a message ready for reading.

#### send

    void send(Message message,
              int packetLen)

Parameters:
  `message` - `Message` instance
  `packetLen` - length of header + payload

#### readMetadata

    ColumnDefinition readMetadata()

#### sendCommand

    M sendCommand(Message queryPacket,
                  boolean skipCheck,
                  int timeoutMillis)

Send a command to the MySQL server.

Parameters:
  `queryPacket` - a packet pre-loaded with data for the protocol (eg. from a client-side prepared statement). The first byte of this packet is the MySQL protocol 'command' from MysqlDefs
  `skipCheck` - do not call checkErrorPacket() if true
  `timeoutMillis` - timeout
Returns:
  the response packet from the server
Throws:
  `CJException` - if an I/O error or SQL error occurs

#### read

    <T extends ProtocolEntity> T read(Class<T> requiredClass,
                                      ProtocolEntityFactory<T,M> protocolEntityFactory)
                               throws IOException

Throws:
  `IOException`

#### read

    <T extends ProtocolEntity> T read(Class<Resultset> requiredClass,
                                      int maxRows,
                                      boolean streamResults,
                                      M resultPacket,
                                      boolean isBinaryEncoded,
                                      ColumnDefinition metadata,
                                      ProtocolEntityFactory<T,M> protocolEntityFactory)
                               throws IOException

Read protocol entity.

Type Parameters:
  `T` - object extending the `ProtocolEntity`
Parameters:
  `requiredClass` - required Resultset class
  `maxRows` - the maximum number of rows to read (-1 means all rows)
  `streamResults` - should the driver leave the results on the wire, and read them only when needed?
  `resultPacket` - the first packet of information in the result set
  `isBinaryEncoded` - true if the binary protocol is used (for server prepared statements)
  `metadata` - use this metadata instead of the one provided on wire
  `protocolEntityFactory` - `ProtocolEntityFactory` instance
Returns:
  `ProtocolEntity` instance
Throws:
  `IOException` - if an error occurs

#### setLocalInfileInputStream

    void setLocalInfileInputStream(InputStream stream)

Sets an InputStream instance that will be used to send data to the MySQL server for a "LOAD DATA LOCAL INFILE" statement rather than a FileInputStream or URLInputStream that represents the path given as an argument to the statement. This stream will be read to completion upon execution of a "LOAD DATA LOCAL INFILE" statement, and will automatically be closed by the driver, so it needs to be reset before each call to execute*() that would cause the MySQL server to request data to fulfill the request for "LOAD DATA LOCAL INFILE". If this value is set to NULL, the driver will revert to using a FileInputStream or URLInputStream as required.

Parameters:
  `stream` - input stream

#### getLocalInfileInputStream

    InputStream getLocalInfileInputStream()

Returns the InputStream instance that will be used to send data in response to a "LOAD DATA LOCAL INFILE" statement. This method returns NULL if no such stream has been set via setLocalInfileInputStream().

Returns:
  input stream

#### getQueryComment

    String getQueryComment()

Returns the comment that will be prepended to all statements sent to the server.

Returns:
  query comment string

#### setQueryComment

    void setQueryComment(String comment)

Sets the comment that will be prepended to all statements sent to the server. Do not use slash-star or star-slash tokens in the comment as these will be added by the driver itself.

Parameters:
  `comment` - query comment string

#### readQueryResult

    <T extends QueryResult> T readQueryResult(ResultBuilder<T> resultBuilder)

Read messages from server and deliver them to resultBuilder.

Type Parameters:
  `T` - result type
Parameters:
  `resultBuilder` - `ResultBuilder` instance
Returns:
  `QueryResult`

#### close

    void close()
        throws IOException

Throws:
  `IOException`

#### configureTimeZone

    void configureTimeZone()

#### initServerSession

    void initServerSession()

#### reset

    void reset()

Return Protocol to its initial state right after successful connect.

#### getQueryTimingUnits

    String getQueryTimingUnits()

#### getValueEncoderSupplier

    Supplier<ValueEncoder> getValueEncoderSupplier(Object obj)

Copyright © 2016, 2023, Oracle and/or its affiliates.