001 package org.bukkit.plugin.messaging;
002
003 import java.util.Set;
004 import org.bukkit.entity.Player;
005 import org.bukkit.plugin.Plugin;
006
007 /**
008 * A class responsible for managing the registrations of plugin channels and
009 * their listeners.
010 */
011 public interface Messenger {
012
013 /**
014 * Represents the largest size that an individual Plugin Message may be.
015 */
016 public static final int MAX_MESSAGE_SIZE = 32766;
017
018 /**
019 * Represents the largest size that a Plugin Channel may be.
020 */
021 public static final int MAX_CHANNEL_SIZE = 16;
022
023 /**
024 * Checks if the specified channel is a reserved name.
025 *
026 * @param channel Channel name to check.
027 * @return True if the channel is reserved, otherwise false.
028 * @throws IllegalArgumentException Thrown if channel is null.
029 */
030 public boolean isReservedChannel(String channel);
031
032 /**
033 * Registers the specific plugin to the requested outgoing plugin channel,
034 * allowing it to send messages through that channel to any clients.
035 *
036 * @param plugin Plugin that wishes to send messages through the channel.
037 * @param channel Channel to register.
038 * @throws IllegalArgumentException Thrown if plugin or channel is null.
039 */
040 public void registerOutgoingPluginChannel(Plugin plugin, String channel);
041
042 /**
043 * Unregisters the specific plugin from the requested outgoing plugin
044 * channel, no longer allowing it to send messages through that channel to
045 * any clients.
046 *
047 * @param plugin Plugin that no longer wishes to send messages through the
048 * channel.
049 * @param channel Channel to unregister.
050 * @throws IllegalArgumentException Thrown if plugin or channel is null.
051 */
052 public void unregisterOutgoingPluginChannel(Plugin plugin, String channel);
053
054 /**
055 * Unregisters the specific plugin from all outgoing plugin channels, no
056 * longer allowing it to send any plugin messages.
057 *
058 * @param plugin Plugin that no longer wishes to send plugin messages.
059 * @throws IllegalArgumentException Thrown if plugin is null.
060 */
061 public void unregisterOutgoingPluginChannel(Plugin plugin);
062
063 /**
064 * Registers the specific plugin for listening on the requested incoming
065 * plugin channel, allowing it to act upon any plugin messages.
066 *
067 * @param plugin Plugin that wishes to register to this channel.
068 * @param channel Channel to register.
069 * @param listener Listener to receive messages on.
070 * @return The resulting registration that was made as a result of this
071 * method.
072 * @throws IllegalArgumentException Thrown if plugin, channel or listener
073 * is null, or the listener is already registered for this channel.
074 */
075 public PluginMessageListenerRegistration registerIncomingPluginChannel(Plugin plugin, String channel, PluginMessageListener listener);
076
077 /**
078 * Unregisters the specific plugin's listener from listening on the
079 * requested incoming plugin channel, no longer allowing it to act upon
080 * any plugin messages.
081 *
082 * @param plugin Plugin that wishes to unregister from this channel.
083 * @param channel Channel to unregister.
084 * @param listener Listener to stop receiving messages on.
085 * @throws IllegalArgumentException Thrown if plugin, channel or listener
086 * is null.
087 */
088 public void unregisterIncomingPluginChannel(Plugin plugin, String channel, PluginMessageListener listener);
089
090 /**
091 * Unregisters the specific plugin from listening on the requested
092 * incoming plugin channel, no longer allowing it to act upon any plugin
093 * messages.
094 *
095 * @param plugin Plugin that wishes to unregister from this channel.
096 * @param channel Channel to unregister.
097 * @throws IllegalArgumentException Thrown if plugin or channel is null.
098 */
099 public void unregisterIncomingPluginChannel(Plugin plugin, String channel);
100
101 /**
102 * Unregisters the specific plugin from listening on all plugin channels
103 * through all listeners.
104 *
105 * @param plugin Plugin that wishes to unregister from this channel.
106 * @throws IllegalArgumentException Thrown if plugin is null.
107 */
108 public void unregisterIncomingPluginChannel(Plugin plugin);
109
110 /**
111 * Gets a set containing all the outgoing plugin channels.
112 *
113 * @return List of all registered outgoing plugin channels.
114 */
115 public Set<String> getOutgoingChannels();
116
117 /**
118 * Gets a set containing all the outgoing plugin channels that the
119 * specified plugin is registered to.
120 *
121 * @param plugin Plugin to retrieve channels for.
122 * @return List of all registered outgoing plugin channels that a plugin
123 * is registered to.
124 * @throws IllegalArgumentException Thrown if plugin is null.
125 */
126 public Set<String> getOutgoingChannels(Plugin plugin);
127
128 /**
129 * Gets a set containing all the incoming plugin channels.
130 *
131 * @return List of all registered incoming plugin channels.
132 */
133 public Set<String> getIncomingChannels();
134
135 /**
136 * Gets a set containing all the incoming plugin channels that the
137 * specified plugin is registered for.
138 *
139 * @param plugin Plugin to retrieve channels for.
140 * @return List of all registered incoming plugin channels that the plugin
141 * is registered for.
142 * @throws IllegalArgumentException Thrown if plugin is null.
143 */
144 public Set<String> getIncomingChannels(Plugin plugin);
145
146 /**
147 * Gets a set containing all the incoming plugin channel registrations
148 * that the specified plugin has.
149 *
150 * @param plugin Plugin to retrieve registrations for.
151 * @return List of all registrations that the plugin has.
152 * @throws IllegalArgumentException Thrown if plugin is null.
153 */
154 public Set<PluginMessageListenerRegistration> getIncomingChannelRegistrations(Plugin plugin);
155
156 /**
157 * Gets a set containing all the incoming plugin channel registrations
158 * that are on the requested channel.
159 *
160 * @param channel Channel to retrieve registrations for.
161 * @return List of all registrations that are on the channel.
162 * @throws IllegalArgumentException Thrown if channel is null.
163 */
164 public Set<PluginMessageListenerRegistration> getIncomingChannelRegistrations(String channel);
165
166 /**
167 * Gets a set containing all the incoming plugin channel registrations
168 * that the specified plugin has on the requested channel.
169 *
170 * @param plugin Plugin to retrieve registrations for.
171 * @param channel Channel to filter registrations by.
172 * @return List of all registrations that the plugin has.
173 * @throws IllegalArgumentException Thrown if plugin or channel is null.
174 */
175 public Set<PluginMessageListenerRegistration> getIncomingChannelRegistrations(Plugin plugin, String channel);
176
177 /**
178 * Checks if the specified plugin message listener registration is valid.
179 * <p>
180 * A registration is considered valid if it has not be unregistered and
181 * that the plugin is still enabled.
182 *
183 * @param registration Registration to check.
184 * @return True if the registration is valid, otherwise false.
185 */
186 public boolean isRegistrationValid(PluginMessageListenerRegistration registration);
187
188 /**
189 * Checks if the specified plugin has registered to receive incoming
190 * messages through the requested channel.
191 *
192 * @param plugin Plugin to check registration for.
193 * @param channel Channel to test for.
194 * @return True if the channel is registered, else false.
195 */
196 public boolean isIncomingChannelRegistered(Plugin plugin, String channel);
197
198 /**
199 * Checks if the specified plugin has registered to send outgoing messages
200 * through the requested channel.
201 *
202 * @param plugin Plugin to check registration for.
203 * @param channel Channel to test for.
204 * @return True if the channel is registered, else false.
205 */
206 public boolean isOutgoingChannelRegistered(Plugin plugin, String channel);
207
208 /**
209 * Dispatches the specified incoming message to any registered listeners.
210 *
211 * @param source Source of the message.
212 * @param channel Channel that the message was sent by.
213 * @param message Raw payload of the message.
214 */
215 public void dispatchIncomingMessage(Player source, String channel, byte[] message);
216 }