com.neeve.sma
Interface MessageView

All Superinterfaces:

com.neeve.util.UtlReferenceTracker.HasReferenceTracker

All Known Subinterfaces:

IRogCollectionNode<T>, IRogCollectionNodeElement, IRogContainerNode, IRogDoubleMap<T>, IRogDoubleMapElement, IRogIntMap<T>, IRogIntMapElement, IRogList<T>, IRogListElement, IRogLongMap<T>, IRogLongMapElement, IRogMessage, IRogNode, IRogPojoShadowNode<T>, IRogQueue<T>, IRogQueueElement, IRogRawMessage, IRogSet<T>, IRogStringMap<T>, IRogStringMapElement, MapMessageView

All Known Implementing Classes:

AepEnvironmentData, MessageViewImpl, RawMessageViewImpl, com.neeve.rog.impl.RogNode

public interface MessageView
extends com.neeve.util.UtlReferenceTracker.HasReferenceTracker

Represents a view into a message.

From SMA's perspective, a message is just an object with a specific encoding e.g. a byte buffer, a hash table, an STO Container etc. A message view is an in-memory wrapper around a message that provides a specific view into the message contents. This interface defines the base class for all message views.

There are two views defined by SMA - the 'raw' view and the 'map' view. The raw view (defined by this interface) exposes the message as an object of a specific encoding type. No additional visibility is available with the raw view. The map view (defined by MapMessageView) enables a user, in addition to seeing the raw message, to view the message as a map i.e. a set of named fields.

Each message transported through SMA needs to be associated with a specific view. The user instantiates a view around a message and then hands the view over to one of SMAs send methods for delivery. The SMA send side machinery transports the underlying message as well as enough of information to reconsititute the send side message view on the receive side.

The SMA send and receive side machinery implement functionality conditional on the message view supplied. Some functionality requires the 'map' message view e.g. dynamic message key resolution. Functionality dependent on a specific message view will not be available for messages instantiated with message views not derived from the required message view.

Message views are instantiated by message view factories. View factories are configured with SMA (served by MessageViewFactoryRegistry). Each view factory has a system wide unique id. Each instantiated view is uniquely associated with one and only one factory. It is the id of the factory that a view is associated that is transported by SMA along with the message. On the receive side, the transported id is used to locate the appropriate factory that is invoked to reconstitute the view around the message.

Threading:

A message view is safe for concurrent access by multiple threads.

Field Summary

static int	ENCODING_TYPE_CUSTOM Identifies the user custom encoding type
static int	ENCODING_TYPE_JSON Identifies the 'JSON' message encoding
static int	ENCODING_TYPE_PROTOBUF Identifies the 'Protocol Buffer' message encoding
static int	ENCODING_TYPE_XBUF Identifies the 'X Buffer' message encoding
static int	NEXT_FREE_ENCODING_TYPE Identifies the next free encoding type

Method Summary

