Clarify in the LazyOptional which methods carry the lazyness over to the returned value and which don't. (#6750)

For consistency, this meant making a few changes:
- Renamed the existing lazy mapping method to lazyMap, to indicate that it doesn't run the mapping immediately.
- Added a new implementation of map(), which returns Optional<T>, and resolves the value in the process.
- Changed filter() to return Optional, since there's no way to filter lazily.
- Added a new method resolve(), which helps convert the custom LazyOptional class into a standard Optional, for use
with library methods that expect Optional<T>.

* Update License headers.

src/main/java/net/minecraftforge/common/BiomeDictionary.java

@@ -16,6 +16,7 @@
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  */
+
 /* Biomes are completely redone in 1.16.2, reevaluate
 package net.minecraftforge.common;
 

src/main/java/net/minecraftforge/common/BiomeManager.java

@@ -16,6 +16,7 @@
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  */
+
 /* Biomes are completely redone in 1.16.2, reevaluate
 package net.minecraftforge.common;
 

src/main/java/net/minecraftforge/common/util/LazyOptional.java

@@ -41,7 +41,7 @@ import net.minecraftforge.common.capabilities.Capability;
  * (map/ifPresent) available, much like {@link Optional}.
  * <p>
  * It also provides the ability to listen for invalidation, via
- * {@link #addListener(Consumer)}. This method is invoked when the provider of
+ * {@link #addListener(NonNullConsumer)}. This method is invoked when the provider of
  * this object calls {@link #invalidate()}.
  * <p>
  * To create an instance of this class, use {@link #of(NonNullSupplier)}. Note
@@ -150,7 +150,7 @@ public class LazyOptional<T>
      * If non-empty, invoke the specified {@link NonNullConsumer} with the object,
      * otherwise do nothing.
      *
-     * @param The {@link NonNullConsumer} to run if this optional is non-empty.
+     * @param consumer The {@link NonNullConsumer} to run if this optional is non-empty.
      * @throws NullPointerException if {@code consumer} is null and this {@link LazyOptional} is non-empty
      */
     public void ifPresent(NonNullConsumer<? super T> consumer)
@@ -171,19 +171,41 @@ public class LazyOptional<T>
      * @apiNote This method supports post-processing on optional values, without the
      *          need to explicitly check for a return status.
      *
-     * @param        <U> The type of the result of the mapping function
+     * @apiNote The returned value does not receive invalidation messages from the original {@link LazyOptional}.
+     *          If you need the invalidation, you will need to manage them yourself.
+     *
      * @param mapper A mapping function to apply to the mod object, if present
      * @return A {@link LazyOptional} describing the result of applying a mapping
      *         function to the value of this {@link LazyOptional}, if a value is
      *         present, otherwise an empty {@link LazyOptional}
-     * @throws NullPointerException if {@code mapper} is null and this {@link LazyOptional} is non-empty
+     * @throws NullPointerException if {@code mapper} is null.
      */
-    public <U> LazyOptional<U> map(NonNullFunction<? super T, ? extends U> mapper)
+    public <U> LazyOptional<U> lazyMap(NonNullFunction<? super T, ? extends U> mapper)
     {
         Objects.requireNonNull(mapper);
         return isPresent() ? of(() -> mapper.apply(getValueUnsafe())) : empty();
     }
 
