From 261bb629d4aee95ed11f14c7de50a2ba896b9ff0 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Thu, 18 Jun 2020 14:54:33 +0200 Subject: [PATCH] Replace "blacklist" with alternative words See gh-25262 --- src/docs/asciidoc/core/core-beans.adoc | 95 +++++++++++++------------- 1 file changed, 48 insertions(+), 47 deletions(-) diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index eb64349f87fe..9f721f50d31b 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -10562,12 +10562,12 @@ simple class that extends Spring's `ApplicationEvent` base class: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java ---- - public class BlackListEvent extends ApplicationEvent { + public class BlockedListEvent extends ApplicationEvent { private final String address; private final String content; - public BlackListEvent(Object source, String address, String content) { + public BlockedListEvent(Object source, String address, String content) { super(source); this.address = address; this.content = content; @@ -10579,7 +10579,7 @@ simple class that extends Spring's `ApplicationEvent` base class: [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] .Kotlin ---- - class BlackListEvent(source: Any, + class BlockedListEvent(source: Any, val address: String, val content: String) : ApplicationEvent(source) ---- @@ -10594,11 +10594,11 @@ example shows such a class: ---- public class EmailService implements ApplicationEventPublisherAware { - private List blackList; + private List blockedList; private ApplicationEventPublisher publisher; - public void setBlackList(List blackList) { - this.blackList = blackList; + public void setBlockedList(List blockedList) { + this.blockedList = blockedList; } public void setApplicationEventPublisher(ApplicationEventPublisher publisher) { @@ -10606,8 +10606,8 @@ example shows such a class: } public void sendEmail(String address, String content) { - if (blackList.contains(address)) { - publisher.publishEvent(new BlackListEvent(this, address, content)); + if (blockedList.contains(address)) { + publisher.publishEvent(new BlockedListEvent(this, address, content)); return; } // send email... @@ -10619,11 +10619,11 @@ example shows such a class: ---- class EmailService : ApplicationEventPublisherAware { - private lateinit var blackList: List + private lateinit var blockedList: List private lateinit var publisher: ApplicationEventPublisher - fun setBlackList(blackList: List) { - this.blackList = blackList + fun setBlockedList(blockedList: List) { + this.blockedList = blockedList } override fun setApplicationEventPublisher(publisher: ApplicationEventPublisher) { @@ -10631,8 +10631,8 @@ example shows such a class: } fun sendEmail(address: String, content: String) { - if (blackList!!.contains(address)) { - publisher!!.publishEvent(BlackListEvent(this, address, content)) + if (blockedList!!.contains(address)) { + publisher!!.publishEvent(BlockedListEvent(this, address, content)) return } // send email... @@ -10653,7 +10653,7 @@ shows such a class: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java ---- - public class BlackListNotifier implements ApplicationListener { + public class BlockedListNotifier implements ApplicationListener { private String notificationAddress; @@ -10661,7 +10661,7 @@ shows such a class: this.notificationAddress = notificationAddress; } - public void onApplicationEvent(BlackListEvent event) { + public void onApplicationEvent(BlockedListEvent event) { // notify appropriate parties via notificationAddress... } } @@ -10669,25 +10669,26 @@ shows such a class: [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] .Kotlin ---- - class BlackListNotifier : ApplicationListener { + class BlockedListNotifier : ApplicationListener { lateinit var notificationAddres: String - override fun onApplicationEvent(event: BlackListEvent) { + override fun onApplicationEvent(event: BlockedListEvent) { // notify appropriate parties via notificationAddress... } } ---- Notice that `ApplicationListener` is generically parameterized with the type of your -custom event (`BlackListEvent` in the preceding example). This means that the `onApplicationEvent()` method can -remain type-safe, avoiding any need for downcasting. You can register as many event -listeners as you wish, but note that, by default, event listeners receive events -synchronously. This means that the `publishEvent()` method blocks until all listeners have -finished processing the event. One advantage of this synchronous and single-threaded -approach is that, when a listener receives an event, it operates inside the transaction -context of the publisher if a transaction context is available. If another strategy for -event publication becomes necessary, see the javadoc for Spring's +custom event (`BlockedListEvent` in the preceding example). This means that the +`onApplicationEvent()` method can remain type-safe, avoiding any need for downcasting. +You can register as many event listeners as you wish, but note that, by default, event +listeners receive events synchronously. This means that the `publishEvent()` method +blocks until all listeners have finished processing the event. One advantage of this +synchronous and single-threaded approach is that, when a listener receives an event, it +operates inside the transaction context of the publisher if a transaction context is +available. If another strategy for event publication becomes necessary, see the javadoc +for Spring's {api-spring-framework}/context/event/ApplicationEventMulticaster.html[`ApplicationEventMulticaster`] interface and {api-spring-framework}/context/event/SimpleApplicationEventMulticaster.html[`SimpleApplicationEventMulticaster`] implementation for configuration options. @@ -10698,7 +10699,7 @@ the classes above: [source,xml,indent=0,subs="verbatim,quotes"] ---- - + known.spammer@example.org known.hacker@example.org @@ -10707,15 +10708,15 @@ the classes above: - - + + ---- Putting it all together, when the `sendEmail()` method of the `emailService` bean is -called, if there are any email messages that should be blacklisted, a custom event of type -`BlackListEvent` is published. The `blackListNotifier` bean is registered as an -`ApplicationListener` and receives the `BlackListEvent`, at which point it can +called, if there are any email messages that should be blocked, a custom event of type +`BlockedListEvent` is published. The `blockedListNotifier` bean is registered as an +`ApplicationListener` and receives the `BlockedListEvent`, at which point it can notify appropriate parties. NOTE: Spring's eventing mechanism is designed for simple communication between Spring beans @@ -10731,13 +10732,13 @@ architectures that build upon the well-known Spring programming model. ==== Annotation-based Event Listeners As of Spring 4.2, you can register an event listener on any public method of a managed -bean by using the `@EventListener` annotation. The `BlackListNotifier` can be rewritten as +bean by using the `@EventListener` annotation. The `BlockedListNotifier` can be rewritten as follows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java ---- - public class BlackListNotifier { + public class BlockedListNotifier { private String notificationAddress; @@ -10746,7 +10747,7 @@ follows: } @EventListener - public void processBlackListEvent(BlackListEvent event) { + public void processBlockedListEvent(BlockedListEvent event) { // notify appropriate parties via notificationAddress... } } @@ -10754,12 +10755,12 @@ follows: [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] .Kotlin ---- - class BlackListNotifier { + class BlockedListNotifier { lateinit var notificationAddress: String @EventListener - fun processBlackListEvent(event: BlackListEvent) { + fun processBlockedListEvent(event: BlockedListEvent) { // notify appropriate parties via notificationAddress... } } @@ -10802,7 +10803,7 @@ The following example shows how our notifier can be rewritten to be invoked only .Java ---- @EventListener(condition = "#blEvent.content == 'my-event'") - public void processBlackListEvent(BlackListEvent blEvent) { + public void processBlockedListEvent(BlockedListEvent blockedListEvent) { // notify appropriate parties via notificationAddress... } ---- @@ -10810,7 +10811,7 @@ The following example shows how our notifier can be rewritten to be invoked only .Kotlin ---- @EventListener(condition = "#blEvent.content == 'my-event'") - fun processBlackListEvent(blEvent: BlackListEvent) { + fun processBlockedListEvent(blockedListEvent: BlockedListEvent) { // notify appropriate parties via notificationAddress... } ---- @@ -10852,7 +10853,7 @@ method signature to return the event that should be published, as the following .Java ---- @EventListener - public ListUpdateEvent handleBlackListEvent(BlackListEvent event) { + public ListUpdateEvent handleBlockedListEvent(BlockedListEvent event) { // notify appropriate parties via notificationAddress and // then publish a ListUpdateEvent... } @@ -10861,7 +10862,7 @@ method signature to return the event that should be published, as the following .Kotlin ---- @EventListener - fun handleBlackListEvent(event: BlackListEvent): ListUpdateEvent { + fun handleBlockedListEvent(event: BlockedListEvent): ListUpdateEvent { // notify appropriate parties via notificationAddress and // then publish a ListUpdateEvent... } @@ -10870,7 +10871,7 @@ method signature to return the event that should be published, as the following NOTE: This feature is not supported for <>. -This new method publishes a new `ListUpdateEvent` for every `BlackListEvent` handled by the +This new method publishes a new `ListUpdateEvent` for every `BlockedListEvent` handled by the method above. If you need to publish several events, you can return a `Collection` of events instead. @@ -10887,8 +10888,8 @@ The following example shows how to do so: ---- @EventListener @Async - public void processBlackListEvent(BlackListEvent event) { - // BlackListEvent is processed in a separate thread + public void processBlockedListEvent(BlockedListEvent event) { + // BlockedListEvent is processed in a separate thread } ---- [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -10896,8 +10897,8 @@ The following example shows how to do so: ---- @EventListener @Async - fun processBlackListEvent(event: BlackListEvent) { - // BlackListEvent is processed in a separate thread + fun processBlockedListEvent(event: BlockedListEvent) { + // BlockedListEvent is processed in a separate thread } ---- @@ -10922,7 +10923,7 @@ annotation to the method declaration, as the following example shows: ---- @EventListener @Order(42) - public void processBlackListEvent(BlackListEvent event) { + public void processBlockedListEvent(BlockedListEvent event) { // notify appropriate parties via notificationAddress... } ---- @@ -10931,7 +10932,7 @@ annotation to the method declaration, as the following example shows: ---- @EventListener @Order(42) - fun processBlackListEvent(event: BlackListEvent) { + fun processBlockedListEvent(event: BlockedListEvent) { // notify appropriate parties via notificationAddress... } ----