Add distributed timer docs.

docs/src/main/asciidoc/_developer-guide/ejb3/Jakarta_Enterprise_Beans_Distributed_Timers.adoc

@@ -0,0 +1,52 @@
+[[Jakarta_Enterprise_Beans_Distributed_Timers]]
+= Jakarta Enterprise Beans Distributed Timers
+
+[abstract]
+
+WildFly now supports distributed timers backed by an embedded Infinispan cache.
+The Infinispan cache not only provides an HA solution for persistent timer metadata, in the case of a server crash or restart,
+but also distributes timer execution evenly between cluster members.
+Consequently, this solution generally provides better performance and scalability than the existing database solution.
+
+This feature can also be used to provide file, databaase, or remote infinispan-server time persistence for single server architectures, effectively replacing the existing file-store and database-store TimerService facilities.
+Additionally, this feature can also provide passivation support for non-persistent timers to allow the creation of large number of transient timers without the risk of running out of memory.
+
+[[setup]]
+== Setup
+
+Distributed timer behavior is configured via the distributable-ejb subsystem, and can be configured globally via the ejb3 subsysetem or customized per EJB via the `timer-service` EJB deployment descriptor namespace.
+To use distributed timers, one must first disable the existing data store mechanism, and then specific the timer management to use for persistent timers, which references a timer management resource from the distributable-ejb subsystem.
+
+[source,options="nowrap"]
+----
+batch
+ /subsystem=ejb3/service=timer-service:undefine-attribute(name=default-data-store)
+ /subsystem=ejb3/service=timer-service:write-attribute(name=default-persistent-timer-management, value=persistent)
+run-batch
+----
+
+To use distributable timer management for transient (i.e. non-persistent) timers, remove the thread-pool-name attribute, and then specific the timer management to use for transient timers, which references a timer management resource from the distributable-ejb subsystem.
+
+[source,options="nowrap"]
+----
+batch
+ /subsystem=ejb3/service=timer-service:undefine-attribute(name=thread-pool)
+ /subsystem=ejb3/service=timer-service:write-attribute(name=default-transient-timer-management, value=transient)
+run-batch
+----
+
+Alternatively, distributable timer management can be enabled via the timer-service deployment descriptor namespace, either globally, or per EJB.
+e.g.
+
+[source,xml]
+----
+<t:timer-service>
+    <ejb-name>*</ejb-name>
+    <t:persistent-timer-management>distributed</t:persistent-timer-management>
+    <t:transient-timer-management>transient</t:transient-timer-management>
+</t:timer-service>
+----
+
+The `<persistent-timer-management/>` and `<transient-timer-management/>` elements above each reference a named timer management resource defined within the distributable-ejb subsystem.
+
+To customize distributed EJB timer behavior, please refer to the link:High_Availability_Guide{outfilesuffix}#timer-management[distributable-ejb subsystem documentation].

docs/src/main/asciidoc/_developer-guide/ejb3/jboss-ejb3.xml_Reference.adoc

@@ -137,3 +137,19 @@ defined in the server configuration (i.e. `standalone.xml` or
 This namespace is deprecated and as of WildFly {wildflyVersion} its use has no effect.
 The clustering behavior of Jakarta Enterprise Beans are determined by the profile in use on
 the server.
+
+[[timer-service-namespace]]
+==== The timer-service namespace urn:timer-service:2.0
+
+This allows you to customize the TimerService behavior for a given EJB.
+
+e.g.
+
+[source,xml,options="nowrap"]
+----
+<t:timer-service>
+    <ejb-name>*</ejb-name>
+    <t:persistent-timer-management>persistent</t:persistent-timer-management>
+    <t:transient-timer-management>transient</t:transient-timer-management>
+</t:timer-service>
+----

docs/src/main/asciidoc/_high-availability/Distributable_Jakarta_Enterprise_Beans_Applications.adoc

@@ -93,11 +93,32 @@ The infinispan-client-mappings-registry provider is a provider based on an Infin
 The client mappings registry provider suitable for a local, non-clustered server.
 
 
-[[ejb-timer]]
-== EJB Timer
+[[timer-management]]
+=== Timer management
 
-WildFly now supports clustered database backed timers. For details have
-a look to the link:Developer_Guide{outfilesuffix}#EJB3_Clustered_Database_Timers[EJB3 reference section].
+The distributable-ejb subsystem defines a set of timer management resources that define behavior for persistent or non-persistent EJB timers.
+
+To use distributable timer management for EJB timers, one must first disable the existing in-memory mechanisms in the ejb3 subsystem.
+See link:Developer_Guide{outfilesuffix}#Jakarta_Enterprise_Beans_Distributed_Persistent_Timers[Jakarta Enterprise Beans Distributed Timer documentation] for details.
+
+==== infinispan-timer-management
+
+This provider stores timer meta data within an embedded Infinispan cache, and utilizes consistent hashing to distribute timer execution between cluster members.
+
+* `cache-container` specifies a cache container defined in the Infinispan subsystem
+* `cache` specifies the a cache configuration within the specified cache-container
+* `max-active-timers` specifies the maximum number active timers to retain in memory at a time, after which the least recently used will passivate
+
+To ensure proper functioning, the associated cache configuration. regardless of type, should use:
+
+* BATCH transaction mode
+* REPEATABLE_READ lock isolation
+
+Generally, persistent timers will leverage a distributed or replicated cache configuration if in a cluster, or a local, persistent cache configuration if on a single server;
+while transient timers will leverage a local, passivating cache configuration.
+
+By default, all cluster members will be eligible for timer execution.
+A given cluster member exclude itself from timer execution by using a cache `capacity-factor` of 0.
 
 [[deploying-clustered-ejbs]]
 == Deploying clustered EJBs