org.pipservices.messaging.queues

Class MessageQueue

java.lang.Object

org.pipservices.messaging.queues.MessageQueue

All Implemented Interfaces:

org.pipservices.commons.config.IConfigurable, org.pipservices.commons.refer.IReferenceable, org.pipservices.commons.run.IClosable, org.pipservices.commons.run.IOpenable, IMessageQueue

Direct Known Subclasses:

MemoryMessageQueue

public abstract class MessageQueue
extends Object
implements IMessageQueue, org.pipservices.commons.refer.IReferenceable, org.pipservices.commons.config.IConfigurable, org.pipservices.commons.run.IOpenable, org.pipservices.commons.run.IClosable

Abstract message queue that is used as a basis for specific message queue implementations.

### Configuration parameters ###

• name: name of the message queue
• connection(s):
  • discovery_key: key to retrieve parameters from discovery service
  • protocol: connection protocol like http, https, tcp, udp
  • host: host name or IP address
  • port: port number
  • uri: resource URI or connection string with all parameters in it
• credential(s):
  • store_key: key to retrieve parameters from credential store
  • username: user name
  • password: user password
  • access_id: application access id
  • access_key: application secret key

### References ###

• *:logger:*:*:1.0 (optional) ILogger components to pass log messages
• *:counters:*:*:1.0 (optional) ICounters components to pass collected measurements
• *:discovery:*:*:1.0 (optional) IDiscovery services to resolve connection
• *:credential-store:*:*:1.0 (optional) ICredentialStore componetns to lookup credential(s)

Field Summary

Fields

Modifier and Type	Field and Description
protected MessagingCapabilities	_capabilities
protected org.pipservices.components.connect.ConnectionResolver	_connectionResolver
protected org.pipservices.components.count.CompositeCounters	_counters
protected org.pipservices.components.auth.CredentialResolver	_credentialResolver
protected String	_kind
protected Object	_lock
protected org.pipservices.components.log.CompositeLogger	_logger
protected String	_name

Constructor Summary

Constructors

Constructor and Description
MessageQueue() Creates a new instance of the message queue.
MessageQueue(String name) Creates a new instance of the message queue.
MessageQueue(String name, org.pipservices.commons.config.ConfigParams config) Creates a new instance of the message queue.

Method Summary

Modifier and Type	Method and Description
abstract void	abandon(MessageEnvelop message) Returnes message into the queue and makes it available for all subscribers to receive it again.
void	beginListen(String correlationId, IMessageReceiver receiver) Listens for incoming messages without blocking the current thread.
abstract void	clear(String correlationId) Clears component state.
abstract void	close(String correlationId) Closes component and frees used resources.
abstract void	complete(MessageEnvelop message) Permanently removes a message from the queue.
void	configure(org.pipservices.commons.config.ConfigParams config) Configures component by passing configuration parameters.
abstract void	endListen(String correlationId) Ends listening for incoming messages.
MessagingCapabilities	getCapabilities() Gets the queue capabilities
abstract Long	getMessageCount() Gets the current number of messages in the queue to be delivered.
String	getName() Gets the queue name
abstract boolean	isOpen() Checks if the component is opened.
abstract void	listen(String correlationId, IMessageReceiver receiver) Listens for incoming messages and blocks the current thread until queue is closed.
abstract void	moveToDeadLetter(MessageEnvelop message) Permanently removes a message from the queue and sends it to dead letter queue.
void	open(String correlationId) Opens the component.
abstract void	open(String correlationId, org.pipservices.components.connect.ConnectionParams connection, org.pipservices.components.auth.CredentialParams credential) Opens the component with given connection and credential parameters.
abstract MessageEnvelop	peek(String correlationId) Peeks a single incoming message from the queue without removing it.
abstract List<MessageEnvelop>	peekBatch(String correlationId, int messageCount) Peeks multiple incoming messages from the queue without removing them.
abstract MessageEnvelop	receive(String correlationId, long waitTimeout) Receives an incoming message and removes it from the queue.
abstract void	renewLock(MessageEnvelop message, long lockTimeout) Renews a lock on a message that makes it invisible from other receivers in the queue.
abstract void	send(String correlationId, MessageEnvelop message) Sends a message into the queue.
void	sendAsObject(String correlationId, String messageType, Object message) Sends an object into the queue.
void	setReferences(org.pipservices.commons.refer.IReferences references) Sets references to dependent components.
String	toString() Gets a string representation of the object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_name

protected String _name

_kind

protected String _kind

_capabilities

protected MessagingCapabilities _capabilities

_lock

protected Object _lock

_logger

protected org.pipservices.components.log.CompositeLogger _logger

_counters

protected org.pipservices.components.count.CompositeCounters _counters

_connectionResolver

protected org.pipservices.components.connect.ConnectionResolver _connectionResolver

_credentialResolver

protected org.pipservices.components.auth.CredentialResolver _credentialResolver

Constructor Detail

MessageQueue

public MessageQueue()

Creates a new instance of the message queue.

MessageQueue

public MessageQueue(String name)

Creates a new instance of the message queue.

Parameters:

name - (optional) a queue name

MessageQueue

public MessageQueue(String name,
                    org.pipservices.commons.config.ConfigParams config)

Creates a new instance of the message queue.

Parameters:

name - (optional) a queue name

config - configuration parameters

Method Detail

configure

public void configure(org.pipservices.commons.config.ConfigParams config)

Configures component by passing configuration parameters.

Specified by:

configure in interface org.pipservices.commons.config.IConfigurable

Parameters:

config - configuration parameters to be set.

setReferences

public void setReferences(org.pipservices.commons.refer.IReferences references)
                   throws org.pipservices.commons.refer.ReferenceException

Sets references to dependent components.

Specified by:

setReferences in interface org.pipservices.commons.refer.IReferenceable

Parameters:

references - references to locate the component dependencies.

Throws:

org.pipservices.commons.refer.ReferenceException - when no found references.

getName

public String getName()

Gets the queue name

Specified by:

getName in interface IMessageQueue

Returns:

the queue name.

getCapabilities

public MessagingCapabilities getCapabilities()

Gets the queue capabilities

Specified by:

getCapabilities in interface IMessageQueue

Returns:

the queue's capabilities object.

getMessageCount

public abstract Long getMessageCount()

Description copied from interface: IMessageQueue

Gets the current number of messages in the queue to be delivered.

Specified by:

getMessageCount in interface IMessageQueue

Returns:

number of messages.

isOpen

public abstract boolean isOpen()

Checks if the component is opened.

Specified by:

isOpen in interface org.pipservices.commons.run.IOpenable

Returns:

true if the component has been opened and false otherwise.

open

public void open(String correlationId)
          throws org.pipservices.commons.errors.ApplicationException

Opens the component.

Specified by:

open in interface org.pipservices.commons.run.IOpenable

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

open

public abstract void open(String correlationId,
                          org.pipservices.components.connect.ConnectionParams connection,
                          org.pipservices.components.auth.CredentialParams credential)
                   throws org.pipservices.commons.errors.ApplicationException

Opens the component with given connection and credential parameters.

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

connection - connection parameters

credential - credential parameters

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

close

public abstract void close(String correlationId)
                    throws org.pipservices.commons.errors.ApplicationException

Closes component and frees used resources.

Specified by:

close in interface org.pipservices.commons.run.IClosable

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

clear

public abstract void clear(String correlationId)
                    throws org.pipservices.commons.errors.ApplicationException

Clears component state.

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

send

public abstract void send(String correlationId,
                          MessageEnvelop message)
                   throws org.pipservices.commons.errors.ApplicationException

Sends a message into the queue.

Specified by:

send in interface IMessageQueue

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

message - a message envelop to be sent.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

sendAsObject

public void sendAsObject(String correlationId,
                         String messageType,
                         Object message)
                  throws org.pipservices.commons.errors.ApplicationException

Sends an object into the queue. Before sending the object is converted into JSON string and wrapped in a [[MessageEnvelop]].

Specified by:

sendAsObject in interface IMessageQueue

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

messageType - a message type

message - an object value to be sent

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

See Also:

send(String, MessageEnvelop)

peek

public abstract MessageEnvelop peek(String correlationId)
                             throws org.pipservices.commons.errors.ApplicationException

Peeks a single incoming message from the queue without removing it. If there are no messages available in the queue it returns null.

Specified by:

peek in interface IMessageQueue

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

Returns:

a message envelop object.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

peekBatch

public abstract List<MessageEnvelop> peekBatch(String correlationId,
                                               int messageCount)
                                        throws org.pipservices.commons.errors.ApplicationException

Peeks multiple incoming messages from the queue without removing them. If there are no messages available in the queue it returns an empty list.

Specified by:

peekBatch in interface IMessageQueue

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

messageCount - a maximum number of messages to peek.

Returns:

a list with messages.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

receive

public abstract MessageEnvelop receive(String correlationId,
                                       long waitTimeout)
                                throws org.pipservices.commons.errors.ApplicationException

Receives an incoming message and removes it from the queue.

Specified by:

receive in interface IMessageQueue

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

waitTimeout - a timeout in milliseconds to wait for a message to come.

Returns:

a message envelop object.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

renewLock

public abstract void renewLock(MessageEnvelop message,
                               long lockTimeout)
                        throws org.pipservices.commons.errors.ApplicationException

Renews a lock on a message that makes it invisible from other receivers in the queue. This method is usually used to extend the message processing time.

Specified by:

renewLock in interface IMessageQueue

Parameters:

message - a message to extend its lock.

lockTimeout - a locking timeout in milliseconds.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

abandon

public abstract void abandon(MessageEnvelop message)
                      throws org.pipservices.commons.errors.ApplicationException

Returnes message into the queue and makes it available for all subscribers to receive it again. This method is usually used to return a message which could not be processed at the moment to repeat the attempt. Messages that cause unrecoverable errors shall be removed permanently or/and send to dead letter queue.

Specified by:

abandon in interface IMessageQueue

Parameters:

message - a message to return.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

complete

public abstract void complete(MessageEnvelop message)
                       throws org.pipservices.commons.errors.ApplicationException

Permanently removes a message from the queue. This method is usually used to remove the message after successful processing.

Specified by:

complete in interface IMessageQueue

Parameters:

message - a message to remove.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

moveToDeadLetter

public abstract void moveToDeadLetter(MessageEnvelop message)
                               throws org.pipservices.commons.errors.ApplicationException

Permanently removes a message from the queue and sends it to dead letter queue.

Specified by:

moveToDeadLetter in interface IMessageQueue

Parameters:

message - a message to be removed.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

listen

public abstract void listen(String correlationId,
                            IMessageReceiver receiver)
                     throws org.pipservices.commons.errors.ApplicationException

Listens for incoming messages and blocks the current thread until queue is closed.

Specified by:

listen in interface IMessageQueue

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

receiver - a receiver to receive incoming messages.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

See Also:

IMessageReceiver

beginListen

public void beginListen(String correlationId,
                        IMessageReceiver receiver)

Listens for incoming messages without blocking the current thread.

Specified by:

beginListen in interface IMessageQueue

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

receiver - a receiver to receive incoming messages.

See Also:

IMessageReceiver

endListen

public abstract void endListen(String correlationId)
                        throws org.pipservices.commons.errors.ApplicationException

Ends listening for incoming messages. When this method is call [[listen]] unblocks the thread and execution continues.

Specified by:

endListen in interface IMessageQueue

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

toString

public String toString()

Gets a string representation of the object.

Overrides:

toString in class Object

Returns:

a string representation of the object.