[API-8] Resource Management

src/main/java/org/spongepowered/api/CatalogTypes.java

@@ -96,6 +96,9 @@
 import org.spongepowered.api.item.recipe.crafting.CraftingRecipe;
 import org.spongepowered.api.placeholder.PlaceholderParser;
 import org.spongepowered.api.registry.GameRegistry;
+import org.spongepowered.api.resource.meta.MetaSection;
+import org.spongepowered.api.resource.pack.PackType;
+import org.spongepowered.api.resource.pack.PackVersion;
 import org.spongepowered.api.scoreboard.CollisionRule;
 import org.spongepowered.api.scoreboard.Visibility;
 import org.spongepowered.api.scoreboard.criteria.Criterion;
@@ -229,6 +232,8 @@ public final class CatalogTypes {
 
     public static final Class<LlamaType> LLAMA_TYPE = LlamaType.class;
 
+    public static final Class<MetaSection> META_SECTION = MetaSection.class;
+
     public static final Class<MooshroomType> MOOSHROOM_TYPE = MooshroomType.class;
 
     public static final Class<MovementType> MOVEMENT_TYPE = MovementType.class;
@@ -241,6 +246,10 @@ public final class CatalogTypes {
 
     public static final Class<Operation> BLOCK_TRANSACTION_OPERATION = Operation.class;
 
+    public static final Class<PackType> PACK_TYPE = PackType.class;
+
+    public static final Class<PackVersion> PACK_VERSION = PackVersion.class;
+
     public static final Class<PandaGene> PANDA_GENE = PandaGene.class;
 
     public static final Class<ParrotType> PARROT_TYPE = ParrotType.class;

src/main/java/org/spongepowered/api/Engine.java

@@ -25,9 +25,17 @@
 package org.spongepowered.api;
 
 import org.spongepowered.api.event.CauseStackManager;
+import org.spongepowered.api.resource.Resource;
+import org.spongepowered.api.resource.ResourceManager;
+import org.spongepowered.api.resource.ResourceReloadListener;
+import org.spongepowered.api.resource.pack.Pack;
+import org.spongepowered.api.resource.pack.PackDiscoverer;
+import org.spongepowered.api.resource.pack.PackList;
 import org.spongepowered.api.registry.ScopedRegistryHolder;
 import org.spongepowered.api.scheduler.Scheduler;
 
+import java.util.concurrent.CompletableFuture;
+
 /**
  * Shared functionality between {@link Client} and {@link Server} engines.
  */
@@ -47,6 +55,20 @@ public interface Engine extends ScopedRegistryHolder {
      */
     CauseStackManager getCauseStackManager();
 
+    /**
+     * Gets the {@link PackList} instance of this engine.
+     *
+     * @return The pack list
+     */
+    PackList getPackList();
+
+    /**
+     * Gets the {@link ResourceManager} for this engine.
+     *
+     * @return The resource manager
+     */
+    ResourceManager getResourceManager();
+
     /**
      * Gets the {@link Scheduler} used to schedule sync tasks on this {@link Engine}.
      *
@@ -60,4 +82,14 @@ public interface Engine extends ScopedRegistryHolder {
      * @return {@code true} if main thread, {@code false} if not
      */
     boolean onMainThread();
+
+    /**
+     * Rediscovers {@link Pack}s using all registered {@link PackDiscoverer}s and
+     * reloads all {@link Resource}s by running all registered {@link ResourceReloadListener}s.
+     *
+     * <p>On the server, the future will always be completed.</p>
+     *
+     * @return A future that completes when reloading is complete
+     */
+    CompletableFuture<Void> reloadResources();
 }

src/main/java/org/spongepowered/api/event/resource/RegisterPackDiscovererEvent.java

@@ -0,0 +1,43 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package org.spongepowered.api.event.resource;
+
+import org.spongepowered.api.Engine;
+import org.spongepowered.api.event.GenericEvent;
+import org.spongepowered.api.resource.pack.PackDiscoverer;
+import org.spongepowered.api.resource.pack.PackList;
+
+/**
+ * Event for registering {@link PackDiscoverer}s.
+ */
+public interface RegisterPackDiscovererEvent<T extends Engine> extends GenericEvent<T> {
+
+    /**
+     * Adds a {@link PackDiscoverer} to the {@link PackList}.
+     *
+     * @param discoverer The discoverer
+     */
+    void register(PackDiscoverer discoverer);
+}

src/main/java/org/spongepowered/api/event/resource/RegisterResourceReloadListenerEvent.java

@@ -0,0 +1,45 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package org.spongepowered.api.event.resource;
+
+import org.spongepowered.api.Engine;
+import org.spongepowered.api.event.GenericEvent;
+import org.spongepowered.api.resource.ResourceManager;
+import org.spongepowered.api.resource.ResourceReloadListener;
+
+/**
+ * Event for registering {@link ResourceReloadListener reload listeners} to the
+ * {@link ResourceManager}.
+ */
+public interface RegisterResourceReloadListenerEvent<T extends Engine> extends GenericEvent<T> {
+
+    /**
+     * Adds a reload listener to the resource manager.
+     *
+     * @param listener The listener
+     * @see ResourceReloadListener
+     */
+    void register(ResourceReloadListener listener);
+}

src/main/java/org/spongepowered/api/event/resource/package-info.java

@@ -0,0 +1,26 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+@org.checkerframework.framework.qual.DefaultQualifier(org.checkerframework.checker.nullness.qual.NonNull.class)
+package org.spongepowered.api.event.resource;

src/main/java/org/spongepowered/api/registry/Registries.java

@@ -110,6 +110,9 @@
 import org.spongepowered.api.item.potion.PotionType;
 import org.spongepowered.api.item.recipe.RecipeType;
 import org.spongepowered.api.placeholder.PlaceholderParser;
+import org.spongepowered.api.resource.meta.NamedMetaSection;
+import org.spongepowered.api.resource.pack.PackType;
+import org.spongepowered.api.resource.pack.PackVersion;
 import org.spongepowered.api.scheduler.TaskPriority;
 import org.spongepowered.api.scoreboard.CollisionRule;
 import org.spongepowered.api.scoreboard.Visibility;
@@ -303,6 +306,8 @@ public final class Registries {
 
     public static final RegistryKey<Registry<MusicDisc>> MUSIC_DISC = Registries.spongeKey("music_disc");
 
+    public static final RegistryKey<Registry<NamedMetaSection<?>>> NAMED_META_SECTION = Registries.spongeKey("named_meta_section");
+
     public static final RegistryKey<Registry<NotePitch>> NOTE_PITCH = Registries.spongeKey("note_pitch");
 
     public static final RegistryKey<Registry<ObjectiveDisplayMode>> OBJECTIVE_DISPLAY_MODE = Registries.spongeKey("objective_display_mode");
@@ -311,6 +316,10 @@ public final class Registries {
 
     public static final RegistryKey<Registry<Orientation>> ORIENTATION = Registries.spongeKey("orientation");
 
+    public static final RegistryKey<Registry<PackType>> PACK_TYPE = Registries.spongeKey("pack_type");
+
+    public static final RegistryKey<Registry<PackVersion>> PACK_VERSION = Registries.spongeKey("pack_version");
+
     public static final RegistryKey<Registry<PaletteType<?>>> PALETTE_TYPE = Registries.spongeKey("palette_type");
 
     public static final RegistryKey<Registry<PandaGene>> PANDA_GENE = Registries.spongeKey("panda_gene");

src/main/java/org/spongepowered/api/resource/Resource.java

@@ -0,0 +1,146 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package org.spongepowered.api.resource;
+
+import org.spongepowered.api.data.persistence.DataFormat;
+import org.spongepowered.api.data.persistence.DataFormats;
+import org.spongepowered.api.data.persistence.DataView;
+import org.spongepowered.api.resource.meta.MetaSection;
+import org.spongepowered.api.resource.meta.NamedMetaSections;
+import org.spongepowered.api.resource.pack.PackInfo;
+import org.spongepowered.api.resource.pack.PackList;
+
+import java.io.BufferedReader;
+import java.io.Closeable;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
+import java.util.Optional;
+import java.util.stream.Stream;
+
+/**
+ * A resource can represent any kind of loaded data. It can be a file on the
+ * filesystem, a network location, or even generated at runtime. Use
+ * {@link #getInputStream()} to load the data held by a resource.
+ */
+public interface Resource extends Closeable {
+
+    /**
+     * Gets the path of this resource.
+     *
+     * @return The path
+     */
+    ResourcePath getPath();
+
+    /**
+     * Gets the name of the {@link PackInfo pack} which owns this resource. To
+     * get the instance, feed the returned value to
+     * {@link PackList#get(String)}.
+     *
+     * @return The parent pack.
+     * @see PackList#get(String)
+     */
+    String getPack();
+
+    /**
+     * Returns the {@link InputStream} of this resource. Multiple calls to this
+     * method will not return a new object. To get a new object, get a new
+     * resource.
+     *
+     * @return The input stream
+     */
+    InputStream getInputStream();
+
+    /**
+     * Checks whether this resource has metadata or not.
+     *
+     * @return True if this resource has metadata, false otherwise
+     */
+    boolean hasMetadata();
+
+    /**
+     * Gets the specified metadata section for this resource or
+     * {@link Optional#empty()} if it has no metadata.
+     *
+     * @param section The section serializer
+     * @return The metadata or empty if it doesn't exist
+     * @see NamedMetaSections
+     */
+    <T> Optional<T> getMetadata(MetaSection<T> section);
+
+    /**
+     * Creates a new {@link BufferedReader} from this resource's
+     * {@link InputStream}.
+     *
+     * @param charset The charset to use, usually utf-8
+     * @return The BufferedReader
+     */
+    BufferedReader newBufferedReader(Charset charset);
+
+    /**
+     * Reads the resource as text.
+     *
+     * @param charset The charset of the text, usually utf-8
+     * @return The text of the resource
+     * @throws IOException If an I/O error occurs
+     * @see StandardCharsets
+     */
+    String readString(Charset charset) throws IOException;
+
+    /**
+     * Reads all the toBytes from this resource and returns them in a byte array.
+     *
+     * @return The toBytes of the resource
+     * @throws IOException If an I/O error occurs
+     */
+    byte[] readBytes() throws IOException;
+
+    /**
+     * Reads the resource and returns a {@link DataView} which corresponds to
+     * the appropriate {@link DataFormat}.
+     *
+     * @param format The data format to use
+     * @return The data view
+     * @throws IOException If an I/O error occurs
+     * @see DataFormats
+     */
+    DataView readDataView(DataFormat format) throws IOException;
+
+    /**
+     * Reads the resource as text and returns a stream of lines.
+     *
+     * <p>Just like {@link BufferedReader#lines()}, the stream will wrap any
+     * {@link IOException} thrown in an {@link java.io.UncheckedIOException}.
+     * </p>
+     *
+     * @param charset The charset of the text, usually utf-8
+     * @return A stream of readLines of the resource
+     * @see StandardCharsets
+     * @see BufferedReader#lines()
+     */
+    Stream<String> lines(Charset charset);
+
+}