From e3f3fe23d5123d894dfc933f97f7eee69e2f9cb4 Mon Sep 17 00:00:00 2001 From: Paul Ferraro Date: Mon, 20 Dec 2021 16:37:05 -0500 Subject: [PATCH] Add distributed timer docs. --- ...a_Enterprise_Beans_Distributed_Timers.adoc | 52 +++++++++++++++++++ .../ejb3/jboss-ejb3.xml_Reference.adoc | 16 ++++++ ...Jakarta_Enterprise_Beans_Applications.adoc | 29 +++++++++-- 3 files changed, 93 insertions(+), 4 deletions(-) create mode 100644 docs/src/main/asciidoc/_developer-guide/ejb3/Jakarta_Enterprise_Beans_Distributed_Timers.adoc diff --git a/docs/src/main/asciidoc/_developer-guide/ejb3/Jakarta_Enterprise_Beans_Distributed_Timers.adoc b/docs/src/main/asciidoc/_developer-guide/ejb3/Jakarta_Enterprise_Beans_Distributed_Timers.adoc new file mode 100644 index 000000000000..81d18e5cab6f --- /dev/null +++ b/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] +---- + + * + distributed + transient + +---- + +The `` and `` 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]. diff --git a/docs/src/main/asciidoc/_developer-guide/ejb3/jboss-ejb3.xml_Reference.adoc b/docs/src/main/asciidoc/_developer-guide/ejb3/jboss-ejb3.xml_Reference.adoc index 4ccd04388baa..7a74e7d1f936 100644 --- a/docs/src/main/asciidoc/_developer-guide/ejb3/jboss-ejb3.xml_Reference.adoc +++ b/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"] +---- + + * + persistent + transient + +---- \ No newline at end of file diff --git a/docs/src/main/asciidoc/_high-availability/Distributable_Jakarta_Enterprise_Beans_Applications.adoc b/docs/src/main/asciidoc/_high-availability/Distributable_Jakarta_Enterprise_Beans_Applications.adoc index da6da32b1826..4f47c826acc6 100644 --- a/docs/src/main/asciidoc/_high-availability/Distributable_Jakarta_Enterprise_Beans_Applications.adoc +++ b/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