Merge branch 'api-8' into api-9

Author: ImMorpheus

gradle.properties

@@ -6,7 +6,7 @@ projectDescription=A plugin API for Minecraft: Java Edition
 
 org.gradle.parallel=true
 
-adventureVersion=4.9.0
+adventureVersion=4.9.2
 caffeineVersion=3.0.2
 configurateVersion=4.1.2
 errorproneVersion=2.8.1

src/main/java/org/spongepowered/api/scheduler/ScheduledTask.java

@@ -25,37 +25,24 @@
 package org.spongepowered.api.scheduler;
 
 import org.spongepowered.api.util.Identifiable;
-import org.spongepowered.plugin.PluginContainer;
+import org.spongepowered.api.util.Nameable;
 
 /**
- * Represents a {@link Task} that was scheduled through a
- * {@link Scheduler} using {@link Scheduler#submit(Task)}.
+ * Represents a {@link Task task} that was scheduled through a
+ * {@link Scheduler scheduler} using {@link Scheduler#submit(Task)}.
  */
-public interface ScheduledTask extends Identifiable {
+public interface ScheduledTask extends Nameable, Identifiable {
 
     /**
-     * Gets the name of this scheduled task.
-     *
-     * @return The name
+     * @return The {@link Scheduler scheduler}
      */
-    String name();
+    Scheduler scheduler();
 
     /**
-     * Gets the {@link Task} that was scheduled.
-     *
-     * @return The task
+     * @return The {@link Task}
      */
     Task task();
 
-    /**
-     * Returns the plugin that scheduled this task.
-     *
-     * @return The plugin that scheduled the task
-     */
-    default PluginContainer owner() {
-        return this.task().owner();
-    }
-
     /**
      * Cancels this scheduled task. Cancelling a repeating task
      * will prevent any further repetitions of the task.

src/main/java/org/spongepowered/api/scheduler/Scheduler.java

@@ -32,7 +32,7 @@
 import java.util.concurrent.ExecutorService;
 
 /**
- * Represents a scheduler for running {@link Task}s.
+ * Represents a scheduler for running {@link Task tasks}.
  */
 public interface Scheduler {
 
@@ -47,43 +47,62 @@ public interface Scheduler {
     /**
      * Returns a set of {@link Task}s that match the Regular Expression pattern.
      *
-     * @param pattern The regular expression pattern applied to the name of
-     *        tasks
-     * @return A set of {@link Task}s that have names that match the pattern,
-     *         the set will be empty if no names match
+     * @param pattern The regular expression pattern applied to the name of tasks
+     * @return A set of {@link Task}s that have names that match the pattern, the
+     * set will be empty if no names match
      */
     Set<ScheduledTask> findTasks(String pattern);
 
     /**
-     * Returns a set of all currently scheduled tasks.
+     * Returns a set of all currently scheduled tasks owned by the given plugin.
      *
+     * @param plugin The plugin that created the tasks
      * @return A set of scheduled tasks
      */
-    Set<ScheduledTask> tasks();
+    Set<ScheduledTask> tasks(PluginContainer plugin);
 
     /**
-     * Returns a set of all currently scheduled tasks owned by the given plugin.
+     * Returns a set of all currently scheduled tasks.
      *
-     * @param plugin The plugin that created the tasks
      * @return A set of scheduled tasks
      */
-    Set<ScheduledTask> tasks(PluginContainer plugin);
+    Set<ScheduledTask> tasks();
 
     /**
-     * Creates a new {@link ExecutorService} that can be used to schedule
+     * Gets an {@link ExecutorService executor} that can be used to schedule
      * tasks through the standard Java concurrency interfaces.
      *
      * @param plugin The plugin that will own the created tasks
-     * @return A new executor service that can be used to execute tasks
+     * @return An executor that can be used to execute tasks
      */
-    TaskExecutorService createExecutor(PluginContainer plugin);
+    TaskExecutorService executor(PluginContainer plugin);
 
     /**
      * Submit a {@link Task} to this scheduler and returns the task
      * as a {@link ScheduledTask}.
+     * <p>
+     * The name of the task will be the form:<br> {@code PLUGIN_ID "-" ( "A-" | "S-" ) SERIAL_ID}
+     * <p>
+     * Examples of default Task names:<br>
      *
+     * {@code "FooPlugin-A-12"}<br>{@code "BarPlugin-S-4322"}
+     * <p>
+     * No two active tasks will have the same serial ID for the same
+     * synchronisation type.<br>i.e {@code APlugin-A-15} and
+     * {@code BPlugin-A-15} is not possible but {@code BPlugin-S-15}
+     * is.
      * @param task The task
      * @return The scheduled task
      */
     ScheduledTask submit(Task task);
+
+    /**
+     * Submit a {@link Task} with a specified {@link String name} to this scheduler and returns the task
+     * as a {@link ScheduledTask}.
+     *
+     * @param task The task
+     * @param name The name
+     * @return The scheduled task
+     */
+    ScheduledTask submit(Task task, String name);
 }

src/main/java/org/spongepowered/api/scheduler/Task.java

@@ -25,7 +25,6 @@
 package org.spongepowered.api.scheduler;
 
 import org.spongepowered.api.Sponge;
-import org.spongepowered.api.event.CauseStackManager;
 import org.spongepowered.api.util.CopyableBuilder;
 import org.spongepowered.api.util.Ticks;
 import org.spongepowered.plugin.PluginContainer;
@@ -51,18 +50,9 @@ static Builder builder() {
     }
 
     /**
-     * Gets the name of this task.
-     *
-     * @return The name of the task
-     */
-    String name();
-
-    /**
-     * Returns the plugin that constructed this task.
-     *
-     * @return The plugin that constructed the task
+     * @return The {@link PluginContainer plugin}
      */
-    PluginContainer owner();
+    PluginContainer plugin();
 
     /**
      * Gets the delay that the task was scheduled to run after. A delay of 0
@@ -80,13 +70,6 @@ static Builder builder() {
      */
     Duration interval();
 
-    /**
-     * Gets the {@link Consumer}>{@link Task}< that this task is running.
-     *
-     * @return The consumer
-     */
-    Consumer<ScheduledTask> consumer();
-
     /**
      * Represents a builder to create a {@link Task}.
      */
@@ -224,37 +207,9 @@ default Builder interval(final long interval, final TimeUnit unit) {
          */
         Builder interval(final Ticks ticks);
 
-        /**
-         * Sets the name of the task, the name cannot be blank.
-         *
-         * <p>If the name is not set in the builder, the name of the task
-         * will be the form:<br> {@code PLUGIN_ID "-" ( "A-" | "S-" ) SERIAL_ID}
-         * </p>
-         *
-         * <p>Examples of default Task names:<br>
-         *
-         * {@code "FooPlugin-A-12"}<br>{@code "BarPlugin-S-4322"}</p>
-         *
-         * <p>No two active tasks will have the same serial ID for the same
-         * synchronisation type.<br>i.e {@code APlugin-A-15} and
-         * {@code BPlugin-A-15} is not possible but {@code BPlugin-S-15}
-         * is.</p>
-         *
-         * @param name The task name
-         * @return This builder, for chaining
-         * @throws IllegalArgumentException If the name is blank
-         */
-        Builder name(String name);
-
         /**
          * Sets the plugin of the task.
          *
-         * <p>If no plugin is set, one will be extracted from the
-         * {@link CauseStackManager} when the {@link #build()} method
-         * is called from a main thread. If it's not called called
-         * from a main thread, a {@link IllegalStateException} will
-         * be thrown.</p>
-         *
          * @param plugin The plugin instance
          * @return This builder, for chaining
          * @throws IllegalArgumentException If the given object isn't a valid plugin
@@ -265,10 +220,8 @@ default Builder interval(final long interval, final TimeUnit unit) {
          * Builds the task.
          *
          * @return A new instance of a {@link Task}
-         * @throws IllegalStateException If the {@link #execute(Runnable)} isn't set. Or
-         *                               in case that {@link #plugin(PluginContainer)} isn't set and
-         *                               no {@link PluginContainer} could be extracted
-         *                               from the {@link CauseStackManager}.
+         * @throws IllegalStateException If the {@link #execute(Runnable)} isn't set or in the
+         * case that {@link #plugin(PluginContainer)} isn't set.
          */
         @Override
         Task build();

src/main/java/org/spongepowered/api/util/Nameable.java

@@ -25,14 +25,12 @@
 package org.spongepowered.api.util;
 
 /**
- * An identifiable object that uses a {@link String} as an identifier.
+ * An object that can be described by a {@link String name}.
  */
 public interface Nameable {
 
     /**
-     * The name that represents this object.
-     *
-     * @return The name.
+     * @return The {@link String name}
      */
     String name();