project documentation and minor fixes

Revxrsal · Dec 14, 2024 · 53cb4a7 · 53cb4a7
1 parent 3dc0457
commit 53cb4a7
Show file tree

Hide file tree

Showing 11 changed files with 99 additions and 40 deletions.
diff --git a/README.md b/README.md
@@ -33,7 +33,7 @@ build.gradle:
 ```groovy
 plugins {
   id 'com.github.johnrengelman.shadow' version '8.1.1'
-  id 'io.github.revxrsal.zapper' version '1.0.0'
+  id 'io.github.revxrsal.zapper' version '0.0.1'
 }
 ```
 
@@ -42,7 +42,7 @@ build.gradle.kts:
 ```groovy
 plugins {
   id("com.github.johnrengelman.shadow") version "8.1.1"
-  id("io.github.revxrsal.zapper") version("1.0.0")
+  id("io.github.revxrsal.zapper") version("0.0.1")
 }
 ```
 
@@ -65,6 +65,9 @@ zapper {
     // directory to download dependencies in
     libsFolder = "libraries"
 
+    // the prefix for relocating libraries
+    relocationPrefix = "myplugin.libs"
+  
     // repositories to fetch dependencies from
     // 
     // by default: includes maven central
@@ -75,8 +78,12 @@ zapper {
 
         // optional: use all repositories declared in this
         // file if you don't want to re-include everything here
-        useProjectRepositories()
+        includeProjectRepositories()
     }
+  
+    // relocate libraries here
+    // com.squareup.moshi --> myplugin.libs.moshi
+    relocate("com.squareup.moshi", "moshi") 
 }
 ```
 
@@ -107,7 +114,7 @@ To add the Zapper API:
 <dependency>
     <groupId>io.github.revxrsal</groupId>
     <artifactId>zapper.api</artifactId>
-    <version>1.0.0</version>
+    <version>0.0.1</version>
     <scope>compile</scope>
 </dependency>
 ```

