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    }