RexPro Messages

Communication over RexPro is achieved by sending and receiving messages that adhere to the format specified on this page. There are several clients that communicate via RexPro that would serve as good examples for how communication over RexPro works:

• Rexster Console – A REPL for executing scripts on a remote Rexster server.
• RexsterClient – A Java language binding
• rexpro-python – A Python language binding

Basic Message Structure

Evern RexPro message consists of the following segments:

[protocol version][message type][message size][message body]

segment	type(bytes)	description
protocol version	byte(1)	The version of RexPro. Currently, this value should be set to zero.
message type	byte(1)	The type of message as described below.
message size	int(4)	The length of the message body
message body	byte(n)	The body of the message itself containing the instructions for the RexPro Server. This portion of the message is serialized using MsgPack.

Message Definitions

RexPro messages are divided into those that deal with requests made from the client and those that involved a response from the server. The following table represents an overview of the basic message set:

message	type	description
session	request	A request to open or close the session with the RexPro Server.
session	response	The response from the RexPro Server to a session request containing session information.
script	request	A request to process a Gremlin script on the RexPro Server.
script	response	A response to a script request. Script response messages actually refer to a set of response messages that are unique to each serialization channel (i.e. MsgPack, GraphSON, and Console).
error	response	A response from the RexPro Server indicating a problem has occurred.

NOTE – The following sections describe the individual RexPro Messages in greater detail. It is important to note that the messages are defined in terms of MsgPack serialization, so data types defined must adhere to MsgPack expectations.

Request Messages

The request class of messages are those that are sent by the client to the RexPro Server for processing.

Session

The Session Request Message is used to establish or destroy a session on the RexPro Server. When a session is opened, future Script Request Messages can be executed within this session and variable bindings established in previous scripts can be accessed.

field	type	description
Meta	Map	Message specific properties described below.
Session	byte(16)	The UUID for the Session. Set each byte to zero for an “empty” session.
Request	byte(16)	The UUID for the request. Uniquely identifies the request from the client. This value gets passed back from the RexPro Server so that the response message can be mapped to a request if necessary.
Channel	Integer	Defines the channel of serialization for the life of the session. The channel cannot be changed on future requests to the session.
Username	String	The username to access the RexPro Server assuming Rexster authentication is turned on. The field is ignored in cases where it is not enabled.
Password	String	The password to access the RexPro Server assuming Rexster authentication is turned on. The field is ignored in cases where it is not enabled.

Meta Attributes

field	type	description
graphName	String	The name of the graph to open a session on. Optional.
graphObjName	String	The variable name of the graph object, defaults to g. Optional.
killSession	Boolean	If true, the given session will be destroyed, otherwise, one will be created, defaults to false.

Script

The Script Request Message is used to send Gremlin scripts to the RexPro Server. Script Requests can be made either in-session or sessionless. In-session requires that a session is already established with the RexPro Server via the Session Request Message. Sessionless Script Request Messages can be sent without the context of the session but come with the limitation that variable bindings established by a script are lost between requests.

field	type	description
Meta	Map	Message specific properties described below.
Session	byte(16)	The UUID for the Session. Set each byte to zero for an “empty” session.
Request	byte(16)	The UUID for the request. Uniquely identifies the request from the client. This value gets passed back from the RexPro Server so that the response message can be mapped to a request if necessary.
LanguageName	String	The Gremlin flavor to request the RexPro Server to process the message with. This value is dependent upon the configured script engine languages in rexster.xml. Generally speaking, this value should be set to groovy.
Script	String	The Gremlin script to execute on the server.
Bindings	Map	Bindings are arguments passed with the script that become variables to the Script Engine when the script is executed. Use bindings to parameterize scripts. Bindings must be serializable by MsgPack.

Meta Attributes

field	type	description
channel	Integer	Used where inSession is false and the channel of communication is established for each request. If this value is used when inSession is true it must match the value established by the session.
inSession	Boolean	Indicates this requests should be executed in the supplied session. Defaults to false. Optional.
isolate	Boolean	Prevents variables defined in this request from being accessible in later requests. Defaults to true. Optional.
transaction	Boolean	Executes script within a transaction, committing if successful, rolling back if not. Has no effect with non transactional graph. Defaults to true. Optional.
graphName	String	The name of the graph to open a session on. Optional.
graphObjName	String	The variable name of the graph object. Defaults to g. Optional.

