Merge pull request #2730 from BentoBoxWorld/develop

Version 3.7.4

Author: tastybento

pom.xml

@@ -75,7 +75,7 @@
         <!-- Do not change unless you want different name for local builds. -->
         <build.number>-LOCAL</build.number>
         <!-- This allows to change between versions. -->
-        <build.version>3.7.3</build.version>
+        <build.version>3.7.4</build.version>
         <sonar.organization>bentobox-world</sonar.organization>
         <sonar.host.url>https://sonarcloud.io</sonar.host.url>
         <server.jars>${project.basedir}/lib</server.jars>
@@ -201,6 +201,12 @@
             <id>matteodev</id>
             <url>https://maven.devs.beer/</url>
         </repository>
+        <!-- Oraxen repo-->
+        <repository>
+              <id>oraxen</id>
+              <name>Oraxen Repository</name>
+              <url>https://repo.oraxen.com/releases</url>
+        </repository>
         <!-- BentoBox Addons -->
         <repository>
             <id>bentoboxworld</id>
@@ -387,6 +393,59 @@
             <version>4.0.2-beta-release-11</version>
             <scope>provided</scope>
         </dependency>
+        <!-- Oraxen -->
+        <dependency>
+            <groupId>io.th0rgal</groupId>
+            <artifactId>oraxen</artifactId>
+            <version>1.193.1</version>
+            <exclusions>
+                <exclusion>
+                    <groupId>me.gabytm.util</groupId>
+                    <artifactId>actions-spigot</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.jetbrains</groupId>
+                    <artifactId>annotations</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>com.ticxo</groupId>
+                    <artifactId>PlayerAnimator</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>com.github.stefvanschie.inventoryframework</groupId>
+                    <artifactId>IF</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>io.th0rgal</groupId>
+                    <artifactId>protectionlib</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>dev.triumphteam</groupId>
+                    <artifactId>triumph-gui</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.bstats</groupId>
+                    <artifactId>bstats-bukkit</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>com.jeff-media</groupId>
+                    <artifactId>custom-block-data</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>com.jeff-media</groupId>
+                    <artifactId>persistent-data-serializer</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>com.jeff_media</groupId>
+                    <artifactId>MorePersistentDataTypes</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>gs.mclo</groupId>
+                    <artifactId>java</artifactId>
+                </exclusion>
+            </exclusions>
+            <scope>provided</scope>
+        </dependency>
         <!-- Multipaper -->
         <dependency>
             <groupId>com.github.puregero</groupId>
@@ -461,10 +520,9 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.8.1</version>
+                <version>3.13.0</version>
                 <configuration>
                     <release>${java.version}</release>
-                    <!-- <source>${java.version}</source> <target>${java.version}</target> -->
                 </configuration>
             </plugin>
             <plugin>
@@ -608,7 +666,7 @@
             <plugin>
                 <groupId>org.jacoco</groupId>
                 <artifactId>jacoco-maven-plugin</artifactId>
-                <version>0.8.10</version>
+                <version>0.8.13</version>
                 <configuration>
                     <append>true</append>
                     <excludes>

src/main/java/world/bentobox/bentobox/BentoBox.java

@@ -34,6 +34,7 @@
 import world.bentobox.bentobox.hooks.MultiverseCore5Hook;
 import world.bentobox.bentobox.hooks.MyWorldsHook;
 import world.bentobox.bentobox.hooks.MythicMobsHook;
+import world.bentobox.bentobox.hooks.OraxenHook;
 import world.bentobox.bentobox.hooks.SlimefunHook;
 import world.bentobox.bentobox.hooks.VaultHook;
 import world.bentobox.bentobox.hooks.ZNPCsPlusHook;