void	acquire() Increase a message view's ownership count.
MessageView	deserializeFromByteArray(byte[] serializedMessage) Deserialize a view's backing message from a byte array.
MessageView	deserializeFromByteBuffer(ByteBuffer serializedMessage) Deserialize a view's backing message from a byte buffer.
MessageView	deserializeFromPacket(PktPacket serializedMessage) Deserialize a view's backing message from a packet.
int	dispose() Dispose a message view.
long	getCreateTs() Get a message's create timestamp.
Object	getMessage() Get a view's backing message.
String	getMessageBus() Get the message bus name.
com.neeve.raw.RawString	getMessageBusAsRaw() Get the message bus in RawString form.
String	getMessageChannel() Get the message channel name.
com.neeve.raw.RawString	getMessageChannelAsRaw() Get the message channel in RawString form.
int	getMessageEncodingType() Get the message's encoding type.
int	getMessageFlow() Get the message flow.
String	getMessageKey() Get the message key.
com.neeve.raw.RawString	getMessageKeyAsRaw() Get the message key.
int	getMessageSender() Get the message sender.
long	getMessageSequenceNumber() Get the message sequence number.
long	getOriginTs() Get a message's origin timestamp.
long	getOutTs() Get a message's out timestamp.
int	getOwnershipCount() Get a message view's ownership count.
long	getPostDeserializeTs() Get a message's post-deserialize timestamp.
long	getPostProcessingTs() Get a message's post-processing timestamp.
long	getPostSerializeTs() Get a message's post-serialize timestamp.
long	getPostWireTs() Get a message's post-wire timestamp.
long	getPreDeserializeTs() Get a message's pre-deserialize timestamp.
long	getPreProcessingTs() Get a message's pre-processing timestamp.
long	getPreSerializeTs() Get a message's pre-serialize timestamp.
long	getPreWireTs() Get a message's pre-wire timestamp.
long	getReceiveTs() Get a message's receive timestamp.
long	getSendTs() Get a message's send timestamp.
Object	getTag(int id) Get a message view tag.
short	getType() Get the view type.
short	getVfid() Get the view factory identifier.
boolean	isPossibleDuplicate() Get whether a message is a possible duplicate..
byte[]	serializeToByteArray() Serialize a view's backing message to a byte array.
ByteBuffer	serializeToByteBuffer() Serialize a view's backing message to a byte buffer.
PktPacket	serializeToPacket() Serialize a view's backing message to a packet.
MessageView	setCreateTs(long ts) Set a message's create timestamp.
MessageView	setMessageBus(String name) Set the message bus name.
MessageView	setMessageBusAsRaw(com.neeve.raw.RawString bus) Set the message bus.
MessageView	setMessageChannel(String name) Set the message channel name.
MessageView	setMessageChannelAsRaw(com.neeve.raw.RawString channel) Set the message channel.
MessageView	setMessageFlow(int flow) Set the message flow.
MessageView	setMessageKey(String key) Set the message key.
MessageView	setMessageKeyAsRaw(com.neeve.raw.RawString key) Set the message key.
MessageView	setMessageSender(int sender) Set the message sender.
MessageView	setMessageSequenceNumber(long sno) Set the message sequence number.
MessageView	setOriginTs(long ts) Set a message's origin timestamp.
MessageView	setOutTs(long ts) Set a message's out timestamp.
MessageView	setPossibleDuplicate() Set a message as a possible duplicate.
MessageView	setPostDeserializeTs(long ts) Set a message's post-deserialize timestamp.
MessageView	setPostProcessingTs(long ts) Set a message's post-processing timestamp.
MessageView	setPostSerializeTs(long ts) Set a message's post-serialize timestamp.
MessageView	setPostWireTs(long ts) Set a message's post-wire timestamp.
MessageView	setPreDeserializeTs(long ts) Set a message's pre-deserialize timestamp.
MessageView	setPreProcessingTs(long ts) Set a message's pre-processing timestamp.
MessageView	setPreSerializeTs(long ts) Set a message's pre-serialize timestamp.
MessageView	setPreWireTs(long ts) Set a message's pre-wire timestamp.
MessageView	setReceiveTs(long ts) Set a message's receive timestamp.
MessageView	setSendTs(long ts) Set a message's send timestamp.
void	setTag(int id, Object tag) Set a message view tag.
void	sync() Ensure a view's backing message is prepared and ready for transport

Methods inherited from interface com.neeve.util.UtlReferenceTracker.HasReferenceTracker

referenceTracker

Field Detail

ENCODING_TYPE_CUSTOM

static final int ENCODING_TYPE_CUSTOM

Identifies the user custom encoding type

See Also:

Constant Field Values

ENCODING_TYPE_XBUF

static final int ENCODING_TYPE_XBUF

Identifies the 'X Buffer' message encoding

See Also:

Constant Field Values

ENCODING_TYPE_PROTOBUF

static final int ENCODING_TYPE_PROTOBUF

