1 /*
2 * *************************************************************************************************************************************************************
3 *
4 * TheseFoolishThings: Miscellaneous utilities
5 * http://tidalwave.it/projects/thesefoolishthings
6 *
7 * Copyright (C) 2009 - 2025 by Tidalwave s.a.s. (http://tidalwave.it)
8 *
9 * *************************************************************************************************************************************************************
10 *
11 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * 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
17 * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
18 *
19 * *************************************************************************************************************************************************************
20 *
21 * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
22 * git clone https://github.com/tidalwave-it/thesefoolishthings-src
23 *
24 * *************************************************************************************************************************************************************
25 */
26 package it.tidalwave.messagebus;
27
28 import javax.annotation.Nonnull;
29
30 /***************************************************************************************************************************************************************
31 *
32 * A simple message bus for a local publish/subscribe facility.
33 *
34 * @author Fabrizio Giudici
35 *
36 **************************************************************************************************************************************************************/
37 public interface MessageBus
38 {
39 /***********************************************************************************************************************************************************
40 * A listener to receive notifications from a {@link MessageBus}.
41 *
42 * @stereotype Listener
43 **********************************************************************************************************************************************************/
44 public static interface Listener<T>
45 {
46 /***************************************************************************************************************
47 *
48 * Notifies the reception of the given message.
49 *
50 * @param message the event
51 *
52 **************************************************************************************************************/
53 public void notify (@Nonnull T message);
54 }
55
56 /***********************************************************************************************************************************************************
57 * Publishes the given event. The topic is the class of the event.
58 *
59 * @param <T> the static type of the topic
60 * @param message the event
61 **********************************************************************************************************************************************************/
62 public <T> void publish (@Nonnull T message);
63
64 /***********************************************************************************************************************************************************
65 * Publishes the given message and topic. Passing an explicit topic can be useful when dealing with a hierarchy of
66 * events (so, perhaps a subclass is passed but the topic is the root of the hierarchy).
67 *
68 * @param <T> the static type of the topic
69 * @param topic the topic
70 * @param message the message
71 **********************************************************************************************************************************************************/
72 public <T> void publish (@Nonnull Class<T> topic, @Nonnull T message);
73
74 /***********************************************************************************************************************************************************
75 * Subscribes a {@link Listener} to a topic.
76 *
77 * @param <T> the static type of the topic
78 * @param topic the topic
79 * @param listener the listener
80 **********************************************************************************************************************************************************/
81 public <T> void subscribe (@Nonnull Class<T> topic, @Nonnull Listener<T> listener);
82
83 /***********************************************************************************************************************************************************
84 * Unsubscribes a {@link Listener}.
85 *
86 * @param listener the listener
87 **********************************************************************************************************************************************************/
88 public void unsubscribe (@Nonnull Listener<?> listener);
89 }