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