Apama  10.5.4.1
com::softwareag::connectivity::Message Class Reference

A container for an payload and associated metadata. More...

#include <sag_connectivity_cpp.hpp>

Inherits sag_underlying_message_t.

Public Types

typedef com::softwareag::connectivity::metadata_t metadata_t
 The type of a message metadata. More...
 
typedef data_t payload_t
 The type of a message payload. More...
 

Public Member Functions

 Message ()
 Construct an empty message. More...
 
 Message (payload_t &&_payload)
 Construct a message from a payload. More...
 
 Message (payload_t &&_payload, metadata_t &&_metadata)
 Construct a message from a payload and metadata. More...
 
 Message (payload_t &&_payload, map_t &&_metadata)
 Construct a message from a payload and map_t. More...
 
 ~Message ()
 Free the underlying payload and metadata. More...
 
 Message (Message &&other)
 Move constructor from another message. More...
 
Messageoperator= (Message &&other)
 Move assignment from another message. More...
 
const payload_tgetPayload () const
 Return a reference to the payload. More...
 
const metadata_tgetMetadata () const
 
payload_tgetPayload ()
 Return a reference to the payload. More...
 
metadata_tgetMetadata ()
 
map_tgetMetadataMap ()
 Return a view on the metadata which can contain non-string values. More...
 
const map_tgetMetadataMap () const
 Return a view on the metadata which can contain non-string values. More...
 
void setPayload (payload_t &&_payload)
 Set the payload. More...
 
void setMetadata (metadata_t &&_metadata)
 Set the metadata as metadata_t. More...
 
void setMetadata (map_t &&_metadata)
 Set the metadata as map_t. More...
 
void swap (Message &&other)
 Swap the contents of this message with another. More...
 
Message copy () const
 Return a deep copy of this message, payload and metadata. More...
 
MessageputMetadataValue (data_t &&key, data_t &&value)
 Sets a value in the metadata. More...
 

Static Public Member Functions

static const char * HOST_MESSAGE_TYPE ()
 Returns the metadata key used by the host for identifying the type of the message - "sag.type". More...
 
static const char * CHANNEL ()
 Returns the metadata key used by the host for identifying the channel of the message - "sag.channel". More...
 
static const char * CONTROL_TYPE ()
 The metadata key indicating that a message is a control message, and what its type is. More...
 
static const char * MESSAGE_ID ()
 The metadata key used for unique identification of towards-host messages. More...
 
static const char * REQUEST_ID ()
 The metadata key used for unique identification of towards-transport control messages, with a value of type int64_t. More...
 
static const char * CONTROL_TYPE_FLUSH ()
 Name of the Flush control message, a towards-transport control message. More...
 
static const char * CONTROL_TYPE_FLUSH_ACK ()
 Name of the FlushAck control message, a towards-host control message in response to Flush, containing the corresponding REQUEST_ID. More...
 
static const char * CONTROL_TYPE_ACK_REQUIRED ()
 Name of the AckRequired control message, a towards-host control message. More...
 
static const char * CONTROL_TYPE_ACK_UPTO ()
 Name of the AckUpTo control message, a towards-transport control message in response to AckRequired, containing the corresponding MESSAGE_ID. More...
 

Detailed Description

A container for an payload and associated metadata.

This class is not thread-safe, so users are required to ensure that each instance of Message is only accessed by the codec or transport plug-in that currently owns it, and that only one thread is accessing it at any one time.

Member Typedef Documentation

◆ metadata_t

◆ payload_t

The type of a message payload.

Constructor & Destructor Documentation

◆ Message() [1/5]

com::softwareag::connectivity::Message::Message ( )

Construct an empty message.

◆ Message() [2/5]

com::softwareag::connectivity::Message::Message ( payload_t &&  _payload)
explicit

Construct a message from a payload.

This is a move constructor so the the argument will be left in an empty state. If you do not want this .copy() otherwise use std::move()

