diff --git a/spring-framework-reference/src/beans.xml b/spring-framework-reference/src/beans.xml
index 67f2e9867bf552900520e8c89b3f44541a914943..5d553f118ccfc355c175878ef63c109fb1f6716c 100644
--- a/spring-framework-reference/src/beans.xml
+++ b/spring-framework-reference/src/beans.xml
@@ -7048,86 +7048,122 @@ argument.required=Ebagum lad, the '{0}' argument is required, I say, required.
- You can also implement custom events. Simply call the
- publishEvent() method on the
- ApplicationContext, specifying a
- parameter that is an instance of your custom event class that implements
- ApplicationEvent. Event listeners receive events
- synchronously. This means the publishEvent()
- method blocks until all listeners have finished processing the event.
- (It is possible to supply an alternate event publishing strategy through
- an ApplicationEventMulticaster
- implementation). Furthermore, when a listener receives an event, it
- operates inside the transaction context of the publisher, if a
- transaction context is available.
-
- This example shows the bean definitions used to configure an
- ApplicationContext:
-
- <bean id="emailer" class="example.EmailBean">
- <property name="blackList">
- <list>
- <value>black@list.org</value>
- <value>white@list.org</value>
- <value>john@doe.org</value>
- </list>
- </property>
-</bean>
+ You can also create and publish your own custom events. This example
+ demonstrates a simple class that extends Spring's
+ ApplicationEvent base class:
+
+ public class BlackListEvent extends ApplicationEvent {
+ private final String address;
+ private final String test;
+
+ public BlackListEvent(Object source, String address, String test) {
+ super(source);
+ this.address = address;
+ this.test = test;
+ }
-<bean id="blackListListener" class="example.BlackListNotifier">
- <property name="notificationAddress" value="spam@list.org"/>
-</bean>
+ // accessor and other methods...
+}
- This example shows the implementation of the classes refered to in
- the previous bean definitions:
+ To publish a custom ApplicationEvent, call
+ the publishEvent() method on an
+ ApplicationEventPublisher. Typically this
+ is done by creating a class that implements
+ ApplicationEventPublisherAware and
+ registering it as a Spring bean. The following example demonstrates such a
+ class:
- public class EmailBean implements ApplicationContextAware {
+ blackList;
+ private ApplicationEventPublisher publisher;
- public void setBlackList(List blackList) {
+ public void setBlackList(List blackList) {
this.blackList = blackList;
}
- public void setApplicationContext(ApplicationContext ctx) {
- this.ctx = ctx;
+ public void setApplicationEventPublisher(ApplicationEventPublisher publisher) {
+ this.publisher = publisher;
}
public void sendEmail(String address, String text) {
if (blackList.contains(address)) {
- BlackListEvent event = new BlackListEvent(address, text);
- ctx.publishEvent(event);
+ BlackListEvent event = new BlackListEvent(this, address, text);
+ publisher.publishEvent(event);
return;
}
- // send email...
+ ]]>// send email...
+}]]>
- public class BlackListNotifier implements ApplicationListener {
+ At configuration time, the Spring container will detect that
+ EmailService implements
+ ApplicationEventPublisherAware and will
+ automatically call
+ setApplicationEventPublisher(). In reality, the
+ parameter passed in will be the Spring container itself; you're simply
+ interacting with the application context via its
+ ApplicationEventPublisher
+ interface.
+
+ To receive the custom ApplicationEvent,
+ create a class that implements
+ ApplicationListener and register it as a
+ Spring bean. The following example demonstrates such a class:
+
+ {
private String notificationAddress;
-
+
public void setNotificationAddress(String notificationAddress) {
this.notificationAddress = notificationAddress;
}
- public void onApplicationEvent(ApplicationEvent event) {
- if (event instanceof BlackListEvent) {
- // notify appropriate person...
- }
+ public void onApplicationEvent(BlackListEvent event) {
+]]> // notify appropriate parties via notificationAddress...
-
-
-
- When the sendEmail method is called, if there are any emails that
- should be blacklisted, a custom event of the type BlackListEvent is
- published to the application context. The BlackListNotifier class which
- implements the interface ApplicationListener is registered as a
- subscriber to the application context and will receive the
- BlackListEvent. In order to access properties specific to
- BlackListEvent, the listener must perform a downcast.
+}]]>
+
+ Notice that ApplicationListener is
+ generically parameterized with the type of your custom event,
+ BlackListEvent. This means that the
+ onApplicationEvent() method can remain
+ type-safe, avoiding any need for downcasting. You may register as many
+ event listeners as you wish, but note that by default event listeners
+ receive events synchronously. This means 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, refer to the JavaDoc for Spring's
+ ApplicationEventMulticaster
+ interface.
+
+ The following example demonstrates the bean definitions used to
+ register and configure each of the classes above:
+
+
+
+ black@list.org
+ white@list.org
+ john@doe.org
+
+
+
+
+
+
+]]>
+
+ Putting it all together, when the sendEmail()
+ method of the emailService bean is called, if there
+ are any emails that should be blacklisted, a custom event of type
+ BlackListEvent is published. The
+ blackListNotifier bean is registered as an
+ ApplicationListener and thus receives the
+ BlackListEvent, at which point it can notify
+ appropriate parties.