Expose a means to implement the plugin's MessagingService via the API

This commit is contained in:
Luck
2018-01-19 23:35:41 +00:00
Unverified
parent 612712f015
commit 821dc4ef56
38 changed files with 1469 additions and 442 deletions
@@ -33,6 +33,7 @@ import me.lucko.luckperms.api.event.EventBus;
import me.lucko.luckperms.api.manager.GroupManager;
import me.lucko.luckperms.api.manager.TrackManager;
import me.lucko.luckperms.api.manager.UserManager;
import me.lucko.luckperms.api.messenger.MessengerProvider;
import me.lucko.luckperms.api.metastacking.MetaStackFactory;
import me.lucko.luckperms.api.platform.PlatformInfo;
@@ -172,6 +173,17 @@ public interface LuckPermsApi {
@Nonnull
Optional<MessagingService> getMessagingService();
/**
* Registers a {@link MessengerProvider} for use by the platform.
*
* <p>Note that the mere action of registering a provider doesn't
* necessarily mean that it will be used.</p>
*
* @param messengerProvider the messenger provider.
* @since 4.1
*/
void registerMessengerProvider(@Nonnull MessengerProvider messengerProvider);
/**
* Gets the {@link ActionLogger}.
*
@@ -25,6 +25,8 @@
package me.lucko.luckperms.api;
import javax.annotation.Nonnull;
/**
* A means to push changes to other servers using the platforms networking
*
@@ -33,12 +35,42 @@ package me.lucko.luckperms.api;
public interface MessagingService {
/**
* Uses the messaging service to inform other servers about changes.
* Gets the name of this messaging service
*
* @return the name of this messaging service
* @since 4.1
*/
String getName();
/**
* Uses the messaging service to inform other servers about a general
* change.
*
* <p>The standard response by other servers will be to execute a overall
* sync of all live data, equivalent to calling
* {@link LuckPermsApi#runUpdateTask()}.</p>
*
* <p>This will push the update asynchronously, and this method will return
* immediately. Calling this method is equivalent to running "/lp networksync",
* except will not sync this server.</p>
* immediately. Note that this method will not cause an update to be
* processed on the local server.</p>
*/
void pushUpdate();
/**
* Uses the messaging service to inform other servers about a change to a
* specific user.
*
* <p>The standard response by other servers is undefined, however the
* current implementation will reload the corresponding users data if they
* are online.</p>
*
* <p>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.</p>
*
* @param user the user to push the update for
* @since 4.1
*/
void pushUserUpdate(@Nonnull User user);
}
@@ -0,0 +1,78 @@
/*
* This file is part of LuckPerms, licensed under the MIT License.
*
* Copyright (c) lucko (Luck) <luck@lucko.me>
* Copyright (c) contributors
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package me.lucko.luckperms.api.messenger;
import me.lucko.luckperms.api.messenger.message.Message;
import me.lucko.luckperms.api.messenger.message.OutgoingMessage;
import javax.annotation.Nonnull;
/**
* Encapsulates the LuckPerms system which accepts incoming {@link Message}s
* from implementations of {@link MessengerProvider}.
*
* @since 4.1
*/
public interface IncomingMessageConsumer {
/**
* Consumes a message instance.
*
* <p>The boolean returned from this method indicates whether or not the
* platform accepted the message. Some implementations which have multiple
* distribution channels may wish to use this result to dispatch the same
* message back to additional receivers.</p>
*
* <p>The implementation will usually return <code>false</code> if a message
* with the same ping id has already been processed.</p>
*
* @param message the message
* @return true if the message was accepted by the plugin
*/
boolean consumeIncomingMessage(@Nonnull Message message);
/**
* Consumes a message in an encoded string format.
*
* <p>This method will decode strings obtained by calling
* {@link OutgoingMessage#asEncodedString()}. This means that basic
* implementations can successfully implement {@link Messenger} without
* providing their own serialisation.</p>
*
* <p>The boolean returned from this method indicates whether or not the
* platform accepted the message. Some implementations which have multiple
* distribution channels may wish to use this result to dispatch the same
* message back to additional receivers.</p>
*
* <p>The implementation will usually return <code>false</code> if a message
* with the same ping id has already been processed.</p>
*
* @param encodedString the encoded string
* @return true if the message was accepted by the plugin
*/
boolean consumeIncomingMessageAsString(@Nonnull String encodedString);
}
@@ -0,0 +1,58 @@
/*
* This file is part of LuckPerms, licensed under the MIT License.
*
* Copyright (c) lucko (Luck) <luck@lucko.me>
* Copyright (c) contributors
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package me.lucko.luckperms.api.messenger;
import me.lucko.luckperms.api.messenger.message.Message;
import me.lucko.luckperms.api.messenger.message.OutgoingMessage;
import javax.annotation.Nonnull;
/**
* Represents an object which dispatches {@link OutgoingMessage}s.
*
* @since 4.1
*/
public interface Messenger extends AutoCloseable {
/**
* Performs the necessary action to dispatch the message using the means
* of the messenger.
*
* <p>The outgoing message instance is guaranteed to be an instance of one
* of the interfaces extending {@link Message} in the
* 'api.messenger.message.type' package.</p>
*
* <p>This call is always made async.</p>
*
* @param outgoingMessage the outgoing message
*/
void sendOutgoingMessage(@Nonnull OutgoingMessage outgoingMessage);
@Override
default void close() {
}
}
@@ -0,0 +1,65 @@
/*
* This file is part of LuckPerms, licensed under the MIT License.
*
* Copyright (c) lucko (Luck) <luck@lucko.me>
* Copyright (c) contributors
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package me.lucko.luckperms.api.messenger;
import me.lucko.luckperms.api.LuckPermsApi;
import javax.annotation.Nonnull;
/**
* Represents a provider for {@link Messenger} instances.
*
* <p>Users wishing to provide their own implementation for the plugins
* "Messaging Service" should implement and register this interface.</p>
*
* @since 4.1
* @see LuckPermsApi#registerMessengerProvider(MessengerProvider)
*/
public interface MessengerProvider {
/**
* Gets the name of this provider.
*
* @return the provider name
*/
@Nonnull
String getName();
/**
* Creates and returns a new {@link Messenger} instance, which passes
* incoming messages to the provided {@link IncomingMessageConsumer}.
*
* <p>As the agent should pass incoming messages to the given consumer,
* this method should always return a new object.</p>
*
* @param incomingMessageConsumer the consumer the new instance should pass
* incoming messages to
* @return a new messenger agent instance
*/
@Nonnull
Messenger obtain(@Nonnull IncomingMessageConsumer incomingMessageConsumer);
}
@@ -0,0 +1,52 @@
/*
* This file is part of LuckPerms, licensed under the MIT License.
*
* Copyright (c) lucko (Luck) <luck@lucko.me>
* Copyright (c) contributors
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package me.lucko.luckperms.api.messenger.message;
import me.lucko.luckperms.api.messenger.Messenger;
import java.util.UUID;
import javax.annotation.Nonnull;
/**
* Represents a message sent received via a {@link Messenger}.
*
* @since 4.1
*/
public interface Message {
/**
* Gets the unique id associated with this message.
*
* <p>This ID is used to ensure a single server instance doesn't process
* the same message twice.</p>
*
* @return the id of the message
*/
@Nonnull
UUID getId();
}
@@ -0,0 +1,62 @@
/*
* This file is part of LuckPerms, licensed under the MIT License.
*
* Copyright (c) lucko (Luck) <luck@lucko.me>
* Copyright (c) contributors
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package me.lucko.luckperms.api.messenger.message;
import me.lucko.luckperms.api.messenger.IncomingMessageConsumer;
import javax.annotation.Nonnull;
/**
* Represents an outgoing {@link Message}.
*
* <p>Outgoing messages are ones which have been generated by this instance.
* (in other words, they are implemented by LuckPerms)</p>
*
* <p>Note that all implementations of this interface are guaranteed to be an
* instance of one of the interfaces extending {@link Message} in the
* 'api.messenger.message.type' package.</p>
*
* @since 4.1
*/
public interface OutgoingMessage extends Message {
/**
* Gets an encoded string form of this message.
*
* <p>The format of this string is likely to change between versions and
* should not be depended on.</p>
*
* <p>Implementations which want to use a standard method of serialisation
* can send outgoing messages using the string returned by this method, and
* pass on the message on the "other side" using
* {@link IncomingMessageConsumer#consumeIncomingMessageAsString(String)}.</p>
*
* @return an encoded string form of the message
*/
@Nonnull
String asEncodedString();
}
@@ -0,0 +1,50 @@
/*
* This file is part of LuckPerms, licensed under the MIT License.
*
* Copyright (c) lucko (Luck) <luck@lucko.me>
* Copyright (c) contributors
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package me.lucko.luckperms.api.messenger.message.type;
import me.lucko.luckperms.api.LogEntry;
import me.lucko.luckperms.api.messenger.message.Message;
import javax.annotation.Nonnull;
/**
* Represents an "log" message.
*
* <p>Used to dispatch live log updates to other servers.</p>
*
* @since 4.1
*/
public interface LogMessage extends Message {
/**
* Gets the log entry being sent
*
* @return the log entry
*/
@Nonnull
LogEntry getLogEntry();
}
@@ -0,0 +1,39 @@
/*
* This file is part of LuckPerms, licensed under the MIT License.
*
* Copyright (c) lucko (Luck) <luck@lucko.me>
* Copyright (c) contributors
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package me.lucko.luckperms.api.messenger.message.type;
import me.lucko.luckperms.api.messenger.message.Message;
/**
* Represents an "update" message.
*
* <p>Used to notify other servers of general changes.</p>
*
* @since 4.1
*/
public interface UpdateMessage extends Message {
}
@@ -0,0 +1,51 @@
/*
* This file is part of LuckPerms, licensed under the MIT License.
*
* Copyright (c) lucko (Luck) <luck@lucko.me>
* Copyright (c) contributors
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package me.lucko.luckperms.api.messenger.message.type;
import me.lucko.luckperms.api.messenger.message.Message;
import java.util.UUID;
import javax.annotation.Nonnull;
/**
* Represents an "user update" message.
*
* <p>Used to notify other servers of a change to a specific user.</p>
*
* @since 4.1
*/
public interface UserUpdateMessage extends Message {
/**
* Gets the user the message is for.
*
* @return the user
*/
@Nonnull
UUID getUser();
}