Version: 10.16.0
Class

solace.MessageConsumer

Contents

class solace.MessageConsumer extends solace.Flow

This class is not exposed for construction by API users. A Message Consumer is created by calling solace.Session#createMessageConsumer.

A MessageConsumer controls Guaranteed Message delivery to this client.

Consumer characteristics and behavior are defined by solace.MessageConsumerProperties. The properties can also be supplied as a simple key-value {Object}. The queue descriptor, solace.MessageConsumerProperties#queueDescriptor must be specified to identify the Guaranteed Message Queue or Guaranteed Message Topic Endpoint on the Solace Message Router.

The MessageConsumer object is an EventEmitter, and will emit events to which the application may choose to subscribe, such as the connection to the Solace Message Router going up or down.

If a registered listener for an emitted event throws an exception, this is caught and emitted as an 'error'.

Fires

Constructor Top

  MessageConsumer ( )

Static Properties & Enumerations Top

solace.QueueAccessType accessType
solace.QueuePermissions permissions
solace.QueueDiscardBehavior queueDiscardBehaviour
Boolean respectsTTL

Properties Top

readonly Boolean disposed inherited from solace.Flow
readonly session inherited from solace.Flow

Methods Top

void addSubscription ( solace.Destination topic, Object | String | null | undefined correlationKey, Number requestTimeout )
void clearStats ( ) inherited from solace.Flow
void connect ( )
void disconnect ( )
void dispose ( ) inherited from solace.Flow
solace.Destination getDestination ( )
solace.MessageConsumerProperties getProperties ( )
Number getStat ( solace.StatType statType ) inherited from solace.Flow
void removeSubscription ( solace.Destination topic, Object | String | null | undefined correlationKey, Number requestTimeout )
void start ( )
void stop ( )
String toString ( ) inherited from solace.Flow

Constructor details Top

MessageConsumer ( )

This class is not exposed for construction by API users. A Message Consumer is created by calling solace.Session#createMessageConsumer.

A MessageConsumer controls Guaranteed Message delivery to this client.

Consumer characteristics and behavior are defined by solace.MessageConsumerProperties. The properties can also be supplied as a simple key-value {Object}. The queue descriptor, solace.MessageConsumerProperties#queueDescriptor must be specified to identify the Guaranteed Message Queue or Guaranteed Message Topic Endpoint on the Solace Message Router.

The MessageConsumer object is an EventEmitter, and will emit events to which the application may choose to subscribe, such as the connection to the Solace Message Router going up or down.

If a registered listener for an emitted event throws an exception, this is caught and emitted as an 'error'.

Fires

Static Properties & Enumerations Detail Top

static public solace.QueueAccessType accessType

