Skip to content

RexPro Messages

Jump to bottom
bdeggleston edited this page Apr 11, 2013 · 28 revisions

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:

Basic Message Structure

Every 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. See the value column.
message size int(4) The length of the message body
message body byte(n) The body of the message itself, containing the instructions for, or a response from, the RexPro Server. This portion of the message is an array of message fields serialized using MsgPack. The fields for each specific message are described below.

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 value description
session request 1 A request to open or close the session with the RexPro Server.
session response 2 The response from the RexPro Server to a session request containing session information.
script request 3 A request to process a Gremlin script on the RexPro Server.
script response 5 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 0 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. The order of fields in the sections below are important to adhering to the format. They should be serialized to a MsgPack array.

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
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.
Meta Map Message specific properties described below.
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
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.
Meta Map Message specific properties described below.
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 Bindings from previous messages are not available in subsequent 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
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.
Meta Map Not applicable for this message
Languages String[] The list of Gremlin flavors that are configured for Rexster. By default the language list will just be groovy.

Console Script Response

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
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.
Meta Map Not applicable for this message
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 Response

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
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.
Meta Map Not applicable for this message
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 Response

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.

field type description
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.
Meta Map Not applicable for this message
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
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.
Meta Map Not applicable for this message
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.
– 6 : The result or an item in the bindings could not be serialized properly.
Clone this wiki locally