MessageBusHelper.java
/*
* *************************************************************************************************************************************************************
*
* TheseFoolishThings: Miscellaneous utilities
* http://tidalwave.it/projects/thesefoolishthings
*
* Copyright (C) 2009 - 2026 by Tidalwave s.a.s. (http://tidalwave.it)
*
* *************************************************************************************************************************************************************
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
* CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
*
* *************************************************************************************************************************************************************
*
* git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
* git clone https://github.com/tidalwave-it/thesefoolishthings-src
*
* *************************************************************************************************************************************************************
*/
package it.tidalwave.messagebus;
import java.lang.reflect.Method;
import jakarta.annotation.Nonnull;
import java.util.ArrayList;
import java.util.List;
import it.tidalwave.messagebus.annotation.ListensTo;
import it.tidalwave.messagebus.annotation.SimpleMessageSubscriber;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import static it.tidalwave.messagebus.spi.ReflectionUtils.*;
import static it.tidalwave.messagebus.spi.ReflectionUtils.MethodProcessor.FilterResult.*;
/***************************************************************************************************************************************************************
* A helper for objects that receive messages by means of listener methods: methods with a single parameter annotated with {@link ListensTo}. It finds such
* methods in the classes of the hierarchy of the owner object that are annotated with {@link SimpleMessageSubscriber}, and subscribes or unsubscribes all of
* them at once.
* {@code MessageBusHelper} doesn't depend on a specific message bus: the actual subscription is performed by means of an {@link Adapter}.
* @author Fabrizio Giudici
**************************************************************************************************************************************************************/
@RequiredArgsConstructor @Slf4j
public class MessageBusHelper
{
/***********************************************************************************************************************************************************
* An adapter between {@link MessageBusHelper} and a specific message bus.
**********************************************************************************************************************************************************/
public static interface Adapter
{
/*******************************************************************************************************************************************************
* Creates a {@link MethodAdapter} that delivers the messages of the given topic to the given method of the given object.
* @param <T> the static type of the topic
* @param object the object that owns the method
* @param method the listener method
* @param topic the topic
* @return the {@code MethodAdapter}
******************************************************************************************************************************************************/
@Nonnull
public <T> MethodAdapter<T> createMethodAdapter (@Nonnull Object object,
@Nonnull Method method,
@Nonnull Class<T> topic);
/*******************************************************************************************************************************************************
* Publishes a message. The topic is the class of the message.
* @param message the message
******************************************************************************************************************************************************/
public void publish (@Nonnull Object message);
/*******************************************************************************************************************************************************
* Publishes a message with an explicit topic.
* @param <T> the static type of the topic
* @param topic the topic
* @param message the message
******************************************************************************************************************************************************/
public <T> void publish (Class<T> topic, @Nonnull T message);
}
/***********************************************************************************************************************************************************
* The binding of a listener method to a message bus, which can subscribe and unsubscribe it.
* @param <T> the static type of the topic
**********************************************************************************************************************************************************/
public static interface MethodAdapter<T>
{
/*******************************************************************************************************************************************************
* Subscribes the listener method to the message bus.
******************************************************************************************************************************************************/
public void subscribe();
/*******************************************************************************************************************************************************
* Unsubscribes the listener method from the message bus.
******************************************************************************************************************************************************/
public void unsubscribe();
}
/** The object whose listener methods are subscribed. */
@Nonnull
private final Object owner;
/** The adapter to the message bus. */
@Nonnull
private final Adapter methodAdapterFactory;
private final List<MethodAdapter<?>> methodAdapters = new ArrayList<>();
/***********************************************************************************************************************************************************
* Subscribes all the listener methods of the owner object: the methods with a single parameter annotated with {@link ListensTo}, declared in the classes of
* the hierarchy of the owner that are annotated with {@link SimpleMessageSubscriber}. Methods declared in classes that are not annotated are ignored.
**********************************************************************************************************************************************************/
public void subscribeAll()
{
forEachMethodInTopDownHierarchy(owner, new MethodProcessor()
{
@Override @Nonnull
public FilterResult filter (@Nonnull final Class<?> clazz)
{
return clazz.getAnnotation(SimpleMessageSubscriber.class) != null ? ACCEPT : IGNORE;
}
@Override
public void process (@Nonnull final Method method)
{
final var parameterAnnotations = method.getParameterAnnotations();
if ((parameterAnnotations.length == 1) && containsAnnotation(parameterAnnotations[0], ListensTo.class))
{
registerMessageListener(method);
}
}
});
}
/***********************************************************************************************************************************************************
* Unsubscribes all the listener methods subscribed by {@link #subscribeAll()}.
**********************************************************************************************************************************************************/
public void unsubscribeAll()
{
for (final var methodAdapter : methodAdapters)
{
methodAdapter.unsubscribe();
}
}
/***********************************************************************************************************************************************************
* Publishes a message. The topic is the class of the message.
* @param message the message to deliver
**********************************************************************************************************************************************************/
public void publish (@Nonnull final Object message)
{
methodAdapterFactory.publish(message);
}
/***********************************************************************************************************************************************************
* Publishes a message with an explicit topic.
* @param <T> the static type of the topic
* @param topicType the topic
* @param topic the message to deliver
**********************************************************************************************************************************************************/
public <T> void publish (@Nonnull final Class<T> topicType, @Nonnull final T topic)
{
methodAdapterFactory.publish(topicType, topic);
}
/***********************************************************************************************************************************************************
* Subscribes a listener method: it creates a {@link MethodAdapter} by means of the {@link Adapter}, keeps it so it can be unsubscribed later, and
* subscribes it. The topic is the type of the single parameter of the method.
* @param <T> the static type of the topic
* @param method the listener method
**********************************************************************************************************************************************************/
private <T> void registerMessageListener (@Nonnull final Method method)
{
log.trace("registerMessageListener({})", method);
final var topic = (Class<T>)method.getParameterTypes()[0];
final var methodAdapter = methodAdapterFactory.createMethodAdapter(owner, method, topic);
methodAdapters.add(methodAdapter);
methodAdapter.subscribe();
}
}