api: add cross-platform API support

10 months ago · 685431a40d
parent 9da3ff5281
commit 685431a40d
7 changed files with 81 additions and 52 deletions
--- a/build.gradle
+++ b/build.gradle
@ -21,6 +21,37 @@ ext {
    set 'snappy_version', snappy_version.toString()
 }

+publishing {
+    repositories {
+        if (System.getenv("RELEASES_MAVEN_USERNAME") != null) {
+            maven {
+                name = "william278-releases"
+                url = "https://repo.william278.net/releases"
+                credentials {
+                    username = System.getenv("RELEASES_MAVEN_USERNAME")
+                    password = System.getenv("RELEASES_MAVEN_PASSWORD")
+                }
+                authentication {
+                    basic(BasicAuthentication)
+                }
+            }
+        }
+        if (System.getenv("SNAPSHOTS_MAVEN_USERNAME") != null) {
+            maven {
+                name = "william278-snapshots"
+                url = "https://repo.william278.net/snapshots"
+                credentials {
+                    username = System.getenv("SNAPSHOTS_MAVEN_USERNAME")
+                    password = System.getenv("SNAPSHOTS_MAVEN_PASSWORD")
+                }
+                authentication {
+                    basic(BasicAuthentication)
+                }
+            }
+        }
+    }
+}
+
 import org.apache.tools.ant.filters.ReplaceTokens

 allprojects {
@ -88,7 +119,7 @@ subprojects {
        }

        // API publishing
-        if ('bukkit'.contains(project.name)) {
+        if (['common', 'bukkit'].contains(project.name)) {
            java {
                withSourcesJar()
                withJavadocJar()
@ -102,43 +133,14 @@ subprojects {
            shadowJar.dependsOn(sourcesJar, javadocJar)

            publishing {
-                repositories {
-                    if (System.getenv("RELEASES_MAVEN_USERNAME") != null) {
-                        maven {
-                            name = "william278-releases"
-                            url = "https://repo.william278.net/releases"
-                            credentials {
-                                username = System.getenv("RELEASES_MAVEN_USERNAME")
-                                password = System.getenv("RELEASES_MAVEN_PASSWORD")
-                            }
-                            authentication {
-                                basic(BasicAuthentication)
-                            }
-                        }
-                    }
-                    if (System.getenv("SNAPSHOTS_MAVEN_USERNAME") != null) {
-                        maven {
-                            name = "william278-snapshots"
-                            url = "https://repo.william278.net/snapshots"
-                            credentials {
-                                username = System.getenv("SNAPSHOTS_MAVEN_USERNAME")
-                                password = System.getenv("SNAPSHOTS_MAVEN_PASSWORD")
-                            }
-                            authentication {
-                                basic(BasicAuthentication)
-                            }
-                        }
-                    }
-                }
-
                publications {
-                    mavenJava(MavenPublication) {
-                        groupId = 'net.william278'
-                        artifactId = 'husksync'
+                    mavenJavaCommon(MavenPublication) {
+                        groupId = 'net.william278.husksync'
+                        artifactId = "husksync-${project.name}"
                        version = "$rootProject.version"
                        artifact shadowJar
-                        artifact javadocJar
                        artifact sourcesJar
+                        artifact javadocJar
                    }
                }
            }
--- a/bukkit/src/main/java/net/william278/husksync/api/BukkitHuskSyncAPI.java
+++ b/bukkit/src/main/java/net/william278/husksync/api/BukkitHuskSyncAPI.java
@ -43,9 +43,6 @@ import java.util.function.Consumer;
@SuppressWarnings("unused")
 public class BukkitHuskSyncAPI extends HuskSyncAPI {

-    // Instance of the plugin
-    private static BukkitHuskSyncAPI instance;
-
    /**
     * <b>(Internal use only)</b> - Constructor, instantiating the API.
     */
@ -55,7 +52,7 @@ public class BukkitHuskSyncAPI extends HuskSyncAPI {
    }

    /**
-     * Entrypoint to the HuskSync API - returns an instance of the API
+     * Entrypoint to the HuskSync API on the bukkit platform - returns an instance of the API
     *
     * @return instance of the HuskSync API
     * @since 3.0
@ -65,7 +62,7 @@ public class BukkitHuskSyncAPI extends HuskSyncAPI {
        if (instance == null) {
            throw new NotRegisteredException();
        }
-        return instance;
+        return (BukkitHuskSyncAPI) instance;
    }

    /**
--- a/common/src/main/java/net/william278/husksync/api/HuskSyncAPI.java
+++ b/common/src/main/java/net/william278/husksync/api/HuskSyncAPI.java
@ -38,14 +38,17 @@ import java.util.UUID;
 import java.util.concurrent.CompletableFuture;

 /**
- * The base implementation of the HuskSync API, containing cross-platform API calls.
+ * The common implementation of the HuskSync API, containing cross-platform API calls.
 * </p>
- * This class should not be used directly, but rather through platform-specific extending API classes.
+ * Retrieve an instance of the API class via {@link #getInstance()}.
 *
 * @since 2.0
 */
@SuppressWarnings("unused")
-public abstract class HuskSyncAPI {
+public class HuskSyncAPI {
+
+    // Instance of the plugin
+    protected static HuskSyncAPI instance;

    /**
     * <b>(Internal use only)</b> - Instance of the implementing plugin.
@ -60,6 +63,20 @@ public abstract class HuskSyncAPI {
        this.plugin = plugin;
    }

+    /**
+     * Entrypoint to the HuskSync API on the common platform - returns an instance of the API
+     *
+     * @return instance of the HuskSync API
+     * @since 3.3
+     */
+    @NotNull
+    public static HuskSyncAPI getInstance() {
+        if (instance == null) {
+            throw new NotRegisteredException();
+        }
+        return instance;
+    }
+
    /**
     * Get a {@link User} by their UUID
     *
--- a/docs/API-Events.md
+++ b/docs/API-Events.md
@ -1,8 +1,10 @@
 HuskSync provides three API events your plugin can listen to when certain parts of the data synchronization process are performed. These events deal with HuskSync class types, so you may want to familiarize yourself with the [API basics](API) first. Two of the events can be cancelled (thus aborting the synchronization process at certain stages), and some events expose methods letting you affect their outcome (such as modifying the data that is saved during the process).

-Consult the Javadocs for more information&mdash;and don't forget to register your listener when listening for these event calls. Please note that carrying out expensive blocking operations during these events is strongly discouraged as this may affect plugin performance.
+Consult the Javadocs for more information. Please note that carrying out expensive blocking operations during these events is strongly discouraged as this may affect plugin performance.

-## List of API Events
+## Bukkit Platform Events
+> **Tip:** Don't forget to register your listener when listening for these event calls.
+> 
 | Bukkit Event class        | Cancellable | Description                                                                                 |
 |---------------------------|:-----------:|---------------------------------------------------------------------------------------------|
 | `BukkitDataSaveEvent`     |      ✅      | Called when player data snapshot is created, saved and cached due to a DataSaveCause        |
--- a/docs/API.md
+++ b/docs/API.md
@ -1,7 +1,7 @@
 The HuskSync API (v3) provides methods for retrieving and updating [data snapshots](Data-Snapshot-API), a number of [[API Events]] for tracking when user data is synced and saved, and infrastructure for registering serializers to [synchronise custom data types](Custom-Data-API).

 ## Compatibility
-[![Maven](https://repo.william278.net/api/badge/latest/releases/net/william278/husksync?color=00fb9a&name=Maven&prefix=v)](https://repo.william278.net/#/releases/net/william278/husksync/)
+[![Maven](https://repo.william278.net/api/badge/latest/releases/net/william278/husksync/husksync-common?color=00fb9a&name=Maven&prefix=v)](https://repo.william278.net/#/releases/net/william278/husksync/)

 The HuskSync API shares version numbering with the plugin itself for consistency and convenience. Please note minor and patch plugin releases may make API additions and deprecations, but will not introduce breaking changes without notice.

@ -11,10 +11,20 @@ The HuskSync API shares version numbering with the plugin itself for consistency
 |    v2.x     | _v2.0&mdash;v2.2.8_  |     ❌     |
 |    v1.x     | _v1.0&mdash;v1.4.1_  |    ❌️     |

+### Platforms
+> **Note:** For versions older than `v3.3`, the HuskSync API was only distributed for the Bukkit platform (as `net.william278:husksync`) 
+
+The HuskClaims API is available for the following platforms:
+
+* `bukkit` - Bukkit, Spigot, Paper, etc. Provides Bukkit API event listeners and adapters to `org.bukkit` objects.
+* `common` - Common API for all platforms.
+
+
 <details>
 <summary>Targeting older versions</summary>

-HuskSync versions prior to `v2.2.5` are distributed on [JitPack](https://jitpack.io/#/net/william278/HuskSync), and you will need to use the `https://jitpack.io` repository instead.
+* The HuskSync API was only distributed for the Bukkit module prior to `v3.3`; the artifact ID was `net.william278:husksync` instead of `net.william278.husksync:husksync-PLATFORM`. 
+* HuskSync versions prior to `v2.2.5` are distributed on [JitPack](https://jitpack.io/#/net/william278/HuskSync), and you will need to use the `https://jitpack.io` repository instead.
 </details>

 ## Table of Contents
@ -44,8 +54,8 @@ Add the repository to your `pom.xml` as per below. You can alternatively specify
 Add the dependency to your `pom.xml` as per below. Replace `VERSION` with the latest version of HuskSync (without the v): ![Latest version](https://img.shields.io/github/v/tag/WiIIiam278/HuskSync?color=%23282828&label=%20&style=flat-square)
 ```xml
 <dependency>
-    <groupId>net.william278</groupId>
-    <artifactId>husksync</artifactId>
+    <groupId>net.william278.husksync</groupId>
+    <artifactId>husksync-PLATFORM</artifactId>
    <version>VERSION</version>
    <scope>provided</scope>
 </dependency>
@ -68,7 +78,7 @@ Add the dependency as per below. Replace `VERSION` with the latest version of Hu

 ```groovy
 dependencies {
-    compileOnly 'net.william278:husksync:VERSION'
+    compileOnly 'net.william278.husksync:husksync-PLATFORM:VERSION'
 }
 ```
 </details>
@ -117,9 +127,10 @@ public class MyPlugin extends JavaPlugin {

 ## 5. Getting an instance of the API
 - You can now get the API instance by calling `HuskSyncAPI#getInstance()`
+- If targeting the Bukkit platform, you can also use `BukkitHuskSyncAPI#getBukkitInstance()` to get the Bukkit-extended API instance (recommended)

 ```java
-import net.william278.husksync.api.BukkitHuskSyncAPI;
+import net.william278.husksync.api.HuskSyncAPI;

 public class HuskSyncAPIHook {

--- a/docs/Custom-Data-API.md
+++ b/docs/Custom-Data-API.md
@ -1,4 +1,4 @@
-HuskSync allows you to save and synchronize custom data through the existing versatile DataSnapshot format. This page assumes you've read the [[API]] introduction and are familiar with the aforementioned [[Data Snapshot API]].
+HuskSync allows you to save and synchronize custom data through the existing versatile DataSnapshot format. This page assumes you've read the [[API]] introduction and are familiar with the aforementioned [[Data Snapshot API]]. This page discusses API implementations that target the Bukkit platform.

 To do this, you create and register an implementation of a platform `Data` class (e.g., `BukkitData`) and a corresponding `Serializer` class (e.g., `BukkitSerializer`). You can then apply your custom data type to a user using the `OnlineUser#setData(Identifier, Data)` method.

--- a/gradle.properties
+++ b/gradle.properties
@ -3,7 +3,7 @@ org.gradle.jvmargs='-Dfile.encoding=UTF-8'
 org.gradle.daemon=true
 javaVersion=17

-plugin_version=3.2.2
+plugin_version=3.3
 plugin_archive=husksync
 plugin_description=A modern, cross-server player data synchronization system