Identifies the 'Protocol Buffer' message encoding

See Also:

Constant Field Values

ENCODING_TYPE_JSON

static final int ENCODING_TYPE_JSON

Identifies the 'JSON' message encoding

See Also:

Constant Field Values

NEXT_FREE_ENCODING_TYPE

static final int NEXT_FREE_ENCODING_TYPE

Identifies the next free encoding type

See Also:

Constant Field Values

Method Detail

setTag

void setTag(int id,
            Object tag)

Set a message view tag.

Threading:

This method is not safe for concurrent access by multiple threads with itself or with getTag(int)

A message view tag is an opaque object that can be tagged to a message view object. Each tag is uniquely identified in the system via a numeric value View tag ids reserved for internal use by the X Platform are defined in MessageViewTags.

getTag

Object getTag(int id)

Get a message view tag.

Returns:

Returns the requested tag

Threading:

This method is not safe for concurrent access by multiple threads with itself or with setTag(int, java.lang.Object)

getVfid

short getVfid()

Get the view factory identifier.

Threading:

This method is safe for concurrent access by multiple threads

This method returns the system wide unique identifier of the view factory that instantiated this message view.

getType

short getType()

Get the view type.

Threading:

This method is safe for concurrent access by multiple threads

A message view type uniquely identifies a message within its factory.

getMessageEncodingType

int getMessageEncodingType()

Get the message's encoding type.

Threading:

This method is safe for concurrent access by multiple threads

This method returns a message's encoding type.

setMessageBus

MessageView setMessageBus(String name)

Set the message bus name.

Parameters:

name - The message bus name to set.

Returns:

Returns this for invocation chaining.

getMessageBus

String getMessageBus()

Get the message bus name.

This method returns the bus associated with a message.

setMessageBusAsRaw

MessageView setMessageBusAsRaw(com.neeve.raw.RawString bus)

Set the message bus.

Parameters:

bus - The message bus to set.

Returns:

Returns this for invocation chaining.

getMessageBusAsRaw

com.neeve.raw.RawString getMessageBusAsRaw()

Get the message bus in RawString form.

This method returns the bus associated with a message.

setMessageChannel

MessageView setMessageChannel(String name)

Set the message channel name.

Parameters:

name - The message channel name to set.

Returns:

Returns this for invocation chaining.

getMessageChannel

String getMessageChannel()

Get the message channel name.

This method returns the channel associated with a message.

setMessageChannelAsRaw

MessageView setMessageChannelAsRaw(com.neeve.raw.RawString channel)

Set the message channel.

Parameters:

channel - The message channel to set.

Returns:

Returns this for invocation chaining.

getMessageChannelAsRaw

com.neeve.raw.RawString getMessageChannelAsRaw()

Get the message channel in RawString form.

This method returns the channel associated with a message.

setMessageKey

MessageView setMessageKey(String key)

Set the message key.

Parameters:

key - The message key to set.

Returns:

Returns this for invocation chaining.

getMessageKey

String getMessageKey()

Get the message key.

This method returns the key associated with a message.

setMessageKeyAsRaw

MessageView setMessageKeyAsRaw(com.neeve.raw.RawString key)

Set the message key.

Parameters:

key - The message key to set.

Returns:

Returns this for invocation chaining.

getMessageKeyAsRaw

com.neeve.raw.RawString getMessageKeyAsRaw()

Get the message key.

This method returns the key associated with a message.

setMessageSender

MessageView setMessageSender(int sender)

Set the message sender.

Parameters:

sender - The message sender to set

Returns:

Returns this for invocation chaining.

getMessageSender

int getMessageSender()

Get the message sender.

This method returns the system-wide unique sender id. Sequence numbers returned by getMessageSequenceNumber() are scoped by sender.

setMessageFlow

MessageView setMessageFlow(int flow)

Set the message flow.

Parameters:

flow - The message flow to set.

Returns:

Returns this for invocation chaining.