◆ Message() [3/5]

com::softwareag::connectivity::Message::Message ( payload_t &&  _payload,
metadata_t &&  _metadata 
)

Construct a message from a payload and metadata.

This is a move constructor so the the argument will be left in an empty state. If you do not want this use .copy() otherwise use std::move()

◆ Message() [4/5]

com::softwareag::connectivity::Message::Message ( payload_t &&  _payload,
map_t &&  _metadata 
)

Construct a message from a payload and map_t.

This is a move constructor so the the argument will be left in an empty state. If you do not want this use .copy() otherwise use std::move()

◆ ~Message()

com::softwareag::connectivity::Message::~Message ( )

Free the underlying payload and metadata.

◆ Message() [5/5]

com::softwareag::connectivity::Message::Message ( Message &&  other)

Move constructor from another message.

The argument will be left in an empty state. If you do not want this use .copy() otherwise use std::move().

Member Function Documentation

◆ CHANNEL()

static const char* com::softwareag::connectivity::Message::CHANNEL ( )
inlinestatic

Returns the metadata key used by the host for identifying the channel of the message - "sag.channel".

◆ CONTROL_TYPE()

static const char* com::softwareag::connectivity::Message::CONTROL_TYPE ( )
inlinestatic

The metadata key indicating that a message is a control message, and what its type is.

The metadata value names the control message, with different types of control message defined in the CONTROL_TYPE_* constants.

Control messages must have a null payload.

See also
CONTROL_TYPE_ACK_REQUIRED()
CONTROL_TYPE_ACK_UPTO()
CONTROL_TYPE_FLUSH()
CONTROL_TYPE_FLUSH_ACK()

◆ CONTROL_TYPE_ACK_REQUIRED()

static const char* com::softwareag::connectivity::Message::CONTROL_TYPE_ACK_REQUIRED ( )
inlinestatic

Name of the AckRequired control message, a towards-host control message.

It is a request for the host to acknowledge that all previous towards-host non-control messages have been fully and reliably processed. Metadata of this control message should also contain the MESSAGE_ID of the immediately preceding non-control message.

See also
CONTROL_TYPE_ACK_UPTO()
MESSAGE_ID()
CONTROL_TYPE()

◆ CONTROL_TYPE_ACK_UPTO()

static const char* com::softwareag::connectivity::Message::CONTROL_TYPE_ACK_UPTO ( )
inlinestatic

Name of the AckUpTo control message, a towards-transport control message in response to AckRequired, containing the corresponding MESSAGE_ID.

AckUpTo messages will be seen in the exact order that their corresponding AckRequired messages were sent, with none missing or duplicated.

See also
CONTROL_TYPE_ACK_REQUIRED()
MESSAGE_ID()
CONTROL_TYPE()

◆ CONTROL_TYPE_FLUSH()

static const char* com::softwareag::connectivity::Message::CONTROL_TYPE_FLUSH ( )
inlinestatic

Name of the Flush control message, a towards-transport control message.

It is a request for the transport to acknowledge that all previous towards-transport non-control messages have been fully and reliably processed. Metadata of this control message will also contain a unique REQUEST_ID.

See also
CONTROL_TYPE_FLUSH_ACK()
REQUEST_ID()
CONTROL_TYPE()

◆ CONTROL_TYPE_FLUSH_ACK()

static const char* com::softwareag::connectivity::Message::CONTROL_TYPE_FLUSH_ACK ( )
inlinestatic

Name of the FlushAck control message, a towards-host control message in response to Flush, containing the corresponding REQUEST_ID.

FlushAck messages implicitly cover all preceding Flush messages. That is, it is safe to miss a Flush if you have a later Flush in hand that succeeds it.

See also
CONTROL_TYPE_FLUSH()
REQUEST_ID()
CONTROL_TYPE()

◆ copy()

Message com::softwareag::connectivity::Message::copy ( ) const
inline

