Object Overview

This object defines a subscription to an ORMQDestination named message queue. Subscriptions enable AlchemyPoint Server to read messages posted to an ORMQ named queue destination. They can be utilized to create loosely coupled event-based systems, decentralized messaging systems, etc.

Subscriptions are capable of interacting with a local ORMQProvider, or a remote Provider via an ORMQ client connection (ORMQSocketConnection, ORMQMemConnection, ORMQPipeConnection).

Example Object Definitions

... directly within an ORMQProvider, ORMQSocketConnection, ORMQPipeConnection, ORMQMemConnection, or the top-level ServerConfiguration object:

Minimal Configuration:

<ORMQSubscription name="Subscription1" 
                  queue="public.queues.queue1"/>

Overview:

A subscription to the ORMQ destination queue named "public.queues.queue1". All other options for this subscription are set to their defaults.

Complex Configuration (all possible attributes shown):

<ORMQSubscription name="Subscription1" tags="ormq subscription"
                  description="example durable subscription to a message queue"
                  provider="ORMQProvider1"
                  queue="public.queues.queue1"
                  subscribeMode="durable">

   ... [[Bindings]] go here ...

</ORMQSubscription>

Overview:

A subscription to the ORMQ destination queue named "public.queues.queue1". This subscription is created within the context of the ORMQ Provider instance "ORQProvider1". The subscription is created to be "durable", meaning that messages will be persisted to an on-disk database during delivery to reliability against system crashes / failures.

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.

Object Attributes:

• queue - (usage: required): The name of the ORMQ queue destination that should be subscribed to.

• provider - (usage: mixed): The published name of the ORMQ Provider instance that this Subscription should interact with. This corresponds to the 'name' attribute of an ORMQProvider within the same AlchemyPoint system configuration.
  • This parameter cannot be utilized if this object resides within an ORMQProvider.
  • This parameter cannot be utilized if the object specifies the 'client' option.
  • This parameter is required if the object does not reside within an ORMQProvider, ORMQSocketConnection, ORMQMemConnection, or ORMQPipeConnection and does not specify a 'client' setting.

• client - (usage: mixed): The published name of the ORMQ Connection instance that this Subscription should interact with. This corresponds to the 'name' attribute of an ORMQSocketConnection, ORMQMemConnection, or ORMQPipeConnection within the same AlchemyPoint system configuration.
  • This parameter cannot be utilized if this object resides within an ORMQConnection? .
  • This parameter cannot be utilized if the object specifies the 'provider' option.
  • This parameter is required if the object does not reside within an ORMQProvider, ORMQSocketConnection, ORMQMemConnection, or ORMQPipeConnection and does not specify a 'provider' setting.

• subscribeMode - (usage: optional, default: "non-durable"): The manner in which a ORMQ queue destination should be subscribed. The following 'subscribeMode' settings are supported:
  • non-durable - ORMQ messages are buffered in memory, and are not persisted to a disk-based database during delivery. This mode is much faster than "durable" ORMQ messaging, but is capable of losing messages in the event of a system failure or lack of system RAM for buffering.
  • durable - ORMQ messages are persisted to a disk-based database during delivery. This is the most reliable form of ORMQ messaging, capable of safely communicating even in the event of system failures, but it is also significantly slower than "non-durable" messaging.

Supported Child Configuration Elements

• Bindings - Bindings object containing zero or more ORMQSubscriptionBinding? elements. These Bindings define the actions that should be taken on ORMQ messages received by this Subscription. Actions can include transformations, triggers for other processes, etc.