com.thorstenmarx.modules.api.message.MessageBus Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of modules-api Show documentation

Modules is a tiny module framework for java.

There is a newer version: 2.8.0

/**
 * ModuleManager
 * Copyright (C) 2016  ThorstenMarx ([email protected])
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.thorstenmarx.modules.api.message;

/**
 * Generic message bus interface.
 * I assume that there can be several possible implementations with different approach to
 * message/threads handling.
 * @param 
 */
public interface MessageBus {

    /**
     * Subscribe consumer to the message bus using weak link.
     *
     * Subscribing same object twice should not affect how many times subscriber will
     * be called per one message.
     *
     * @param subscriber The object to subscribe to the message bus.
     */
    void subscribe(MessageHandler subscriber);

    /**
     * Removes the specified consumer from the message bus subscription list.
     * Once removed, the specified object will no longer receive messages posted to the
     * message bus.
     *
     * @param subscriber The object previous subscribed to the message bus.
     */
    void unsubscribe(MessageHandler subscriber);

    /**
     * Sends a message to the bus which will be propagated to the appropriate subscribers (handlers).
     *
     * There is no specification given as to how the messages will be delivered,
     * and should be determine in each implementation.
     *
     * @param message Message to publish
     */
    void publish(E message);

    /**
     * Indicates whether the bus has pending messages to publish. Since message
     * delivery can be asynchronous (on other threads), the method can be used to
     * start or stop certain actions based on all the messages having been published.
     * I.e. perhaps before an application closes, etc.
     *
     * @return True if messages are still being delivered.
     */
    boolean hasPendingMessages();

}