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

Go to download
//
// Copyright 2017 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;

/**
 * Provides a common view of single- and multi-key request feeds,
 * allowing such feeds to be referenced in a common way.
 *
 * @author Charles W. Rapp
 */

public interface IERequestFeed
    extends IEFeed
{
//---------------------------------------------------------------
// Member methods.
//

    /**
     * Puts the feed status callback in place.
     * @param cb the feed status update callback. May be
     * {@code null}.
     */
    void statusCallback(FeedStatusCallback cb);

    /**
     * Puts the reply message callback in place
     * for all reply types. If {@code cb} is
     * not {@code null}, replies will be passed to {@code cb}
     * rather than
     * {@link ERequestor#reply(int, EReplyMessage, ERequestFeed.ERequest)}.
     * A {@code null cb} results in replies posted to the
     * {@code ERequestor.reply(int, EReplyMessage, ERequestFeed.ERequest)}
     * override.
     * 
     * Note that this method call overrides all previous calls
     * to {@link #replyCallback(Class, ReplyCallback)}. If
     * the goal is to use a generic callback for all replies
     * except one specific message, then use this method to put
     * the generic callback in place first and then use
     * {@code replyCallback(EMessageKey, ReplyCallback)}.
     * 
     * @param cb reply message callback. May be {@code null}.
     * @throws IllegalStateException
     * if this feed is either closed or subscribed.
     *
     * @see #replyCallback(Class, ReplyCallback)
     */
    void replyCallback(final ReplyCallback cb);

    /**
     * Sets the callback for a specific reply message class. If
     * {@code cb} is not {@code null}, replies will be passed to
     * {@code cb} rather than
     * {@link ERequestor#reply(int, EReplyMessage, ERequestFeed.ERequest)}.
     * A {@code cb} results in replies posted to the
     * {@code ERequestor.reply(int, EReplyMessage, ERequestFeed.ERequest)}
     * override.
     * 
     * If the goal is to set a single callback method for all
     * reply message types, then use
     * {@link #replyCallback(ReplyCallback)}. Note that method
     * overrides all previous set reply callbacks.
     * 
     * @param mc the reply message class.
     * @param cb callback for the reply message.
     * @throws NullPointerException
     * if {@code mc} is {@code null}.
     * @throws IllegalArgumentException
     * if {@code mc} is not a reply for this request.
     * @throws IllegalStateException
     * if this feed is either closed or subscribed.
     */
    void replyCallback(final Class mc,
                       final ReplyCallback cb);

    /**
     * Activates this replier status subscription.
     */
    void subscribe();

    /**
     * De-activates this replier status subscription. Does
     * nothing if not currently subscribed.
     */
    void unsubscribe();
} // end of interface IERequestFeed