Interface MessagingService

public interface MessagingService
A means to send messages to other servers using the platforms networking

  • Method Summary

    Modifier and Type
    Method
    Description
    @NonNull String
    getName()
    Gets the name of this messaging service
    void
    pushUpdate()
    Uses the messaging service to inform other servers about a general change.
    void
    pushUserUpdate(@NonNull User user)
    Uses the messaging service to inform other servers about a change to a specific user.
    void
    sendCustomMessage(@NonNull String channelId, @NonNull String payload)
    Uses the messaging service to send a message with a custom payload.

  • Method Details

    • getName

      @NonNull String getName()
      Gets the name of this messaging service
      Returns:
      the name of this messaging service

    • pushUpdate

      void pushUpdate()
      Uses the messaging service to inform other servers about a general change.

      The standard response by other servers will be to execute a overall sync of all live data, equivalent to calling LuckPerms.runUpdateTask().

      This will push the update asynchronously, and this method will return immediately. Note that this method will not cause an update to be processed on the local server.

    • pushUserUpdate

      void pushUserUpdate(@NonNull User user)
      Uses the messaging service to inform other servers about a change to a specific user.

      The standard response by other servers is undefined, however the current implementation will reload the corresponding users data if they are online.

      This will push the update asynchronously, and this method will return immediately. Note that this method will not cause an update to be processed on the local server.

      Parameters:
      user - the user to push the update for

    • sendCustomMessage

      void sendCustomMessage(@NonNull String channelId, @NonNull String payload)
      Uses the messaging service to send a message with a custom payload.

      The intended use case of this functionality is to allow plugins/mods to send lightweight and permissions-related custom messages between instances, piggy-backing on top of the messenger abstraction already built into LuckPerms.

      It is not intended as a full message broker replacement/abstraction. Note that some of the messenger implementations in LuckPerms cannot handle a high volume of messages being sent (for example the SQL messenger). Additionally, some implementations do not give any guarantees that a message will be delivered on time or even at all (for example the plugin message messengers).

      With all of that in mind, please consider that if you are using this functionality to send messages that have nothing to do with LuckPerms or permissions, or that require guarantees around delivery reliability, you are most likely misusing the API and would be better off building your own integration with a message broker.

      Whilst there is (currently) no strict validation, it is recommended that the channel id should use the same format as Minecraft resource locations / namespaced keys. For example, a plugin called "SuperRanks" sending rank-up notifications using custom payload messages might use the channel id "superranks:notifications" for this purpose.

      The payload can be any valid UTF-8 string.

      The message will be delivered asynchronously.

      Other LuckPerms instances that receive the message will publish it to API consumers using the CustomMessageReceiveEvent.

      Parameters:
      channelId - the channel id
      payload - the message payload
      Since:
      5.5