Annotation Interface MessageSubscribe

@Documented
@Target(METHOD)
@Retention(RUNTIME)
public @interface MessageSubscribe

Marks a method as a cross-proxy message subscriber.

Methods annotated with @MessageSubscribe are automatically registered when the containing class is registered with the messaging service.

Method Signature

The annotated method may accept either:

• One parameter: the message data type only (e.g., ScoreData data)
• Two parameters: the source proxy ID as a String first, followed by the message data type (e.g., String sourceProxyId, GameEvent event)

The parameter order for two-parameter methods is always: (String sourceProxyId, MessageType data)

Examples

@Plugin(id = "my-plugin", name = "My Plugin", version = "1.0.0")
public class MyPlugin {

    // Single parameter: message data type only
    @MessageSubscribe(channel = "scores")
    public void onScoreUpdate(ScoreData data) {
        logger.info("Player {} scored {}", data.playerName(), data.score());
    }

    // Two parameters: sourceProxyId first, then message data type
    @MessageSubscribe(channel = "events")
    public void onGameEvent(String sourceProxyId, GameEvent event) {
        logger.info("Received event from proxy {}", sourceProxyId);
    }

    // Subscribe to system channel messages (type-safe enum)
    @MessageSubscribe(SystemChannel.CHAT)
    public void onChatMessage(ChatMessage message) {
        // Handle cross-proxy chat
    }

    // Subscribe to heartbeats
    @MessageSubscribe(SystemChannel.HEARTBEAT)
    public void onHeartbeat(HeartbeatMessage message) {
        logger.info("Proxy {} is alive", message.sourceProxyId());
    }
}

Registration

// In your plugin's onEnable:
proxy.getMessagingService().registerListener(this);

See Also:

• SystemChannel
• MessagingService.registerListener(Object)

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	channel	The channel name for plugin-specific messages.
boolean	includeSelf	Whether to receive messages sent by this proxy instance.
SystemChannel	value	The system channel to subscribe to.

Element Details

value

SystemChannel value

The system channel to subscribe to.

Use this for subscribing to built-in system channels like SystemChannel.CHAT or SystemChannel.HEARTBEAT.

Leave as SystemChannel.NONE when using channel() for plugin messages.

Returns:

the system channel to subscribe to

Default:

NONE

channel

String channel

The channel name for plugin-specific messages.

When specified, the plugin ID is automatically inferred from the @Plugin annotation on the listener class (or its enclosing plugin class).

Leave empty when using value() with a system channel.

Returns:

the channel name within the plugin

Default:

""

includeSelf

boolean includeSelf

Whether to receive messages sent by this proxy instance.

Default is false - messages from the local proxy are filtered out.

Returns:

true to include self-messages

Default:

false