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