Configures storage options for the application. An application's store provides the foundation for HA and Fault Tolerance. Applications achieve clustering through configuring the store, which will discover other application members and elect a single primary member through a leader election algorithm. The store serves as the foundation for HA by replicating changes from the primary application member to backups in a highly efficient, pipelined, asynchronous manner - a core requirement for In Memory Computing. While the primary mechanism for HA is memory to memory replication, an application's storage configuration may also configure disk-based persistence as a fall back mechanism in the event that connections to backup instance fail.

An application that runs standalone without any persistence does not need to include a store, which is a perfectly valid configuration for an application that does not have HA requirements.

<model>
  <env>...</env>
  <buses>...</buses>
  <apps>
    <app ...>
      ...
      <storage descriptor="${%FORWARDER_STOREDESCRIPTOR::native://.}" enabled="true">
        <persistence enabled="true">
          <pageSize>16384</pageSize>
          <detachedPersist enabled="false"/>
        </persistence>
      </storage>
      ...
    </app>
  </apps>
  <servers>...</servers>
</model 

<storage

descriptor

The store descriptor which is used to localize the store to a specific provider.

Usage: Required prior to 3.4, Deprecated in 3.4+
Default: native://.
X DDL Override:
x.apps.app.<appname>.storage.descriptor

enabled>

Can be set to false to disable the store for this application.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.enabled
Constraints: true | false

<factories>

Configures a state factories for an application. Each state factory defined under this element is registered with the application's underlying engine and store. Registered message factories are used by the store's replication receiver and transaction log for materialize entity instances from factory and type ids received over the wire.

It is not mandatory to configure factories via DDL, they can also be registered programmatically by the application during application initialization.

<factory

name

The state factory's fully qualified name.

Usage: Required
X DDL Override: Not overridable (key)

</factory>

<factories>

<persistenceQuorum>

Sets a store's persistence quorum. The persistence quorum is the minimum number of store members running in a cluster that determines whether persister commits are executed synchronously or not. If the number of members is greater or equal to the quorum, then persistence commits are always performed asynchronously. Otherwise, they are persisted synchronously.

Usage: Optional
Default: 2
X DDL Override:
x.apps.app.<appname>.storage.persistenceQuorum
Constraints: non negative integer

<maxPersistSyncBacklog>

When set to a value greater than 0 in seconds, the store's persister will be periodically synced to disk. This limits the amount of unsynced data (in time) that hasn't been synced in the event of a JVM failure, which can be useful for low volume applications that are operating above their persistence quorum.

Usage: Optional
Default: 0
X DDL Override:
x.apps.app.<appname>.storage.maxPersistSyncBacklog
Constraints: non negative integer

<icrQuorum>

Set's a store's ICR quorum. The ICR quorum is the minimum number of store members running in a cluster that determines whether ICR send commits are executed synchronously or not. If the number of members is greater or equal to the quorum, then ICR commits are always performed asynchronously. Otherwise, they are performed ssynchronously.

Usage: Optional
Default: 2
X DDL Override:
x.apps.app.<appname>.storage.icrQuorum
Constraints: non negative integer

<maxIcrSyncBacklog>

When set to a value greater than 0 in seconds, the store's icr sendder is periodically synced. This limits the amount of unsynced data (in time) that hasn't been synced in the event of a JVM failure, which can be useful for low volume applications that are operating above their icr quorum.

Usage: Optional
Default: 0
X DDL Override:
x.apps.app.<appname>.storage.maxIcrSyncBacklog
Constraints: non negative integer

<checkpointingType>

Sets the store's checkpoint controller type. A checkpoint controller determines the checkpoint boundaries within a transaction log by incrementing the checkpoint version for log entries. The checkpoint version is used by CDC and Log Compaction algorithms as the boundaries upon which those operations occur.

Usage: Optional
Default: 'Default'
X DDL Override:
x.apps.app.<appname>.storage.checkpointingType
Constraints: See CheckpointingType

<checkpointThreshold>

Sets the store's checkpoint threshold. The threshold controls the maximum number of entries before a transaction log's checkpoint version is increased, a checkpoint controller keeps track of the number of entries that count towards reaching this threshold.

Usage: Optional
Default: 'Default'
X DDL Override:
x.apps.app.<appname>.storage.checkpointThreshold
Constraints: positive integer

<checkpointMaxInterval>

Sets the max time interval (in millis) that can occur before triggering a new checkpoint.

Usage: Optional
Default: 'Default'
X DDL Override:
x.apps.app.<appname>.storage.checkpointMaxInterval
Constraints: positive integer

<discoveryDescriptor>

Sets the custom discovery descriptor for the store.

When set, this descriptor is used to load the discovery provider for the store (providing the store implementation uses discovery). Store implementations such as the default (native) store implementation use the discovery provider to broadcast their presence and connection information and presence to cluster peers.

In most cases, an application will simply want to use the default discovery configured for the server JVM in which they are running. In such cases, the store descriptor of 'native://.' should be used, and this value need not be set. The store will simply use the default discovery provider returned by DiscoveryCacheFactory.getDefaultCache().

However, in some cases where discovery within the same JVM must be partitioned, it can be useful to specify a separate discovery provider for the store, and this property facilitates that.

Usage: Optional
Default: unset
X DDL Override:
x.apps.app.<appname>.storage.discoveryDescriptor
Constraints: String

<failOnMultiplePrimaries>

This property has been deprecated and should be set under the clustering element.

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.storage.failOnMultiplePrimaries
Constraints: true | false

<clustering

The clustering element, when enabled, is used to configure store clustering which provides the ability for applications' store members to discover one another and form an HA cluster.

enabled>

Can be set to false to disable store clustering.

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.storage.clustering.enabled
Constraints: true | false

<storeName>

Sets the name of the store. Applications with the same store name automatically form a cluster. If this configuration parameter is not specified, then the application name is used as the store name

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.storage.clustering.storeName
Constraints: String

<localIfAddr>

Sets the local network interface to bind to when establishing cluster network connections.

Usage: Optional
Default: unset
X DDL Override:
x.apps.app.<appname>.storage.clustering.localIfAddr
Constraints: String

<localPort>

Sets the TCP port to bind to when listening for cluster connections.

Usage: Optional
Default: unset
X DDL Override:
x.apps.app.<appname>.storage.clustering.localPort
Constraints: integer

<linkParams>

A comma separate set of key=value pairs that serve as additional configuration parameters for the network connections between the cluster members.

Usage: Optional
Default: unset
X DDL Override:
x.apps.app.<appname>.storage.clustering.linkParams
Constraints: String (a comma separated list of key=value pairs)

<linkReaderCpuAffinityMask>

Sets the CPU affinity mask to use for the cluster connection reader thread. Each cluster member uses a single thread to read replication traffic from other cluster members.

The affinity string can either be a long that represents a mask of logical cpu, or a square bracket enclosed comma separated list enumerating the logical cpus.

For example, specifying "1" or "[0]" indicates Core 0. "3" or "[0, 1]" would indicate Core 0 or Core 1. Specifying a value of "0" indicates that the thread should be affinitized to the platform's default cpu, and omitting this value indicates that the thread should be affinitized according to the platform's default policy for the multiplexer.

See com.neeve.util.UtlThread.setCPUAffinityMask(String) for details.

