com.swirlds.common.notification.NotificationEngine Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of swirlds-common Show documentation
Show all versions of swirlds-common Show documentation
Swirlds is a software platform designed to build fully-distributed applications that harness the power of the cloud without servers. Now you can develop applications with fairness in decision making, speed, trust and reliability, at a fraction of the cost of traditional server-based platforms.
/*
* Copyright (C) 2016-2024 Hedera Hashgraph, LLC
*
* 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.
*/
package com.swirlds.common.notification;
import com.swirlds.common.notification.internal.AsyncNotificationEngine;
import com.swirlds.common.threading.futures.StandardFuture;
import com.swirlds.common.threading.manager.ThreadManager;
import java.util.concurrent.Future;
/**
* Provides a lightweight and extensible (event) notification engine supporting both synchronous and asynchronous event
* models along with unordered or ordered delivery of notifications.
*/
public interface NotificationEngine {
/**
* Build a new notification engine.
*
* @param threadManager
* the thread manager for this node
* @return a new notification engine
*/
static NotificationEngine buildEngine(final ThreadManager threadManager) {
return new AsyncNotificationEngine(threadManager);
}
/**
* Prepares the engine for use and acquires any necessary threads or external resources.
*/
void initialize();
/**
* Shuts down all underlying resources acquired during initialization and operation. This includes any threads or
* other external resources that must be explicitly released.
*/
void shutdown();
/**
* Dispatches a {@link Notification} instance to the listeners of the specified type.
*
* If the listener class uses {@link DispatchMode#SYNC} then this method will block until all registered listeners
* have been notified and the {@link Future} returned by this method will already be complete.
*
* However, If the listener class uses {@link DispatchMode#ASYNC} then this method will return immediately after the
* dispatch request has been given to the dispatcher. Only when the returned {@link Future} is resolved will all the
* registered listeners have been notified. Any exceptions thrown during listener notification will be provided by
* the {@link NotificationResult#getExceptions()} method.
*
* @param listenerClass
* the type of listener to which the given notification should be sent
* @param notification
* the notification to be sent to all registered listeners
* @param
* the type of the {@link Listener} class
* @param
* the type of the {@link Notification} class
* @return a {@link Future} that upon resolution provides the status of the dispatch request as {@link
* NotificationResult} instance
*/
default , N extends Notification> Future> dispatch(
final Class listenerClass, final N notification) {
return dispatch(listenerClass, notification, null);
}
/**
* Dispatches a {@link Notification} instance to the listeners of the specified type.
*
* If the listener class uses {@link DispatchMode#SYNC} then this method will block until all registered listeners
* have been notified and the {@link Future} returned by this method will already be complete.
*
* However, If the listener class uses {@link DispatchMode#ASYNC} then this method will return immediately after the
* dispatch request has been given to the dispatcher. Only when the returned {@link Future} is resolved will all the
* registered listeners have been notified. Any exceptions thrown during listener notification will be provided by
* the {@link NotificationResult#getExceptions()} method.
*
* @param listenerClass
* the type of listener to which the given notification should be sent
* @param notification
* the notification to be sent to all registered listeners
* @param
* the type of the {@link Listener} class
* @param
* the type of the {@link Notification} class
* @param notificationsCompletedCallback
* an optional callback that is invoked when the returned future
* is completed, ignored if null.
* @return a {@link Future} that upon resolution provides the status of the dispatch request as {@link
* NotificationResult} instance
*/
, N extends Notification> Future> dispatch(
final Class listenerClass,
final N notification,
final StandardFuture.CompletionCallback> notificationsCompletedCallback);
/**
* Registers a concrete {@link Listener} implementation with the underlying dispatcher.
*
* @param listenerClass
* the type of listener for which the concrete implementation should be registered
* @param callback
* the concrete listener implementation to be registered
* @param
* the type of the {@link Listener} class
* @return true if the listener was successfully registered with the dispatcher; otherwise false
*/
> boolean register(final Class listenerClass, final L callback);
/**
* Removes a concrete {@link Listener} implementation from the underlying dispatcher.
*
* @param listenerClass
* the type of listener for which the concrete implementation should be unregistered
* @param callback
* the concrete listener implementation to be unregistered
* @param
* the type of the {@link Listener} class
* @return true if the listener was successfully unregistered from the dispatcher; otherwise false
*/
> boolean unregister(final Class listenerClass, final L callback);
// FUTURE WORK this method can removed once the notification engine is managed by the PlatformContext
/**
*
* Unregister ALL listeners.
*
*
*
* DANGER: calling this method on a running system could have disastrous consequences.
* Think very carefully before calling this method.
*
*/
void unregisterAll();
}