Listening for Registration Events

The messaging API supports listening for destination and message listener registration events. Here are some reasons to listen for these events:

Messages that interest you may be sent to the new destinations
Messaging at the destinations may require tuning
You may depend on a destination that’s been unregistered
Unregistrations free up resources that can reallocated

The example project demonstrates listening for these registration events. Start with running the example. Then examine the event listener implementations. Lastly, trigger the unregistration events.

Trigger the Events in an Example

These deploy a destination registration listener, a message listener registration listener, and classes that trigger the events they’re listening for.

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.55-ga55

Sign in to Liferay at http://localhost:8080. Use the email address [email protected] and the password test. When prompted, change the password to learn.

Then, follow these steps:

Download and unzip the example.

curl https://resources.learn.liferay.com/dxp/latest/en/building-applications/core-frameworks/message-bus/liferay-s3z9.zip -O

unzip liferay-s3z9.zip

Launch the Message Bus event listener by deploying the s3z9-able-impl module.
```
cd liferay-s3z9/s3z9-able-impl
```
```
../gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
```
note

This command is the same as copying the module JAR to /opt/liferay/osgi/modules on the Docker container.

Add a destination by deploying the s3z9-baker-impl module.

cd ../s3z9-baker-impl

../gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)

The Docker container console shows S3Z9AbleMessageBusEventListener’s response to the newly added destination.
```
[main][S3Z9AbleMessageBusEventListener:17] Destination added acme/s3z9_baker
```

Launch the destination event listener by deploying the s3z9-charlie-impl module.

cd ../s3z9-charlie-impl

../gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)

cd ../s3z9-dog-impl

../gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)

The Docker container console shows S3Z9CharlieDestinationEventListener’s response to the newly registered message listener.
```
[S3Z9CharlieDestinationEventListener:23] Registered message listener to acme/s3z9_baker
```

Here’s the module overview:

s3z9-able-impl’s MessageBusEventListener implementation listens for destination additions and removals.
s3z9-baker-impl’s messaging configurator class adds a destination; s3z9-able-impl’s MessageBusEventListener implementation receives the added destination notification and logs the event.
s3z9-charlie-impl’s DestinationEventListener implementation listens for message listeners registering to or unregistering from the destination.
s3z9-dog-impl’s MessageListener implementation registers to the destination; s3z9-charlie-impl’s DestinationEventListener implementation receives message listener registration notification and logs the event.

Examine the `MessageBusEventListener`

Message Bus notifies MessageBusEventListeners when Destinations are added or removed. Here’s the example MessageBusEventListener implementation:

@Component(service = MessageBusEventListener.class)
public class S3Z9AbleMessageBusEventListener
	implements MessageBusEventListener {

	@Override
	public void destinationAdded(Destination destination) {
		if (_log.isInfoEnabled()) {
			_log.info("Added destination " + destination.getName());
		}
	}

	@Override
	public void destinationRemoved(Destination destination) {
		if (_log.isInfoEnabled()) {
			_log.info("Removed destination " + destination.getName());
		}
	}

	private static final Log _log = LogFactoryUtil.getLog(
		S3Z9AbleMessageBusEventListener.class);

}

The @Component annotation and its service = MessageBusEventListener.class attribute signal the runtime framework to register S3Z9AbleMessageBusEventListener as a MessageBusEventListener. The implementation overrides MessageBusEventListener’s two methods:

destinationAdded(Destination destination) responds to the newly added Destination.
destinationRemoved(Destination destination) responds to the newly removed Destination.

S3Z9AbleMessageBusEventListener’s method implementations log the destination events.

Examine the `DestinationEventListener`

Message Bus notifies a DestinationEventListener when MessageListeners register to or unregister from the DestinationEventListener’s specified destination. Here’s the example DestinationEventListener implementation:

@Component(
	property = "destination.name=acme/s3z9_baker",
	service = DestinationEventListener.class
)
public class S3Z9CharlieDestinationEventListener
	implements DestinationEventListener {

	@Override
	public void messageListenerRegistered(
		String destinationName, MessageListener messageListener) {

		if (_log.isInfoEnabled()) {
			_log.info("Registered message listener to " + destinationName);
		}
	}

	@Override
	public void messageListenerUnregistered(
		String destinationName, MessageListener messageListener) {

		if (_log.isInfoEnabled()) {
			_log.info("Unregistered message listener from " + destinationName);
		}
	}

	private static final Log _log = LogFactoryUtil.getLog(
		S3Z9CharlieDestinationEventListener.class);

}

The @Component annotation’s property = "destination.name=acme/s3z9_baker" and service = MessageBusEventListener.class attributes signal the runtime framework to register S3Z9CharlieDestinationEventListener as a DestinationEventListener for the acme/s3z9_baker destination. The implementation overrides DestinationEventListener’s two methods:

messageListenerRegistered(String destinationName, MessageListener messageListener) responds to a new message listener registered to the destination.
messageListenerUnregistered(String destinationName, MessageListener messageListener) responds to a new message listener unregistered from the destination.

S3Z9CharlieDestinationEventListener’s method implementations log the message listener registration events.

Read on to see the example MessageBusEventListener and DestinationEventListener respond to a message bus listener unregistration and a destination removal.

Trigger the Other Events

You can unregister the example message listener and remove the example destination by stopping their modules. Remember that s3z9-dog-impl deployed the message listener and s3z9-able-impl deployed the destination. When you stop these modules, their classes unregister the message listener and destination, respectively.

Visit the Liferay instance with your browser at http://localhost:8080 and sign in using your credentials.
Open the Gogo shell.

List the example modules by entering this command in the Gogo shell command field:

lb | grep S3Z9

The start of each line includes the corresponding module’s ID number.

1839|Active     |   10|Acme S3Z9 Able Implementation (1.0.0)|1.0.0
1840|Active     |   10|Acme S3Z9 Baker Implementation (1.0.0)|1.0.0
1841|Active     |   10|Acme S3Z9 Charlie Implementation (1.0.0)|1.0.0
1842|Active     |   10|Acme S3Z9 Dog Implementation (1.0.0)|1.0.0

Stop the message listener’s module by entering the following Gogo shell command, replacing the number with your module’s ID:
```
stop 1842
```
Confirm the destination event listener’s logged response to the message listener unregistration.
```
[S3Z9CharlieDestinationEventListener:33] Unregistered message listener from acme/s3z9_baker
```
Stop the destination’s module by entering the following Gogo shell command, replacing the number with your module’s ID:
```
stop 1840
```

Congratulations! You’ve triggered all of the message bus event listener and destination event listener events.

What’s Next

Now that you know how to listen for these Message Bus events, you can listen for messages at new destinations or tune your messaging environment in response to new registration related activities.