Merge branch 'api-8' into api-9

Author: Daniel Naylor

src/ap/java/org/spongepowered/plugin/processor/ListenerParameterAnnotation.java

@@ -63,7 +63,7 @@ void validate(final ParameterContext ctx) {
                     if (!contained.getModifiers().contains(Modifier.STATIC)) {
                         ctx.logError("The @ContextValue annotation must refer to a static field", entry.getValue());
                     }
-                    if (!ctx.types().isSubtype(contained.asType(), key.asType())) {
+                    if (!ctx.types().isSubtype(contained.asType(), ctx.types().erasure(key.asType()))) {
                         ctx.logError("The @ContextValue annotation must refer to a field with type EventContextKey, but got '" + contained.asType() + "' instead", entry.getValue());
                     }
                     // validate field type?
@@ -123,7 +123,7 @@ void validate(final ParameterContext ctx) {
                             expectedType = declared.getTypeArguments().get(0);
                         }
                     }
-                    if (!ctx.types().isSameType(expectedType, ctx.param().asType())) {
+                    if (!ctx.types().isAssignable(ctx.param().asType(), expectedType)) {
                         ctx.logParamError(
                             "Annotated parameter was of incorrect type for the method referenced in @Getter. The parameter type should be '"
                             + expectedType + "'!"

src/main/java/org/spongepowered/api/block/BlockSnapshot.java

@@ -40,22 +40,15 @@
 
 import java.util.Optional;
 import java.util.UUID;
-import java.util.function.Supplier;
 
 /**
  * An immutable representation of a {@link BlockState} and any extra data that
  * may be associated with it, including {@link BlockEntity} related data.
  */
 public interface BlockSnapshot extends LocatableSnapshot<BlockSnapshot> {
 
-    /**
-     * Represents a {@link BlockSnapshot} with the default state of
-     * {@link BlockTypes#AIR} and a {@link ServerLocation} that cannot be determined.
-     */
-    Supplier<BlockSnapshot> NONE = BlockSnapshot::empty;
-
     static BlockSnapshot empty() {
-        return Sponge.game().builderProvider().provide(Builder.class).empty();
+        return Sponge.game().factoryProvider().provide(Factory.class).empty();
     }
 
     /**
@@ -205,6 +198,9 @@ interface Builder extends SerializableDataHolderBuilder.Immutable<BlockSnapshot,
          * @return This builder, for chaining
          */
         Builder notifier(UUID uuid);
+    }
+
+    interface Factory {
 
         BlockSnapshot empty();
     }

src/main/java/org/spongepowered/api/command/CommandResult.java

@@ -45,21 +45,19 @@ static Builder builder() {
     }
 
     /**
-     * Builds a result that indicates successes.
+     * Builds a result that indicates success (where {@link Builder#result(int)}
+     * is set to 1.
      *
-     * @return The {@link CommandResult}
-     */
-    static CommandResult success() {
-        return CommandResults.SUCCESS;
-    }
-
-    /**
-     * Builds an empty result.
+     * <p>Note that a successful result is one where the command has done what
+     * is expected of it. This should be used in place of "empty" from previous
+     * API iterations. If an error condition should be reported, use
+     * {@link #error(Component)} instead, which will allow the system to react
+     * accordingly.</p>
      *
      * @return The {@link CommandResult}
      */
-    static CommandResult empty() {
-        return CommandResults.EMPTY;
+    static CommandResult success() {
+        return Sponge.game().factoryProvider().provide(Factory.class).success();
     }
 
     /**
@@ -105,7 +103,8 @@ interface Builder extends org.spongepowered.api.util.Builder<CommandResult, Buil
          *
          * <ul>
          *     <li>A positive value indicates successful execution,</li>
-         *     <li>Zero indicates the command didn't fulfil its task</li>
+         *     <li>Zero (generally) indicates the command didn't fulfil its
+         *     task, though that is not necessarily an error condition.</li>
          *     <li>A negative value is undefined in the API, if returned, the
          *     effects are implementation specific.</li>
          * </ul>
@@ -116,11 +115,12 @@ interface Builder extends org.spongepowered.api.util.Builder<CommandResult, Buil
         Builder result(int result);
 
         /**
-         * Sets or removes the error message to return to the user without
-         * throwing an exception.
+         * Sets the built result to report an error, with an optional error
+         * message.
          *
          * <p>If this is set, then the command parser will send this message to
-         * the command invoker.</p>
+         * the command invoker. Otherwise, the parser will report an unknown
+         * exception.</p>
          *
          * @param errorMessage The message to send to the user.
          * @return This builder, for chaining
@@ -137,4 +137,10 @@ interface Builder extends org.spongepowered.api.util.Builder<CommandResult, Buil
 
     }
 
+    interface Factory {
+
+        CommandResult success();
+
+    }
+
 }

src/main/java/org/spongepowered/api/entity/Entity.java

@@ -328,6 +328,13 @@ default boolean canSee(final Entity entity) {
         return !optional.isPresent() || !optional.get();
     }
 
+    /**
+     * Makes the entity look at the specified target position.
+     *
+     * @param targetPos Position to target
+     */
+    void lookAt(Vector3d targetPos);
+
     /**
      * {@link Keys#DISPLAY_NAME}
      *

src/main/java/org/spongepowered/api/entity/living/Living.java

@@ -31,7 +31,6 @@
 import org.spongepowered.api.entity.attribute.Attribute;
 import org.spongepowered.api.entity.attribute.AttributeHolder;
 import org.spongepowered.api.item.inventory.ItemStackSnapshot;
-import org.spongepowered.api.projectile.source.EntityProjectileSource;
 import org.spongepowered.api.scoreboard.TeamMember;
 import org.spongepowered.math.imaginary.Quaterniond;
 import org.spongepowered.math.vector.Vector3d;
@@ -164,13 +163,6 @@ default Value.Mutable<Double> walkingSpeed() {
         return this.requireValue(Keys.WALKING_SPEED).asMutable();
     }
 
-    /**
-     * Makes the entity look at the specified target position.
-     *
-     * @param targetPos Position to target
-     */
-    void lookAt(Vector3d targetPos);
-
     /**
      * Converts the {@link Living}'s head rotation into a quaternion direction unit vector.
      *

src/main/java/org/spongepowered/api/event/filter/cause/ContextValue.java

@@ -26,6 +26,7 @@
 
 import org.spongepowered.api.event.EventContext;
 import org.spongepowered.api.event.EventContextKey;
+import org.spongepowered.api.event.EventContextKeys;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
@@ -46,6 +47,8 @@
     /**
      * Gets the name to use with the {@link EventContextKey}.
      *
+     * <p>This must be a field in {@link EventContextKeys}.</p>
+     *
      * @return The name to use
      */
     String value();

src/main/java/org/spongepowered/api/event/world/chunk/ChunkEvent.java

@@ -36,62 +36,80 @@
 public interface ChunkEvent extends Event {
 
     /**
-     * Gets the position of the {@link Chunk}, in chunk co-ordinates.
+     * Gets the position of the {@link Chunk chunk}, in chunk co-ordinates.
      *
      * @return the position
      */
     Vector3i chunkPosition();
 
     /**
-     * Represents an event that has knowledge about the {@link ServerWorld} that
+     * Represents an event that has knowledge about the {@link ServerWorld world} that
      * is being operated upon.
      */
     @NoFactoryMethod
     interface WorldScoped extends ChunkEvent {
 
         /**
-         * Gets the {@link ResourceKey} of the {@link WorldScoped} that the
-         * {@link WorldChunk} resides in.
+         * Gets the {@link ResourceKey key} of the {@link WorldScoped} that the
+         * {@link WorldChunk chunk} resides in.
          *
-         * <p>Be careful when retrieving the {@link ServerWorld} within this
+         * <p>Be careful when retrieving the {@link ServerWorld world} within this
          * event as some events may not fire on the main thread and such world
          * access is not thread safe.</p>
          *
-         * @return The world's {@link ResourceKey}
+         * @return The world's {@link ResourceKey key}
          */
         ResourceKey worldKey();
-
     }
 
     /**
-     * Called when a {@link WorldChunk} was unloaded.
+     * Called when a {@link WorldChunk chunk} was unloaded.
      */
     interface Unload extends WorldScoped {
 
+        /**
+         * Called before the {@link WorldChunk chunk} is unloaded.
+         */
+        interface Pre extends Unload {
+
+            /**
+             * Gets the {@link WorldChunk chunk} being changed.
+             *
+             * @return The chunk
+             */
+            WorldChunk chunk();
+        }
+
+        /**
+         * Called after the {@link WorldChunk chunk} is unloaded.
+         */
+        interface Post extends Unload {
+
+        }
     }
 
     /**
-     * Called when a {@link WorldChunk} is performing a save.
+     * Called when a {@link WorldChunk chunk} is performing a save.
      */
     interface Save extends WorldScoped {
 
         /**
-         * Called before the {@link WorldChunk} is saved. Cancelling this will prevent any of
+         * Called before the {@link WorldChunk chunk} is saved. Cancelling this will prevent any of
          * the chunk's data being written to it's storage container.
          */
         interface Pre extends Save, Cancellable {
 
             /**
-             * Gets the {@link WorldChunk} being changed.
+             * Gets the {@link WorldChunk chunk} being changed.
              *
-             * @return The Chunk
+             * @return The chunk
              */
-            WorldChunk targetChunk();
+            WorldChunk chunk();
 
         }
 
         /**
-         * Called after the {@link WorldChunk} is saved. Guaranteed to exist in the chunk's
+         * Called after the {@link WorldChunk chunk} is saved. Guaranteed to exist in the chunk's
          * storage container.
          *
          * Depending on the implementation, this event may be called off-thread.
@@ -100,22 +118,22 @@ interface Post extends Save {}
     }
 
     /**
-     * Called when a new {@link WorldChunk} was generated.
+     * Called when a new {@link WorldChunk chunk} was generated.
      */
     interface Generated extends WorldScoped {
 
     }
 
     /**
-     * Called when a {@link WorldChunk} is done loading.
+     * Called when a {@link WorldChunk chunk} is done loading.
      */
     interface Load extends WorldScoped {
 
         /**
-         * Gets the {@link WorldChunk} being changed.
+         * Gets the {@link WorldChunk chunk} being changed.
          *
-         * @return The Chunk
+         * @return The chunk
          */
-        WorldChunk targetChunk();
+        WorldChunk chunk();
     }
 }

src/main/java/org/spongepowered/api/item/inventory/ItemStack.java

@@ -37,7 +37,6 @@
 import org.spongepowered.api.entity.attribute.AttributeModifier;
 import org.spongepowered.api.entity.attribute.type.AttributeType;
 import org.spongepowered.api.item.ItemType;
-import org.spongepowered.api.item.ItemTypes;
 import org.spongepowered.api.item.inventory.equipment.EquipmentType;
 import org.spongepowered.api.registry.DefaultedRegistryReference;
 
@@ -59,6 +58,15 @@
  */
 public interface ItemStack extends SerializableDataHolder.Mutable {
 
+    /**
+     * Returns an empty {@link ItemStack}.
+     *
+     * @return The empty ItemStack
+     */
+    static ItemStack empty() {
+        return Sponge.game().factoryProvider().provide(Factory.class).empty();
+    }
+
     /**
      * Creates a new {@link Builder} to build an {@link ItemStack}.
      *
@@ -112,15 +120,6 @@ static ItemStack of(ItemType itemType) {
         return ItemStack.of(itemType, 1);
     }
 
-    /**
-     * Returns an empty {@link ItemStack}.
-     *
-     * @return The empty ItemStack
-     */
-    static ItemStack empty() {
-        return ItemStack.builder().itemType(ItemTypes.AIR).build();
-    }
-
     /**
      * Gets the {@link ItemType} of this {@link ItemStack}.
      *
@@ -413,4 +412,9 @@ default Builder apply(Predicate<Builder> predicate, Consumer<Builder> consumer)
         @Override
         ItemStack build() throws IllegalStateException;
     }
+
+    interface Factory {
+
+        ItemStack empty();
+    }
 }

src/main/java/org/spongepowered/api/plugin/PluginManager.java

@@ -59,14 +59,4 @@ public interface PluginManager {
      * @return The plugins
      */
     Collection<PluginContainer> plugins();
-
-    /**
-     * Checks if a plugin is loaded based on its ID.
-     * This may contain plugins/mods from other systems in some implementations.
-     *
-     * @param id the id of the {@link PluginContainer}
-     * @return {@code true} if loaded {@code false} if not loaded.
-     */
-    boolean isLoaded(String id);
-
 }

…epowered/api/command/CommandResults.java …epowered/api/world/DefaultWorldKeys.javasrc/main/java/org/spongepowered/api/command/CommandResults.java renamed to src/main/java/org/spongepowered/api/world/DefaultWorldKeys.java src/main/java/org/spongepowered/api/command/CommandResults.java renamed to src/main/java/org/spongepowered/api/world/DefaultWorldKeys.java

@@ -22,25 +22,22 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package org.spongepowered.api.command;
+package org.spongepowered.api.world;
+
+import org.spongepowered.api.ResourceKey;
+import org.spongepowered.api.world.server.ServerWorld;
 
 /**
- * Common {@link CommandResult}s.
+ * A listing of the {@link ResourceKey keys} of the default {@link ServerWorld worlds} in Minecraft.
  */
-public final class CommandResults {
+public final class DefaultWorldKeys {
 
-    /**
-     * Indicates that the command executed successfully.
-     */
-    public static final CommandResult SUCCESS = CommandResult.builder().result(1).build();
+    public static final ResourceKey OVERWORLD = ResourceKey.minecraft("overworld");
 
-    /**
-     * Indicates that the command executed but was unable to carry out its task.
-     */
-    public static final CommandResult EMPTY = CommandResult.builder().build();
+    public static final ResourceKey THE_NETHER = ResourceKey.minecraft("the_nether");
 
-    private CommandResults() {
-        throw new AssertionError("You shouldn't be trying to instantiate this");
-    }
+    public static final ResourceKey THE_END = ResourceKey.minecraft("the_end");
 
+    private DefaultWorldKeys() {
+    }
 }