+    /**
+     * If a this {@link LazyOptional} is non-empty, return a new
+     * {@link Optional} encapsulating the mapped value. Otherwise, returns
+     * {@link Optional#empty()}.
+     *
+     * @apiNote This method explicitly resolves the value of the {@link LazyOptional}.
+     *          For a non-resolving mapper that will lazily run the mapping, use {@link #lazyMap(NonNullFunction)}.
+     *
+     * @param mapper A mapping function to apply to the mod object, if present
+     * @return An {@link Optional} describing the result of applying a mapping
+     *         function to the value of this {@link Optional}, if a value is
+     *         present, otherwise an empty {@link Optional}
+     * @throws NullPointerException if {@code mapper} is null.
+     */
+    public <U> Optional<U> map(NonNullFunction<? super T, ? extends U> mapper)
+    {
+        Objects.requireNonNull(mapper);
+        return isPresent() ? Optional.of(mapper.apply(getValueUnsafe())) : Optional.empty();
+    }
+
     /**
      * Resolve the contained supplier if non-empty, and filter it by the given
      * {@link NonNullPredicate}, returning empty if false.
@@ -194,17 +216,26 @@ public class LazyOptional<T>
      * 
      * @param predicate A {@link NonNullPredicate} to apply to the result of the
      *                  contained supplier, if non-empty
-     * @return A {@link LazyOptional} containing the result of the contained
+     * @return An {@link Optional} containing the result of the contained
      *         supplier, if and only if the passed {@link NonNullPredicate} returns
-     *         true, otherwise an empty {@link LazyOptional}
+     *         true, otherwise an empty {@link Optional}
      * @throws NullPointerException If {@code predicate} is null and this
-     *                              {@link LazyOptional} is non-empty
+     *                              {@link Optional} is non-empty
      */
-    public LazyOptional<T> filter(NonNullPredicate<? super T> predicate)
+    public Optional<T> filter(NonNullPredicate<? super T> predicate)
     {
         Objects.requireNonNull(predicate);
         final T value = getValue(); // To keep the non-null contract we have to evaluate right now. Should we allow this function at all?
-        return value != null && predicate.test(value) ? of(() -> value) : empty();
+        return value != null && predicate.test(value) ? Optional.of(value) : Optional.empty();
+    }
+
+    /**
+     * Resolves the value of this LazyOptional, turning it into a standard non-lazy {@link Optional<T>}
+     * @return The resolved optional.
+     */
+    public Optional<T> resolve()
+    {
+        return isPresent() ? Optional.of(getValueUnsafe()) : Optional.empty();
     }
 
     /**

src/main/java/net/minecraftforge/event/AddReloadListenerEvent.java

@@ -1,3 +1,22 @@
+/*
+ * Minecraft Forge
+ * Copyright (c) 2016-2020.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation version 2.1
+ * of the License.
+ *
+ * This library 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 this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
 package net.minecraftforge.event;
 
 import com.google.common.collect.ImmutableList;

src/main/java/net/minecraftforge/event/RegisterCommandsEvent.java

@@ -1,3 +1,22 @@
+/*
+ * Minecraft Forge
+ * Copyright (c) 2016-2020.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation version 2.1
+ * of the License.
+ *
+ * This library 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 this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
 package net.minecraftforge.event;
 
 import com.mojang.brigadier.CommandDispatcher;

src/main/java/net/minecraftforge/event/entity/EntityLeaveWorldEvent.java

@@ -1,3 +1,22 @@
+/*
+ * Minecraft Forge
+ * Copyright (c) 2016-2020.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation version 2.1
+ * of the License.
+ *
+ * This library 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 this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
 package net.minecraftforge.event.entity;
 
 import net.minecraftforge.common.MinecraftForge;

src/main/java/net/minecraftforge/fluids/FluidUtil.java

@@ -48,6 +48,8 @@ import net.minecraftforge.items.CapabilityItemHandler;
 import net.minecraftforge.items.IItemHandler;
 import net.minecraftforge.items.ItemHandlerHelper;
 
+import java.util.Optional;
+
 public class FluidUtil
 {
     private FluidUtil()
@@ -428,7 +430,7 @@ public class FluidUtil
     /**
      * Helper method to get the fluid contained in an itemStack
      */
-    public static LazyOptional<FluidStack> getFluidContained(@Nonnull ItemStack container)
+    public static Optional<FluidStack> getFluidContained(@Nonnull ItemStack container)
     {
         if (!container.isEmpty())
         {
@@ -436,7 +438,7 @@ public class FluidUtil
             return getFluidHandler(container)
                     .map(handler -> handler.drain(Integer.MAX_VALUE, IFluidHandler.FluidAction.SIMULATE));
         }
-        return LazyOptional.empty();
+        return Optional.empty();
     }
 
     /**

src/main/java/net/minecraftforge/fml/client/gui/screen/ConfirmationScreen.java

@@ -15,9 +15,9 @@
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
- *//*
+ */
-
 
