com.mysql.cj.protocol.x

Class AsyncMessageReader

java.lang.Object

com.mysql.cj.protocol.x.AsyncMessageReader

All Implemented Interfaces:

MessageReader<XMessageHeader,XMessage>

public class AsyncMessageReader
extends java.lang.Object
implements MessageReader<XMessageHeader,XMessage>

Asynchronous low-level message reader for Protocol buffers encoded messages delivered by X Protocol. The MessageReader will generally be used in one of two ways (See note regarding exceptions for Error messages):

• The next message type is known and it's an error to read any other type of message. The caller will generally call the reader like so:

   MessageType msg = reader.readPayload(null, 0, ServerMessages.Type.THE_TYPE_VALUE);
   

• The next message type is not known and the caller must conditionally decide what to do based on the type of the next message. The readHeader() method supports this use case. The caller will generally call the reader like so:

   XMessageHeader header = reader.readHeader();
   if (header.getMessageType() == ServerMessages.Type.TYPE_1_VALUE) {
       MessageType1 msg1 = reader.readPayload(null, 0, ServerMessages.Type.TYPE_1_VALUE);
       // do something with msg1
   } else if (header.getMessageType() == ServerMessages.Type.TYPE_2_VALUE) {
       MessageType2 msg2 = reader.readPayload(null, 0, ServerMessages.Type.TYPE_2_VALUE);
       // do something with msg2
   }
   

If the MessageReader encounters an Error message, it will throw a XProtocolError exception to indicate that an error was returned from the server.

All external interaction should know about message types listed in com.mysql.cj.x.protobuf.Mysqlx.ServerMessages.

TODO: write about async usage

Constructor Summary

Constructors

Constructor and Description
AsyncMessageReader(PropertySet propertySet, SocketConnection socketConnection)

Method Summary

Modifier and Type	Method and Description
void	pushMessageListener(MessageListener<XMessage> l) Queue a MessageListener to receive messages delivered asynchronously.
XMessageHeader	readHeader() Peek into the pending message for it's class/type.
XMessage	readMessage(java.util.Optional<XMessage> reuse, int expectedType) Read message from server into to the given Message instance or into the new one if not present.
XMessage	readMessage(java.util.Optional<XMessage> reuse, XMessageHeader hdr) Read message from server into to the given Message instance or into the new one if not present.
void	start() Start reading messages reader from the provided channel.
void	stopAfterNextMessage() Signal to the reader that it should stop reading messages after reading the next message.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.mysql.cj.protocol.MessageReader

getMessageSequence, resetMessageSequence, undecorate, undecorateAll

Constructor Detail

AsyncMessageReader

public AsyncMessageReader(PropertySet propertySet,
                          SocketConnection socketConnection)

Method Detail

start

public void start()

Description copied from interface: MessageReader

Start reading messages reader from the provided channel.

Specified by:

start in interface MessageReader<XMessageHeader,XMessage>

stopAfterNextMessage

public void stopAfterNextMessage()

Description copied from interface: MessageReader

Signal to the reader that it should stop reading messages after reading the next message.

Specified by:

stopAfterNextMessage in interface MessageReader<XMessageHeader,XMessage>

pushMessageListener

public void pushMessageListener(MessageListener<XMessage> l)

Description copied from interface: MessageReader

Queue a MessageListener to receive messages delivered asynchronously.

Specified by:

pushMessageListener in interface MessageReader<XMessageHeader,XMessage>

Parameters:

l - MessageListener

readHeader

public XMessageHeader readHeader()
                          throws java.io.IOException

Peek into the pending message for it's class/type. This method blocks until a message is available. A message will not become available to peek until there are no pending message listeners on this reader.

Specified by:

readHeader in interface MessageReader<XMessageHeader,XMessage>

Returns:

the header of the next message to be delivered

Throws:

java.io.IOException - if an error occurs

readMessage

public XMessage readMessage(java.util.Optional<XMessage> reuse,
                            XMessageHeader hdr)
                     throws java.io.IOException

Description copied from interface: MessageReader

Read message from server into to the given Message instance or into the new one if not present. For asynchronous channel it synchronously reads the next message in the stream, blocking until the message is read fully. Could throw CJCommunicationsException wrapping an IOException during read or parse

Specified by:

readMessage in interface MessageReader<XMessageHeader,XMessage>

Parameters:

reuse - Message object to reuse. May be ignored by implementation.

hdr - MessageHeader instance

Returns:

Message instance

Throws:

java.io.IOException - if an error occurs

readMessage

public XMessage readMessage(java.util.Optional<XMessage> reuse,
                            int expectedType)
                     throws java.io.IOException

Description copied from interface: MessageReader

Read message from server into to the given Message instance or into the new one if not present. For asynchronous channel it synchronously reads the next message in the stream, blocking until the message is read fully. Could throw WrongArgumentException if the expected message type is not the next message (exception will be thrown in *caller* context).

Specified by:

readMessage in interface MessageReader<XMessageHeader,XMessage>

Parameters:

reuse - Message object to reuse. May be ignored by implementation.

expectedType - Expected type of message.

Returns:

Message instance

Throws:

java.io.IOException - if an error occurs