NOTE – supplying graphName or graphObjName for a session request which already has these values defined will raise an exception.

Response Messages

The response class of messages are those that are sent by the RexPro Server back to the client, in response to a request message.

Session

The Session Response Message is used to send a response to a Session Request Message and is sent when the session is successfully created. The Session Response Message will contain information about the session created by the RexPro Server.

field	type	description
Meta	Map	Not applicable for this message
Session	byte(16)	The UUID for the Session. Used on future Script Request Messages that need to be made on the session.
Request	byte(16)	The UUID for the request. Uniquely identifies the request from the client. This value gets passed back from the RexPro Server so that the response message can be mapped to a request if necessary.
Languages	String[]	The list of Gremlin flavors that are configured for Rexster. By default the language list will just be groovy.

Console Script

The Console Script Response Message contains the results of a Gremlin script sent in a Script Request Message, where the results are serialized into strings that are best displayed in a console or terminal. Rexster Console uses this message for communication with the RexPro Server.

field	type	description
Meta	Map	Not applicable for this message
Session	byte(16)	The UUID for the Session. Used on future Script Request Messages that need to be made on the session.
Request	byte(16)	The UUID for the request. Uniquely identifies the request from the client. This value gets passed back from the RexPro Server so that the response message can be mapped to a request if necessary.
ConsoleLines	String[]	List of results serialized to strings where each string is a line that should be printed to a console output.
Bindings	Map	Once the script is executed any bindings on the Script Engine that can be serialized via MsgPack are returned. Any that cannot be properly serialized are converted via toString.

GraphSON Script

The GraphSON Script Response Message contains the results of a Gremlin script sent in a Script Request Message, where the results are serialized into a JSON string by the GraphSON converter from Blueprints.

field	type	description
Meta	Map	Not applicable for this message
Session	byte(16)	The UUID for the Session. Used on future Script Request Messages that need to be made on the session.
Request	byte(16)	The UUID for the request. Uniquely identifies the request from the client. This value gets passed back from the RexPro Server so that the response message can be mapped to a request if necessary.
Results	String	The result serialized to a JSON string.
Bindings	Map	Once the script is executed any bindings on the Script Engine that can be serialized via MsgPack are returned. Any that cannot be properly serialized are converted via toString.

MsgPack Script

The MsgPack Script Response Message contains the results of a Gremlin script sent in a Script Request Message, where the results are serialized by MsgPack to a byte array.

field	type	description
Meta	Map	Not applicable for this message
Session	byte(16)	The UUID for the Session. Used on future Script Request Messages that need to be made on the session.
Request	byte(16)	The UUID for the request. Uniquely identifies the request from the client. This value gets passed back from the RexPro Server so that the response message can be mapped to a request if necessary.
Results	Object	The result serialized by MsgPack. Any result not serializable by MsgPack is converted via toString.
Bindings	Map	Once the script is executed any bindings on the Script Engine that can be serialized via MsgPack are returned. Any that cannot be properly serialized are converted via toString.

Error

An Error Response Message may be returned by the RexPro Server for any request message sent.

field	type	description
Meta	Map	Not applicable for this message
Session	byte(16)	The UUID for the Session. Used on future Script Request Messages that need to be made on the session.
Request	byte(16)	The UUID for the request. Uniquely identifies the request from the client. This value gets passed back from the RexPro Server so that the response message can be mapped to a request if necessary.
ErrorMessage	String	The error message from the server.

Meta Attributes

field	type	description
flag	Integer	– 0 : The message sent to the RexPro Server was malformed. – 1 : A session was requested that has either expired or no longer exists. – 2 : A script failed to execute (likely cause is syntax error). – 3 : Invalid username/password if authentication is turned on. – 4 : A graph requested via graphName meta attribute did not exist. – 5 : The channel requested did not exist or the channel was changed after being established on the session.