After the MessageConsumer has connected to an endpoint (solace.MessageConsumerEventName#UP), accesstype represents the access type for the endpoint to which this Message Consumer is bound.

static public solace.QueuePermissions permissions

After the MessageConsumer has connected as indicated by the event solace.MessageConsumerEventName#event:UP, this property represents permissions granted by the router to this user on this Message Consumer

static public solace.QueueDiscardBehavior queueDiscardBehaviour

After the MessageConsumer has connected as indicated by the event solace.MessageConsumerEventName#event:UP, queueDiscardBehavior represents the discard behavior flags for the endpoint to which this Message Consumer is bound.

static public Boolean respectsTTL

After the MessageConsumer has connected as indicated by the event solace.MessageConsumerEventName#event:UP respectsTTL is true when the endpoint respects Time To Live on messages and 'false' otherwise.

Properties Detail Top

public readonly Boolean disposed

Returns true if this Guaranteed Message Consumer was disposed.

Inherited from solace.Flow

public readonly session

Methods Detail Top

public void addSubscription ( solace.Destination topic, Object | String | null | undefined correlationKey, Number requestTimeout )

Subscribe the queue to a topic, always requesting confirmation from the router.

solace.MessageConsumerEventName.SUBSCRIPTION_OK is generated when subscription is added successfully; otherwise, session event solace.MessageConsumerEventName.SUBSCRIPTION_ERROR is generated.

When the application receives the event solace.MessageConsumerEventName.SUBSCRIPTION_ERROR, it can obtain the failed topic subscription by calling solace.MessageConsumerEvent#reason. The returned string is in the format of "Topic: ".

Parameters

solace.Destination topic

The topic destination subscription to add.
Object | String | null | undefined correlationKey

If specified, this value is echoed in the messageConsumer event within MessageConsumerEvent.
Number requestTimeout

The request timeout period (in milliseconds). If specified, this value overwrites readTimeoutInMsecs property in SessionProperties.

Return Value

void

Throws

solace.OperationError

public void clearStats ( )

Clears all statistics for this Guaranteed Message Connection. All previous Guaranteed Message Connection statistics are lost when this is called.

Inherited from solace.Flow

Return Value

void

Throws

solace.OperationError

public void connect ( )

Connects the consumer immediately. The application should add event listeners (see solace.MessageConsumerEventName). If there is no listener added for solace.MessageConsumerEventName#event:MESSAGE then up to a window solace.MessageConsumerProperties.windowSize of messages can be queued internally. to the solace.MessageConsumer before calling this method.

Return Value

void

Throws

solace.OperationError

public void disconnect ( )

Initiates an orderly disconnection of the Message Consumer. The API will send any pending client acknowledgements on the Message Consumer, then send an unbind request. Any messages subsequently received are discarded silently. When the unbind message is acknowledged, the application receives a solace.MessageConsumerEventName#event:DOWN event if it has set a listener for that event.

Return Value

void

Throws

solace.OperationError

public void dispose ( )

Disposes the Guaranteed Message connection, removing all listeners and releasing references.

Inherited from solace.Flow

Return Value

void

public solace.Destination getDestination ( )

Returns the destination that should be used to publish messages that this consumer will receive.

The destination returned can be used to set the ReplyTo field in a message, or otherwise communicated to partners that need to send messages to this Message Consumer. This is especially useful for temporary endpoints (Queues and Topic Endpoints), as the destination is unknown before the endpoint is created.

This method will succeed after solace.MessageConsumerEventName#event:UP for temporaries with generated destinations.

Return Value

solace.Destination

The publishing destination that delivers to this consumer.

Throws

solace.OperationError

public solace.MessageConsumerProperties getProperties ( )

Creates and returns copy of the properties for this MessageConsumer.

If the object was constructed using an solace.AbstractQueueDescriptor, and the queue descriptor was subsequently connected to an endpoint, the MessageConsumerProperties returned will include a solace.QueueDescriptor that contains the resolved name.

A new copy of the properties object is returned each time this property is accessed. The returned object cannot be polled for mutations such as the one described above.

Return Value

solace.MessageConsumerProperties

The properties associated with this object.

public Number getStat ( solace.StatType statType )

Returns a statistic for this Guaranteed Message connection.

Inherited from solace.Flow

Parameters

solace.StatType statType

The statistic to return.

Return Value

Number

The value for the statistic.

public void removeSubscription ( solace.Destination topic, Object | String | null | undefined correlationKey, Number requestTimeout )

Unsubscribe the queue from a topic, requesting confirmation from the router.

solace.MessageConsumerEventName.SUBSCRIPTION_OK is generated when subscription is removed successfully; otherwise, session event solace.MessageConsumerEventName.SUBSCRIPTION_ERROR is generated.

When the application receives the message consumer event solace.MessageConsumerEventName.SUBSCRIPTION_ERROR, it can obtain the failed topic subscription by calling solace.MessageConsumerEvent#reason. The returned string is in the format "Topic: ".

Parameters

solace.Destination topic

The topic destination subscription to remove.
Object | String | null | undefined correlationKey

If null or undefined, a Correlation Key is not set in the confirmation session event.
Number requestTimeout

The request timeout period (in milliseconds). If specified, this value overwrites readTimeoutInMsecs property in SessionProperties.

Return Value

void

Throws

solace.OperationError

public void start ( )

Begins delivery of messages to this consumer. This method opens the protocol window to the Solace Message Router so further messages can be received.

A newly created consumer is in started state.

If the consumer was already started, this method has no effect.

A consumer is stopped by calling solace.MessageConsumer.stop

Return Value

void

Throws

solace.OperationError

public void stop ( )

Stops messages from being delivered to this consumer from the Solace Message Router. Messages may continue to be prefetched by the API and queued internally until solace.MessageConsumer#start is called.

If the consumer was already stopped, this method has no effect.

Return Value

void

Throws

solace.OperationError

public String toString ( )

Return Value

String

A description of this Guaranteed Message Connection