-
Notifications
You must be signed in to change notification settings - Fork 116
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
- RexsterClient – A Java language binding
- rexpro-python – A Python language binding
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. |
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.
The request class of messages are those that are sent by the client to the RexPro Server for processing.
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<String, Object> |
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. |
| 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. |
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<String, Object> |
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 |
byte(n) |
HOW DOES THIS WORK AGAIN? |
| 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.
The response class of messages are those that are sent by the RexPro Server back to the client, in response to a request message.
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<String, Object> |
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. |
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<String, Object> |
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 |
byte[] |
HOW DOES THIS WORK AGAIN? |
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<String, Object> |
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 |
byte[] |
HOW DOES THIS WORK AGAIN? |
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<String, Object> |
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 |
byte[] |
The result serialized by MsgPack. |
Bindings |
byte[] |
HOW DOES THIS WORK AGAIN? |
An Error Response Message may be returned by the RexPro Server for any request message sent.
| field | type | description |
|---|---|---|
Meta |
Map<String, Object> |
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. |
| field | type | description |
|---|---|---|
flag |
Integer |
– INVALID_MESSAGE:0 – INVALID_SESSION:1 – SCRIPT_FAILURE:2 – AUTH_FAILURE:3 – GRAPH_CONFIG:4 – CHANNEL_CONFIG:5 |