refactor(fluid_api): fluent interface (#1407)

* refactor(fluid_api): fluent interface

Improves the initial construction model into a fluent interface.
See: https://java-design-patterns.com/patterns/fluentinterface/

This change provides the built and saved states of a GT_Fluid,
with their own interface, so that: object state validations are
performed at build time, rather than causing an `IllegalStateException`
to be thrown at runtime, with the previous implementation.

This also allows the IDE to display and check the applicable methods
for the GT_Fluid object's state, as it moves through the call chain.

* hotfix off-by-one in FluidState.fromValue

* minor: deduplicate buildAndRegister action

* fix(withIconsFrom): needs dependency management

Cracked fluid Icons were copied too early from non-cracked fluid
within the `IGT_FluidBuilder`'s implementation.
At this stage, the source Fluid has not registered its own icons yet,
so the Cracked fluid got null Icons (fallback to Error checkerboard).

This commit delegates the copy of the source fluid's Icons, to the
`run` Icons texture's registration task; ensuring the source Fluid
runs its own Icons textures registration before copying them,
as a light-weight dependency management.

3 files changed, 73 insertions, 74 deletions

diff --git a/src/main/java/gregtech/api/interfaces/fluid/IGT_Fluid.java b/src/main/java/gregtech/api/interfaces/fluid/IGT_Fluid.java
index 5529e111bb..7c8b2b3f11 100644
--- a/src/main/java/gregtech/api/interfaces/fluid/IGT_Fluid.java
+++ b/src/main/java/gregtech/api/interfaces/fluid/IGT_Fluid.java
@@ -1,11 +1,5 @@
 package gregtech.api.interfaces.fluid;
 
-import gregtech.api.enums.FluidState;
-import gregtech.api.enums.Materials;
-import net.minecraft.item.ItemStack;
-import net.minecraft.util.ResourceLocation;
-import net.minecraftforge.fluids.Fluid;
-import net.minecraftforge.fluids.FluidContainerRegistry;
 import net.minecraftforge.fluids.FluidRegistry;
 
 @SuppressWarnings("unused") // API might legitimately expose unused methods within this local project's scope
@@ -14,68 +8,7 @@ public interface IGT_Fluid {
     /**
      * Adds this {@link IGT_Fluid} to the {@link FluidRegistry} and internally-implemented registrations
      *
-     * @return {@link IGT_Fluid} self for call chaining
+     * @return {@link IGT_RegisteredFluid} The GregTech registered fluid
      */
-    IGT_Fluid addFluid();
-
-    /**
-     * Registers the containers in the {@link FluidContainerRegistry} for this {@link IGT_Fluid}
-     *
-     * @param fullContainer  The full fluid container
-     * @param emptyContainer The empty fluid container
-     * @param containerSize  The size of the container
-     * @return The {@link IGT_Fluid} for chaining
-     *
-     * @throws IllegalStateException on attempt to register containers for an unregistered fluid
-     */
-    IGT_Fluid registerContainers(
-            final ItemStack fullContainer, final ItemStack emptyContainer, final int containerSize);
-
-    /**
-     * Registers the bucket-sized 1000L containers in the {@link FluidContainerRegistry} for this {@link IGT_Fluid}
-     *
-     * @param fullContainer  The full container to associate with this {@link IGT_Fluid}
-     * @param emptyContainer The empty container associate with this {@link IGT_Fluid}
-     * @return {@link IGT_Fluid} self for call chaining
-     *
-     * @throws IllegalStateException on attempt to register containers for an unregistered fluid
-     */
-    IGT_Fluid registerBContainers(final ItemStack fullContainer, final ItemStack emptyContainer);
-
-    /**
-     * Registers the potion-sized 250L containers in the {@link FluidContainerRegistry} for this {@link IGT_Fluid}
-     *
-     * @param fullContainer  The full container to associate with this {@link IGT_Fluid}
-     * @param emptyContainer The empty container associate with this {@link IGT_Fluid}
-     * @return {@link IGT_Fluid} self for call chaining
-     *
-     * @throws IllegalStateException on attempt to register containers for an unregistered fluid
-     */
-    IGT_Fluid registerPContainers(final ItemStack fullContainer, final ItemStack emptyContainer);
-
-    /**
-     * Updates the {@link Materials}'s fluids from this {@link IGT_Fluid}'s state
-     *
-     * @param material the {@link Materials} to configure based on this {@link IGT_Fluid} and {@link FluidState}
-     * @return The {@link IGT_Fluid} for chaining
-     *
-     * @throws IllegalStateException on unknown {@link FluidState}
-     * @throws IllegalStateException on attempt to register containers for an unregistered fluid
-     */
-    IGT_Fluid configureMaterials(final Materials material);
-
-    /**
-     * @return this {@link IGT_Fluid} cast to {@link Fluid}
-     */
-    Fluid asFluid();
-
-    /**
-     * @return the {@link ResourceLocation} of the still fluid texture
-     */
-    ResourceLocation getStillIconResourceLocation();
-
-    /**
-     * @return the {@link ResourceLocation} of the flowing fluid texture
-     */
-    ResourceLocation getFlowingIconResourceLocation();
+    IGT_RegisteredFluid addFluid();
 }
diff --git a/src/main/java/gregtech/api/interfaces/fluid/IGT_FluidBuilder.java b/src/main/java/gregtech/api/interfaces/fluid/IGT_FluidBuilder.java
index 4010a465ce..a643b8aace 100644
--- a/src/main/java/gregtech/api/interfaces/fluid/IGT_FluidBuilder.java
+++ b/src/main/java/gregtech/api/interfaces/fluid/IGT_FluidBuilder.java
@@ -1,6 +1,7 @@
 package gregtech.api.interfaces.fluid;
 
 import gregtech.api.enums.FluidState;
+import javax.annotation.Nonnull;
 import net.minecraft.block.Block;
 import net.minecraft.util.ResourceLocation;
 import net.minecraftforge.fluids.Fluid;
@@ -12,12 +13,14 @@ public interface IGT_FluidBuilder {
      * @param colorRGBA The {@code short[]} RGBA color of the {@link Fluid} or {@code null} for no defined RGBA color
      * @return {@link IGT_FluidBuilder} self for call chaining
      */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
     IGT_FluidBuilder withColorRGBA(final short[] colorRGBA);
 
     /**
      * @param localizedName The localized name of this {@link IGT_FluidBuilder}
      * @return {@link IGT_FluidBuilder} self for call chaining
      */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
     IGT_FluidBuilder withLocalizedName(final String localizedName);
 
     /**
@@ -25,43 +28,50 @@ public interface IGT_FluidBuilder {
      * @param temperature The Kelvin temperature of this {@link IGT_FluidBuilder}
      * @return {@link IGT_FluidBuilder} self for call chaining
      */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
     IGT_FluidBuilder withStateAndTemperature(final FluidState fluidState, final int temperature);
 
     /**
      * @param stillIconResourceLocation the {@link ResourceLocation} of the still fluid icon
      * @return {@link IGT_FluidBuilder} self for call chaining
      */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
     IGT_FluidBuilder withStillIconResourceLocation(final ResourceLocation stillIconResourceLocation);
 
     /**
      * @param flowingIconResourceLocation the {@link ResourceLocation} of the flowing fluid icon
      * @return {@link IGT_FluidBuilder} self for call chaining
      */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
     IGT_FluidBuilder withFlowingIconResourceLocation(final ResourceLocation flowingIconResourceLocation);
 
     /**
      * @param textureName The name of the GregTech mod texture of this {@link IGT_FluidBuilder}
      * @return {@link IGT_FluidBuilder} self for call chaining
      */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
     IGT_FluidBuilder withTextureName(final String textureName);
 
     /**
-     * @param fromGTFluid the {@link IGT_Fluid} to copy the texture from
+     * @param fluidBlock the {@link Block} implementation of the {@link IGT_Fluid}
      * @return {@link IGT_FluidBuilder} self for call chaining
      */
-    IGT_FluidBuilder withTextureFrom(final IGT_Fluid fromGTFluid);
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
+    IGT_FluidBuilder withFluidBlock(final Block fluidBlock);
 
     /**
-     * @param fluidBlock the {@link Block} implementation of the {@link IGT_Fluid}
+     * @param fromFluid the {@link Fluid} to copy the icons from
      * @return {@link IGT_FluidBuilder} self for call chaining
      */
-    IGT_FluidBuilder withFluidBlock(final Block fluidBlock);
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
+    IGT_FluidBuilder withIconsFrom(@Nonnull final Fluid fromFluid);
 
     /**
      * @param stillIconResourceLocation   The {@link ResourceLocation} of the still fluid texture
      * @param flowingIconResourceLocation The {@link ResourceLocation} of the flowing fluid texture
      * @return {@link IGT_FluidBuilder} self for call chaining
      */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
     IGT_FluidBuilder withTextures(
             final ResourceLocation stillIconResourceLocation, final ResourceLocation flowingIconResourceLocation);
 
@@ -79,5 +89,5 @@ public interface IGT_FluidBuilder {
      * @see #build()
      * @see IGT_Fluid#addFluid()
      */
-    IGT_Fluid buildAndRegister();
+    IGT_RegisteredFluid buildAndRegister();
 }
diff --git a/src/main/java/gregtech/api/interfaces/fluid/IGT_RegisteredFluid.java b/src/main/java/gregtech/api/interfaces/fluid/IGT_RegisteredFluid.java
new file mode 100644
index 0000000000..1d8cd2384f
--- /dev/null
+++ b/src/main/java/gregtech/api/interfaces/fluid/IGT_RegisteredFluid.java
@@ -0,0 +1,56 @@
+package gregtech.api.interfaces.fluid;
+
+import gregtech.api.enums.FluidState;
+import gregtech.api.enums.Materials;
+import net.minecraft.item.ItemStack;
+import net.minecraftforge.fluids.Fluid;
+import net.minecraftforge.fluids.FluidContainerRegistry;
+
+public interface IGT_RegisteredFluid {
+
+    /**
+     * Registers the containers in the {@link FluidContainerRegistry} for this {@link IGT_Fluid}
+     *
+     * @param fullContainer  The full fluid container
+     * @param emptyContainer The empty fluid container
+     * @param containerSize  The size of the container
+     * @return The {@link IGT_RegisteredFluid} for call chaining
+     */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
+    IGT_RegisteredFluid registerContainers(
+            final ItemStack fullContainer, final ItemStack emptyContainer, final int containerSize);
+
+    /**
+     * Registers the bucket-sized 1000L containers in the {@link FluidContainerRegistry} for this {@link IGT_Fluid}
+     *
+     * @param fullContainer  The full container to associate with this {@link IGT_Fluid}
+     * @param emptyContainer The empty container associate with this {@link IGT_Fluid}
+     * @return {@link IGT_RegisteredFluid} for call chaining
+     */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
+    IGT_RegisteredFluid registerBContainers(final ItemStack fullContainer, final ItemStack emptyContainer);
+
+    /**
+     * Registers the potion-sized 250L containers in the {@link FluidContainerRegistry} for this {@link IGT_Fluid}
+     *
+     * @param fullContainer  The full container to associate with this {@link IGT_Fluid}
+     * @param emptyContainer The empty container associate with this {@link IGT_Fluid}
+     * @return {@link IGT_RegisteredFluid} self for call chaining
+     */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
+    IGT_RegisteredFluid registerPContainers(final ItemStack fullContainer, final ItemStack emptyContainer);
+
+    /**
+     * Updates the {@link Materials}'s fluids from this {@link IGT_Fluid}'s state
+     *
+     * @param material the {@link Materials} to configure based on this {@link IGT_Fluid} and {@link FluidState}
+     * @return The {@link IGT_RegisteredFluid} for call chaining
+     */
+    @SuppressWarnings("UnusedReturnValue") // Last call in chain, may not use this returned value
+    IGT_RegisteredFluid configureMaterials(final Materials material);
+
+    /**
+     * @return this {@link IGT_Fluid} cast to {@link Fluid}
+     */
+    Fluid asFluid();
+}