org.neo4j.bolt.v1.runtime

Class BoltStateMachine

java.lang.Object

org.neo4j.bolt.v1.runtime.BoltStateMachine

All Implemented Interfaces:

AutoCloseable, org.neo4j.kernel.api.bolt.ManagedBoltStateMachine

public class BoltStateMachine
extends Object
implements AutoCloseable, org.neo4j.kernel.api.bolt.ManagedBoltStateMachine

This state machine oversees the exchange of messages for the Bolt protocol. Central to this are the five active states -- CONNECTED, READY, STREAMING, FAILED and INTERRUPTED -- as well as the transitions between them which correspond to the Bolt protocol request messages INIT, ACK_FAILURE, RESET, RUN, DISCARD_ALL and PULL_ALL. Of particular note is RESET which exhibits dual behaviour in both marking the current query for termination and clearing down the current connection state.

To help ensure a secure protocol, any transition not explicitly defined here (i.e. a message sent out of sequence) will result in an immediate failure response and a closed connection.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BoltStateMachine.State

Constructor Summary

Constructors

Constructor and Description
BoltStateMachine(org.neo4j.bolt.v1.runtime.BoltStateMachine.SPI spi, Runnable onClose, Clock clock)

Method Summary

Modifier and Type	Method and Description
void	ackFailure(BoltResponseHandler handler) Clear any outstanding error condition.
void	close()
void	discardAll(BoltResponseHandler handler) Discard all the remaining entries in the current result stream.
void	externalError(Neo4jError error, BoltResponseHandler handler)
void	init(String userAgent, Map<String,Object> authToken, BoltResponseHandler handler) Initialize the session.
void	interrupt() When this is invoked, the machine will make attempts at interrupting any currently running action, and will then ignore all inbound messages until a reset message is received.
boolean	isClosed()
String	key() A session id that is unique for this database instance
String	owner()
void	pullAll(BoltResponseHandler handler) Retrieve all remaining entries in the current result.
void	reset(BoltResponseHandler handler) Reset the session to an IDLE state.
void	run(String statement, Map<String,Object> params, BoltResponseHandler handler) Run a statement, yielding a result stream which can be retrieved through pulling it in a subsequent call.
BoltStateMachine.State	state()
StatementProcessor	statementProcessor()
void	terminate()
boolean	willTerminate()

Methods inherited from class java.lang.Object

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

Constructor Detail

BoltStateMachine

public BoltStateMachine(org.neo4j.bolt.v1.runtime.BoltStateMachine.SPI spi,
                        Runnable onClose,
                        Clock clock)

Method Detail

state

public BoltStateMachine.State state()

statementProcessor

public StatementProcessor statementProcessor()

init

public void init(String userAgent,
                 Map<String,Object> authToken,
                 BoltResponseHandler handler)
          throws BoltConnectionFatality

Initialize the session.

Throws:

BoltConnectionFatality

ackFailure

public void ackFailure(BoltResponseHandler handler)
                throws BoltConnectionFatality

Clear any outstanding error condition. This differs from reset(BoltResponseHandler) in two important ways: 1) If there was an explicitly created transaction, the session will move back to IN_TRANSACTION, rather than IDLE. This allows a more natural flow for client side drivers, where explicitly opened transactions always are ended with COMMIT or ROLLBACK, even if an error occurs. In all other cases, the session will move to the IDLE state. 2) It will not interrupt any ahead-in-line messages.

Throws:

BoltConnectionFatality

reset

public void reset(BoltResponseHandler handler)
           throws BoltConnectionFatality

Reset the session to an IDLE state. This clears any outstanding failure condition, disposes of any outstanding result records and rolls back the current transaction (if any). This differs from ackFailure(BoltResponseHandler) in that it is more "radical" - it does not matter what the state of the session is, as long as it is open, reset will move it back to IDLE. This is designed to cater to two use cases: 1) Rather than create new sessions over and over, drivers can maintain a pool of sessions, and reset them before each re-use. Since establishing sessions can be high overhead, this is quite helpful. 2) Kill any stuck or long running operation

Throws:

BoltConnectionFatality

run

public void run(String statement,
                Map<String,Object> params,
                BoltResponseHandler handler)
         throws BoltConnectionFatality

Run a statement, yielding a result stream which can be retrieved through pulling it in a subsequent call.

If there is a statement running already, all remaining items in its stream must be pulled or discarded.

Throws:

BoltConnectionFatality

discardAll

public void discardAll(BoltResponseHandler handler)
                throws BoltConnectionFatality

Discard all the remaining entries in the current result stream. This has the same semantic behavior as pullAll(BoltResponseHandler), but without actually retrieving the stream. This is useful for completing the run of a statement when you don't care about the data result.

Throws:

BoltConnectionFatality

pullAll

public void pullAll(BoltResponseHandler handler)
             throws BoltConnectionFatality

Retrieve all remaining entries in the current result. This is a distinct operation from 'run' in order to enable pulling the output stream in chunks controlled by the user

Throws:

BoltConnectionFatality

key

public String key()

A session id that is unique for this database instance

interrupt

public void interrupt()

When this is invoked, the machine will make attempts at interrupting any currently running action, and will then ignore all inbound messages until a reset message is received. If this is called multiple times, an equivalent number of reset messages must be received before the SSM goes back to a good state. You can imagine this is as a "call ahead" mechanism used by RESET to cancel any statements ahead of it in line, without compromising the single- threaded processing of messages that the state machine does. This can be used to cancel a long-running statement or transaction.

externalError

public void externalError(Neo4jError error,
                          BoltResponseHandler handler)
                   throws BoltConnectionFatality

Throws:

BoltConnectionFatality

isClosed

public boolean isClosed()

close

public void close()

Specified by:

close in interface AutoCloseable

owner

public String owner()

Specified by:

owner in interface org.neo4j.kernel.api.bolt.ManagedBoltStateMachine

terminate

public void terminate()

Specified by:

terminate in interface org.neo4j.kernel.api.bolt.ManagedBoltStateMachine

willTerminate

public boolean willTerminate()

Specified by:

willTerminate in interface org.neo4j.kernel.api.bolt.ManagedBoltStateMachine