Bukkit-API  1.7.9-R0.2
The inofficial Bukkit-API
Messenger.java
1 package org.bukkit.plugin.messaging;
2 
3 import java.util.Set;
4 import org.bukkit.entity.Player;
5 import org.bukkit.plugin.Plugin;
6 
7 /**
8  * A class responsible for managing the registrations of plugin channels and
9  * their listeners.
10  */
11 public interface Messenger {
12 
13  /**
14  * Represents the largest size that an individual Plugin Message may be.
15  */
16  public static final int MAX_MESSAGE_SIZE = 32766;
17 
18  /**
19  * Represents the largest size that a Plugin Channel may be.
20  */
21  public static final int MAX_CHANNEL_SIZE = 16;
22 
23  /**
24  * Checks if the specified channel is a reserved name.
25  *
26  * @param channel Channel name to check.
27  * @return True if the channel is reserved, otherwise false.
28  * @throws IllegalArgumentException Thrown if channel is null.
29  */
30  public boolean isReservedChannel(String channel);
31 
32  /**
33  * Registers the specific plugin to the requested outgoing plugin channel,
34  * allowing it to send messages through that channel to any clients.
35  *
36  * @param plugin Plugin that wishes to send messages through the channel.
37  * @param channel Channel to register.
38  * @throws IllegalArgumentException Thrown if plugin or channel is null.
39  */
40  public void registerOutgoingPluginChannel(Plugin plugin, String channel);
41 
42  /**
43  * Unregisters the specific plugin from the requested outgoing plugin
44  * channel, no longer allowing it to send messages through that channel to
45  * any clients.
46  *
47  * @param plugin Plugin that no longer wishes to send messages through the
48  * channel.
49  * @param channel Channel to unregister.
50  * @throws IllegalArgumentException Thrown if plugin or channel is null.
51  */
52  public void unregisterOutgoingPluginChannel(Plugin plugin, String channel);
53 
54  /**
55  * Unregisters the specific plugin from all outgoing plugin channels, no
56  * longer allowing it to send any plugin messages.
57  *
58  * @param plugin Plugin that no longer wishes to send plugin messages.
59  * @throws IllegalArgumentException Thrown if plugin is null.
60  */
61  public void unregisterOutgoingPluginChannel(Plugin plugin);
62 
63  /**
64  * Registers the specific plugin for listening on the requested incoming
65  * plugin channel, allowing it to act upon any plugin messages.
66  *
67  * @param plugin Plugin that wishes to register to this channel.
68  * @param channel Channel to register.
69  * @param listener Listener to receive messages on.
70  * @return The resulting registration that was made as a result of this
71  * method.
72  * @throws IllegalArgumentException Thrown if plugin, channel or listener
73  * is null, or the listener is already registered for this channel.
74  */
76 
77  /**
78  * Unregisters the specific plugin's listener from listening on the
79  * requested incoming plugin channel, no longer allowing it to act upon
80  * any plugin messages.
81  *
82  * @param plugin Plugin that wishes to unregister from this channel.
83  * @param channel Channel to unregister.
84  * @param listener Listener to stop receiving messages on.
85  * @throws IllegalArgumentException Thrown if plugin, channel or listener
86  * is null.
87  */
88  public void unregisterIncomingPluginChannel(Plugin plugin, String channel, PluginMessageListener listener);
89 
90  /**
91  * Unregisters the specific plugin from listening on the requested
92  * incoming plugin channel, no longer allowing it to act upon any plugin
93  * messages.
94  *
95  * @param plugin Plugin that wishes to unregister from this channel.
96  * @param channel Channel to unregister.
97  * @throws IllegalArgumentException Thrown if plugin or channel is null.
98  */
99  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 }
boolean isReservedChannel(String channel)
Set< PluginMessageListenerRegistration > getIncomingChannelRegistrations(Plugin plugin)
boolean isOutgoingChannelRegistered(Plugin plugin, String channel)
boolean isIncomingChannelRegistered(Plugin plugin, String channel)
PluginMessageListenerRegistration registerIncomingPluginChannel(Plugin plugin, String channel, PluginMessageListener listener)
void dispatchIncomingMessage(Player source, String channel, byte[] message)
void registerOutgoingPluginChannel(Plugin plugin, String channel)
boolean isRegistrationValid(PluginMessageListenerRegistration registration)
void unregisterIncomingPluginChannel(Plugin plugin, String channel, PluginMessageListener listener)
void unregisterOutgoingPluginChannel(Plugin plugin, String channel)