View Javadoc

1   /*
2    * Copyright (c) 1998-2002 The Jgroup Team.
3    *
4    * This program is free software; you can redistribute it and/or modify
5    * it under the terms of the GNU Lesser General Public License version 2 as
6    * published by the Free Software Foundation.
7    *
8    * This program is distributed in the hope that it will be useful,
9    * but WITHOUT ANY WARRANTY; without even the implied warranty of
10   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11   * GNU Lesser General Public License for more details.
12   *
13   * You should have received a copy of the GNU Lesser General Public License
14   * along with this program; if not, write to the Free Software
15   * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
16   *
17   */
18  
19  package jgroup.core.multicast;
20  
21  import java.io.IOException;
22  import java.io.OutputStream;
23  
24  import jgroup.core.JgroupException;
25  import jgroup.core.Layer;
26  
27  
28  /**
29   *  The facilities provided by the reliable multicast service included
30   *  in Jgroup may be accessed using the <code>MulticastService</code>
31   *  interface.  Methods in this interfaces enable members of a group to
32   *  communicate among themselves by multicasting messages or complex
33   *  objects. <p>
34   *
35   *  Instances of <code>MulticastService</code> may be obtained through
36   *  the <code>GroupManager</code> class.
37   *
38   *  @author Alberto Montresor
39   *  @author Hein Meling
40   *  @since Jgroup 0.8
41   */
42  public interface MulticastService
43    extends Layer
44  {
45  
46    /**
47     *  Multicast a message enclosed in the stream <code>out</code> to the
48     *  members of the current view of the group. <p>
49     *
50     *  The invoker may specify an <code>AckListener</code> object, which
51     *  will be notified when objects returned by members delivering this
52     *  message, are received.
53     *
54     *  @param out
55     *    The stream message to be multicast.
56     *  @param ackl
57     *    Acknowledgement listener to be notified; if null, no listener
58     *    will be notified.
59     *  @param chainId
60     *    Identifier of a previous message (delivered through a 
61     *    {@link jgroup.core.multicast.MulticastListener#deliverStream(java.io.InputStream, jgroup.core.MemberId, int) deliverStream}).
62     *    This is only required for multicast messages
63     *    that relate to some previous multicast message.  It will only
64     *    be used in extremely rare cases, to avoid that the membership service
65     *    delays the message while running the agreement protocol, which would
66     *    otherwise prevent the agreement protocol from concluding.
67     *
68     *  @exception UnsupportedOperationException
69     *    Raised if the member associated with this group manager is not a
70     *    <code>MulticastListener</code>, and thus is unable to receive messages.
71     *  @exception JgroupException
72     *    Rasied if the group manager receives a request to multicast a
73     *    message after having joined a group, but before having received
74     *    the first view for it; or after having requested to leave the group.
75     */
76    public void mcast(OutputStream out, AckListener ackl, ChainIdentifier chainId)
77      throws JgroupException;
78  
79    /**
80     *  Multicast a message enclosed in the stream <code>out</code> to the
81     *  members of the current view of the group. <p>
82     *
83     *  The invoker may specify an <code>AckListener</code> object, which
84     *  will be notified when objects returned by members delivering this
85     *  message, are received.
86     *
87     *  @param out
88     *    The stream message to be multicast.
89     *  @param ackl
90     *    Acknowledgement listener to be notified; if null, no listener
91     *    will be notified.
92     *
93     *  @exception UnsupportedOperationException
94     *    Raised if the member associated with this group manager is not a
95     *    <code>MulticastListener</code>, and thus is unable to receive messages.
96     *  @exception JgroupException
97     *    Rasied if the group manager receives a request to multicast a
98     *    message after having joined a group, but before having received
99     *    the first view for it; or after having requested to leave the group.
100    */
101   public void mcast(OutputStream out, AckListener ackl)
102     throws JgroupException;
103 
104 
105   /**
106    *  Multicast a serializable object to the members of the current view
107    *  of a group. <p>
108    *
109    *  The invoker may specify an <code>AckListener</code> object, which
110    *  will be notified when objects returned by members delivering this
111    *  message are received.
112    *
113    *  @param protocol
114    *    The protocol for the message object to be multicast.
115    *  @param obj
116    *    The message object to be multicast.
117    *  @param ackl
118    *    Acknowledgement listener to be notified; if null, no listener
119    *    will be notified.
120    *
121    *  @exception UnsupportedOperationException
122    *    Raised if the member associated with this group manager is not a
123    *    <code>MulticastListener</code>, and thus is unable to receive messages.
124    *  @exception JgroupException
125    *    Rasied if the group manager receives a request to multicast a
126    *    message after having joined a group, but before having received
127    *    the first view for it; or after having requested to leave the group.
128    *  @exception IOException
129    *    Raised if the object to be multicast could not be serialized.
130    */
131   public void mcast(String protocol, Object obj, AckListener ackl)
132     throws JgroupException, IOException;
133 
134 
135   /**
136    *  Returns an output stream to be used to encode a message.  Method
137    *  <code>mcast(OutputStream, AckListener)</code> accepts only
138    *  multicast messages obtained through this method.  The provided output
139    *  stream is a memory data structure optimized to avoid useless data
140    *  copies.
141    *
142    *  @param protocol
143    *     The protocol name used for the <code>OutputStream</code> message
144    *     object to be multicast.
145    */
146   public OutputStream getMessage(String protocol)
147     throws IOException;
148 
149 } // END MulticastService