All Downloads are FREE. Search and download functionalities are using the official Maven repository.

dorkbox.messageBus.IMessageBus Maven / Gradle / Ivy

/*
 * Copyright 2012 Benjamin Diedrichsen
 *
 * Permission is hereby granted, free  of charge, to any person obtaining
 * a  copy  of this  software  and  associated  documentation files  (the
 * "Software"), to  deal in  the Software without  restriction, including
 * without limitation  the rights to  use, copy, modify,  merge, publish,
 * distribute,  sublicense, and/or sell  copies of  the Software,  and to
 * permit persons to whom the Software  is furnished to do so, subject to
 * the following conditions:
 *
 * The  above  copyright  notice  and  this permission  notice  shall  be
 * included in all copies or substantial portions of the Software.
 *
 * THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
 * EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
 * MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 * OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 *
 * Copyright 2015 dorkbox, 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 dorkbox.messageBus;

import dorkbox.messageBus.error.IPublicationErrorHandler;

/**
 * A message bus offers facilities for publishing messages to the message handlers of registered listeners.
 * 

* * Because the message bus keeps track of classes that are subscribed and published, reloading the classloader means that you will need to * SHUTDOWN the messagebus when you unload the classloader, and then re-subscribe relevant classes when you reload the classes. *

* * Messages can be published synchronously or asynchronously and may be of any type that is a valid sub type of the type parameter T. * Message handlers can be invoked synchronously or asynchronously depending on their configuration. Thus, there * are two notions of synchronicity / asynchronicity. One on the caller side, e.g. the invocation of the message publishing * methods. The second on the handler side, e.g. whether the handler is invoked in the same or a different thread. * *

* Each message publication is isolated from all other running publications such that it does not interfere with them. * Hence, the bus generally expects message handlers to be stateless as it may invoke them concurrently if multiple * messages publish published asynchronously. If handlers are stateful and not thread-safe they can be marked to be invoked * in a synchronized fashion using @Synchronized annotation * *

* A listener is any object that defines at least one message handler and that has been subscribed to at least * one message bus. A message handler can be any method that accepts exactly one parameter (the message) and is marked * as a message handler using the @Handler annotation. * *

* By default, the bus uses weak references to all listeners such that registered listeners do not need to * be explicitly unregistered to be eligible for garbage collection. Dead (garbage collected) listeners are * removed on-the-fly as messages publish dispatched. This can be changed using the @Listener annotation. * *

* Generally message handlers will be invoked in inverse sequence of subscription but any * client using this bus should not rely on this assumption. The basic contract of the bus is that it will deliver * a specific message exactly once to each of the respective message handlers. * *

* Messages are dispatched to all listeners that accept the type or supertype of the dispatched message. Additionally * a message handler may define filters to narrow the set of messages that it accepts. * *

* Subscribed message handlers are available to all pending message publications that have not yet started processing. * Any message listener may only be subscribed once -> subsequent subscriptions of an already subscribed message listener * will be silently ignored) * *

* Removing a listener (unsubscribing) means removing all subscribed message handlers of that listener. This remove operation * immediately takes effect and on all running dispatch processes -> A removed listener (a listener * is considered removed after the remove(Object) call returned) will under no circumstances receive any message publications. * Any running message publication that has not yet delivered the message to the removed listener will not see the listener * after the remove operation completed. * *

* NOTE: Generic type parameters of messages will not be taken into account, e.g. a List will * publish dispatched to all message handlers that take an instance of List as their parameter * * @author bennidi * Date: 2/8/12 * @author dorkbox, llc * Date: 2/2/15 */ public interface IMessageBus extends PubSubSupport { enum DispatchMode { /** * Will only publish to listeners with this exact message signature. This is the fastest */ Exact, /** * Will publish to listeners with this exact message signature, as well as listeners that match the super class types signatures. */ ExactWithSuperTypes, } /** * Publication errors may occur at various points of time during message delivery. A handler may throw an exception, * may not be accessible due to security constraints or is not annotated properly. * In any of all possible cases a publication error is created and passed to each of the registered error handlers. * A call to this method will add the given error handler to the chain */ void addErrorHandler(IPublicationErrorHandler errorHandler); /** * Check whether any asynchronous message publications are pending to be processed * * @return true if any unfinished message publications are found */ boolean hasPendingMessages(); /** * Shutdown the bus such that it will stop delivering asynchronous messages. Executor service and * other internally used threads will be shutdown gracefully. *

* After calling shutdown it is not safe to further use the message bus. */ void shutdown(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy