## Contents

- Static Properties & Enumerations
- Properties
- Methods

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

- solace.MessageConsumerEventName#event:ACTIVE
- solace.MessageConsumerEventName#event:CONNECT_FAILED_ERROR
- solace.MessageConsumerEventName#event:DISPOSED
- solace.MessageConsumerEventName#event:DOWN
- solace.MessageConsumerEventName#event:DOWN_ERROR
- solace.MessageConsumerEventName#event:GM_DISABLED
- solace.MessageConsumerEventName#event:INACTIVE
- solace.MessageConsumerEventName#event:MESSAGE
- solace.MessageConsumerEventName#event:UP
- solace.MessageConsumerEventName#event:SUBSCRIPTION_OK
- solace.MessageConsumerEventName#event:SUBSCRIPTION_ERROR

## Constructor Top

| MessageConsumer ( ) |  |

## Static Properties & Enumerations Top

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

## Properties Top

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

## Methods Top

void | addSubscription ( solace.Destination topic, Object 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 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

- solace.MessageConsumerEventName#event:ACTIVE
- solace.MessageConsumerEventName#event:CONNECT_FAILED_ERROR
- solace.MessageConsumerEventName#event:DISPOSED
- solace.MessageConsumerEventName#event:DOWN
- solace.MessageConsumerEventName#event:DOWN_ERROR
- solace.MessageConsumerEventName#event:GM_DISABLED
- solace.MessageConsumerEventName#event:INACTIVE
- solace.MessageConsumerEventName#event:MESSAGE
- solace.MessageConsumerEventName#event:UP
- solace.MessageConsumerEventName#event:SUBSCRIPTION_OK
- solace.MessageConsumerEventName#event:SUBSCRIPTION_ERROR

## 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 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 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: <failed topic subscription>".

#### Parameters

solace.Destination | topic The topic destination subscription to add.
Object | 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

- if the session is disposed or disconnected, or the consumer is inactive, down, disconnected, or disposed. Or if the consumer is bound to a topic endpoint instead of a queue. Subcode: solace.ErrorSubcode.INVALID_OPERATION.
- if the parameters have an invalid type. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE.
- if the parameters have an invalid value. Subcode: solace.ErrorSubcode.PARAMETER_OUT_OF_RANGE.
- if the topic has invalid syntax. Subcode: solace.ErrorSubcode.INVALID_TOPIC_SYNTAX.
- if there's no space in the transport to send the request. Subcode: solace.ErrorSubcode.INSUFFICIENT_SPACE. See: solace.SessionEventCode#event:CAN_ACCEPT_DATA.
- if the topic is a shared subscription and the peer router does not support Shared Subscriptions. Subcode: solace.ErrorSubcode.SHARED_SUBSCRIPTIONS_NOT_SUPPORTED.
- if the topic is a shared subscription and the client does not allowed Shared Subscriptions. Subcode: solace.ErrorSubcode.SHARED_SUBSCRIPTIONS_NOT_ALLOWED.

###
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

- if the Message Consumer is disposed. subcode = solace.ErrorSubcode.INVALID_OPERATION

###
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

- if consumer is not supported by router for this client. subcode = solace.ErrorSubcode.INVALID_OPERATION

###
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

- if the Message Consumer is disconnected. subcode = solace.ErrorSubcode.INVALID_OPERATION

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

- For topic endpoints, this is the topic to which the topic endpoint is subscribed.
- For queues, this is the associated queue destination.

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

- if the solace.MessageConsumer is disconnected and the destination is temporary.

###
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 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: <failed topic subscription>".

#### Parameters

solace.Destination | topic The topic destination subscription to remove.
Object | 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

- if the session is disposed or disconnected, or the consumer is inactive, down, disconnected, or disposed. Or if the consumer is bound to a topic endpoint instead of a queue. Subcode: solace.ErrorSubcode.INVALID_OPERATION.
- if the parameters have an invalid type. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE.
- if the parameters have an invalid value. Subcode: solace.ErrorSubcode.PARAMETER_OUT_OF_RANGE.
- if the topic has invalid syntax. Subcode: solace.ErrorSubcode.INVALID_TOPIC_SYNTAX.
- if there's no space in the transport to send the request. Subcode: solace.ErrorSubcode.INSUFFICIENT_SPACE. See: solace.SessionEventCode#event:CAN_ACCEPT_DATA.
- if the topic is a shared subscription and the peer router does not support Shared Subscriptions. Subcode: solace.ErrorSubcode.SHARED_SUBSCRIPTIONS_NOT_SUPPORTED.
- if the topic is a shared subscription and the client does not allowed Shared Subscriptions. Subcode: solace.ErrorSubcode.SHARED_SUBSCRIPTIONS_NOT_ALLOWED.

###
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

- if the Message Consumer is disposed. subcode = solace.ErrorSubcode.INVALID_OPERATION
- if the Message Consumer is disconnected. subcode = solace.ErrorSubcode.INVALID_OPERATION

###
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

- if the Message Consumer is disconnected. subcode = solace.ErrorSubcode.INVALID_OPERATION

###
public String toString ( )

#### Return Value

String | A description of this Guaranteed Message Connection