docs/design/jet/023-jobupload.md
| Related Jira | https://hazelcast.atlassian.net/browse/HZ-1455 |
| Related Github issues | None |
| Document Status / Completeness | DRAFT |
| Requirement owner | TBD |
| Developer(s) | Orçun Çolak |
| Quality Engineer | TBD |
| Support Engineer | TBD |
| Technical Reviewers | Frantisek Hartman |
| Simulator or Soak Test PR(s) | TBD |
| Term | Definition |
|---|---|
| Client Binary Protocol | The binary messages used between Hazelcast Clients and Hazelcast Server |
Any language that implements Client Binary Protocol
Provide a list of functions user(s) can perform.
None
Jar On Client case :
Jar On Member case :
This feature uses private API. Therefore, the client needs to cast JetService to JetClientInstanceImpl
for Jar Upload
HazelcastInstance client=...;
JetClientInstanceImpl jetService=(JetClientInstanceImpl)client.getJet();
SubmitJobParameters submitJobParameters=SubmitJobParameters.withJarOnClient()
...;
//If there is an error, throws JetException
jetService.submitJobFromJar(submitJobParameters);
for Jar Execution
HazelcastInstance client=...;
JetClientInstanceImpl jetService=(JetClientInstanceImpl)client.getJet();
SubmitJobParameters submitJobParameters=SubmitJobParameters.withJarOnMember()
...;
//If there is an error, throws JetException
jetService.submitJobFromJar(submitJobParameters);
A new method has been added to JetClientInstanceImpl interface.
void submitJobFromJar(@Nonnull SubmitJobParameters submitJobParameters);
The client protocol needs to support job uploading. So that non-java clients can also upload and execute jet jobs. For this purpose two new messages have been added to client protocol.
These messages should be sent to a member in the cluster
1. uploadJobMetaData Message
This message is used for both jar upload and jar execution
Jar On Member case :
Jar is only executed. Uses only uploadJobMetaData. This message contains the fields below.
| Term | Type | Definition |
|---|---|---|
| sessionId | UUID - Not null | The UUID. |
| jarOnMember | Boolean - Needs to be true | Flag that indicates that the jar to be executed is already present on the member, and no jar will be uploaded from the client |
| filename | String - Not null | The full path of the jar file |
| sha256Hex | String - Not null but ignored, use empty string | Hexadecimal SHA256 of the jar file. |
| snapshotName | String - Nullable | Argument passed when starting the job |
| jobName | String - Nullable | Argument passed when starting the job |
| mainClass | String - Nullable | Argument passed when starting the job. If null the jar manifest should contain the mainClass value |
| jobParameters | List_String - Not null, use empty list for no parameters | Argument passed when starting the job. |
Jar On Client case :
** Note For Cloud Environment** : The uploaded file is stored in a temporary folder.
The upload process starts with uploadJobMetaData. This message contains the fields below.
| Term | Type | Definition |
|---|---|---|
| sessionId | UUID - Not null | The UUID. This field associates all messages in a session |
| jarOnMember | Boolean - Needs to be false | Flag that indicates that the jar to be executed is already present on the member, and no jar will be uploaded from the client |
| filename | String - Not null | Name of the jar file without extension |
| sha256Hex | String - Not null | Hexadecimal SHA256 of the jar file |
| snapshotName | String - Nullable | Argument passed when starting the job |
| jobName | String - Nullable | Argument passed when starting the job |
| mainClass | String - Nullable | Argument passed when starting the job. If null the jar manifest should contain the mainClass value |
| jobParameters | List_String - Not null , use empty list for no parameters | Argument passed when starting the job. |
Upon reception of uploadJobMetaData message, the server performs validation. If any validation rule them fails, a * JetException* is thrown. If the message can be validated, the server stores a new entry in the JobUploadStore class
2. uploadJobMultipart message
The upload process continues with this message. It contains jar's bytes. This message contains these fields
| Term | Type | Definition |
|---|---|---|
| sessionId | UUID | Explained in the previous message |
| currentPartNumber | int | Starts from 1 and shows the sequence number of the part. For example 1 of 5 |
| totalPartNumber | int | The total number of parts of the sequence |
| partData | byteArray | The byte[] containing jar data |
| partSize | int | Shows how many bytes of the partData byte[] is valid, |
| sha256Hex | String | Hexadecimal SHA256 of the part |
Why do we need an extra partSize field?
For optimization, it is assumed that partData is allocated only once on the client side. So we need another field to indicate the number of bytes to be read from this buffer
Upon reception of uploadJobMultipart, various checks are performed on the message and current session. If any of them fail, a JetException is thrown. If the message can be validated, it is processed. Some checks are
Pros of using the same JVM
Cons of using the same JVM
The uploadJobMultipart by default allocates a buffer of 10_000_000 bytes. The size of the buffer can be controlled by ClientProperty.JOB_UPLOAD_PART_SIZE property. So clients that want to allocate less memory may prefer to send a bigger total number of messages
HazelcastBootstrap was designed to work only by the hz-client command. With this PR it is modified to work on the server side. However, it is still a singleton.
If an exception is thrown by the server the upload operation fails. A timer in JetServiceBackend cleans the expired JobUploadStore items and deletes the temporary file
Describe testing approach to developed functionality
None