/*
 * ICESOFT COMMERCIAL SOURCE CODE LICENSE V 1.1
 *
 * The contents of this file are subject to the ICEsoft Commercial Source
 * Code License Agreement V1.1 (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.icesoft.com/license/commercial-source-v1.1.html
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 * License for the specific language governing rights and limitations under
 * the License.
 *
 * Copyright 2009-2015 ICEsoft Technologies Canada, Corp. All Rights Reserved.
 */
package com.icesoft.net.messaging;

/**
 * <p>
 *   The MessageHandler interface defines message handlers that can be added to the MessageServiceClient.  The
 *   MessageServiceClient will pass on any Message that matches the MessageSelector to the MessageHandler in order for
 *   the Message to be handled.
 * </p>
 * <p>
 *   When the MessageHandler is added to a MessageServiceClient and delivery of incoming messages is started, the
 *   MessageSelector contained in this MessageHandler can be changed on-the-fly and is thus immediately effective for
 *   the next incoming message.
 * </p>
 *
 * @see        MessageServiceClient
 * @see        MessageSelector
 * @see        Message
 */
public interface MessageHandler {
    void addCallback(Callback callback);
    
    void addCallback(Callback callback, MessageSelector messageSelector);

    /**
     * <p>
     *   Gets the MessageSelector of this MessageHandler.
     * </p>
     *
     * @return     the MessageSelector
     *
     * @see        #setMessageSelector(MessageSelector)
     */
    MessageSelector getMessageSelector();

    /**
     * <p>
     *   Handles the specified <code>message</code>.
     * </p>
     *
     * @param      message
     *                 the message to be handled.
     */
    void handle(Message message);

    void removeCallback(Callback callback);

    /**
     * <p>
     *   Sets the MessageSelector of this MessageHandler to the specified <code>messageSelector</code>.
     * </p>
     *
     * @param      messageSelector
     *                 the new MessageSelector.
     *
     * @see        #getMessageSelector()
     */
    void setMessageSelector(MessageSelector messageSelector);

    public static interface Callback { /* marker interface */ }
}