@@ -257,6 +258,9 @@ private void completeSetup(long loadTime) {
 
         // Register ItemsAdder
         hooksManager.registerHook(new ItemsAdderHook(this));
+        
+        // Register Oraxen
+        hooksManager.registerHook(new OraxenHook(this));
 
         // TODO: re-enable after implementation
         //hooksManager.registerHook(new DynmapHook());

src/main/java/world/bentobox/bentobox/api/addons/Addon.java

@@ -31,10 +31,34 @@
 import world.bentobox.bentobox.util.Util;
 
 /**
- * Add-on class for BentoBox. Extend this to create an add-on. The operation
- * and methods are very similar to Bukkit's JavaPlugin.
+ * The main class for a BentoBox addon.
+ * <p>
+ * To create an addon, you must extend this class. The operation and methods are
+ * very similar to Bukkit's {@code JavaPlugin}.
+ * <p>
+ * Each addon must have an {@code addon.yml} file in its root directory. This file
+ * contains metadata about the addon, such as its name, version, and main class.
+ * <p>
+ * Example of a simple addon main class:
+ * <pre>
+ * public class MyAddon extends Addon {
+ *
+ *     {@literal @}Override
+ *     public void onEnable() {
+ *         // Addon startup logic
+ *         getLogger().info("MyAddon has been enabled!");
+ *     }
+ *
+ *     {@literal @}Override
+ *     public void onDisable() {
+ *         // Addon shutdown logic
+ *         getLogger().info("MyAddon has been disabled!");
+ *     }
+ * }
+ * </pre>
  *
  * @author tastybento, ComminQ_Q
+ * @since 1.0
  */
 public abstract class Addon {
 
@@ -71,7 +95,7 @@ protected Addon() {
     /**
      * Executes code when loading the addon.
      * This is called before {@link #onEnable()}.
-     * This <b>must</b> be used to setup configuration, worlds and commands.
+     * This <b>must</b> be used to set up configuration, worlds and commands.
      */
     public void onLoad() {}
 
@@ -196,7 +220,7 @@ private FileConfiguration loadYamlFile() {
                 yamlConfig = new YamlConfiguration();
                 yamlConfig.load(yamlFile);
             } catch (Exception e) {
-                Bukkit.getLogger().severe(() -> "Could not load config.yml: " + e.getMessage());
+                BentoBox.getInstance().logError("Could not load config.yml: " + e.getMessage());
             }
         }
         return yamlConfig;
@@ -218,7 +242,7 @@ public void saveConfig() {
         try {
             getConfig().save(new File(dataFolder, ADDON_CONFIG_FILENAME));
         } catch (IOException e) {
-            Bukkit.getLogger().severe("Could not save config! " + this.getDescription().getName() + " " + e.getMessage());
+            BentoBox.getInstance().logError("Could not save config! " + this.getDescription().getName() + " " + e.getMessage());
         }
     }
 
@@ -267,7 +291,7 @@ public void saveResource(String resourcePath, boolean replace) {
      * @return file written, or null if none
      */
     public File saveResource(String jarResource, File destinationFolder, boolean replace, boolean noPath) {
-        if (jarResource == null || jarResource.equals("")) {
+        if (jarResource == null || jarResource.isEmpty()) {
             throw new IllegalArgumentException("ResourcePath cannot be null or empty");
         }
 
@@ -300,6 +324,7 @@ public File saveResource(String jarResource, File destinationFolder, boolean rep
                         "The embedded resource '" + jarResource + "' cannot be found in " + jar.getName());
             }
         } catch (IOException e) {
+            e.printStackTrace();
             BentoBox.getInstance().logError(
                     "Could not save from jar file. From " + jarResource + " to " + destinationFolder.getAbsolutePath());
         }
@@ -314,7 +339,7 @@ public File saveResource(String jarResource, File destinationFolder, boolean rep
      * @throws InvalidConfigurationException - if the yaml is malformed
      */
     public YamlConfiguration getYamlFromJar(String jarResource) throws IOException, InvalidConfigurationException {
-        if (jarResource == null || jarResource.equals("")) {
+        if (jarResource == null || jarResource.isEmpty()) {
             throw new IllegalArgumentException("jarResource cannot be null or empty");
         }
         YamlConfiguration result = new YamlConfiguration();
@@ -336,7 +361,7 @@ public YamlConfiguration getYamlFromJar(String jarResource) throws IOException,
      * @return resource or null if there is a problem
      */
     public InputStream getResource(String jarResource) {
-        if (jarResource == null || jarResource.equals("")) {
+        if (jarResource == null || jarResource.isEmpty()) {
             throw new IllegalArgumentException("ResourcePath cannot be null or empty");
         }
 
@@ -349,7 +374,7 @@ public InputStream getResource(String jarResource) {
                 }
             }
         } catch (IOException e) {
-            Bukkit.getLogger().severe("Could not open from jar file. " + jarResource);
+            BentoBox.getInstance().logError("Could not open from jar file. " + jarResource);
         }
         return null;
     }

src/main/java/world/bentobox/bentobox/api/addons/AddonClassLoader.java

@@ -25,13 +25,31 @@
 import world.bentobox.bentobox.managers.AddonsManager;
 
 /**
- * Loads addons and sets up permissions
- * @author Tastybento, ComminQ
+ * This class loader is responsible for loading an addon's JAR file, its classes,
+ * and its {@code addon.yml} metadata.
+ * <p>
+ * Each addon is loaded with its own {@link AddonClassLoader}, which allows for
+ * class isolation and management. This loader also facilitates inter-addon
+ * class sharing by coordinating with the {@link AddonsManager}.
+ * 
+ * This approach is now rarely used as most addons are now Plugin-based and so are loaded by the server as plugins.
+ *
+ * @author tastybento, ComminQ
+ * @since 1.0
  */
 public class AddonClassLoader extends URLClassLoader {
 
+    /**
+     * A cache of classes that have been loaded by this class loader.
+     */
     private final Map<String, Class<?>> classes = new HashMap<>();
+    /**
+     * The addon instance that was loaded by this class loader.
+     */
     private final Addon addon;
+    /**
+     * The addon manager that created this class loader.
+     */
     private final AddonsManager loader;
 
     /**
@@ -47,6 +65,22 @@ protected AddonClassLoader(Addon addon, AddonsManager loader, File jarFile) thro
         this.loader = loader;
     }
 
+    /**
+     * Constructs a new AddonClassLoader for a given addon.
+     *
+     * @param addonsManager The addon manager instance.
+     * @param data The addon's metadata from {@code addon.yml}.
+     * @param jarFile The addon's JAR file.
+     * @param parent The parent class loader.
+     * @throws InvalidAddonInheritException If the main class does not extend {@link Addon}.
+     * @throws MalformedURLException If the JAR file path is invalid.
+     * @throws InvalidDescriptionException If the addon cannot be loaded.
+     * @throws InvalidAddonDescriptionException If the {@code addon.yml} is invalid.
+     * @throws InstantiationException If the addon's main class cannot be instantiated.
+     * @throws IllegalAccessException If the addon's main class constructor is not accessible.
+     * @throws InvocationTargetException If the addon's constructor throws an exception.
+     * @throws NoSuchMethodException If the addon's main class has no default constructor.
+     */
     public AddonClassLoader(AddonsManager addonsManager, YamlConfiguration data, File jarFile, ClassLoader parent)
             throws InvalidAddonInheritException,
             MalformedURLException,
@@ -64,32 +98,36 @@ public AddonClassLoader(AddonsManager addonsManager, YamlConfiguration data, Fil
             if (mainClass == null) {
                 throw new InvalidAddonFormatException("addon.yml does not define a main class!");
             }
-            javaClass = Class.forName(mainClass, true, this);
+            // Do not allow addons to use BentoBox's package.
             if(mainClass.startsWith("world.bentobox.bentobox")){
                 throw new InvalidAddonFormatException("Package declaration cannot start with 'world.bentobox.bentobox'");
             }
+            javaClass = Class.forName(mainClass, true, this);
         } catch (Exception e) {
             throw new InvalidDescriptionException("Could not load '" + jarFile.getName() + "' in folder '" + jarFile.getParent() + "' - " + e.getMessage());
         }
 
         Class<? extends Addon> addonClass;
         try {
+            // Check if the main class extends Addon.
             addonClass = javaClass.asSubclass(Addon.class);
         } catch (ClassCastException e) {
             throw new InvalidAddonInheritException("Main class does not extend 'Addon'");
         }
 
+        // Instantiate the addon and set its description from addon.yml.
         addon = addonClass.getDeclaredConstructor().newInstance();
         addon.setDescription(asDescription(data));
     }
 
 
 
     /**
-     * Converts the addon.yml to an AddonDescription
-     * @param data - yaml config (addon.yml)
-     * @return Addon Description
-     * @throws InvalidAddonDescriptionException - if there's a bug in the addon.yml
+     * Parses the addon.yml configuration into an {@link AddonDescription} object.
+     *
+     * @param data The YAML configuration from {@code addon.yml}.
+     * @return An {@link AddonDescription} instance.
+     * @throws InvalidAddonDescriptionException If the {@code addon.yml} is missing required fields or contains invalid values.
      */
     @NonNull
     public static AddonDescription asDescription(YamlConfiguration data) throws InvalidAddonDescriptionException {
@@ -159,32 +197,49 @@ protected Class<?> findClass(String name) {
     }
 
     /**
-     * This is a custom findClass that enables classes in other addons to be found
-     * @param name - class name
-     * @param checkGlobal - check globally or not when searching
-     * @return Class - class if found
+     * Finds and loads the specified class.
+     * <p>
+     * This custom implementation enables classes in one addon to be found by another.
+     * The loading strategy is as follows:
+     * <ol>
+     *     <li>Check the local cache for this class loader.</li>
+     *     <li>If not found, check the global cache in {@link AddonsManager} (if {@code checkGlobal} is true).</li>
+     *     <li>If still not found, try to load the class from the addon's JAR file.</li>
+     *     <li>If loaded successfully from the JAR, register it in the global cache.</li>
+     *     <li>Finally, cache the class locally.</li>
+     * </ol>
+     *
+     * @param name The fully qualified name of the class.
+     * @param checkGlobal If true, check for classes loaded by other addons.
+     * @return The loaded {@link Class}, or {@code null} if the class could not be found.
      */
     public Class<?> findClass(String name, boolean checkGlobal) {
+        // Do not allow addons to load BentoBox classes.
         if (name.startsWith("world.bentobox.bentobox")) {
             return null;
         }
+        // Check local cache first.
         Class<?> result = classes.get(name);
         if (result == null) {
+            // Check global cache for classes from other addons.
             if (checkGlobal) {
                 result = loader.getClassByName(name);
             }
 
             if (result == null) {
+                // Try to find the class in this addon's jar.
                 try {
                     result = super.findClass(name);
                 } catch (ClassNotFoundException | NoClassDefFoundError e) {
-                    // Do nothing.
+                    // Do nothing. The class is not in this jar.
                 }
                 if (result != null) {
+                    // Class found in this addon's jar, so add it to the global cache.
                     loader.setClass(name, result);
 
                 }
             }
+            // Add the class to the local cache.
             classes.put(name, result);
         }
         return result;
@@ -198,7 +253,8 @@ public Addon getAddon() {
     }
 
     /**
-     * @return class list
+     * Gets the set of fully qualified class names loaded by this class loader.
+     * @return A set of class names.
      */
     public Set<String> getClasses() {
         return classes.keySet();