getMessageFlow

int getMessageFlow()

Get the message flow.

This method returns the system-wide unique flow id. Flows define the order in which messages need to be processed.

setMessageSequenceNumber

MessageView setMessageSequenceNumber(long sno)

Set the message sequence number.

Parameters:

sno - The sequence number to set.

Returns:

Returns this for invocation chaining.

getMessageSequenceNumber

long getMessageSequenceNumber()

Get the message sequence number.

This method returns the sender scoped message sequence number.

setPossibleDuplicate

MessageView setPossibleDuplicate()

Set a message as a possible duplicate.

Returns:

Returns this for invocation chaining.

isPossibleDuplicate

boolean isPossibleDuplicate()

Get whether a message is a possible duplicate..

setOriginTs

MessageView setOriginTs(long ts)

Set a message's origin timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getOriginTs

long getOriginTs()

Get a message's origin timestamp.

Returns:

Returns the origin timestamp. A value of zero indicates that the origin timestamp was not recorded.

This timestamp, in microseconds, specifies the time at which the first message in this message's flow originated.

setCreateTs

MessageView setCreateTs(long ts)

Set a message's create timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getCreateTs

long getCreateTs()

Get a message's create timestamp.

Returns:

Returns the create timestamp. A value of zero indicates that the create timestamp was not recorded.

This timestamp, in microseconds, specifies the time at which the message was created.

setSendTs

MessageView setSendTs(long ts)

Set a message's send timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getSendTs

long getSendTs()

Get a message's send timestamp.

Returns:

Returns the send timestamp. A value of zero indicates that the outbound timestamp was not recorded.

This timestamp, in microseconds, specifies the time at which the message was sent by the application.

setOutTs

MessageView setOutTs(long ts)

Set a message's out timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getOutTs

long getOutTs()

Get a message's out timestamp.

Returns:

Returns the out timestamp. A value of zero indicates that the outbound timestamp was not recorded.

This timestamp is the same timestamp as the 'send' timestamp but in milliseconds.

setPreSerializeTs

MessageView setPreSerializeTs(long ts)

Set a message's pre-serialize timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getPreSerializeTs

long getPreSerializeTs()

Get a message's pre-serialize timestamp.

Returns:

Returns the timestamp. A value of zero indicates that the inbound timestamp was not recorded.

This timestamp, in microseconds, specifies the time just before a message was serialized for transport.

setPostSerializeTs

MessageView setPostSerializeTs(long ts)

Set a message's post-serialize timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getPostSerializeTs

long getPostSerializeTs()

Get a message's post-serialize timestamp.

Returns:

Returns the timestamp. A value of zero indicates that the inbound timestamp was not recorded.

This timestamp, in microseconds, specifies the time just after a message was serialized for transport.

setPreWireTs

MessageView setPreWireTs(long ts)

Set a message's pre-wire timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

This timestamp, in microseconds, specifies the time just before a message was sent on the network (the accuracy of this depends on how close to the wire the SMA binding used can timestamp the message)

getPreWireTs

long getPreWireTs()

Get a message's pre-wire timestamp.

Returns:

Returns the timestamp. A value of zero indicates that the inbound timestamp was not recorded.

The returned timestamp is in microseconds.

setPostWireTs

MessageView setPostWireTs(long ts)

Set a message's post-wire timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getPostWireTs

long getPostWireTs()

Get a message's post-wire timestamp.

Returns:

Returns the timestamp. A value of zero indicates that the inbound timestamp was not recorded.

This timestamp, in microseconds, specifies the time just after a message was received from the network (the accuracy of this depends on how close to the wire the SMA binding used can timestamp the message)

setPreDeserializeTs

MessageView setPreDeserializeTs(long ts)

Set a message's pre-deserialize timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getPreDeserializeTs

long getPreDeserializeTs()

Get a message's pre-deserialize timestamp.

Returns:

