net.sf.eBus.client.ERequestMonitor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of core Show documentation
The newest version!
//
// Copyright 2024 Charles W. Rapp
//
// 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 net.sf.eBus.client;

import net.sf.eBus.messages.EReplyMessage;
import net.sf.eBus.messages.ERequestMessage;


/**
 * Classes needing to monitor {@link EReplier} request processing
 * must implement this interface. A request monitor must:
 * 
 *   
 *     {@link ERequestMonitorFeed.Builder build} the request
 *     monitor feed,
 *   
 *   
 *     {@link ERequestMonitorFeed#monitor() monitor} for requests
 *     to and replies from local
 *     {@link EReplier repliers},
 *   
 *   
 *     {@link ERequestMonitorFeed#unmonitor() retract} monitoring
 *     when no longer necessary, and
 *   
 *   
 *     {@link ERequestMonitorFeed#close() close} feed when no
 *     longer needed.
 *   
 * 
 * 
 * {@code ERequestMonitor} supports three callbacks:
 * 
 * 
 *   
 *     {@code request(ERequestMessage, String)}: request message
 *     delivered to named replier. Because eBus maintains only
 *     weak references to eBus objects, the replier's name is
 *     passed to the request monitor and not the {@code EReplier}
 *     instance itself. Therefore, the developer is encouraged
 *     to give repliers unique, meaningful names.
 *   
 *   
 *     {@code reply(EReplyMessage, String)}: reply message sent
 *     from named replier.
 *   
 *   
 *     {@code cancel(ERequestMessage, String)}: request message
 *     is now canceled on named replier.
 *   
 * 
 * 
 * As mentioned previously, a request monitor can only monitor
 * requests posted to and replies from local {@code EReplier}
 * objects. Requests and replies with remote repliers cannot be
 * locally monitored.
 * 
 * 
 * Note: unlike the other four roles (publisher,
 * subscriber, requester, and replier) the request monitor is
 * not informed if requester and repliers for the configured
 * request message key are in place or not. That is because the
 * request monitor is not interacting with requesters
 * and repliers; instead the monitor is standing to the side and
 * watching the interaction between the two.
 * 
 *
 * @see ERequestMonitorFeed
 * @see EReplier
 * @see ERequestMessage
 *
 * @author Charles W. Rapp
 */

public interface ERequestMonitor
    extends EObject
{
//---------------------------------------------------------------
// Member methods.
//

    /**
     * An incoming request for given replier.
     * @param request inbound request message.
     * @param replier request delivered to replier with this
     * eBus object name.
     * @throws UnsupportedOperationException
     * if this method is not overridden or replaced by a lambda
     * expression.
     */
    default void request(ERequestMessage request,
                         String replier)
    {
        throw (
            new UnsupportedOperationException(
                "request callback not implemented"));
    } // end of request(ERequestMessage, String)

    /**
     * An outgoing reply from given replier.
     * @param reply outbound reply message.
     * @param replier reply send from replier with this eBus
     * object name.
     * @throws UnsupportedOperationException
     * if this method is not overridden or replaced by a lambda
     * expression.
     */
    default void reply(EReplyMessage reply,
                       String replier)
    {
        throw (
            new UnsupportedOperationException(
                "reply callback not implemented"));
    } // end of reply(EReplyMessage, String)

    /**
     * An existing request is being automatically canceled.
     * @param message canceled request.
     * @param replier eBus object name of replier handling this
     * request
     * @throws UnsupportedOperationException
     * if this method is not overridden or replaced by a lambda
     * expression.
     */
    default void cancel(ERequestMessage message,
                        String replier)
    {
        throw (
            new UnsupportedOperationException(
                "cancel callback not implemented"));
    } // end of cancel(ERequestMessage, String)
} // end of interface ERequestMonitor