Last round of changes for 0.8.0

- PluginLoader -> ContainerLoader - Remove StandardInheritable toBuilder, add back StandardPluginMetadata toBuilder (this would be used far more) - Remaining javadocs on non-builtin classes and rewordings Signed-off-by: Chris Sanders <[email protected]>
SpongePowered · Sep 4, 2021 · 1bb9edd · 1bb9edd
1 parent f388fd2
commit 1bb9edd
Show file tree

Hide file tree

Showing 18 changed files with 203 additions and 116 deletions.
diff --git a/src/main/java/org/spongepowered/plugin/metadata/Container.java b/src/main/java/org/spongepowered/plugin/metadata/Container.java
@@ -24,47 +24,51 @@
  */
 package org.spongepowered.plugin.metadata;
 
-import org.spongepowered.plugin.metadata.model.PluginLoader;
+import org.apache.maven.artifact.Artifact;
+import org.spongepowered.plugin.metadata.model.ContainerLoader;
 
 import java.util.Optional;
 import java.util.Set;
 
 /**
  *  A container joins together {@link Inheritable global metadata} with specific one or more
  *  {@link PluginMetadata plugin metadata}.
+ *  <p>
+ *  How the vendor utilizes this concept is largely left up to their discretion. A
+ *  typical use case would be to load a file as a container.
  *
- *  <p>How a library consumer utilizes this concept is largely left up to their discretion. A
- *  typical use case would be to load a file as a container</p>
- *
- * @see org.spongepowered.plugin.metadata.builtin.MetadataContainer for a generic implementation
+ * @see org.spongepowered.plugin.metadata.builtin.MetadataContainer MetadataContainer, for a generic implementation
  */
 public interface Container {
 
     /**
-     * @return The {@link PluginLoader loader}.
+     * @return The {@link ContainerLoader loader}.
      */
-    PluginLoader loader();
+    ContainerLoader loader();
 
     /**
      * Gets the {@link String license} of the data within this container.
-     *
-     * <p>Consult the vendor of this library for how this field is used. In the generic
-     * implementation, a license's name is expected (i.e. MIT or All Rights Reserved).</p>
+     * <p>
+     * Consult the vendor for how this field is used.
+     * <p>
+     * In the generic implementation, a license's name is expected.
+     * <p>
+     * Notable examples include MIT or All Rights Reserved.
      *
      * @return The license
      */
     String license();
 
     /**
-     * Gets the {@link String mappings} that code within this container might be written in.
-     *
-     * <p>The format of this string should be in maven dependency format (group:artifact:version).</p>
+     * Gets the {@link Artifact mappings} that code within this container might be written in.
+     * <p>
+     * The format of this string should be in maven dependency format (group:artifact:version).
+     * <p>
+     * Consult the vendor for how this field is used. As an example, that entity could use this
+     * purely for information purposes or go farther and perform artifact remapping from these
+     * mappings to another.
      *
-     * <p>Consult the vendor of this library for how this field is used. As an example, a vendor could
-     * use this purely for information purposes or go farther and perform artifact remapping from
-     * this mappings to another.</p>
-     *
-     * @return The {@link String mappings} or {@link Optional#empty()} otherwise
+     * @return The mappings or {@link Optional#empty()} otherwise
      */
     Optional<String> mappings();
 
@@ -74,17 +78,17 @@ public interface Container {
     Optional<Inheritable> globalMetadata();
 
     /**
-     * Gets a {@link PluginMetadata} by its {@link String id}.
-     *
-     * <p>This maps to {@link PluginMetadata#id()}</p>
+     * Gets a {@link PluginMetadata plugin metadata} by its {@link String id}.
+     * <p>
+     * This maps to {@link PluginMetadata#id()}.
      *
      * @param id The id
      * @return The plugin metadata or {@link Optional#empty()} otherwise
      */
     Optional<PluginMetadata> metadata(String id);
 
     /**
-     * @return The {@link PluginMetadata plugin metadata} as an unmodifiable {@link Set}.
+     * @return All of the {@link PluginMetadata plugin metadata} as an unmodifiable {@link Set}.
      */
     Set<PluginMetadata> metadata();
 }
diff --git a/src/main/java/org/spongepowered/plugin/metadata/Inheritable.java b/src/main/java/org/spongepowered/plugin/metadata/Inheritable.java
@@ -38,13 +38,13 @@
 /**
  * Represents metadata that is meant to be inherited/overwritten, per contract.
  *
- * @see org.spongepowered.plugin.metadata.builtin.StandardInheritable for a generic implementation
- * @see PluginMetadata for specific "plugin" metadata
+ * @see org.spongepowered.plugin.metadata.builtin.StandardInheritable StandardInheritable, for a generic implementation
+ * @see PluginMetadata PluginMetadata, for specific "plugin" metadata
  */
 public interface Inheritable {
 
     /**
-     * @return The version, as a maven artifact.
+     * @return The {@link ArtifactVersion version}.
      */
     ArtifactVersion version();
 
@@ -54,7 +54,7 @@ public interface Inheritable {
     PluginBranding branding();
 
     /**
-     * @return {@link PluginLinks links} to various web resources.
+     * @return The {@link PluginLinks links} to various web resources.
      */
     PluginLinks links();
 
@@ -64,8 +64,9 @@ public interface Inheritable {
     List<PluginContributor> contributors();
 
     /**
-     * Gets the {@link PluginDependency} by {@link String id}.
-     *
+     * Gets the {@link PluginDependency plugin dependency} by {@link String id}.
+     * <p>
+     * This maps to {@link PluginDependency#id()}.
      * @param id The id
      * @return The dependency or {@link Optional#empty()} otherwise.
      */

diff --git a/src/main/java/org/spongepowered/plugin/metadata/PluginMetadata.java b/src/main/java/org/spongepowered/plugin/metadata/PluginMetadata.java
@@ -29,7 +29,8 @@
 /**
  * Represents specific, unique metadata to a plugin.
  *
- * @see Inheritable for metadata that might be shared between multiple plugin metadata.
+ * @see Inheritable Inheritable, for metadata that might be shared between multiple plugin metadata
+ * @see org.spongepowered.plugin.metadata.builtin.StandardPluginMetadata StandardPluginMetadata, for a generic implementation
  */
 public interface PluginMetadata extends Inheritable {
 
@@ -55,9 +56,10 @@ public interface PluginMetadata extends Inheritable {
 
     /**
      * Gets the {@link String entrypoint}.
+     * <p>
+     * Consult the vendor for how this field is used. As an example, this could be
+     * the name of a module or a fully realized path to a discrete class.
      *
-     * <p>Consult the vendor of this library for how this field is used. As an example,
-     * this could be the name of a module or a fully realized path to a discrete class.</p>
      * @return The entrypoint
      */
     String entrypoint();

diff --git a/src/main/java/org/spongepowered/plugin/metadata/builtin/MetadataContainer.java b/src/main/java/org/spongepowered/plugin/metadata/builtin/MetadataContainer.java
@@ -32,13 +32,14 @@
 import com.google.gson.JsonParseException;
 import com.google.gson.JsonSerializationContext;
 import com.google.gson.JsonSerializer;
+import org.apache.maven.artifact.ArtifactUtils;
 import org.apache.maven.artifact.versioning.InvalidVersionSpecificationException;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.spongepowered.plugin.metadata.Container;
 import org.spongepowered.plugin.metadata.Inheritable;
 import org.spongepowered.plugin.metadata.PluginMetadata;
 import org.spongepowered.plugin.metadata.builtin.model.Adapters;
-import org.spongepowered.plugin.metadata.builtin.model.StandardPluginLoader;
+import org.spongepowered.plugin.metadata.builtin.model.StandardContainerLoader;
 import org.spongepowered.plugin.metadata.util.GsonUtils;
 
 import java.lang.reflect.Type;
@@ -57,7 +58,7 @@ public final class MetadataContainer implements Container {
 
     private final String license;
     @Nullable private final String mappings;
-    private final StandardPluginLoader loader;
+    private final StandardContainerLoader loader;
     @Nullable private final Inheritable globalMetadata;
     private final Set<StandardPluginMetadata> metadata = new LinkedHashSet<>();
     private final Map<String, StandardPluginMetadata> metadataById = new LinkedHashMap<>();
@@ -75,7 +76,7 @@ private MetadataContainer(final Builder builder) {
     }
 
     @Override
-    public StandardPluginLoader loader() {
+    public StandardContainerLoader loader() {
         return this.loader;
     }
 
@@ -118,10 +119,10 @@ public static final class Builder {
 
         final Set<StandardPluginMetadata> metadata = new LinkedHashSet<>();
         @Nullable String license, mappings;
-        @Nullable StandardPluginLoader loader;
+        @Nullable StandardContainerLoader loader;
         @Nullable Inheritable globalMetadata;
 
-        public Builder loader(final StandardPluginLoader loader) {
+        public Builder loader(final StandardContainerLoader loader) {
             this.loader = Objects.requireNonNull(loader, "loader");
             return this;
         }
@@ -132,10 +133,14 @@ public Builder license(final String license) {
         }
 
         public Builder mappings(@Nullable final String mappings) {
-            this.mappings = mappings;
-            if (this.mappings != null) {
-                // TODO validation
+
+            if (mappings != null) {
+                final String[] elements = mappings.split("\\.", 3);
+                // Triggers their sanity checks
+                ArtifactUtils.key(elements[0], elements[1], elements[2]);
             }
+
+            this.mappings = mappings;
             return this;
         }
 
@@ -173,7 +178,7 @@ public MetadataContainer deserialize(final JsonElement element, final Type type,
                 throws JsonParseException {
             final JsonObject obj = element.getAsJsonObject();
             final Builder builder = new Builder()
-                    .loader(Adapters.Deserializers.PLUGIN_LOADER.fromJsonTree(obj.get("loader")).build())
+                    .loader(Adapters.Deserializers.CONTAINER_LOADER.fromJsonTree(obj.get("loader")).build())
                     .license(obj.get("license").getAsString());
 
             GsonUtils.consumeIfPresent(obj, "mappings", e -> builder.mappings(e.getAsString()));
@@ -219,11 +224,10 @@ public MetadataContainer deserialize(final JsonElement element, final Type type,
         @Override
         public JsonElement serialize(final MetadataContainer value, final Type type, final JsonSerializationContext context) {
             final JsonObject obj = new JsonObject();
-            obj.add("loader", Adapters.Serializers.PLUGIN_LOADER.toJsonTree(value.loader));
+            obj.add("loader", Adapters.Serializers.CONTAINER_LOADER.toJsonTree(value.loader));
             obj.addProperty("license", value.license);
             GsonUtils.writeIfPresent(obj, "mappings", value.mappings());
 
-            // TODO Determine what properties are equal and not write all the plugin's metadata?
             final JsonArray plugins = new JsonArray();
             for (final PluginMetadata metadata : value.metadata) {
                 plugins.add(context.serialize(metadata, StandardPluginMetadata.class));

diff --git a/src/main/java/org/spongepowered/plugin/metadata/builtin/MetadataParser.java b/src/main/java/org/spongepowered/plugin/metadata/builtin/MetadataParser.java
@@ -39,6 +39,9 @@
 
 public final class MetadataParser {
 
+    private MetadataParser() {
+    }
+
     public static GsonBuilder gsonBuilder() {
         return new GsonBuilder()
                 .registerTypeAdapter(MetadataContainer.class, new MetadataContainer.Serializer())
@@ -153,7 +156,4 @@ public static void write(final Writer writer, final MetadataContainer container,
             gson.toJson(container, MetadataContainer.class, jsonWriter);
         }
     }
-
-    private MetadataParser() {
-    }
 }
diff --git a/src/main/java/org/spongepowered/plugin/metadata/builtin/StandardInheritable.java b/src/main/java/org/spongepowered/plugin/metadata/builtin/StandardInheritable.java
@@ -72,6 +72,7 @@ public class StandardInheritable implements Inheritable {
     protected final Map<String, Object> properties = new LinkedHashMap<>();
     private final Map<String, StandardPluginDependency> dependenciesById = new LinkedHashMap<>();
 
+    @SuppressWarnings("rawtypes")
     protected StandardInheritable(final AbstractBuilder builder) {
         this.version = builder.version;
         this.rawVersion = builder.rawVersion;
@@ -85,10 +86,6 @@ protected StandardInheritable(final AbstractBuilder builder) {
         this.properties.putAll(builder.properties);
     }
 
-    public static Builder builder() {
-        return new Builder();
-    }
-
     @Override
     public ArtifactVersion version() {
         return this.version;
@@ -254,16 +251,15 @@ public static final class Serializer implements JsonSerializer<StandardInheritab
 
         @Override
         public StandardInheritable deserialize(final JsonElement element, final Type type, final JsonDeserializationContext context)
-            throws JsonParseException {
+                throws JsonParseException {
 
             final JsonObject obj = element.getAsJsonObject();
-            final Builder builder = StandardInheritable.builder().version(GsonUtils.<String>get(obj, "version", JsonElement::getAsString).orElse(null));
+            final Builder builder = new Builder();
+            builder.version(GsonUtils.get(obj, "version", JsonElement::getAsString).orElse(null));
             GsonUtils.consumeIfPresent(obj, "branding", e -> builder.branding(Adapters.Deserializers.PLUGIN_BRANDING.fromJsonTree(e).build()));
             GsonUtils.consumeIfPresent(obj, "links", e -> builder.links(Adapters.Deserializers.PLUGIN_LINKS.fromJsonTree(e).build()));
-            GsonUtils.consumeIfPresent(obj, "contributors", e -> builder.contributors(GsonUtils.read((JsonArray) e, Adapters.Deserializers.PLUGIN_CONTRIBUTOR, LinkedList::new).stream().map(
-                    StandardPluginContributor.Builder::build).collect(Collectors.toList())));
-            GsonUtils.consumeIfPresent(obj, "dependencies", e -> builder.dependencies(GsonUtils.read((JsonArray) e, Adapters.Deserializers.PLUGIN_DEPENDENCY, LinkedHashSet::new).stream().map(
-                    StandardPluginDependency.Builder::build).collect(Collectors.toList())));
+            GsonUtils.consumeIfPresent(obj, "contributors", e -> builder.contributors(GsonUtils.read((JsonArray) e, Adapters.Deserializers.PLUGIN_CONTRIBUTOR, LinkedList::new).stream().map(StandardPluginContributor.Builder::build).collect(Collectors.toList())));
+            GsonUtils.consumeIfPresent(obj, "dependencies", e -> builder.dependencies(GsonUtils.read((JsonArray) e, Adapters.Deserializers.PLUGIN_DEPENDENCY, LinkedHashSet::new).stream().map(StandardPluginDependency.Builder::build).collect(Collectors.toList())));
             GsonUtils.consumeIfPresent(obj, "properties", e -> builder.properties(GsonUtils.read((JsonObject) e, JsonElement::getAsString, LinkedHashMap::new)));
 
             return builder.build();

diff --git a/src/main/java/org/spongepowered/plugin/metadata/builtin/StandardPluginMetadata.java b/src/main/java/org/spongepowered/plugin/metadata/builtin/StandardPluginMetadata.java
@@ -45,9 +45,9 @@
 
 public final class StandardPluginMetadata extends StandardInheritable implements PluginMetadata {
 
-    @Nullable private Container container;
     private final String id, entrypoint;
     @Nullable private final String name, description;
+    @Nullable private Container container;
 
     private StandardPluginMetadata(final Builder builder) {
         super(builder);
@@ -57,6 +57,10 @@ private StandardPluginMetadata(final Builder builder) {
         this.description = builder.description;
     }
 
+    public static StandardPluginMetadata.Builder builder() {
+        return new Builder();
+    }
+
     @Override
     public Container container() {
         return this.container;

diff --git a/src/main/java/org/spongepowered/plugin/metadata/builtin/model/Adapters.java b/src/main/java/org/spongepowered/plugin/metadata/builtin/model/Adapters.java
@@ -28,8 +28,13 @@
 
 public final class Adapters {
 
+    private Adapters() {
+    }
+
     public static final class Deserializers {
 
+        public static final TypeAdapter<StandardContainerLoader.Builder> CONTAINER_LOADER = new StandardContainerLoader.Deserializer();
+
         public static final TypeAdapter<StandardPluginBranding.Builder> PLUGIN_BRANDING = new StandardPluginBranding.Deserializer();
 
         public static final TypeAdapter<StandardPluginContributor.Builder> PLUGIN_CONTRIBUTOR = new StandardPluginContributor.Deserializer();
@@ -38,13 +43,14 @@ public static final class Deserializers {
 
         public static final TypeAdapter<StandardPluginLinks.Builder> PLUGIN_LINKS = new StandardPluginLinks.Deserializer();
 
-        public static final TypeAdapter<StandardPluginLoader.Builder> PLUGIN_LOADER = new StandardPluginLoader.Deserializer();
-
         private Deserializers() {
         }
     }
 
     public static final class Serializers {
+
+        public static final TypeAdapter<StandardContainerLoader> CONTAINER_LOADER = new StandardContainerLoader.Serializer();
+
         public static final TypeAdapter<StandardPluginBranding> PLUGIN_BRANDING = new StandardPluginBranding.Serializer();
 
         public static final TypeAdapter<StandardPluginContributor> PLUGIN_CONTRIBUTOR = new StandardPluginContributor.Serializer();
@@ -53,12 +59,7 @@ public static final class Serializers {
 
         public static final TypeAdapter<StandardPluginLinks> PLUGIN_LINKS = new StandardPluginLinks.Serializer();
 
-        public static final TypeAdapter<StandardPluginLoader> PLUGIN_LOADER = new StandardPluginLoader.Serializer();
-
         private Serializers() {
         }
     }
-
-    private Adapters() {
-    }
 }