+/*
 package net.minecraftforge.fml.client.gui.screen;
 import net.minecraft.client.gui.widget.button.Button;
 import net.minecraft.util.text.StringTextComponent;

src/main/java/net/minecraftforge/fml/client/gui/screen/NotificationScreen.java

@@ -15,9 +15,9 @@
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
- *//*
+ */
-
 
+/*
 package net.minecraftforge.fml.client.gui.screen;
 
 import com.mojang.blaze3d.matrix.MatrixStack;

src/main/java/net/minecraftforge/fml/event/lifecycle/IModBusEvent.java

@@ -1,3 +1,22 @@
+/*
+ * Minecraft Forge
+ * Copyright (c) 2016-2020.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation version 2.1
+ * of the License.
+ *
+ * This library 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 this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
 package net.minecraftforge.fml.event.lifecycle;
 
 /**

src/main/java/net/minecraftforge/items/VanillaInventoryCodeHooks.java

@@ -38,6 +38,7 @@ import org.apache.commons.lang3.tuple.Pair;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
+import java.util.Optional;
 
 public class VanillaInventoryCodeHooks
 {
@@ -210,7 +211,7 @@ public class VanillaInventoryCodeHooks
         return stack;
     }
 
-    private static LazyOptional<Pair<IItemHandler, Object>> getItemHandler(IHopper hopper, Direction hopperFacing)
+    private static Optional<Pair<IItemHandler, Object>> getItemHandler(IHopper hopper, Direction hopperFacing)
     {
         double x = hopper.getXPos() + (double) hopperFacing.getXOffset();
         double y = hopper.getYPos() + (double) hopperFacing.getYOffset();
@@ -244,7 +245,7 @@ public class VanillaInventoryCodeHooks
         return true;
     }
 
-    public static LazyOptional<Pair<IItemHandler, Object>> getItemHandler(World worldIn, double x, double y, double z, final Direction side)
+    public static Optional<Pair<IItemHandler, Object>> getItemHandler(World worldIn, double x, double y, double z, final Direction side)
     {
         int i = MathHelper.floor(x);
         int j = MathHelper.floor(y);
@@ -262,6 +263,6 @@ public class VanillaInventoryCodeHooks
             }
         }
 
-        return LazyOptional.empty();
+        return Optional.empty();
     }
 }

src/test/java/net/minecraftforge/debug/block/ToolInteractTest.java

@@ -1,3 +1,22 @@
+/*
+ * Minecraft Forge
+ * Copyright (c) 2016-2020.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation version 2.1
+ * of the License.
+ *
+ * This library 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 this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
 package net.minecraftforge.debug.block;
 
 import org.apache.logging.log4j.LogManager;

src/test/java/net/minecraftforge/debug/entity/player/PlayerNameEventTest.java

@@ -1,3 +1,22 @@
+/*
+ * Minecraft Forge
+ * Copyright (c) 2016-2020.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation version 2.1
+ * of the License.
+ *
+ * This library 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 this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
 package net.minecraftforge.debug.entity.player;
 
 import net.minecraft.util.text.StringTextComponent;

src/test/java/net/minecraftforge/debug/item/CustomElytraTest.java

@@ -1,6 +1,6 @@
 /*
  * Minecraft Forge
- * Copyright (c) 2016-2019.
+ * Copyright (c) 2016-2020.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public

src/test/java/net/minecraftforge/debug/item/EnderMaskTest.java

@@ -1,3 +1,22 @@
+/*
+ * Minecraft Forge
+ * Copyright (c) 2016-2020.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation version 2.1
+ * of the License.
+ *
+ * This library 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 this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
 package net.minecraftforge.debug.item;
 
 import net.minecraft.entity.monster.EndermanEntity;

src/test/java/net/minecraftforge/debug/world/RaidEnumTest.java

@@ -1,3 +1,22 @@
+/*
+ * Minecraft Forge
+ * Copyright (c) 2016-2020.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation version 2.1
+ * of the License.
+ *
+ * This library 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 this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
 package net.minecraftforge.debug.world;
 
 import net.minecraft.entity.EntityType;