Return a deep copy of this message, payload and metadata.

◆ getMetadata() [1/2]

const metadata_t& com::softwareag::connectivity::Message::getMetadata ( ) const
inline
Deprecated:
Return a reference to the metadata

◆ getMetadata() [2/2]

metadata_t& com::softwareag::connectivity::Message::getMetadata ( )
inline
Deprecated:
Return a reference to the metadata

◆ getMetadataMap() [1/2]

map_t& com::softwareag::connectivity::Message::getMetadataMap ( )
inline

Return a view on the metadata which can contain non-string values.

◆ getMetadataMap() [2/2]

const map_t& com::softwareag::connectivity::Message::getMetadataMap ( ) const
inline

Return a view on the metadata which can contain non-string values.

◆ getPayload() [1/2]

const payload_t& com::softwareag::connectivity::Message::getPayload ( ) const

Return a reference to the payload.

◆ getPayload() [2/2]

payload_t& com::softwareag::connectivity::Message::getPayload ( )
inline

Return a reference to the payload.

◆ HOST_MESSAGE_TYPE()

static const char* com::softwareag::connectivity::Message::HOST_MESSAGE_TYPE ( )
inlinestatic

Returns the metadata key used by the host for identifying the type of the message - "sag.type".

◆ MESSAGE_ID()

static const char* com::softwareag::connectivity::Message::MESSAGE_ID ( )
inlinestatic

The metadata key used for unique identification of towards-host messages.

This is not mandatory, and only has to be populated for messages that you would like to see reliably acknowledged.

The identifier can be an arbitrary value of string type, and must uniquely identify a message within the scope of the chain and the lifetime of the system. That is, possibly across host reboots and reconnections. Where applicable you should use an id provided by the external messaging system. This will help traceability of messages.

See also
CONTROL_TYPE_ACK_REQUIRED()
CONTROL_TYPE_ACK_UPTO()
CONTROL_TYPE()

◆ operator=()

Message& com::softwareag::connectivity::Message::operator= ( Message &&  other)
inline

Move assignment from another message.

The argument will be left in an empty state and our old contents freed. If you do not want this use .copy() otherwise use std::move().

◆ putMetadataValue()

Message& com::softwareag::connectivity::Message::putMetadataValue ( data_t &&  key,
data_t &&  value 
)

Sets a value in the metadata.

Despite taking a data_t this must only take string value. Using this method may be more efficient even if you are copying the data_t.

 Note this overwrites a previous value if it exists, unlike the insert method on metadata_t. 

◆ REQUEST_ID()

static const char* com::softwareag::connectivity::Message::REQUEST_ID ( )
inlinestatic

The metadata key used for unique identification of towards-transport control messages, with a value of type int64_t.

Used to correlate Flush and FlushAck control messages.

See also
CONTROL_TYPE_FLUSH()
CONTROL_TYPE_FLUSH_ACK()
CONTROL_TYPE()

◆ setMetadata() [1/2]

void com::softwareag::connectivity::Message::setMetadata ( metadata_t &&  _metadata)

Set the metadata as metadata_t.

This is a move operation so the argument will be left in an empty state and the old metadata freed If you do not want this .copy() otherwise use std::move()

◆ setMetadata() [2/2]

void com::softwareag::connectivity::Message::setMetadata ( map_t &&  _metadata)

Set the metadata as map_t.

This is a move operation so the argument will be left in an empty state and the old metadata freed If you do not want this .copy() otherwise use std::move()

◆ setPayload()

void com::softwareag::connectivity::Message::setPayload ( payload_t &&  _payload)

Set the payload.

This is a move operation so the argument will be left in an empty state and the old payload freed If you do not want this .copy() otherwise use std::move()

◆ swap()

void com::softwareag::connectivity::Message::swap ( Message &&  other)

Swap the contents of this message with another.


The documentation for this class was generated from the following file: