Object Overview

This object is the core of the ORMQ messaging system, responsible for servicing client connections, creating and managing ORMQDestination queues, persisting durable messages to disk, and all other server-side tasks.

Multiple ORMQProvider instances may be utilized simultaneously within a single AlchemyPoint Server configuration, allowing for a variety of different messaging scenarios.

ORMQ client connections are handled by a Provider through the use of an ORMQ listener (ORMQSocketListener, ORMQPipeListener, ORMQMemListener). Multiple listeners may be embedded within a Provider, allowing for simultaneous communcation over a variety of messaging transports (TCP sockets, interprocess communcations pipes, local shared-memory streams).

Named message queue destinations may be created within a Provider by embedding an ORMQDestination configuration element. Multiple named queue destinations may be created within a Provider, each with their own delivery and persistence settings. Queues within a Provider may be subscribed to by embedding an ORMQSubscription or ORMQInputConnector configuration element. ORMQOutputConnector objects may also be embedded within a Provider to allow for rate-limit and message pipelining control over data sent to an ORMQ queue.

Example Object Definitions

... directly within the top-level ServerConfiguration object:

Minimal Configuration:

<ORMQProvider name=""Provider1"
              allowAnonymous="true"/>

Overview:

An ORMQ Provider named "Provider1" that is configured to accept anonymous client connections. All other Provider options are set to their defaults.

Complex Configuration (all possible attributes shown):

<ORMQProvider name=""Provider1" tags="ormq provider"
              description="example ORMQ provider instance"
              usernameVM="testuser"
              passwordVM="testpw1"
              streamTimeout="60"
              maxMsgSize="256000"
              keepaliveInterval="5000"
              maxRedeliveryCount="3"
              redeliveryTimeout="6000"
              redeliveryInterval="1000"
              authRealm="AuthenticationRealm1"
              authType="digest"
              authSecret="secret123"
              allowAnonymous="false">

   ... ORMQ listeners, subscriptions, queue destinations, SSL server config go here ...

</ORMQProvider>

Overview:

An ORMQ Provider named "Provider1" that is configured to with a maximum message size of 256,000 bytes, stream timeout of 60 seconds, and a keepalive interval of 5,000 milliseconds. Messages delivered by this Provider will be redelivered up to 3 times, with a 1,000 millisecond delay between each redelivery attempt, and up to 6,000 milliseconds total delivery time.

Client connections to this Provider are authorized using the MD5 digest authentication, with username / password information from the "AuthenticationRealm1" authentication store. The secret phrase "secret123" is used during MD5 digest authentication. Anonymous client connections are not allowed to this Provider.

AlchemyPoint Server will utilize the username "testuser" and password "testpw1" when making a virtual machine (internal) connection to this Provider. This username / password corresponds to an entry in the "AuthenticationRealm1" authentication store.

Supported Attributes

General Attributes:

• name - (usage: required): Public name of the configuration object. This name must be globally-unique across the entire AlchemyPoint ServerConfiguration definition.

• description - (usage: optional): Textual description of the configuration object.

• tags - (usage: optional): Space-delimited list of one or more tags used to describe the configuration object.

Connection Attributes:

• streamTimeout - (usage: optional, default: "5000"): The number of seconds timeout for socket send / receive operations. Send / receive operations that exceed this timeout will result in a client being disconnected from the ORMQ Provider.

• maxMsgSize - (usage: optional, default: "1048576"): The maximum number of bytes that any ORMQ message can be.

• keepaliveInterval - (usage: optional, default: "60000"): The number of seconds to wait between sending keepalive messages to connected ORMQ clients (to avoid idle disconnects).

Message Redelivery Attributes:

• maxRedeliveryCount - (usage: optional, default: "10"): The maximum number of times the Provider will attempt to redeliver ORMQ messages to connected clients.

• redeliveryInterval - (usage: optional, default: "60000"): The number of milliseconds to wait between each ORMQ message redelivery attempt.

• redeliveryTimeout - (usage: optional, default: "600000"): The number of milliseconds that may elapse during ORMQ message redelivery attempts, before a message is discarded.

Authentication Attributes:

• allowAnonymous - (usage: optional, default: "false"): If set to "true", the Provider will accept anonymous ORMQ client connections.

• usernameVM - (usage: mixed): The username that should be utilized interally by AlchemyPoint Server when making VM connections to the ORMQ Provider. This should correspond to a user account in the specified AuthenticationRealm.
  • This parameter is required if the "allowAnonymous" option is set to "false".
  • This parameter is optional if the "allowAnonymous" option is set to "true".

• passwordVM - (usage: mixed): The password that should be utilized interally by AlchemyPoint Server when making VM connections to the ORMQ Provider. This should correspond to a user account password in the specified AuthenticationRealm.
  • This parameter is required if the "allowAnonymous" option is set to "false".
  • This parameter is optional if the "allowAnonymous" option is set to "true".

• authRealm - (usage: optional): Name of the AuthenticationRealm configuration object that should be utilized to secure connections to this protocol listener.

• authType - (usage: optional): Authentication type to utilize when servicing client requests. Supported types are:
  • plain - (default): HTTP plain authentication
  • digest - HTTP digest authentication

• authSecret - (usage: optional): Secret passphrase used when authType is set to 'digest'.

Supported Child Configuration Elements

SSL:

• SSLServerConfig - (usage: optional): SSL server configuration object, to be specified if the ORMQ listener is using an ORMQSocketListener that is operating in secure (SSL / TLS) mode.

Queue Destinations / Subscriptions:

• ORMQDestination - A named message queue. These queues may be written to (via a DispatcherSource? , InputConnector or any of the ProtocolListeners), or subscribed to. ORMQ queues support a variety of delivery and reliability options, to operate successfully in a variety of messaging scenarios.

• ORMQSubscription - Subscription to an ORMQDestination queue on the connected ORMQProvider. Bindings may be embedded within ORMQ subscriptions to specify actions, transformations, and triggers that should be utilized on received ORMQ messages.

Connection Listeners:

• ORMQSocketListener - Embedded within an ORMQProvider, this object creates a TCP socket listener instance. Multiple socket listeners may be bound to a single Provider, each with their own unique SSL / authentication / messaging settings. Socket listeners are useful when remote ORMQ clients need to connect to a Provider over a TCP/IP network.

• ORMQPipeListener - Embedded within an ORMQProvider, this object creates an interprocess communications pipe listener instance. Multiple pipe listeners may be bound to a single Provider, each with their own unique authentication / messaging settings. Pipe listeners are useful when system processes running on the same physical host as AlchemyPoint Server needs to access ORMQ message queues. Pipes may not be utilized remotely, but can be utilized across system "process" boundaries. Pipe messaging is faster than socket-based communcation, but slower than memory-based messaging.

• ORMQMemListener - Embedded within an ORMQProvider, this object creates a local shared memory stream listener instance. Multiple memory listeners may be bound to a single Provider, each with their own unique authentication / messaging settings. Memory listeners are useful when an AlchemyPoint Server needs to access its own message queues in a local fashion. Memory-based messaging may only be utilized locally within the scope of a single AlchemyPoint Server; it is the fastest form of ORMQ messaging.

Connector Facades:

• ORMQInputConnector - Accesses named queue destinations on an ORMQ Provider in a polling fashion, checking for new messages on a regular interval. This object differs from an ORMQSubscription in that messages are only retrieved from the queue on an interval, versus being processed as soon as they are available.

• ORMQOutputConnector - Posts messages to an ORMQ named queue destination using rate limiting and pipelining. This object is useful when it is necessary to limit the speed at which messages are posted to an ORMQ queue, as ORMQDestination does not inherently support any sort of rate / message limiting capabilities.