Skip to end of metadata
Go to start of metadata

WildFly 10 introduces a “singleton” subsystem, which defines a set of policies that define how an HA singleton should behave. A singleton policy can be used to instrument singleton deployments or to create singleton MSC services.


The default subsystem configuration from WildFly’s ha and full-ha profile looks like:

A singleton policy defines:

  1. A unique name
  2. A cache container and cache with which to register singleton provider candidates
  3. An election policy
  4. A quorum (optional)

One can add a new singleton policy via the following management operation:

Cache configuration

The cache-container and cache attributes of a singleton policy must reference a valid cache from the Infinispan subsystem. If no specific cache is defined, the default cache of the cache container is assumed. This cache is used as a registry of which nodes can provide a given service and will typically use a replicated-cache configuration.

Election policies

WildFly 10 includes 2 singleton election policy implementations:

  • simple
    Elects the provider (a.k.a. master) of a singleton service based on a specified position in a circular linked list of eligible nodes sorted by descending age. Position=0, the default value, refers to the oldest node, 1 is second oldest, etc. ; while position=-1 refers to the youngest node, -2 to the second youngest, etc.
  • random
    Elects a random member to be the provider of a singleton service

Additionally, any singleton election policy may indicate a preference for one or more members of a cluster. Preferences may be defined either via node name or via outbound socket binding name. Node preferences always take precedent over the results of an election policy.


Network partitions are particularly problematic for singleton services, since they can trigger multiple singleton providers for the same service to run at the same time. To defend against this scenario, a singleton policy may define a quorum that requires a minimum number of nodes to be present before a singleton provider election can take place. A typical deployment scenario uses a quorum of N/2 + 1, where N is the anticipated cluster size. This value can be updated at runtime, and will immediately affect any active singleton services.

Non-HA environments

The singleton subsystem can be used in a non-HA profile, so long as the cache that it references uses a local-cache configuration. In this manner, an application leveraging singleton functionality (via the singleton API or using a singleton deployment descriptor) will continue function as if the server was a sole member of a cluster. For obvious reasons, the use of a quorum does not make sense in such a configuration.

For any deployment using a singleton-deployment.xml descriptor, this descriptor will be ignored and the deployment will start as any other deployment.
If the jboss-all.xml singleton-deployment is used the deployment will fail with a parser error because of the missing singleton subsystem.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.