Returns the timestamp. A value of zero indicates that the inbound timestamp was not recorded.

This timestamp, in microseconds, specifies the time just before a message was de-serialized after transport.

setPostDeserializeTs

MessageView setPostDeserializeTs(long ts)

Set a message's post-deserialize timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getPostDeserializeTs

long getPostDeserializeTs()

Get a message's post-deserialize timestamp.

Returns:

Returns the timestamp. A value of zero indicates that the inbound timestamp was not recorded.

This timestamp, in microseconds, specifies the time just after a message was de-serialized after transport.

setReceiveTs

MessageView setReceiveTs(long ts)

Set a message's receive timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getReceiveTs

long getReceiveTs()

Get a message's receive timestamp.

Returns:

Returns the in timestamp. A value of zero indicates that the inbound timestamp was not recorded.

This timestamp, in microseconds, specifies the time just before a message was received by X's application dispatch machinery. It is the same as the pre-processing timestamp if the message is not being redelivered to the application by the in-process X runtime.

setPreProcessingTs

MessageView setPreProcessingTs(long ts)

Set a message's pre-processing timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getPreProcessingTs

long getPreProcessingTs()

Get a message's pre-processing timestamp.

Returns:

Returns the timestamp just before the message was dispatched into the application for processing. A value of zero indicates that the pre-processing timestamp was not recorded.

This timestamp, in milliseconds, specifies the time just before a message was dispatched to the application for processing.

setPostProcessingTs

MessageView setPostProcessingTs(long ts)

Set a message's post-processing timestamp.

Parameters:

ts - The timestamp to set.

Returns:

Returns this for invocation chaining.

getPostProcessingTs

long getPostProcessingTs()

Get a message's post-processing timestamp.

Returns:

Returns the timestamp just after the message was processed by the application. A value of zero indicates that the post-processing timestamp was not recorded.

This timestamp, in milliseconds, specifies the time just after a message processing handler completes.

getMessage

Object getMessage()

Get a view's backing message.

Threading:

This method is safe for concurrent access by multiple threads

This method returns the actual message wrapped by the view. It is the message that is transported

sync

void sync()

Ensure a view's backing message is prepared and ready for transport

serializeToByteArray

byte[] serializeToByteArray()

Serialize a view's backing message to a byte array.

serializeToByteBuffer

ByteBuffer serializeToByteBuffer()

Serialize a view's backing message to a byte buffer.

serializeToPacket

PktPacket serializeToPacket()

Serialize a view's backing message to a packet.

deserializeFromByteArray

MessageView deserializeFromByteArray(byte[] serializedMessage)

Deserialize a view's backing message from a byte array.

Parameters:

serializedMessage - The view's backing message serialized as a byte array.

deserializeFromByteBuffer

MessageView deserializeFromByteBuffer(ByteBuffer serializedMessage)

Deserialize a view's backing message from a byte buffer.

Parameters:

serializedMessage - The view's backing message serialized as a byte buffer.

deserializeFromPacket

MessageView deserializeFromPacket(PktPacket serializedMessage)

Deserialize a view's backing message from a packet.

Parameters:

serializedMessage - The view's backing message serialized as a packet.

acquire

void acquire()

Increase a message view's ownership count.

This method increments a message view's ownership count. View ownership is used in conjunction with managing message view pools. If a view is tagged to an object pool, the packet is released back to the pool by dispose() when the ownership count reduces to 0. If not tagged to a pool, change of ownership count has no side effects.

A packet's ownership count starts at 1.

getOwnershipCount

int getOwnershipCount()

Get a message view's ownership count.

dispose

int dispose()

Dispose a message view.

This method should be invoked by the user when done with a message view. It decrements the view's ownership count and releases it to its object pool if one is tagged to it and this method cause the ownership count to reduce to zero. If not tagged to a pool, ownership change methods have no side effects aside from just updating the ownership counter.

Once disposed, all references to the disposed view should be discarded.