org.spongepowered.api.network

Interface ChannelRegistrar

public interface ChannelRegistrar

A registrar handling custom payloads via ChannelBindings to and from PlayerConnections and the server.

Method Summary

Modifier and Type	Method and Description
ChannelBinding.IndexedMessageChannel	createChannel(Object plugin, String channel) Creates a new channel binding for the given channel name.
ChannelBinding.RawDataChannel	createRawChannel(Object plugin, String channel) Creates a new raw channel binding.
Optional<ChannelBinding>	getChannel(String channel) Gets a channel binding if a channel registered by that name exists.
default ChannelBinding.IndexedMessageChannel	getOrCreate(Object plugin, String channel) Gets or creates a ChannelBinding.IndexedMessageChannel by the given name.
default ChannelBinding.RawDataChannel	getOrCreateRaw(Object plugin, String channel) Gets or creates a ChannelBinding.RawDataChannel by the given name.
Set<String>	getRegisteredChannels(Platform.Type side) Gets the set of registered channels.
boolean	isChannelAvailable(String channelName) Returns whether the given channel name is available for creating with createChannel(java.lang.Object, java.lang.String).
void	unbindChannel(ChannelBinding channel) Remove the channel binding from this registrar, freeing up the channel name.

Method Detail

createChannel

ChannelBinding.IndexedMessageChannel createChannel(Object plugin,
                                                   String channel)
                                            throws ChannelRegistrationException

Creates a new channel binding for the given channel name. The channel can be used to send and receive messages.

Parameters:

plugin - The plugin registering the channel

channel - The channel to register

Returns:

A new ChannelBinding instance bound to the channel name

Throws:

ChannelRegistrationException - The channel name is too long

ChannelRegistrationException - The channel name is reserved

createRawChannel

ChannelBinding.RawDataChannel createRawChannel(Object plugin,
                                               String channel)
                                        throws ChannelRegistrationException

Creates a new raw channel binding. The channel can be used to send and Receive data from ChannelBuf objects.

Parameters:

plugin - The plugin registering the channel

channel - The channel to register

Returns:

A new ChannelBinding instance bound to the channel name

Throws:

ChannelRegistrationException - The channel name is too long

ChannelRegistrationException - The channel name is reserved

See Also:

createChannel(java.lang.Object, java.lang.String)

getChannel

Optional<ChannelBinding> getChannel(String channel)

Gets a channel binding if a channel registered by that name exists.

Parameters:

channel - The name of the channel

Returns:

The channel if it exists

getOrCreate

default ChannelBinding.IndexedMessageChannel getOrCreate(Object plugin,
                                                         String channel)
                                                  throws ChannelRegistrationException

Gets or creates a ChannelBinding.IndexedMessageChannel by the given name. If the channel exists and is a indexed message channel, then it is returned. If the channel is not an indexed message channel, then IllegalStateException is thrown. Otherwise, a new channel is created.

Parameters:

plugin - The plugin to register the channel if it doesn't exist

channel - The channel name

Returns:

A new or existing indexed message channel binding

Throws:

IllegalStateException - if the existing channel is not an IndexedMessageChannel

ChannelRegistrationException - for same reasons as createChannel(java.lang.Object, java.lang.String).

getOrCreateRaw

default ChannelBinding.RawDataChannel getOrCreateRaw(Object plugin,
                                                     String channel)
                                              throws ChannelRegistrationException

Gets or creates a ChannelBinding.RawDataChannel by the given name. If the channel exists and is a raw data channel, then it is returned. If the channel is not a raw data channel, then IllegalStateException is thrown. Otherwise, a new channel is created.

Parameters:

plugin - The plugin to register the channel if it doesn't exist

channel - The channel name

Returns:

A new or existing raw data channel binding

Throws:

IllegalStateException - if the existing channel is not an RawDataChannel

ChannelRegistrationException - for same reasons as createRawChannel(java.lang.Object, java.lang.String).

unbindChannel

void unbindChannel(ChannelBinding channel)

Remove the channel binding from this registrar, freeing up the channel name. All method calls on the channel binding instance will now throw IllegalStateException.

Parameters:

channel - The channel to unbind

getRegisteredChannels

Set<String> getRegisteredChannels(Platform.Type side)

Gets the set of registered channels.

Parameters:

side - The side to get the registered channels from

Returns:

A copy of the list of channels

isChannelAvailable

boolean isChannelAvailable(String channelName)

Returns whether the given channel name is available for creating with createChannel(java.lang.Object, java.lang.String).

Parameters:

channelName - The channel name to test

Returns:

True if available