Skip to content

Commit

Permalink
Replace "blacklist" with alternative words
Browse files Browse the repository at this point in the history 
See spring-projectsgh-25262
  • Loading branch information
@sbrannen
sbrannen authored and xcl(徐程林) committed Aug 16, 2020
1 parent 5bb02e3 commit 261bb62
Showing 1 changed file with 48 additions and 47 deletions.
95 changes: 48 additions & 47 deletions src/docs/asciidoc/core/core-beans.adoc
View file
Expand Up @@ -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;
Expand All @@ -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)
----
Expand All @@ -10594,20 +10594,20 @@ example shows such a class:
----
public class EmailService implements ApplicationEventPublisherAware {
private List<String> blackList;
private List<String> blockedList;
private ApplicationEventPublisher publisher;
public void setBlackList(List<String> blackList) {
this.blackList = blackList;
public void setBlockedList(List<String> blockedList) {
this.blockedList = blockedList;
}
public void setApplicationEventPublisher(ApplicationEventPublisher publisher) {
this.publisher = publisher;
}
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...
Expand All @@ -10619,20 +10619,20 @@ example shows such a class:
----
class EmailService : ApplicationEventPublisherAware {
private lateinit var blackList: List<String>
private lateinit var blockedList: List<String>
private lateinit var publisher: ApplicationEventPublisher
fun setBlackList(blackList: List<String>) {
this.blackList = blackList
fun setBlockedList(blockedList: List<String>) {
this.blockedList = blockedList
}
override fun setApplicationEventPublisher(publisher: ApplicationEventPublisher) {
this.publisher = publisher
}
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...
Expand All @@ -10653,41 +10653,42 @@ shows such a class:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
----
public class BlackListNotifier implements ApplicationListener<BlackListEvent> {
public class BlockedListNotifier implements ApplicationListener<BlockedListEvent> {
private String notificationAddress;
public void setNotificationAddress(String notificationAddress) {
this.notificationAddress = notificationAddress;
}
public void onApplicationEvent(BlackListEvent event) {
public void onApplicationEvent(BlockedListEvent event) {
// notify appropriate parties via notificationAddress...
}
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
class BlackListNotifier : ApplicationListener<BlackListEvent> {
class BlockedListNotifier : ApplicationListener<BlockedListEvent> {
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.
Expand All @@ -10698,7 +10699,7 @@ the classes above:
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="emailService" class="example.EmailService">
<property name="blackList">
<property name="blockedList">
<list>
<value>known.spammer@example.org</value>
<value>known.hacker@example.org</value>
Expand All @@ -10707,15 +10708,15 @@ the classes above:
</property>
</bean>
<bean id="blackListNotifier" class="example.BlackListNotifier">
<property name="notificationAddress" value="blacklist@example.org"/>
<bean id="blockedListNotifier" class="example.BlockedListNotifier">
<property name="notificationAddress" value="blockedlist@example.org"/>
</bean>
----

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
Expand All @@ -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;
Expand All @@ -10746,20 +10747,20 @@ follows:
}
@EventListener
public void processBlackListEvent(BlackListEvent event) {
public void processBlockedListEvent(BlockedListEvent event) {
// notify appropriate parties via notificationAddress...
}
}
----
[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...
}
}
Expand Down Expand Up @@ -10802,15 +10803,15 @@ 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...
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
@EventListener(condition = "#blEvent.content == 'my-event'")
fun processBlackListEvent(blEvent: BlackListEvent) {
fun processBlockedListEvent(blockedListEvent: BlockedListEvent) {
// notify appropriate parties via notificationAddress...
}
----
Expand Down Expand Up @@ -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...
}
Expand All @@ -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...
}
Expand All @@ -10870,7 +10871,7 @@ method signature to return the event that should be published, as the following
NOTE: This feature is not supported for
<<context-functionality-events-async, asynchronous listeners>>.

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.

Expand All @@ -10887,17 +10888,17 @@ 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"]
.Kotlin
----
@EventListener
@Async
fun processBlackListEvent(event: BlackListEvent) {
// BlackListEvent is processed in a separate thread
fun processBlockedListEvent(event: BlockedListEvent) {
// BlockedListEvent is processed in a separate thread
}
----

Expand All @@ -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...
}
----
Expand All @@ -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...
}
----
Expand Down

0 comments on commit 261bb62

Please sign in to comment.