feat(API): Implements a featured API for GT_Fluid (#1345)

* feat(API): Implements a featured API for GT_Fluid

*** Rationale

The current implementation, which is based on the `GT_Fluid` object,
does not allow for the evolution of the functionalities, or the
variation of the fluid-related implementations in GregTech.

*** Objectives

This replacement API should free from these constraints, by providing :

1. The separation of responsibilities of the different tasks and steps:
  - The definition and progressive construction of an `IGT_Fluid`,
  - Registration of the `IGT_Fluid`,
  - Configuration of related equipment, such as containers,
  - Propagation of properties of an `IGT_Fluid` to related services
    such as Materials

2. The separation of interfaces exposed to the API from their internal
   implementations to allow:
  - Evolve the implementations in the most transparent way possible
  - To have internal GregTech implementations or outsourced
    implementations coexist in its extensions.

*** Specificity of this new API

- Provides a new interface to build and interact with fluid related records
- Deprecates the old `api/objects/GT_Fluid` object and the
  `common/GT_Proxy.addFluid` record methods

* fix(conversations): addresses @Glease review comments

https://github.com/GTNewHorizons/GT5-Unofficial/pull/1345#pullrequestreview-1096261703

* ./gradlew :spotlessApply

* fix(review): add review comments from @eigenraven

Added missing final qualifiers on methods parameters.
https://github.com/GTNewHorizons/GT5-Unofficial/pull/1345#pullrequestreview-1096318523

* fix(review) address remaining review comments from @eigenraven

2 files changed, 153 insertions, 0 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
new file mode 100644
index 0000000000..1a34b44b5a
--- /dev/null
+++ b/src/main/java/gregtech/api/interfaces/fluid/IGT_Fluid.java
@@ -0,0 +1,71 @@
+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;
+
+public interface IGT_Fluid {
+
+    /**
+     * Registers this {@link IGT_Fluid} to ths {@link FluidRegistry}
+     *
+     * @return {@link IGT_Fluid} self for call chaining
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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();
+}
diff --git a/src/main/java/gregtech/api/interfaces/fluid/IGT_FluidBuilder.java b/src/main/java/gregtech/api/interfaces/fluid/IGT_FluidBuilder.java
new file mode 100644
index 0000000000..1e5ec60fa0
--- /dev/null
+++ b/src/main/java/gregtech/api/interfaces/fluid/IGT_FluidBuilder.java
@@ -0,0 +1,82 @@
+package gregtech.api.interfaces.fluid;
+
+import gregtech.api.enums.FluidState;
+import net.minecraft.block.Block;
+import net.minecraft.util.ResourceLocation;
+import net.minecraftforge.fluids.Fluid;
+import net.minecraftforge.fluids.FluidRegistry;
+
+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
+     */
+    IGT_FluidBuilder withColorRGBA(final short[] colorRGBA);
+
+    /**
+     * @param localizedName The localized name of this {@link IGT_FluidBuilder}
+     * @return {@link IGT_FluidBuilder} self for call chaining
+     */
+    IGT_FluidBuilder withLocalizedName(final String localizedName);
+
+    /**
+     * @param fluidState  The {@link FluidState} of this {@link IGT_FluidBuilder}
+     * @param temperature The Kelvin temperature of this {@link IGT_FluidBuilder}
+     * @return {@link IGT_FluidBuilder} self for call chaining
+     */
+    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
+     */
+    IGT_FluidBuilder withStillIconResourceLocation(final ResourceLocation stillIconResourceLocation);
+
+    /**
+     * @param flowingIconResourceLocation the {@link ResourceLocation} of the flowing fluid icon
+     * @return {@link IGT_FluidBuilder} self for call chaining
+     */
+    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
+     */
+    IGT_FluidBuilder withTextureName(final String textureName);
+
+    /**
+     * @param fromGTFluid the {@link IGT_Fluid} to copy the texture from
+     * @return {@link IGT_FluidBuilder} self for call chaining
+     */
+    IGT_FluidBuilder withTextureFrom(final IGT_Fluid fromGTFluid);
+
+    /**
+     * @param fluidBlock the {@link Block} implementation of the {@link IGT_Fluid}
+     * @return {@link IGT_FluidBuilder} self for call chaining
+     */
+    IGT_FluidBuilder withFluidBlock(final Block fluidBlock);
+
+    /**
+     * @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
+     */
+    IGT_FluidBuilder withTextures(
+            final ResourceLocation stillIconResourceLocation, final ResourceLocation flowingIconResourceLocation);
+
+    /**
+     * Builds the {@link IGT_Fluid}
+     *
+     * @return the built {@link IGT_Fluid}
+     */
+    IGT_Fluid build();
+
+    /**
+     * Builds, then adds the {@link IGT_Fluid} to the {@link FluidRegistry}
+     *
+     * @return the {@link IGT_Fluid}
+     * @see #build()
+     * @see IGT_Fluid#addFluid()
+     */
+    IGT_Fluid buildAndRegister();
+}