diff --git a/api/src/main/java/revxrsal/zapper/DependencyDownloadResult.java b/api/src/main/java/revxrsal/zapper/DependencyDownloadResult.java
@@ -17,18 +17,34 @@ public interface DependencyDownloadResult {
      */
     boolean wasSuccessful();
 
+    /**
+     * Returns this {@link DependencyDownloadResult} as a {@link Failure}
+     *
+     * @return The failure
+     */
     @Contract("-> this")
     default @NotNull Failure asFailure() {
         if (this instanceof Failure)
             return (Failure) this;
         throw new IllegalArgumentException("Dependency was downloaded successfully.");
     }
 
+    /**
+     * Represents a successful dependency download
+     *
+     * @return The success result
+     */
     @Contract(pure = true)
     static @NotNull Success success() {
         return Success.INSTANCE;
     }
 
+    /**
+     * Represents a failed dependency download
+     *
+     * @param throwable The error
+     * @return The failure result
+     */
     static @NotNull Failure failure(@NotNull Throwable throwable) {
         Objects.requireNonNull(throwable, "throwable cannot be null!");
         return new Failure(throwable);
@@ -38,6 +54,9 @@ final class Success implements DependencyDownloadResult {
 
         private static final Success INSTANCE = new Success();
 
+        private Success() {
+        }
+
         @Override
         public boolean wasSuccessful() {
             return true;
@@ -48,7 +67,7 @@ final class Failure implements DependencyDownloadResult {
 
         private final Throwable throwable;
 
-        public Failure(Throwable throwable) {
+        Failure(Throwable throwable) {
             this.throwable = throwable;
         }
 

diff --git a/api/src/main/java/revxrsal/zapper/RuntimeLibPluginConfiguration.java b/api/src/main/java/revxrsal/zapper/RuntimeLibPluginConfiguration.java
@@ -30,22 +30,26 @@ public final class RuntimeLibPluginConfiguration {
     }
 
     public static @NotNull RuntimeLibPluginConfiguration parse() {
-        Properties config = parseProperties();
-        String libsFolder = config.getProperty("libs-folder");
-        String relocationPrefix = config.getProperty("relocation-prefix");
-        List<Repository> repositories = parseRepositories();
-        List<Dependency> dependencies = parseDependencies();
-        List<Relocation> relocations = parseRelocations();
-        return new RuntimeLibPluginConfiguration(
-                libsFolder,
-                relocationPrefix,
-                dependencies,
-                repositories,
-                relocations
-        );
+        try {
+            Properties config = parseProperties();
+            String libsFolder = config.getProperty("libs-folder");
+            String relocationPrefix = config.getProperty("relocation-prefix");
+            List<Repository> repositories = parseRepositories();
+            List<Dependency> dependencies = parseDependencies();
+            List<Relocation> relocations = parseRelocations();
+            return new RuntimeLibPluginConfiguration(
+                    libsFolder,
+                    relocationPrefix,
+                    dependencies,
+                    repositories,
+                    relocations
+            );
+        } catch (IOException e) {
+            throw new IllegalArgumentException("Generated Zapper files are missing. Have you applied the Gradle plugin?");
+        }
     }
 
-    private static @NotNull List<Relocation> parseRelocations() {
+    private static @NotNull List<Relocation> parseRelocations() throws IOException {
         List<Relocation> relocations = new ArrayList<>();
         InputStream stream = ClassLoaderReader.getResource("zapper/relocations.txt");
         for (String line : readAllLines(stream)) {

diff --git a/api/src/main/java/revxrsal/zapper/ZapperJavaPlugin.java b/api/src/main/java/revxrsal/zapper/ZapperJavaPlugin.java
@@ -9,6 +9,12 @@
 import java.io.File;
 import java.net.URLClassLoader;
 
+/**
+ * An extension of {@link JavaPlugin} that downloads dependencies at runtime.
+ * <p>
+ * This should only be used in tandem with the Gradle plugin! Please consult
+ * the documentation otherwise.
+ */
 public abstract class ZapperJavaPlugin extends JavaPlugin {
 
     static {

diff --git a/api/src/main/java/revxrsal/zapper/classloader/ByUnsafe.java b/api/src/main/java/revxrsal/zapper/classloader/ByUnsafe.java
@@ -30,8 +30,8 @@
 import java.util.Collection;
 import java.util.List;
 
-import static revxrsal.zapper.util.ClassLoaderUtil.getField;
-import static revxrsal.zapper.util.ClassLoaderUtil.isJava8;
+import static revxrsal.zapper.classloader.UnsafeUtil.getField;
+import static revxrsal.zapper.classloader.UnsafeUtil.isJava8;
 
 /**
  * An implementation that uses sun.misc.Unsafe to inject URLs

diff --git a/api/src/main/java/revxrsal/zapper/classloader/IsolatedClassLoader.java b/api/src/main/java/revxrsal/zapper/classloader/IsolatedClassLoader.java
@@ -26,6 +26,10 @@
 import java.net.URL;
 import java.net.URLClassLoader;
 
+/**
+ * A {@link URLClassLoader} that is detatched from the entire plugin classloader.
+ * This is used for relocating
+ */
 public final class IsolatedClassLoader extends URLClassLoader {
 
     static {

diff --git a/...revxrsal/zapper/util/ClassLoaderUtil.java → ...vxrsal/zapper/classloader/UnsafeUtil.java b/...revxrsal/zapper/util/ClassLoaderUtil.java → ...vxrsal/zapper/classloader/UnsafeUtil.java
@@ -21,7 +21,7 @@
  *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  *  SOFTWARE.
  */
-package revxrsal.zapper.util;
+package revxrsal.zapper.classloader;
 
 import com.google.common.base.Supplier;
 import com.google.common.base.Suppliers;
@@ -30,7 +30,7 @@
 import java.lang.reflect.Field;
 import java.util.Objects;
 
-public final class ClassLoaderUtil {
+final class UnsafeUtil {
 
     private static final Supplier<Unsafe> Unsafe = Suppliers.memoize(() -> {
         try {
@@ -61,7 +61,7 @@ public static <T> T getField(Object instance, String name, Class<?> from) {
             Field field = from.getDeclaredField(name);
             long offset = unsafe.objectFieldOffset(field);
             T value = (T) unsafe.getObject(instance, offset);
-            return Objects.requireNonNull(value, "getField(" + name + " from " + from + ")");
+            return Objects.requireNonNull(value, "getField(" + name + ") from " + from);
         } catch (Throwable t) {
             throw new RuntimeException(t);
         }

diff --git a/api/src/main/java/revxrsal/zapper/relocation/Relocation.java b/api/src/main/java/revxrsal/zapper/relocation/Relocation.java
@@ -27,11 +27,19 @@
 
 import java.util.Objects;
 
+/**
+ * Represents a relocation rule.
+ */
 public final class Relocation {
 
     private final String pattern;
     private final String newPattern;
 
+    public Relocation(@NotNull String pattern, @NotNull String newPattern) {
+        this.pattern = pattern;
+        this.newPattern = newPattern;
+    }
+
     public String getPattern() {
         return pattern;
     }
@@ -40,23 +48,21 @@ public String getNewPattern() {
         return newPattern;
     }
 
-    public Relocation(@NotNull String pattern, @NotNull String newPattern) {
-        this.pattern = pattern;
-        this.newPattern = newPattern;
-    }
-
-    @Override public String toString() {
+    @Override
+    public String toString() {
         return String.format("Relocation{pattern='%s', newPattern='%s'}", pattern, newPattern);
     }
 
-    @Override public boolean equals(Object o) {
+    @Override
+    public boolean equals(Object o) {
         if (this == o) return true;
         if (!(o instanceof Relocation)) return false;
         Relocation that = (Relocation) o;
         return Objects.equals(pattern, that.pattern) && Objects.equals(newPattern, that.newPattern);
     }
 
-    @Override public int hashCode() {
+    @Override
+    public int hashCode() {
         return Objects.hash(pattern, newPattern);
     }
 }
diff --git a/api/src/main/java/revxrsal/zapper/relocation/Relocator.java b/api/src/main/java/revxrsal/zapper/relocation/Relocator.java
@@ -23,7 +23,6 @@
  */
 package revxrsal.zapper.relocation;
 
-
 import org.jetbrains.annotations.NotNull;
 import revxrsal.zapper.Dependency;
 import revxrsal.zapper.Repository;
@@ -38,9 +37,15 @@
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.atomic.AtomicBoolean;
 
+/**
+ * The relocator utility
+ */
 public final class Relocator {
 
+    private static boolean initialized = false;
+
     private Relocator() {
     }
 
@@ -50,14 +55,18 @@ private Relocator() {
             new Dependency("me.lucko", "jar-relocator", "1.7")
     );
 
-    private static final Constructor<?> relocatorConstructor;
-    private static final Method relocateMethod;
+    private static Constructor<?> relocatorConstructor;
+    private static Method relocateMethod;
 
     public static void relocate(
             @NotNull File input,
             @NotNull File output,
             @NotNull List<Relocation> relocations
     ) {
+        if (!initialized) {
+            downloadJarRelocator(input.getParentFile());
+            initialized = true;
+        }
         try {
             Map<String, String> rules = new LinkedHashMap<>();
             for (Relocation relocation : relocations) {
@@ -70,11 +79,9 @@ public static void relocate(
         }
     }
 
-    static {
+    private static void downloadJarRelocator(File dir) {
         try {
             URL[] urls = new URL[3];
-            File dataFolder = ClassLoaderReader.getDataFolder(Relocator.class);
-            File dir = new File(dataFolder, "libraries");
             dir.mkdirs();
             for (int i = 0; i < dependencies.size(); i++) {
                 Dependency d = dependencies.get(i);

diff --git a/api/src/main/java/revxrsal/zapper/util/ClassLoaderReader.java b/api/src/main/java/revxrsal/zapper/util/ClassLoaderReader.java
@@ -35,12 +35,18 @@
 import java.net.URLClassLoader;
 import java.net.URLConnection;
 
+/**
+ * A utility for accessing the data folder and the plugin.yml information
+ * from classloaders directly, without needing {@link org.bukkit.plugin.Plugin}
+ * instances.
+ */
 public final class ClassLoaderReader {
 
     private static final Field description, dataFolder;
     private static final Class<? extends URLClassLoader> PL_CL_LOADER;
 
-    private ClassLoaderReader() {}
+    private ClassLoaderReader() {
+    }
 
     public static @NotNull PluginDescriptionFile getDescription(@NotNull Class<?> cl) {
         ClassLoader classLoader = cl.getClassLoader();
@@ -83,6 +89,7 @@ public static InputStream getResource(String fileName) {
             }
         }
     }
+
     static {
         try {
             PL_CL_LOADER = Class.forName("org.bukkit.plugin.java.PluginClassLoader")

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -65,7 +65,6 @@ subprojects {
         }
 
         publishToMavenCentral(SonatypeHost.CENTRAL_PORTAL)
-
         signAllPublications()
     }
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -65,7 +65,6 @@ subprojects { @@
             }
             publishToMavenCentral(SonatypeHost.CENTRAL_PORTAL)
             signAllPublications()
         }
     }
@@ Expand Down @@