# 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
Detail
- IOT
  - RECORD_TYPE
  - TIME
  - MEASUREMENT
Trailer
- IOT
  - RECORD_TYPE
  - COUNT

Then in a Javascript processor we can do this:

...
onMessage(message) {
    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(OUTPUT_PORT, message);
}
...

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));
    }
}
...

# Definition

Kind: global class
Properties

Name	Type
data	`Object`
type	`Object`

Message
- instance
  - .addStatus(severity, status, [addToLog])
  - .clone() ⇒ Message
  - .exists(entityDeclaration) ⇒ boolean
  - .findStatus(callback) ⇒ Array.<Status>
  - .getCrc64(message) ⇒ string
  - .getMessageDigest([algorithm], [toLowerCase], [accessorArray])
  - .getStatus(index) ⇒ Status | undefined
  - .pack() ⇒ PackedMessage
- static
  - .getBigInteger(accessor) ⇒ BigInteger
  - .getBoolean(accessor, [defaultValue]) ⇒ Boolean
  - .getByte(accessor) ⇒ Byte
  - .getByteString(accessor) ⇒ ByteString
  - .getCharacter(accessor) ⇒ char
  - .getDateTime(accessor) ⇒ OffsetDateTime
  - .getDecimal(accessor) ⇒ BigDecimal
  - .getDouble(accessor) ⇒ Double
  - .getInt(accessor) ⇒ Integer
  - .getLong(accessor) ⇒ Long
  - .getObject(accessor) ⇒ Object
  - .getString(accessor) ⇒ string
  - .hasStatusAttached(severity) ⇒ boolean
  - .getNumStatusAttached() ⇒ number
  - .setBigInteger(accessor, value)
  - .setBoolean(accessor, value)
  - .setByte(accessor, value)
  - .setByteString(accessor, value)
  - .setCharacter(accessor, value)
  - .setDateTime(accessor, value)
  - .setDecimal(accessor, value)
  - .setDouble(accessor, value)
  - .setInt(accessor, value)
  - .setLong(accessor, value)
  - .setObject(accessor, value)
  - .setString(accessor, value)
  - .toString()

# addStatus

Adds a Status to a message. The Status must have been created with Status.create or otherwise instantiated.

Example:

 if (error) {
     message.addStatus(Severity.ERROR, Status.create(VENDOR, 'ILLEGAL_VALUE', valueString));
 }

Kind: instance method of Message

Param	Type	Default	Description
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.

# clone

Creates a full clone of a Message

clonedMessage = message.clone();

Kind: instance method of Message
Returns: Message - A copy of a Message

# exists

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 meessage is of a certain type, or not.

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)) {
    ...
}

Kind: instance method of Message
Returns: boolean - - True, if it exists, else false.

Param	Type	Description
entityDeclaration	`EntityDeclaration`	Path to data dictionary structure which you want to test for existence in the message (EntityDeclaration.)

# findStatus

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; ",
 });",

Kind: instance method of Message
Returns: Array.<Status> - - Array of found States. Empty array if nothing found.

Param	Type	Description
callback	`function`	Callback function used to find a specific status.

# getCrc64

Creates a CRC 64 checksum from specified node within a Message.

Example:

const crc64 = message.getCrc64(message.data.CSV);

Kind: instance method of Message
Returns: string - CRC 64 checksum

Param	Type	Description
message	`MessageNode`	MessageNode for which to create the CRC64 checksum.

# getMessageDigest

Returns a calculated digest for a given message 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);

Kind: instance method of Message

Param	Type	Default	Description
[algorithm]	`"MD5"`		Algorithm with which to calculate the digest. Currently only supprts "MD5".
[toLowerCase]	`boolean`	`false`	Set to true if digest should be lower-case only.
[accessorArray]	`Array.<EntityDeclaration>`		Array of EntityDeclaration on which to calculate the digest.

# getStatus

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.

Example:

// Retrieve the first Status from the list of States attached to the message.
const status = message.getStatus(0);

Kind: instance method of Message
Returns: Status | undefined - - Status or undefined if no Status found with that index.

Param	Type	Description
index	`number`	Index of Status to retrieve.

# pack

Packs the message into a memory efficient format.

// Pack message
const packedMsg = message.pack();

// Unpack message
const unpackedMsg = packedMsg.unpack();

Kind: instance method of Message
Returns: PackedMessage - - Packed message.

# getBigInteger

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.

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"

Kind: static method of Message
Returns: BigInteger - Number in Java native BigInteger type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getBoolean

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).

Example:

const b = message.getBoolean(dataDictionary.type.Detail.CSV.A_BOOLEAN_FIELD);

Kind: static method of Message
Returns: Boolean - Number in Java native Boolean type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.
[defaultValue]	`Boolean`	Default value if no Boolean value could be retrieved from message.

# getByte

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).

Example:

const b = message.getByte(dataDictionary.type.Detail.CSV.A_BYTE_FIELD);

Kind: static method of Message
Returns: Byte - Java native Byte type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getByteString

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).

Example:

const b = message.getByteString(dataDictionary.type.Detail.CSV.FIELD);

Kind: static method of Message
Returns: ByteString - ByteString type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getCharacter

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).

Example:

const c = message.getCharacter(dataDictionary.type.Detail.CSV.FIELD);

Kind: static method of Message
Returns: char - Character in Java native char type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getDateTime

Return a OffsetDateTime typed value from a message field. Important!: Please note that this method returns a "OffsetDateTime (opens new window)" typed value (a Java native data type).

Example:

const dt = message.getDateTime(dataDictionary.type.Detail.CSV.FIELD);

Kind: static method of Message
Returns: 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".

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getDecimal

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).

Example:

const dec = message.getDecimal(dataDictionary.type.Detail.CSV.FIELD);

Kind: static method of Message
Returns: BigDecimal - BigDecimal in Java native char type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getDouble

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).

Example:

const dbl = message.getDouble(dataDictionary.type.Detail.CSV.FIELD);

Kind: static method of Message
Returns: Double - Double in Java native char type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getInt

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).

Example:

const int = message.getInt(dataDictionary.type.Detail.CSV.FIELD);

Kind: static method of Message
Returns: Integer - Integer in Java native char type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getLong

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).

Example:

const l = message.getLong(dataDictionary.type.Detail.CSV.FIELD);

Kind: static method of Message
Returns: Long - Long in Java native char type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getObject

Return a Object value a message field.

Example:

const o = message.getObject(dataDictionary.type.Detail.CSV.FIELD);

Kind: static method of Message
Returns: Object - Object in Java native char type.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# getString

Return a String typed value from a message field.

Example:

const l = message.getLong(dataDictionary.type.Detail.CSV.FIELD);

Kind: static method of Message
Returns: string - The value as string.

Param	Type	Description
accessor	`EntityDeclaration`	EntityDeclaration describing the access path to the field value.

# hasStatusAttached

Checks if a message has a Status attached which matches a particular Severity.

const result = message.hasStatusAttached(Severity.ERROR);

Kind: static method of Message
Returns: boolean - - True, if match found, else false.

Param	Type	Description
severity	`Severity`	Severity to check against.

# getNumStatusAttached

Gets the number of States Status attached.

const result = message.getNumStatusAttached();

Kind: static method of Message
Returns: number - - Number of States attached to the message.