Class: Message
Events traversing layline.io Workflows are instantiated as a Message. This class exposes a number of properties and methods to extract and set data within messages.
To understand the anatomy of a message please read the respective chapter in the documentation.
Example Message Structure
Assume we have the following data dictionary structure
- Header
- IOT
- RECORD_TYPE
- DEVICE_NO
- IOT
- Detail
- IOT
- RECORD_TYPE
- TIME
- MEASUREMENT
- IOT
- Trailer
- IOT
- RECORD_TYPE
- COUNT
- IOT
Then in a Javascript processor we can do this:
...
export function onMessage() {
if (message.type.Header) {
onHeader (message);
} else if (message.type.Detail) {
onDetail(message);
} else if (message.type.Trailer) {
onDetail(message);
}
// send the message on through OUTPUT_PORT of Processor
stream.emit(message, OUTPUT_PORT);
}
...
And this:
...
// Handle a detail record type
onDetail (message) {
const m = message.data.IOT.MEASUREMENT;
const VENDOR = Status.getVendorByName('MyVendorLongName');
if (m < 0) {
message.addStatus(Severity.ERROR, Status.create(VENDOR, 'ILLEGAL_MEASUREMENT', m));
}
}
...
Properties
data
data:
object
Methods
addStatus()
addStatus(
severity
,status
,addToLog
?):void
Adds a Status to a message. The Status must have been created with Status.create or otherwise instantiated.
Parameters
• severity: Severity
Severity value.
• status: Status
The Status which should be added.
• addToLog?: boolean
= true
Signals whether the Status shall also be added to the log, or not. Will be added by default if not specified.
If true
then the Status will be visible in the Stream Log of the Audit Trail.
Returns
void
Example
if (error) {
message.addStatus(Severity.ERROR, Status.create(VENDOR, 'ILLEGAL_VALUE', valueString));
}
clone()
clone():
Message
Creates a full clone of a Message
clonedMessage = message.clone();
Returns
A copy of a Message
exists()
exists(
entityDeclaration
):boolean
Checks if a known data structure is recognized within a given Message. Data structures are spawned into existence by the definition of data formats (Format Assets). You can test a particular Message on whether a specific structure is present within a message by using this method.
This is typically used to check whether a message is of a certain type, or not.
Parameters
• entityDeclaration: EntityDeclaration
The Path to data dictionary structure which you want to test for existence in the message (EntityDeclaration.)
Returns
boolean
True, if it exists, else false.
Example
// Get the access path to a structure within the compiled data dictionary
const MY_RECORD_TYPE = dataDictionary.type.MyFormat.Detail;
// Test message against the existence of the data dictionary structure.
if (message.exists(MY_RECORD_TYPE)) {
...
}
findStatus()
findStatus(
callback
):Status
Check whether a message carries a specified status.
const VENDOR = Status.getVendorByName('MyVendorLongName');
const foundStatusArray = detail.findStatus(function(status) { ",
// Code 9 means 'DISCARD'",
return status.vendorId === VENDOR.id && status.code === 9; ",
});",
Parameters
• callback: Function
Returns
- Array of found States. Empty array if nothing found.
getBigInteger()
getBigInteger(
accessor
):Uint8Array
Return a BigInteger typed value from a message field. Important!: Please note that this method returns a Java object "Big Integer" (a Java native data type). Because of this you cannot reliably use simple Javascript number operators without risking implicit conversion errors.
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
Uint8Array
Number in Java native BigInteger type.
Example
const n = message.getBigInteger(dataDictionary.type.Detail.CSV.A_REALLY_BIG_NUMBER_FIELD);
// Compare BigInteger to another BigInteger
const BigInteger = Java.type("java.math.BigInteger");
x = new BigInteger(123); // x now a java type BigInteger
x == 123; // -> "true", via implicit conversion --> be careful here, because x will be implicitly be converted to JS number and may lose precision
x.equals(123); // -> "false", because comparing different data types (BigInteger / Number)
x.equals(new BigInteger(123)); // -> "true"
getBoolean()
getBoolean(
accessor
,defaultValue
?):Boolean
Return the Boolean typed value from a message field. Important!: Please note that this method returns a Java object "Boolean" (a Java native data type).
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• defaultValue?: boolean
Default value if no Boolean value could be retrieved from message.
Returns
Boolean
Number in Java native Boolean type.
Example
const b = message.getBoolean(dataDictionary.type.Detail.CSV.A_BOOLEAN_FIELD);
getByte()
getByte(
accessor
):Byte
Return the Byte typed value from a message field. Important!: Please note that this method returns a Java object "Byte" (a Java native data type).
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
Java native Byte type.
Example
const b = message.getByte(dataDictionary.type.Detail.CSV.A_BYTE_FIELD);
getByteString()
getByteString(
accessor
):ByteString
Return the ByteString typed value from a message field. Important!: Please note that this method returns a "ByteString" typed value (a Java native data type).
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
ByteString type.
Example
const b = message.getByteString(dataDictionary.type.Detail.CSV.FIELD);
getCharacter()
getCharacter(
accessor
):Character
Return a Character typed value from a message field. Important!: Please note that this method returns a "char" typed value (a Java native data type).
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
Character in Java native char type.
Example
const c = message.getCharacter(dataDictionary.type.Detail.CSV.FIELD);
getCrc64()
getCrc64(
message
):string
Creates a CRC 64 checksum from specified node within a Message.
Parameters
• message: MessageNode
MessageNode for which to create the CRC64 checksum.
Returns
string
CRC 64 checksum
Example
const crc64 = message.getCrc64(message.data.CSV);
getDateTime()
getDateTime(
accessor
):OffsetDateTime
Return a OffsetDateTime typed value from a message field. Important!: Please note that this method returns a "OffsetDateTime" typed value (a Java native data type).
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
A date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system, such as "2022-12-03T10:15:30+01:00".
Example
const dt = message.getDateTime(dataDictionary.type.Detail.CSV.FIELD);
getDecimal()
getDecimal(
accessor
):BigDecimal
Return a BigDecimal typed value from a message field. Important!: Please note that this method returns a "BigDecimal" typed value (a Java native data type).
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
BigDecimal in Java native char type.
Example
const dec = message.getDecimal(dataDictionary.type.Detail.CSV.FIELD);
getDouble()
getDouble(
accessor
):Double
Return a Double typed value from a message field. Important!: Please note that this method returns a "Double" typed value (a Java native data type).
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
Double in Java native char type.
Example
const dbl = message.getDouble(dataDictionary.type.Detail.CSV.FIELD);
getInt()
getInt(
accessor
):Integer
Return a Int typed value from a message field. Important!: Please note that this method returns a "Integer" typed value (a Java native data type).
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
Integer in Java native char type.
Example
const int = message.getInt(dataDictionary.type.Detail.CSV.FIELD);
getLong()
getLong(
accessor
):Long
Return a Long typed value from a message field. Important!: Please note that this method returns a "Long" typed value (a Java native data type).
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
Long in Java native char type.
Example
const l = message.getLong(dataDictionary.type.Detail.CSV.FIELD);
getMessageDigest()
getMessageDigest(
algorithm
?,toLowerCase
?,accessorArray
?):string
Returns a calculated digest for a given message
Parameters
• algorithm?: string
Algorithm with which to calculate the digest. Currently only supports "MD5".
• toLowerCase?: boolean
= false
Set to true if digest should be lower-case only.
• accessorArray?: EntityDeclaration
[]
Array of EntityDeclaration on which to calculate the digest.
Returns
string
Example
// Option: 1. Return digest considering complete message content.
// Digest calculation defaults to MD5 hash and no lower case.
const md5DigestFull = message.getMessageDigest();
// Option: 2. Return digest for full message content based on MD5 hash.
// Returned digest will be lower case only.
const md5DigestFullLower = message.getMessageDigest("MD5", true);
// Option: 3. Calculate digest considering specific data structures within message only.
recordAccessorForMD5 = [
dataDictionary.type.Detail.CSV.RECORD_TYPE,
dataDictionary.type.Detail.CSV.LAST_NAME,
dataDictionary.type.Detail.CSV.FIRST_NAME
]
const md5Digest = message.getMessageDigest("MD5", true, recordAccessorForMD5);
getNumStatusAttached()
getNumStatusAttached():
void
Gets the number of States Status attached.
const result = message.getNumStatusAttached();
Returns
void
- Number of States attached to the message.
getObject()
getObject(
accessor
):Object
Return a Object value a message field.
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
Object
Object in Java native char type.
Example
const o = message.getObject(dataDictionary.type.Detail.CSV.FIELD);
getStatus()
getStatus(
index
):Status
Retrieves a Status by index from the list of States attached to a message. A message keeps track of related States in a Status array attached to it. This list may be empty or filled with one more States.
Parameters
• index: number
Index of Status to retrieve.
Returns
- Status or undefined if no Status found with that index.
Example
// Retrieve the first Status from the list of States attached to the message.
const status = message.getStatus(0);
getString()
getString(
accessor
):String
Return a String typed value from a message field.
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
Returns
String
The value as string.
Example
const l = message.getLong(dataDictionary.type.Detail.CSV.FIELD);
hasStatusAttached()
hasStatusAttached(
severity
):void
Checks if a message has a Status attached which matches a particular Severity.
const result = message.hasStatusAttached(Severity.ERROR);
Parameters
• severity: Severity
Severity to check against.
Returns
void
- True, if match found, else false.
pack()
pack():
PackedMessage
Packs the message into a memory efficient format.
// Pack message
const packedMsg = message.pack();
// Unpack message
const unpackedMsg = packedMsg.unpack();
Returns
- Packed message.
setBigInteger()
setBigInteger(
accessor
,value
):void
Sets a BigInteger value in a message target field.
const BigInteger = Java.type("java.math.BigInteger");
bigInt = new BigInteger(123); // x now a java type BigInteger
message.setBigInteger(dataDictionary.type.Detail.CSV.FIELD, bigInt)
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: Uint8Array
A native BigInteger value or a value which can be implicitly converted to such.
Returns
void
setBoolean()
setBoolean(
accessor
,value
):void
Sets a Boolean value in a message target field.
message.setBoolean(dataDictionary.type.Detail.CSV.FIELD, true)
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: Boolean
A native Byte value or a value which can be implicitly converted to such.
Returns
void
setByte()
setByte(
accessor
,value
):void
Sets a Byte value in a message target field.
const Byte = Java.type("java.math.Byte");
b = new Byte(123); // b now a java type Byte
message.setByte(dataDictionary.type.Detail.CSV.FIELD, b)
// or
message.setByte(dataDictionary.type.Detail.CSV.FIELD, 7)
// or
message.setByte(dataDictionary.type.Detail.CSV.FIELD, 'X')
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: string
| number
A native Byte value or a value which can be implicitly converted to such.
Returns
void
setByteString()
setByteString(
accessor
,value
):void
Sets a ByteString value in a message target field.
const ByteString = Java.type("java.math.ByteString");
b = new ByteString("XYZ"); // b now a java type ByteString
message.setByteString(dataDictionary.type.Detail.CSV.FIELD, b)
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: string
A native ByteString value or a value which can be implicitly converted to such.
Returns
void
setCharacter()
setCharacter(
accessor
,value
):void
Sets a Character value in a message target field.
message.setCharacter(dataDictionary.type.Detail.CSV.FIELD, 'c')
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: Character
A native Character value or a value which can be implicitly converted to such.
Returns
void
setDateTime()
setDateTime(
accessor
,value
):void
Sets a OffsetDateTime value in a message target field.
message.setCharacter(dataDictionary.type.Detail.CSV.FIELD, "2022-12-03T10:15:30+01:00")
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: OffsetDateTime
A date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system, such as "2022-12-03T10:15:30+01:00".
Returns
void
setDecimal()
setDecimal(
accessor
,value
):void
Sets a Decimal value in a message target field. Internally represented as a Java BigDecimal. Will try to infer result from passed value.
message.setDecimal(dataDictionary.type.Detail.CSV.FIELD, 123.45)
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: BigDecimal
| BigInteger
| Double
| Integer
| Long
| Number
| String
A value which can be represented as a Decimal.
Returns
void
setDouble()
setDouble(
accessor
,value
):void
Sets a Double value in a message target field. Internally represented as a Java Double. Will try to infer result from passed value.
message.setDouble(dataDictionary.type.Detail.CSV.FIELD, 123.45)
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: Number
| BigDecimal
| BigInteger
| Double
| Integer
| Long
| String
A value which can be represented as a Double.
Returns
void
setInt()
setInt(
accessor
,value
):void
Sets a Int value in a message target field. Internally represented as a Java Int. Will try to infer result from passed value.
message.setInt(dataDictionary.type.Detail.CSV.FIELD, 123)
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: Number
| Uint8Array
| BigDecimal
| Double
| Integer
| Long
| String
A value which can be represented as a Int.
Returns
void
setLong()
setLong(
accessor
,value
):void
Sets a Long value in a message target field. Internally represented as a Java Long. Will try to infer result from passed value.
message.setLong(dataDictionary.type.Detail.CSV.FIELD, 12345)
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: BigDecimal
| BigInteger
| Double
| Integer
| Long
| Number
| String
A value which can be represented as a Long.
Returns
void
setObject()
setObject(
accessor
,value
):void
Sets a Object value in a message target field.
const obj = [1, 2, 3, 4, 5];
message.setObject(dataDictionary.type.Detail.CSV.FIELD, obj)
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: Object
A value which can be represented as a Object.
Returns
void
setString()
setString(
accessor
,value
):void
Sets a Object value in a message target field.
message.setString(dataDictionary.type.Detail.CSV.FIELD, "XYZ")
// or simply
message.data.CSV.FIELD = "XYZ"
Parameters
• accessor: EntityDeclaration
EntityDeclaration describing the access path to the field value.
• value: Object
A value which can be represented as a String.
Returns
void
toString()
toString():
void
Returns the message in a string representation.
Returns
void
Example
stream.logInfo("Current message: " + message.toString());