RexPro Messages

stephen mallette edited this page Aug 13, 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][serializer type][reserved (4x)][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 one.
serializer type byte(1) The type of serializer to use. 0 for msgpack, 1 for json.
reserved byte(4) These bytes reserved for future use.
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.
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.
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
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.
console String A console response will be returned if true. Defaults to false. 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.

Script Response

The Script Response Message contains the results of a Gremlin script sent in a Script Request Message.

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.
6 : The result or an item in the bindings could not be serialized properly.

Previous Versions

For RexPro formats for Rexster versions prior to 2.4.0, see here