More flexible definition of calling Extension methods

Plan/api/build.gradle

@@ -2,7 +2,7 @@ plugins {
     id "com.jfrog.bintray" version "1.8.1"
 }
 
-ext.apiVersion = '0.0.2'
+ext.apiVersion = '0.0.3'
 
 bintray {
     user = System.getenv('BINTRAY_USER')
@@ -15,7 +15,7 @@ bintray {
         issueTrackerUrl = 'https://github.com/plan-player-analytics/Plan/issues'
         version {
             name = "$apiVersion"
-            desc = 'Plan APIv5 version 0.0.1'
+            desc = "Plan APIv5 version $apiVersion"
         }
         publications = ['BintrayPublication']
     }

Plan/api/src/main/java/com/djrapitops/plan/extension/CallEvents.java

@@ -0,0 +1,65 @@
+/*
+ *  This file is part of Player Analytics (Plan).
+ *
+ *  Plan is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License v3 as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  Plan is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with Plan. If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.djrapitops.plan.extension;
+
+/**
+ * Enum representing different events when Plan calls methods of {@link DataExtension} automatically.
+ * <p>
+ * You can also call the update methods via {@link Caller} manually.
+ *
+ * @author Rsl1122
+ */
+public enum CallEvents {
+
+    /**
+     * This event represents a manual call via {@link Caller}.
+     * Definition inside {@link DataExtension#callExtensionMethodsOn()} is NOT REQUIRED for using Caller methods.
+     */
+    MANUAL,
+    /**
+     * This event represents call to player methods on a Player Join event.
+     * <p>
+     * The call is made from a listener at the last event priority (Bukkit/Bungee: MONITOR, Sponge: POST).
+     * Method calls are asynchronous.
+     */
+    PLAYER_JOIN,
+    /**
+     * This event represents a call to player methods on a Player Leave event.
+     * <p>
+     * The call is made from a listener at the first event priority (Bukkit/Bungee: LOWEST, Sponge: PRE).
+     * Method calls are asynchronous.
+     */
+    PLAYER_LEAVE,
+    /**
+     * This event represents a call to server methods when the {@link DataExtension} is registered.
+     * <p>
+     * Server methods include any {@link Group} parameter methods.
+     * <p>
+     * Method calls are asynchronous.
+     */
+    SERVER_EXTENSION_REGISTER,
+    /**
+     * This event represents a call to server methods via a periodical task.
+     * <p>
+     * Server methods include any {@link Group} parameter methods.
+     * <p>
+     * Periodic task with a runs user configured period (Plan config).
+     * Method calls are asynchronous.
+     */
+    SERVER_PERIODICAL
+
+}

Plan/api/src/main/java/com/djrapitops/plan/extension/Caller.java

@@ -0,0 +1,50 @@
+/*
+ *  This file is part of Player Analytics (Plan).
+ *
+ *  Plan is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License v3 as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  Plan is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with Plan. If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.djrapitops.plan.extension;
+
+import java.util.UUID;
+
+/**
+ * Interface for manually calling update methods on a registered {@link DataExtension}.
+ * <p>
+ * You can obtain an instance by registering an extension via {@link ExtensionService#register(DataExtension)}.
+ * <p>
+ * Plan calls the methods in DataExtension based on {@link CallEvents} defined by {@link }
+ *
+ * @author Rsl1122
+ */
+public interface Caller {
+
+    /**
+     * Calls all player methods of the associated {@link DataExtension}.
+     * <p>
+     * Player methods have {@code UUID} or {@code String} as a method parameter and a Provider annotation.
+     *
+     * @param playerUUID UUID of the player.
+     * @param playerName Name of the player.
+     * @throws IllegalArgumentException If playerUUID or playerName is null.
+     */
+    void updatePlayerData(UUID playerUUID, String playerName) throws IllegalArgumentException;
+
+    /**
+     * Calls all server methods of the associated {@link DataExtension}.
+     * <p>
+     * Server methods have no parameters or {@link Group} method parameter and a Provider annotation.
+     */
+    void updateServerData();
+
+}

Plan/api/src/main/java/com/djrapitops/plan/extension/DataExtension.java

@@ -50,6 +50,8 @@ package com.djrapitops.plan.extension;
  * {@link com.djrapitops.plan.extension.annotation.TabOrder} Optional information about preferred tab
  * <hr>
  * <p>
+ * Method calls are asynchronous. You can control when the calls are made via {@link DataExtension#callExtensionMethodsOn()} and {@link Caller}.
+ * <p>
  * You can check against implementation violations by using {@link com.djrapitops.plan.extension.extractor.ExtensionExtractor#validateAnnotations()} in your Unit Tests.
  * <p>
  * Implementation violations:
@@ -64,6 +66,28 @@ package com.djrapitops.plan.extension;
  * - Method name is over 50 characters (Used as an identifier for storage)
  *
  * @author Rsl1122
+ * @see com.djrapitops.plan.extension.annotation.PluginInfo Required Annotation
+ * @see CallEvents for method call event types.
  */
 public interface DataExtension {
+
+    /**
+     * Determines when DataExtension methods are called automatically by Plan.
+     * <p>
+     * Override this method to determine more suitable call times for your plugin.
+     * You can also use {@link Caller} to update manually.
+     * <p>
+     * If an empty array is supplied the DataExtension methods are not called by Plan automatically.
+     *
+     * @return Event types that will trigger method calls to the DataExtension.
+     * @see CallEvents for details when the methods are called.
+     */
+    default CallEvents[] callExtensionMethodsOn() {
+        return new CallEvents[]{
+                CallEvents.PLAYER_JOIN,
+                CallEvents.PLAYER_LEAVE,
+                CallEvents.SERVER_EXTENSION_REGISTER
+        };
+    }
+
 }

Plan/api/src/main/java/com/djrapitops/plan/extension/ExtensionService.java

@@ -54,9 +54,10 @@ public interface ExtensionService {
      * You can use {@link ExtensionExtractor#validateAnnotations()} in your Unit Tests to prevent IllegalArgumentExceptions here at runtime.
      *
      * @param extension Your DataExtension implementation, see {@link DataExtension} for requirements.
+     * @return Optional {@link Caller} that can be used to call for data update in Plan database manually - If the Optional is not present the user has disabled the extension in Plan config.
      * @throws IllegalArgumentException If an implementation violation is found.
      */
-    void register(DataExtension extension);
+    Optional<Caller> register(DataExtension extension);
 
     /**
      * Unregister your {@link DataExtension} implementation.

Plan/api/src/main/java/com/djrapitops/plan/extension/Group.java

@@ -22,6 +22,7 @@ package com.djrapitops.plan.extension;
  * Usage Example: {@code @StringProvider String provideStringAboutGroup(Group group)}
  * <p>
  * Group names of users are provided with {@code @GroupProvider String[] provideGroups(UUID playerUUID)}
+ * {@code Group} parameter methods are not called without knowledge of a group name.
  * <p>
  * This method parameter is used since it is not possible to differentiate String playerName and String groupName.
  *