Usage: Optional
Default: unset
X DDL Override:
x.apps.app.<appname>.storage.clustering.linkReaderCpuAffinityMask
Constraints: String

<discoveryDescriptor>

Sets the custom discovery descriptor for the store.

When set, this descriptor is used to load the discovery provider for the store. In most cases, an application will simply want to use the default discovery configured for the server JVM in which they are running. In such cases this value need not be set. The store will simply use the default discovery provider returned by DiscoveryCacheFactory.getDefaultCache().

However, in some cases where discovery within the same JVM must be partitioned, it can be useful to specify a separate discovery provider for the store, and this property facilitates that.

Usage: Optional
Default: unset
X DDL Override:
x.apps.app.<appname>.storage.clustering.discoveryDescriptor
Constraints: String

<initWaitTime>

Sets the time, in milliseconds, that the store cluster manager will wait on open for the cluster to stabilize. When a store binding opens its binding to the store, it joins the discovery network to discover other store cluster members. Once discovered, the members need to connect to each other, perform handshakes and elect roles. This parameter governs how long, after the binding has joined the discovery network, does the cluster manager wait for the store cluster to "stabilize"

A longer initWaitTime will cause the store open operation to take at least that amount of time. It will continue to wait for additiona instances to be discovered even if one other member is found. initWaitTime should be set high enough to accomodate the maximum amount of time that is reasonable to expect another member to broadcast itself via discover and accept an connection. For example, if the store or its peers is subject to stop the world VM pauses as a result of long garbage collection, the initWaitTime should be set high enough to accomodate this to avoid to members entering the primary role.

Usage: Optional
Default: unset
X DDL Override:
x.apps.app.<appname>.storage.clustering.initWaitTime
Constraints: integer

<failOnMultiplePrimaries>

Set whether a store cluster manager should fail the store binding on detecting multiple primaries in a cluster. The default policy is to fail on detecting multiple primaries. This means that if multiple primaries are detected, the members detected as primaries will shut down to prevent a "split-brain" situation. If this parameter is set to true, then the members detected as primaries will not establish connectivity with each other and will continue to operate independently as primaries.

This parameter should only be used if the application or messaging layer possess a distributed locking mechanism that will cause one of the two dual primaries to be unable to start messaging when elected as primary (because there is another primary that has acquired the lock). Specifying this parameter as false without such a mechanism can have significant operational impact on the running of the application.

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.storage.clustering.failOnMultiplePrimaries
Constraints: true | false

<detachedSend

Configures whether or not to send the outbound replication traffic by the engine thread or pass off the send to a detached replicator sender thread.

Offloading the send to a sender thread can increase store throughput and reduce latency (in some complex flows) but requires an extra processor core for the sender thread.

Usage: Optional

enabled>

Can be set to true to enable detached sends for store replication.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedSend.enabled
Constraints: true | false

<queueDepth>

The size of the feeder queue for the event multiplexer. Typically this value should be a power of 2. When not specified the platform's default value for the multiplexer will be used.

See <queueDepth>

X DDL Override:
x.apps.app.<appname>.clustering.detachedSend.queueDepth
Constraints: positive integer

<queueOfferStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueOfferStrategy> 

X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedSend.queueOfferStrategy
Constraints: See QueueOfferStrategy

<queueWaitStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueWaitStrategy>  

X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedSend.queueWaitStrategy
Constraints: See QueueWaitStrategy

<queueDrainerCpuAffinityMask>

Sets the CPU affinity mask to use for the drainer thread. The affinity string can either be a long that represents a mask of logical cpu, or a square bracket enclosed comma separated list enumerating the logical cpus.

See <queueDrainerCpuAffinityMask>   

X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedSend.queueDrainerCpuAffinityMask

<queueFeedMaxConcurrency>

Sets the maximum number of threads that will feed the multiplexer's queue.

See <queueFeedMaxConcurrency>     

Usage: Optional
Default: 16
X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedSend.queueFeedMaxConcurrency
Constraints: positive integer

</detachedSend>

<detachedDispatch

Configures whether or not to dispatch the inbound replication traffic and events by the replication link reader thread or pass the dispatch off to a detached replicator dispatcher thread.

Offloading the dispatch to a dispatcher thread can increase store throughput but requires an extra processor core for the dispatcher thread.

Usage: Optional

enabled>

Can be set to true to enable detached sends for store replication.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedDispatch.enabled
Constraints: true | false

<queueDepth>

The size of the feeder queue for the event multiplexer. Typically this value should be a power of 2. When not specified the platform's default value for the multiplexer will be used.

See <queueDepth>

X DDL Override:
x.apps.app.<appname>.clustering.detachedDispatch.queueDepth
Constraints: positive integer

<queueOfferStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueOfferStrategy> 

X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedDispatch.queueOfferStrategy
Constraints: See QueueOfferStrategy

<queueWaitStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueWaitStrategy>  

X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedDispatch.queueWaitStrategy
Constraints: See QueueWaitStrategy

<queueDrainerCpuAffinityMask>

Sets the CPU affinity mask to use for the drainer thread. The affinity string can either be a long that represents a mask of logical cpu or a square bracket enclosed comma separated list enumerating the logical cpus.

See <queueDrainerCpuAffinityMask>   

X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedDispatch.queueDrainerCpuAffinityMask

<queueFeedMaxConcurrency>

Sets the maximum number of threads that will feed the multiplexer's queue.

See <queueFeedMaxConcurrency>     

Usage: Optional
Default: 16
X DDL Override:
x.apps.app.<appname>.storage.clustering.detachedDispatch.queueFeedMaxConcurrency
Constraints: positive integer

</detachedDispatch>

</clustering>

<persistence

Configures the persister for this store. A persister is responsible for storing the stores transactional updates to disk (or some other recoverable storage medium). Persisters typically serve as a secondary fault tolerance mechanism for clustered applications, but for an application that will only operate standalone this can serve as the primary mechanism for fault tolerance.

Usage: Optional

See Also: StorePersisterDescriptor

class

Can be set to the fully qualified classname of a custom implemenation of a store persister class. If omitted or "native" is specified, then the platform's default persister will be used (recommended)

Usage: Optional
Default: native
X DDL Override:
x.apps.app.<appname>.storage.persistence.class

enabled>

Can be set to false to disable the persister for this store.

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.storage.persistence.enabled
Constraints: true | false

<autoFlushSize>

In the absense of explicit flushes (e.g. flushOnCommit) of written entries, the size at which flush is automatically triggered for queued writes. If not set the platform default (8192) is used.

Usage: Optional
Default: 8192
X DDL Override:
x.apps.app.<appname>.storage.persistence.autoFlushSize
Constraints: positive integer

<flushOnCommit>

Whether or not the persister should be flushed on commit. By default a persister buffers writes into an internal buffer and doesn't write to disk until that buffer has filled. Enabling flush on commit will flush the persister regardless of whether the buffer has filled.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.persistence.flushOnCommit
Constraints: true | false

<autoRepair>

Whether or not an attempt will be made to automatically repair non-empty logs by truncating malformed entries at the end of the log that are part of incomplete transactions.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.persistence.autoRepair
Constraints: true | false

<storeRoot>

Specifies the root folder in which the persister's transaction log files are located.

