1   // ========================================================================
2   // Copyright 2007 Dojo Foundation
3   // ------------------------------------------------------------------------
4   // Licensed under the Apache License, Version 2.0 (the "License");
5   // you may not use this file except in compliance with the License.
6   // You may obtain a copy of the License at 
7   // http://www.apache.org/licenses/LICENSE-2.0
8   // Unless required by applicable law or agreed to in writing, software
9   // distributed under the License is distributed on an "AS IS" BASIS,
10  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11  // See the License for the specific language governing permissions and
12  // limitations under the License.
13  // ========================================================================
14  
15  package dojox.cometd;
16  
17  import java.util.EventListener;
18  
19  /**
20   * Message Listener Interface.
21   * 
22   * Objects implementing this interface may listen for message deliverly events
23   * by calling the {@link Client#addListener(EventListener)}.  The {@link Synchronous}
24   * or {@link Asynchronous} nested interfaces may be used as a mixin to specify the style 
25   * of delivery required.  If neither subtype is specified, then the {@link Bayeux} 
26   * implementation may use either method.
27   * 
28   * @author gregw
29   *
30   */
31  public interface MessageListener extends EventListener
32  {
33      /**
34       * Called when a message is delivered to the client
35       * @param msg TODO
36       */
37      public void deliver(Client fromClient, Client toClient, Message msg);
38      
39      /**
40       * Subtype of MessageListener that requires synchronous message delivery.
41       * The {@link Client} object is locked during the call to 
42       * {@link MessageListener#deliver(Client, Client, Message)}, thus 
43       * guaranteeing that only a single message will be delivered at once and 
44       * in order of receipt.
45       *
46       */
47      public interface Synchronous {};
48      
49      /** 
50       * subtype of MesssageListener that requires asynchronous message delivery.
51       * Calls to {@link MessageListener#deliver(Client, Client, Message)} may occur
52       * in parallel and possible out of order.
53       * 
54       */
55      public interface Asynchronous {};
56  }