Messaging Module
How to use the Mineplex Studio Messaging Module.
The Messaging Module enables communication between containers in the same namespace by sending and receiving messages. Messages can be targeted to specific containers based on various criteria.
Key Concepts 🔗
- Namespace-Specific Messaging: Messages can only be sent to and received from containers within the same namespace.
- Event-Driven Architecture: Messages trigger events, enabling responsive and asynchronous communication.
- Targeted Delivery: Messages can be directed to specific containers, projects, or namespaces.
Use Cases 🔗
- Inter-Container Communication: Facilitate communication between different containers within the same namespace for coordinated actions.
- Event Handling: Use event-driven architecture to respond to specific messages with appropriate handlers.
- Targeted Messaging: Send messages to specific containers based on predefined criteria for targeted communication.
Primary Functionalities 🔗
Registering a Listener 🔗
You can register a listener to receive messages associated with a specific key. When a message with the registered key is received, an AsyncMineplexMessageReceivedEvent is triggered.
void registerKey(@NonNull String key);
Parameters: 🔗
- key: The key for the messages you want to listen for.
Sending a Message to a Single Target 🔗
Send a message to a specific target with a designated key.
@NonNull CompletableFuture<Void> sendMessage(
@NonNull String key,
@NonNull Object message,
@NonNull MineplexMessageTarget target
);
Parameters: 🔗
- key: Identifier for the message type.
- message: The message content.
- target: The target container details.
Returns: 🔗
A CompletableFuture<Void>
indicating the success or failure of the send operation.
Sending a Message to Multiple Targets 🔗
Send a message to multiple specified targets with a designated key.
@NonNull CompletableFuture<Void> sendMessage(
@NonNull String key,
@NonNull Object message,
@NonNull Collection<@NonNull MineplexMessageTarget> targets
);
Parameters: 🔗
- key: Identifier for the message type.
- message: The message content.
- targets: Collection of target container details.
Returns: 🔗
A CompletableFuture<Void>
indicating the success or failure of the send operation.
Sending Multiple Messages to a Single Target 🔗
Send multiple messages to a single target with the same key.
@NonNull CompletableFuture<Void> sendMessages(
@NonNull String key,
@NonNull Collection<@NonNull Object> messages,
@NonNull MineplexMessageTarget target
);
Parameters: 🔗
- key: Identifier for the message type.
- messages: Collection of messages to be sent.
- target: The target container details.
Returns: 🔗
A CompletableFuture<Void>
indicating the success or failure of the send operation.
MineplexMessageTarget 🔗
Matching Namespace 🔗
Create a message target by targeting any container in a given namespace.
public static MineplexMessageTarget matchingNamespace(@NonNull final String namespaceIdentifier);
Matching Project 🔗
Create a message target by targeting any container in a given project.
public static MineplexMessageTarget matchingProject(@NonNull final String projectIdentifier);
Matching Pod 🔗
Create a message target by targeting a specific container.
public static MineplexMessageTarget matchingPod(@NonNull final String podIdentifier);
Example 🔗
To assist in using this module, here is an example which sends and receives message objects.
package com.mineplex.studio.example;
import lombok.Builder;
import lombok.Getter;
import lombok.extern.jackson.Jacksonized;
@Jacksonized
@Data
@Builder
public class GameMessage {
String message;
}
package com.mineplex.studio.example;
import com.mineplex.studio.sdk.modules.messaging.MessagingModule;
import com.mineplex.studio.sdk.modules.MineplexModuleManager;
import com.mineplex.studio.sdk.modules.messaging.target.MineplexMessageTarget;
import org.bukkit.plugin.java.JavaPlugin;
public class MyGame extends JavaPlugin {
private MessagingModule messagingModule;
@Override
public void onEnable() {
// Initialize the messaging module
this.messagingModule = MineplexModuleManager.getRegisteredModule(MessagingModule.class);
// Register a listener for incoming messages
// This is only required if you'd like to also listen to the incoming message on this key
messagingModule.registerKey("exampleKey");
// Send a test message
sendMessage();
}
private void sendMessage() {
final String key = "exampleKey";
final GameMessage message = GameMessage.builder().message("Hello from MessagingPlugin!").build();
// namespace ID can be found in your configuration file
final MineplexMessageTarget target = MineplexMessageTarget.matchingNamespace("exampleNamespace");
messagingModule
.sendMessage(key, message, target)
.thenAccept(voidResult -> {
getLogger().info("Message sent successfully.");
}).exceptionally(ex -> {
getLogger().severe("Failed to send message: " + ex.getMessage());
return null;
}
);
}
}
And then to listen to the messaging that will come in:
package com.mineplex.studio.example;
import com.mineplex.studio.sdk.modules.messaging.event.AsyncMineplexMessageReceivedEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;
import java.util.Optional;
public class MessageListener implements Listener {
private final JavaPlugin plugin;
public MessageListener(final JavaPlugin plugin) {
this.plugin = plugin;
}
@EventHandler
public void onMessageReceived(final AsyncMineplexMessageReceivedEvent event) {
final Optional<GameMessage> data = event.getMessageIf("exampleKey");
if (data.isPresent()) {
final String message = data.getMessage();
plugin.getLogger().info("Received message: " + message);
}
}
}
And don't forget to register the listener in your main class!
getServer().getPluginManager().registerEvents(new MessageListener(this), this);