Usage: Optional
Default: ${NVROOT}/rdat
X DDL Override:
x.apps.app.<appname>.storage.persistence.storeRoot
Constraints: a file path (possibly relative to the working directory.

If the expected value of of NVROOT on your target deployment host is not on the device where you want to place your transaction logs (e.g. slow or small disk), then consider making this a substitutable vlaue such as:

<storeRoot>${myapp.storeRoot}</storeRoot>, so that you can customize its location at runtime appropriate to the environment in which you are launching.

 <shared>

Whether or not the persister is a share. If omitted or false, the application will use shared nothing persistence. If true it indicates that the persister is using the same physical storage between backup and primaries meaning that instances in a backup role will not persist to disk and leave it to the primary. In most cases applications will leave this as false.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.icr.shared
Constraints: true | false

<cdcEnabled>

Whether CDC is enabled on the log.

If CDC is not enabled, then a CDC processor run on a log will not dispatch any events. If CDC is not enabled on a log and then reenabled later, CDC will start from the live log at the time the CDC is enabled. If a compaction occurred while CDC was disabled, then the change events that occurred during that time will be lost; in other words, CDC enablement instructs the compactor to preserve data on disk necessary for performing CDC rather than deleting it on compaction.

CDC enabled is only supported for applications using StateReplication as an HAPolicy.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.persistence.cdcEnabled
Constraints: true | false

<compactionThreshold>

Sets the log compaction threshold.

The log compaction threshold is the size (in megabytes) that triggers a log compaction. The act of compacting a log will compact as many complete checkpoints in the log and switch the live log over to the compacted log. A threshold value of less than or equal to 0 disables live log compaction.

Usage: Optional
Default: 0
X DDL Override:
x.apps.app.<appname>.storage.persistence.compactionThreshold
Constraints: integer

Log Compaction is currently only applicable to applications using StateReplication as an HAPolicy.

<maxCompactionWindowSize>

The log compaction window is the approximate maximum size (in megabytes) rounded up to the end of the nearest checkpoint that a compact operation uses to determine how many log entries it will hold in memory. The more entries the compactor can hold in memory while performing a compaction, the more efficient the compact operation will be.

Note: The minimum compaction window is a checkpoint. Therefore, if the system is configured such that a checkpooint covers entries that cumulatively exceeds the value of this parameter, then this parameter will not reduce the compaction memory usage; rather, the compactor will load the entire checkpoint into memory when performing the checkpoint operation.

Note: When calculating memory needed by the compaction operation, one should multiply this parameter by a factor of 2: i.e. the memory used by compaction will be twice the memory specified via this parameter.

Usage: Optional
Default: 1024 (1Gb)
X DDL Override:
x.apps.app.<appname>.storage.persistence.maxCompactionWindowSize
Constraints: integer

Log Compaction is currently only applicable to applications using StateReplication as an HAPolicy.

<logScavengePolicy>

Sets policy used to scavenge logs.

A log with number N is considered a candidate for scavenging when N is less than the live log number and N less than the CDC log number. This parameter specifies how such logs need to be scavenged. Currently, the only permissible value is 'Delete'

Usage: Optional
Default: Delete
X DDL Override:
x.apps.app.<appname>.storage.persistence.logScavengePolicy
Constraints: Delete

The log scavenge policy only make sense for applications using StateReplication as an HAPolicy, as it pertains only to stale transaction logs left over from CDC or Compaction.

<initialLogLength>

Sets the intial file size of persister's transaction log in gigabytes.

Preallocating the transaction log can save costs in growing the file size over time since the operation of growing a log file may actually result in a write of file data + the metadata operation of updating the file size, and may also benefit from allocating contiguous sectors on disk.

Usage: Optional
Default: 1 (1Gb)
X DDL Override:
x.apps.app.<appname>.storage.persistence.initialLogLength
Constraints: positive float

The log size is specified in Gb. For an initial size of less than 1 Gb, specify a float value. for example a value of .01 would result in a preallocated size of ~10Mb, this can be useful for test environments.

<zeroOutInitial>

Whether the log file should be explictly zeroed out (to force commit all disk pages) if newly created.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.persistence.zeroOutInitial
Constraints: true | false

<pageSize>

Sets the page size for the disk in bytes. The persister will use this as a hint in several areas to optimize its operation.

Usage: Optional
Default: 8192
X DDL Override:
x.apps.app.<appname>.storage.persistence.pageSize
Constraints: positive float

<detachedPersist

Configures whether or not persister writes are done by the store commit thread or passed off to a detached persister write thread. Offloading the persist to a persister thread can increase store throughput but requires an extra processor core for the persister thread.

enabled>

Can be set to true to enable detached persister for the persister.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.persistence.detachedPersist.enabled
Constraints: true | false

<queueDepth>

The size of the feeder queue for the event multiplexer. Typically this value should be a power of 2. When not specified, the platform's default value for the multiplexer will be used.

See <queueDepth>

X DDL Override: x.apps.app.<appname>.storage.persistence.detachedPersist.queueDepth
Constraints: positive integer

<queueOfferStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueOfferStrategy> 

X DDL Override: x.apps.app.<appname>.storage.persistence.detachedPersist.queueOfferStrategy
Constraints: See QueueOfferStrategy

<queueWaitStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueWaitStrategy>  

X DDL Override:
x.apps.app.<appname>.storage.persistence.detachedPersist.queueWaitStrategy
Constraints: See QueueWaitStrategy

<queueDrainerCpu
AffinityMask>

Sets the CPU affinity mask to use for the drainer thread. The affinity string can either be a long that represents a mask of logical cpu, or a square bracket enclosed comma separated list enumerating the logical cpus.

See <queueDrainerCpuAffinityMask>   

X DDL Override:
x.apps.app.<appname>.storage.persistence.detachedPersist.queueDrainerCpuAffinityMask

<queueFeedMax
Concurrency>

Sets the maximum number of threads that will feed the multiplexer's queue.

See <queueFeedMaxConcurrency>     

Usage: Optional
Default: 16
X DDL Override:
x.apps.app.<appname>.storage.persistence.detachedPersist.queueFeedMaxConcurrency
Constraints: positive integer

</detachedPersist>

</persistence>

<icr

role

Configures the inter-cluster replication role.

See ICRRole
for this application instance

Usage: Required
Default: false
X DDL Override:
x.apps.app.<appname>.storage.icr.role
Constraints: Sender | StandaloneReceiver

busDescriptor

Configures the bus descriptor for ICR. ICR uses its own private bus instance created from this descriptor.

This can be instead of specifying the provider, address, and port properties.

Usage: Required
Default: false
X DDL Override:
x.apps.app.<appname>.storage.icr.busDescriptor
Constraints: String

enabled>

Can be set to true to enable inter cluster replication.

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.storage.icr.enabled
Constraints: true | false

<bus

Defines and configures the private bus instance used for ICR.

The ICR bus can be configured by either the bus element or the bus descriptor attribute.

It is illegal to use both mechanism.

<provider>

The bus provider name.

Usage: Required
Default: false
X DDL Override:
x.apps.app.<appname>.storage.icr.bus.provider
Constraints: String

<address> 

The bus address.

Usage: Required
Default: false
X DDL Override:
x.apps.app.<appname>.storage.icr.bus.address
Constraints: String

<port>

The bus port for bus providers that accept a port.

Usage: Required
Default: false
X DDL Override:
x.apps.app.<appname>.storage.icr.bus.port
Constraints: short

<properties>

</properties>

List the bus descriptor parameters in key=value pairs e.g.

<properties>
  <username>jane</username>
  <single_session>true</single_session>
</properties>

Usage: Optional
X DDL Override:
x.apps.app.<appname>.storage.icr.bus.<propname>
Constraints: short

 <shared>

Whether or not an ICR Sender is a shared sender. Applications should set this to true when using ICR to a Standalone Receiver, e.g. only the primary instance should send updated to the ICR queue.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.icr.shared
Constraints: true | false

In most cases applications will want to set this to true.

<flushOnCommit>

Whether or not the icr sender should be flushed on commit. Setting this value to true will flush all updates to the underlying message bus on commit. With a value of false the bus may buffer some messages until new updates are sent on subsequent commits.

Usage: Optional
Default: false
X DDL Override: x.apps.app.<appname>.storage.icr.flushOnCommit
Constraints: true | false

<detachedSend

Configures whether or not ICR sends are done by the store commit thread or passed off to a detached send thread. Offloading the send to a sender thread can increase store throughput but requires an extra processor core for the sender thread. When enabled the properties here configure the multiplexer for the detached send thread.

enabled

Configures whether or not detached ICR send is enabled.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.storage.icr.detachedSend.enabled
Constraints: true | false

<queueDepth>

The size of the feeder queue for the event multiplexer. Typically this value should be a power of 2. When not specified, the platform's default value for the multiplexer will be used.

See <queueDepth>

X DDL Override: x.apps.app.<appname>.storage.icr.detachedSend.queueDepth
Constraints: positive integer

<queueOfferStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueOfferStrategy> 

X DDL Override:
x.apps.app.<appname>.storage.icr.detachedSend.queueOfferStrategy
Constraints: See QueueOfferStrategy

<queueWaitStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueWaitStrategy>  

X DDL Override:
x.apps.app.<appname>.storage.icr.detachedSend.queueWaitStrategy
Constraints: See QueueWaitStrategy

<queueDrainerCpu
AffinityMask>

Sets the CPU affinity mask to use for the drainer thread. The affinity string can either be a long that represents a mask of logical cpu or a square bracket enclosed comma separated list enumerating the logical cpus.

See <queueDrainerCpuAffinityMask>   

X DDL Override:
x.apps.app.<appname>.storage.icr.detachedSend.queueDrainerCpuAffinityMask

<queueFeedMax
Concurrency>

Sets the maximum number of threads that will feed the multiplexer's queue.

See <queueFeedMaxConcurrency>     

Usage: Optional
Default: 16
X DDL Override:
x.apps.app.<appname>.storage.icr.detachedSend.queueFeedMaxConcurrency
Constraints: positive integer

</detachedSend>

</icr>

</storage>

The remaining elements under the <app> element configure the operation of the application's AepEngine

<app>
  <messaging/>
  <storage descriptor="${%FORWARDER_STOREDESCRIPTOR::native://.}" enabled="true"/>
  <!-- General Engine Configuration -->
</app> 

<inboundEventMultiplexing

<queueDepth>

The size of the feeder queue for the event multiplexer. Typically this value should be a power of 2. When not specified, the platform's default value for the multiplexer will be used.

See <queueDepth>

X DDL Override:
x.apps.app.<appname>.inboundEventMultiplexing.queueDepth
Constraints: positive integer

<queueOfferStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueOfferStrategy> 

X DDL Override: x.apps.app.<appname>.inboundEventMultiplexing.queueOfferStrategy
Constraints: See QueueOfferStrategy

<queueWaitStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueWaitStrategy>  

X DDL Override:
x.apps.app.<appname>.inboundEventMultiplexing.queueWaitStrategy
Constraints: See QueueWaitStrategy

<queueDrainerCpuAffinityMask>

Sets the CPU affinity mask to use for the drainer thread. The affinity string can either be a long that represents a mask of logical cpu, or a square bracket enclosed comma separated list enumerating the logical cpus.

See <queueDrainerCpuAffinityMask>   

X DDL Override:
x.apps.app.<appname>.inboundEventMultiplexing.queueDrainerCpuAffinityMask

<queueFeedMaxConcurrency>

Sets the maximum number of threads that will feed the multiplexer's queue.

See <queueFeedMaxConcurrency>     

Usage: Optional
Default: 16
X DDL Override:
x.apps.app.<appname>.inboundEventMultiplexing.queueFeedMaxConcurrency
Constraints: positive integer

</inboundEventMultiplexing>

<inboundMessageLogging

Configures inbound message logging for the engine. An inbound message logger logs inbound messages to a transaction log file. Inbound logging does not play a role in HA for the application, but can be useful for auditing purposes.

policy

The inbound message logging policy for the application.

See InboundMessageLoggingPolicy

Usage: Required
Default: "Default"
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.policy
Constraints: Default | Off | UseDedicated

failurePolicy

See InboundMessageLoggingFailurePolicy

Usage: Optiona
Default: StopEngine
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.failurePolicy
Constraints: StopEngine| StopLogging

<autoFlushSize>

In the absence of explicit flushes (e.g. flushOnCommit) of written entries, the size at which flush is automatically triggered for queued writes. If not set, the platform default (8192) is used.

Usage: Optional
Default: 8192
X DDL Override: x.apps.app.<appname>.inboundMessageLogging.autoFlushSize
Constraints: positive integer

<flushOnCommit>

Whether or not the logger should be flushed on commit. By default the logger buffers writes into an internal buffer and doesn't write to disk until that buffer has filled. Enabling flush on commit will flush the logger regardless of whether the buffer has filled.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.flushOnCommit
Constraints: true | false

<autoRepair>

Whether or not an attempt will be made to automatically repair a non-empty log on open by truncating malformed entries at the end of the log that are part of incomplete transactions.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.autoRepair
Constraints: true | false

<storeRoot>

Specifies the root folder in which the logger's transaction log files are located.

Usage: Optional
Default: ${NVROOT}/rdat
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.storeRoot
Constraints: a file path (possibly relative to the working directory. 

<initialLogLength>

Sets the initial file size of logger's transaction log in gigabytes.

Preallocating the transaction log can save costs in growing the file size over time since the operation of growing a log file may actually results in a write of file data + the metadata operation of updating the file size, and may also benefit from allocating contiguous sectors on disk.

Usage: Optional
Default: 1 (1Gb)
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.initialLogLength
Constraints: positive float

<zeroOutInitial>

Whether the log file should be explictly zeroed out (to force commit all disk pages) if newly created.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.zeroOutInitial
Constraints: true | false

<pageSize>

Sets the page size for the disk in bytes. The logger will use this as a hint in several areas to optimize its operation.

Usage: Optional
Default: 8192
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.pageSize
Constraints: positive int

<detachedWrite

Configures whether or not logger writes are done by the committing thread or passed off to a detached writer thread. Offloading to a writer thread can increase application throughput but requires an extra processor core for the logger thread.

enabled>

Can be set to true to enable detached logging for the logger.

Usage: Required
Default: false
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.detachedWrite.enabled
Constraints: true | false

<queueDepth>

The size of the feeder queue for the event multiplexer. Typically this value should be a power of 2. When not specified, the platform's default value for the multiplexer will be used.

See <queueDepth>

X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.detachedWrite.queueDepth
Constraints: positive integer

<queueOfferStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueOfferStrategy>

X DDL Override: x.apps.app.<appname>.inboundMessageLogging.detachedWrite.queueOfferStrategy
Constraints: See QueueOfferStrategy

<queueWaitStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueWaitStrategy>  

X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.detachedWrite.queueWaitStrategy
Constraints: See QueueWaitStrategy

<queueDrainerCpuAffinityMask>

Sets the CPU affinity mask to use for the drainer thread. The affinity string can either be a long that represents a mask of logical cpu or a square bracket enclosed comma separated list enumerating the logical cpus.

See <queueDrainerCpuAffinityMask>   

X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.
detachedWrite.queueDrainerCpuAffinityMask

<queueFeedMaxConcurrency>

Sets the maximum number of threads that will feed the multiplexer's queue.

See <queueFeedMaxConcurrency>     

Usage: Optional
Default: 16
X DDL Override:
x.apps.app.<appname>.inboundMessageLogging.
detachedWrite.queueFeedMaxConcurrency
Constraints: positive integer

</detachedWrite>

</inboundMessageLogging>

<outboundMessageLogging

Configures outbound message logging for the engine. An inbound message logger logs sent messages to a transaction log file. An outbound message log file does not play a role in HA for the application, but can be useful for auditing purposes.

policy

The outbound message logging policy for the application.

See OutboundMessageLoggingPolicy

Usage: Required
Default: "Default"
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.policy
Constraints: Default | Off | UseDedicated

failurePolicy

See OutboundMessageLoggingFailurePolicy

Usage: Optiona
Default: StopEngine
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.failurePolicy
Constraints: StopEngine| StopLogging

<autoFlushSize>

In the absence of explicit flushes (e.g. flushOnCommit) of written entries, the size at which flush is automatically triggered for queued writes. If not set, the platform default (8192) is used.

Usage: Optional
Default: 8192
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.autoFlushSize
Constraints: positive integer

<flushOnCommit>

Whether or not the logger should be flushed on commit. By default the logger buffers writes into an internal buffer and doesn't write to disk until that buffer has filled. Enabling flush on commit will flush the logger regardless of whether the buffer has filled.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.flushOnCommit
Constraints: true | false

<autoRepair>

Whether or not an attempt will be made to automatically repair a non-empty log on open by truncating malformed entries at the end of the log that are part of incomplete transactions.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.autoRepair
Constraints: true | false

<storeRoot>

Specifies the root folder in which the logger's transaction log files are located.

Usage: Optional
Default: ${NVROOT}/rdat
X DDL Override: x.apps.app.<appname>.outboundMessageLogging.storeRoot
Constraints: a file path (possibly relative to the working directory.

<initialLogLength>

Sets the initial file size of logger's transaction log in gigabytes.

Preallocating the transaction log can save costs in growing the file size over time since the operation of growing a log file may actually results in a write of file data + the metadata operation of updating the file size, and may also benefit from allocating contiguous sectors on disk.

Usage: Optional
Default: 1 (1Gb)
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.initialLogLength
Constraints: positive float

<zeroOutInitial>

Whether the log file should be explictly zeroed out (to force commit all disk pages) if newly created.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.zeroOutInitial
Constraints: true | false

<pageSize>

Sets the page size for the disk in bytes. The logger will use this as a hint in several areas to optimize its operation.

Usage: Optional
Default: 8192
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.pageSize
Constraints: positive float

<detachedWrite

Configures whether or not logger writes are done by the committing thread or passed off to a detached writer thread. Offloading to a writer thread can increase application throughput but requires an extra processor core for the logger thread.

enabled>

Can be set to true to enable detached logging for the logger.

Usage: Required
Default: false
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.detachedWrite.enabled
Constraints: true | false

<queueDepth>

The size of the feeder queue for the event multiplexer. Typically this value should be a power of 2. When not specified, the platform's default value for the multiplexer will be used.

See <queueDepth>

X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.detachedWrite.queueDepth
Constraints: positive integer

<queueOfferStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueOfferStrategy> 

X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.detachedWrite.queueOfferStrategy
Constraints: See QueueOfferStrategy

<queueWaitStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueWaitStrategy>  

X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.detachedWrite.queueWaitStrategy
Constraints: See QueueWaitStrategy

<queueDrainerCpuAffinityMask>

Sets the CPU affinity mask to use for the drainer thread. The affinity string can either be a long that represents a mask of logical cpu, or a square bracket enclosed comma separated list enumerating the logical cpus.

See <queueDrainerCpuAffinityMask>   

X DDL Override: x.apps.app.<appname>.outboundMessageLogging.
detachedWrite.queueDrainerCpuAffinityMask

<queueFeedMaxConcurrency>

Sets the maximum number of threads that will feed the multiplexer's queue.

See <queueFeedMaxConcurrency>     

Usage: Optional
Default: 16
X DDL Override:
x.apps.app.<appname>.outboundMessageLogging.detachedWrite.queueFeedMaxConcurrency
Constraints: positive integer

</detachedWrite>

</outboundMessageLogging>

<perTransactionStatsLogging

Configures per transaction stats binary logging for the engine.

A per transaction stats logger logs per transaction stats to a transaction log when capturePerTransactionStats is enabled for an AEP engine.

Per transaction stats logging is currently classified as an experimental feature

policy

The per transaction stats logging policy for the application.

See PerTransactionStatsLoggingPolicy

Usage: Required
Default: "Default"
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.policy

Constraints: Default | Off | UseDedicated

failurePolicy

The per transaction stats logging failure policy for the application.

See PerTransactionStatsLoggingFailurePolicy

Usage: Optiona
Default: StopEngine
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.failurePolicy
Constraints: StopEngine| StopLogging

<autoFlushSize>

In the absence of explicit flushes (e.g. flushOnCommit) of written entries, the size at which flush is automatically triggered for queued writes. If not set, the platform default (8192) is used.

Usage: Optional
Default: 8192
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.autoFlushSize
Constraints: positive integer

<flushOnCommit>

Whether or not the logger should be flushed on commit. By default the logger buffers writes into an internal buffer and doesn't write to disk until that buffer has filled. Enabling flush on commit will flush the logger regardless of whether the buffer has filled.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.flushOnCommit
Constraints: true | false

<autoRepair>

Whether or not an attempt will be made to automatically repair a non-empty log on open by truncating malformed entries at the end of the log that are part of incomplete transactions.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.autoRepair
Constraints: true | false

<storeRoot>

Specifies the root folder in which the logger's transaction log files are located.

Usage: Optional
Default: ${NVROOT}/rdat
X DDL Override: x.apps.app.<appname>.perTransactionStatsLogging.storeRoot
Constraints: a file path (possibly relative to the working directory.

<initialLogLength>

Sets the initial file size of logger's transaction log in gigabytes.

Preallocating the transaction log can save costs in growing the file size over time since the operation of growing a log file may actually results in a write of file data + the metadata operation of updating the file size, and may also benefit from allocating contiguous sectors on disk.

Usage: Optional
Default: 1 (1Gb)
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.initialLogLength
Constraints: positive float

<zeroOutInitial>

Whether the log file should be explictly zeroed out (to force commit all disk pages) if newly created.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.zeroOutInitial
Constraints: true | false

<pageSize>

Sets the page size for the disk in bytes. The logger will use this as a hint in several areas to optimize its operation.

Usage: Optional
Default: 8192
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.pageSize
Constraints: positive float

<detachedWrite

Configures whether or not logger writes are done by the committing thread or passed off to a detached writer thread. Offloading to a writer thread can increase application throughput but requires an extra processor core for the logger thread.

enabled>

Can be set to true to enable detached logging for the logger.

Usage: Required
Default: false
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.detachedWrite.enabled
Constraints: true | false

<queueDepth>

The size of the feeder queue for the event multiplexer. Typically this value should be a power of 2. When not specified, the platform's default value for the multiplexer will be used.

See <queueDepth>

X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.detachedWrite.queueDepth
Constraints: positive integer

<queueOfferStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueOfferStrategy> 

X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.detachedWrite.queueOfferStrategy
Constraints: See QueueOfferStrategy

<queueWaitStrategy>

Controls the offer strategy for threads publishing to the queue. When not specified, the platform's default value for the multiplexer will be used.

See <queueWaitStrategy>  

X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.detachedWrite.queueWaitStrategy
Constraints: See QueueWaitStrategy

<queueDrainerCpuAffinityMask>

Sets the CPU affinity mask to use for the drainer thread. The affinity string can either be a long that represents a mask of logical cpu, or a square bracket enclosed comma separated list enumerating the logical cpus.

See <queueDrainerCpuAffinityMask>   

X DDL Override: x.apps.app.<appname>.perTransactionStatsLogging.
detachedWrite.queueDrainerCpuAffinityMask

<queueFeedMaxConcurrency>

Sets the maximum number of threads that will feed the multiplexer's queue.

See <queueFeedMaxConcurrency>     

Usage: Optional
Default: 16
X DDL Override:
x.apps.app.<appname>.perTransactionStatsLogging.
detachedWrite.queueFeedMaxConcurrency

Constraints: positive integer

</detachedWrite>

</perTransactionStatsLogging>

<startupExpectations

Specifies expectations that must be met on application startup.

Unmet startup expectations will prevent the application from starting, ensuring that operational conditions are met.

Usage: Optional

<role>

Checks the HA Role of the application on startup.

The role of an application is defined by the underlying role of its store. If the application has no store configured, its role will be 'Primary'.

See StoreBindingRoleExpectation  

Usage: Optional
X DDL Override: x.apps.app.<appname>.startupExpectations.role
Constraints: Primary | Backup | None

<logEmptiness>

Enforces log emptiness expectations at startup.

See LogEmptinessExpectation  

Usage: Optional
Default: None
X DDL Override: x.apps.app.<appname>.startupExpectations.logEmptiness
Constraints: None | Empty | NotEmpty

</startupExpectations>

<messageHandlingPolicy>

Specifies the application's message handling policy.

It is rare that an application would want to set anything other than 'Normal' for the message handling policy outside of a diagnostic or debug context.

See MessageHandlingPolicy   

Usage: Optional
Default: Normal
X DDL Override: x.apps.app.<appname>.messageHandlingPolicy
Constraints: Normal | Noop | Discard

<messagingStartFailPolicy>

Specifies an engine's messaging start fail policy.

The messaging start operation establishes the bindings to the various buses that an engine is configured to bind to. This enumeration enumerates the policy that determines the conditions under which a messaging start operation is considered to have failed.

The NeverFail option causes a start operation to be considered successful as long as all bind attempts do not result in permanent exceptions (a permanent exception reported by a bind attempt causes the bind operation to not be retried while a non-permanent exception causes the bind attempt to be periodically retried). In other words, the NeverFail option causes a messaging start operation to be reported as successful as long as at least one bind attempt was successful or failed with a non-permanent exception. 

See MessagingStartFailPolicy   

Usage: Optional
Default: FailIfOneBindingFails
X DDL Override: x.apps.app.<appname>.messageStartFailPolicy
Constraints: Normal | FailIfOneBindingFails | FailIfAllBindingsFail

<messageBusBindingFailPolicy>

Specifies the policy that determines what action an engine takes when a message bus binding fails. 

See MessageBusBindingFailPolicy   

Usage: Optional
Default: FailIfAnyBindingFails
X DDL Override: x.apps.app.<appname>.messageBusBindingFailPolicy
Constraints: Reconnect | FailIfAnyBindingFails

<replicationPolicy>

Specifies the application's replication policy.

The replication policy controls how messages are replicated to backup members (or disk).

In most cases an application should specify a policy of Pipelined. Specifying the wrong value for this property can compromise recovery and cause message loss or duplication.

See ReplicationPolicy   

Usage: Optional
Default: Pipelined
X DDL Override:
x.apps.app.<appname>.replicationPolicy
Constraints: Pipelined | Asynchronous

<messageSendPolicy>

Enumerates an application's AepEngine's outbound message send policies.

The message send policy controls at what point during transaction commit processing that application sent messages are transmitted out of the application. 

In most cases, an application should specify a policy of Pipelined. Specifying the wrong value for this property can compromise recovery and cause message loss or duplication.

See MessageSendPolicy   

Usage: Optional
Default: ReplicateBeforeSend
X DDL Override:
x.apps.app.<appname>.messageSendPolicy
Constraints: ReplicateBeforeSend| SendBeforeReplicate | Noop

<inboundEventAcknowledgementPolicy>

Enumerates an engine's inbound event acknowledgement policy.

The general contract of an AepEngine is that it cannot acknowledge up stream events (such as message events) in a transaction until such as the transaction has been stabilized to the point that in the event of a failure the message will not be lost.

When the engine is not configured with a store this property has no effect and events are acknowledged when the entire transaction is committed (e.g. when downstream acknowledgements are received.)

See InboundEventAcknowledgementPolicy   

Usage: Optional
Default: Default
X DDL Override:
x.apps.app.<appname>.inboundEventAcknowledgementPolicy
Constraints: Default | OnSendStability | OnStoreStability

appExceptionHandlingPolicy>

Set an engine's application exception handling policy, using which an engine determines how to handle unchecked exceptions thrown by an application handler.

See AppExceptionHandlingPolicy

Usage: Optional
Default: RollbackAndStop
X DDL Override:
x.apps.app.<appname>.appExceptionHandlingPolicy
Constraints: RollbackAndStop | QuarantineAndStop | LogExceptionAndContinue

<quarantineChannel>

Set an engine's quarantine channel.

Sets the channel on which quarantined messages are transmitted. It must take the form of channelName@busName

This applies when the application throws an exception and the application exception policy is configured to be 'quarantine and stop' i.e. QuarantineAndStop

Usage: Optional
Default: null
X DDL Override:
x.apps.app.<appname>.quarantineChannel
Constraints: (.)+@(.)+

<quarantineMessageKey>

Set an engine's quarantine message key.

Used to explicitly set the message key to be associated with outbound quarantine messages. If the key is set using this method, the sending of the quarantine message will bypass the dynamic key resolution machinery. 

Usage: Optional
Default: null
X DDL Override:
x.apps.app.<appname>.quarantineMessageKey
Constraints: valid channel key

<messageSend
ExceptionHandlingPolicy>

The policy used by an application's AepEngine to determine how to handle unchecked exceptions thrown on message sends.

Note that policy covers only the send of the message through the underlying bus binding during transaction commit. In particular, It does not cover:

• Exceptions thrown from send calls made by the application during message processing. That policy must be set via the AppExceptionHandlingPolicy.
• Exceptions that result from processing of acknowledgements for guaranteed message traffic from the message bus which count as stability failures and are deemed fatal.

See MessageSendExceptionHandlingPolicy

Usage: Optional
Default: TreatAsStabilityFailure
X DDL Override:
x.apps.app.<appname>.messageSendExceptionHandlingPolicy
Constraints: TreatAsStabilityFailure | LogExceptionAndContinue

<replicationPolicy>

Specifies the application's replication policy.

In most cases an application should specify a policy of Pipelined. Specifying the wrong value for this property can compromise recovery and cause message loss or duplication.

See ReplicationPolicy   

Usage: Optional
Default: Pipelined
X DDL Override: x.apps.app.<appname>.replicationHandlingPolicy
Constraints: Pipelined | Asynchronous

<adaptiveCommitBatchCeiling>

Set the application's AepEngine's adaptive commit batch ceiling.

The adaptive commit batch ceiling controls the maximum number of inbound messages to group into a single transaction which can improve throughput.

A value less than or equal to 1 disables adaptive commit.

Usage: Optional
Default: TreatAsStabilityFailure
X DDL Override:
x.apps.app.<appname>.adaptiveCommitBatchCeiling
Constraints: TreatAsStabilityFailure | LogExceptionAndContinue

<enableTransactionCommitSuspension>

Sets whether transaction commit suspension is enabled or disabled.

Transaction commit suspension is an experimental feature that allows an application to temporarily suspend commit of a transaction.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.enableTransactionCommitSuspension
Constraints: true | false

<dispatchTransactionStageEvents>

Sets whether transaction stage events are emitted by the application's AepEngine.

Controls whether or not AepTransactionStageEvent are emitted by the application's engine. An AepTransactionStageEvent is used by a user to suspend a transaction.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.dispatchTransactionStageEvents
Constraints: true | false

<replicateSolicitedSends>

Sets whether or not to replicate solicited sends to a backup.

This parameter governs whether solicited sends (sends triggered by the processing of inbound messages) performed on clustered State Replication engines will be replicated or not. This setting has no effect on Event Sourced engines or engines that are not clustered.

<replicateUnsolicitedSends>

Set whether to replicate unsolicited sends.

This parameter governs whether unsolicited sends performed on clustered engines will be replicated or not. This setting has no effect on engines that are not clustered. An unsolicited send is a send done outside of a event handler via an AepEngine.send method. Because unsolicited sends aren't part of an engine's transactional message processing, they are not considered to be part of the application's HA state. To treat unsolicited sends as part of an application's HA state, see sequenceUnsolicitedSendsWithSolicitedSends.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.replicateUnsolicitedSends
Constraints: true | false

<sequenceUnsolicitedSends>

Set whether to sequence unsolicited sends.

By default, unsolicited sends are sent with a sequence number of 0. Specifying true in this parameter will cause sequence numbers to also be attached to unsolicited sends.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.sequenceUnsolicitedSends
Constraints: true | false

<sequenceUnsolicitedSends
WithSolicitedSends>

Set whether to sequence unsolicited sends with solicited sends.

This parameter is applicable for applications performing concurrent solicited and unsolicited sends and want the unsolicited sends to be sequenced. Setting this parameter ensures that unsolicited and solicited sends are sequenced on the wire in the same order in which the sequence numbers were attached to the messages. In effect, this causes an unsolicited send to be injected into the underlying engine's transactional event processing stream promoting it to a transaction event.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.sequenceUnsolicitedSendsWithSolicitedSends
Constraints: true | false

<disposeOnSend>

Set whether or not the engine disposes sent messages.

If set, then the AepEngine.sendMessage method will dispose a message after it has been sent. This means that the caller must not hold onto or reference a message beyond the call to the send message method. If unset, then a zero garbage application must call dispose on each sent message to ensure it is returned to its pool.

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.disposeOnSend
Constraints: true | false

<clusterHeartbeatInterval>

Sets the cluster heartbeat interval for the application in milliseconds.

When replicating message and state to its cluster peers, the AepEngine piggybacks internal state, such as outbound message acknowledgements and other internal control data. Setting a cluster heartbeat interval can be useful for low throughput applications to keep the backup in closer sync to the primary. The most common use case for setting this would be to reduce the number of in doubt messages outstanding in backup peers to a window.

A value of 0 (default) disables the cluster heartbeat interval

Usage: Optional
Default: 0
X DDL Override:
x.apps.app.<appname>.clusterHeartbeatInterval
Constraints: non negative integer

<administrative>

Marks the application as an 'administrative' application.

Marking an application as 'administrative' excludes it from being included in latency or throughput optimizations that demand system resources.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.administrative
Constraints: true | false

<stuckAlertEventThreshold>

Sets the threshold, in seconds, after which an AepStuckAlertEvent is dispatched to the application's IAepAsynchronousEventHandler. 

An AepStuckAlertEvent event is intended to alert that the engine's transaction pipeline is "stuck" i.e. there are one or more transaction commits in the pipeline and the event multiplexer thread is not processing any events. For example, the event multiplexer thread could be flow controlled on the replication TCP connection due to an issue in the backup or could be spinning in a loop in the business logic due to a bug in a business logic handler.

See Stuck Engine Alerts for more information

Usage: Optional
Default: 0
X DDL Override:
x.apps.app.<appname>.stuckAlertEventThreshold
Constraints: non negative integer

<performDuplicateChecking>

Set whether the application's engine should perform duplicate checking.

When duplicate checking is enabled, received messages that are deemed duplicates are discarded by the application's engine. A message is considered to be a duplicate under the following circumstances:

• The message has a sequence number that is greater than 1.
• The sequence number is less than the last received sequence number for the flowId and senderId in the message.
  • A sequence number of 1 is interpreted as a restart of a messaging stream.
  • A value of 0 or less means the message is not sequenced and will ignored for duplicate checks.

Sequence id assignment by an AepEngine

• MessageSender: Is assigned by the AepEngine using the hashcode of the engine name.
• MessageFlow: Leaves flow unset as 0 (default). At present it is not recommended for applications to set a flow.
• MessageSequenceNumber: Set for each send from a event handler by incrementing a sequence number or for each unsolicited send (outside of a event handler) when sequenceUnsolicitedSends is true.

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.performDuplicateChecking
Constraints: boolean

<setOutboundSequenceNumbers>

Disables setting of sequence numbers outbound messages.

The setting of sequence numbers in outbound messages comes at a very slight performance penalty that may not be tolerated by ultra low latency applications. This property can be used to switch off the setting of sequence numbers in oubound messages for such performance critical applications. However, note that this effectively disables checking for duplicates for messages sent by such a configured engine by downstream apps.

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.setOutboundSequenceNumbers
Constraints: boolean

<syncInjectedMessages>

Sets whether MessageView.sync() is called during AepEngine.injectMessage.

When using Event Sourcing or inbound message logging injected messages injected messages may be replicated and/or persisted to disk. To do so means that the contents of the message must be synced. By doing sync() during the inject call, it can save the engine's processor thread cpu cycles.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.syncInjectedMessages
Constraints: boolean

<performMidstreamInitializationValidation>

Set whether the engine checks that initial transactions are not missing during recovery or replication. This parameter is only applicable to event sourced engines.

It is not recommended that you disable this check unless recommended by Neeve Support.

Usage: Optional
Default: true
X DDL Override:
x.apps.app.<appname>.performMidstreamInitializationValidation
Constraints: true | false

<enableSequenceNumberTrace>

Enables diagnostic trace logging related to message sequencing. Enabling this trace can assist in diagnosing issues related to the loss, duplicate or out of order events. When enabled, trace will be emitted at debug level (TRACE level for SLF4J) to the logger named 'nv.aep.sno'.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.enableSequenceNumberTrace
Constraints: true | false

<enableEventTrace>

Enables diagnostic trace logging of events received and dispatched by an engine. Enabling this trace is useful in determining the sequence of events processed by the engine. When enabled, trace will be emitted at debug level (TRACE level for SLF4J) to the logger named 'nv.aep.event'.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.enableEventTrace
Constraints: true | false

<enableTransactionTrace>

Enables diagnostic trace logging related to transactions processed by an engine. Enabling this trace is useful in determining the relative sequencing and timing of transaction commits as the commits are executed by the engine. When enabled, trace will be emitted at debug level (TRACE level for SLF4J) to the logger named 'nv.aep.txn'.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.enableTransactionTrace
Constraints: true | false

<enableScheduleTrace>

Enable diagnostic trace logging related to schedules (timers) managed by an engine. Enabling this trace is useful for diagnosing issues related to engine timer execution and scheduling. When enabled, trace will be emitted at debug level (TRACE level for SLF4J) to the logger named 'nv.aep.sched'.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.enableScheduleTrace
Constraints: true | false

<enableMessageTrace>

Enables diagnostic trace logging for messages as they pass through the engine. Enabling this trace is useful for tracing the contents of messages at different stages of execution within the engine. When enabled, trace will be emitted at debug level (TRACE level for SLF4J) to the logger named 'nv.aep.msg'.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.enableMessageTrace
Constraints: true | false

<messageTraceInJson>

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.messageTraceInJson
Constraints: true | false

<messageTraceJsonStyle>

Sets the styling for Json formatted message trace. This parameter is only applicable if message trace in Json is enabled.

Valid options are:

• Default: Specifies the default jackson pretty printer should be used (DefaultPrettyPrinter)
• PrettyPrint: Same as default.
• Minimal: A minimal single line pretty printer.
• SingleLine: A minimal single line pretty printer. Same as minimal, but with a space after the colon between objects field and value separator (e.g. "intField": 1 vs "intField":1)

Usage: Optional
Default: Default
X DDL Override:
x.apps.app.<appname>.messageTraceJsonStyle
Constraints: Default | PrettyPrint | Minimal | SingleLine

<messageTraceFilterUnsetFields>

Sets whether unset fields are filtered for json formatted objects when json message tracing is enabled.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.messageTraceFilterUnsetFields

Constraints: true | false

<messageTraceMetadataDisplayPolicy>

Sets whether metadata, payload or both will be traced when message tracing is enabled.

Valid Options are:

• On:  Specifies that metadata should be displated along with the message payload.
• Off:  Specifies that only the message payload should be displayed.
• Only: Specifies that only the metadata should be displayed.

Usage: Optional
Default: On
X DDL Override:
x.apps.app.<appname>.messageTraceMetadataDisplayPolicy
Constraints: On | Off | Only

<maxEnvironmentProviders>

Sets the maximum number of environment providers that can be registered with the engine.

Usage: Optional
Default: 256
X DDL Override:
x.apps.app.<appname>.maxEnvironmentProviders
Constraints: positive integer.

<enableSendCommitCompleteSequenceAlerts>

Set whether or not to enable out of order send commit completion detection. When enabled, the engine will check that stability events (acknowledgements) from the underlying messaging provider are received in an ordered fashion. If acknowledgements are received out of order, then the engine will dispatch appropriate alerts.

This check can introduce overhead and is useful in situations in which the message bus is expected to return acks in an ordered fashion. A raised alert is not necessarily an indicator of a problem as the engine will ensure that transactions are completed out in order. In general it is not recommended that this property be enabled unless diagnosing an issue where a bus binding appears not to be acknowledging messages.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.enableSendCommitCompleteSequenceAlerts
Constraints: true | false

<captureMessageTypeStats>

Sets whether statistics are additionally recorded ona per message type basis. Collection of message type specific statistics records counts and rates per type as well as message processing time statistics for each message which can be useful in finding particular handlers that have high execution times.

Enabling message type stats introduces a fair amount of overhead. Before running with this in production be sure to gauge its performance impact for your application to determine whether or not the overhead is worth the additional visibility.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.captureMessageTypeStats
Constraints: true | false

<captureTransactionLatencyStats>

Sets whether or not the engine records transaction latency stats.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.captureTransactionLatencyStats
Constraints: true | false

<capturePerTransactionStats>

Sets whether or not the engine records per transaction stats.

Unlike captureTransactionLatencyStats which records histographical latencies, this setting is much more expensive in that it records and emits individual timestamps for operations that occured in the transaction including store commit timestamps and individual message timestamps.

In most cases the capturing this level of detail is not worth the overhead it incurs, as the histographical latency captured via captureTransactionLatencyStats is usually sufficient for inferring timings within a given sampling interval. However, in cases where it is critical to determine the exact timings of transaction processing to better understand product behavior it can be useful.

If used in production (which is not recommended), applications should undergo stress testing under maximum peak load to determine the impact of enabling collection of per transaction stats.

Per transaction stats collection is currently classified as an experimental feature. It is subject to change without notice.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.capturePerTransactionStats
Constraints: true | false

<captureEventLatencyStats>

Sets whether or not the engine records event latency stats (such as the amount of time of events spent in its input queue).

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.captureEventLatencyStats
Constraints: true | false

<replicateInParallel>

Enables  parallel replication. When parallel replication is enabled, the engine replicates inbound messages to the cluster backups in parallel with the processing of the message by the message handler. This parameter only applies to Event Sourced engines.

This parameter is particularly useful for Event Sourced applications that have higher message processing times because in this case it may be possible to replicate the message prior to completion of the message handler.

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.replicateInParallel
Constraints: true | false

<preserveChannelJoinsOnStop>

Sets whether or not to preserve joined channels when the engine stops normally.

By default, when an engine is stopped without an error bus channels that were 'joined' will be 'left', meaning that any subscriptions or interests created by the message bus will be unsubscribed or unregistered. Setting this value to true causes the engine to preserve channel interest even on a clean shutdown.

Note that this property has no effect for the case where an engine shuts down with an error (e.g. AepEngine.stop(Exception) with a non-null cause. In this case channel joins are left intact allowing a backup to take over.

Note that this behavior can be overridden programmatically on a case by case basis by a handler for AepEngineStoppingEvent by setting AepEngineStoppingEvent.setPreserveChannelJoins(boolean).

Usage: Optional
Default: false
X DDL Override:
x.apps.app.<appname>.preserveChannelJoinsOnStop
Constraints: true | false

</app>

<apps>