From 685431a40dc780d2df801c30789795729828a4ae Mon Sep 17 00:00:00 2001 From: William278 Date: Wed, 24 Jan 2024 23:25:37 +0000 Subject: [PATCH] api: add cross-platform API support --- build.gradle | 70 ++++++++++--------- .../husksync/api/BukkitHuskSyncAPI.java | 7 +- .../william278/husksync/api/HuskSyncAPI.java | 23 +++++- docs/API-Events.md | 6 +- docs/API.md | 23 ++++-- docs/Custom-Data-API.md | 2 +- gradle.properties | 2 +- 7 files changed, 81 insertions(+), 52 deletions(-) diff --git a/build.gradle b/build.gradle index 62def83f..7a716728 100644 --- 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 } } } diff --git a/bukkit/src/main/java/net/william278/husksync/api/BukkitHuskSyncAPI.java b/bukkit/src/main/java/net/william278/husksync/api/BukkitHuskSyncAPI.java index 6abf75c0..0994a7a7 100644 --- 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; - /** * (Internal use only) - 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; } /** diff --git a/common/src/main/java/net/william278/husksync/api/HuskSyncAPI.java b/common/src/main/java/net/william278/husksync/api/HuskSyncAPI.java index 20dc7415..14b1fda1 100644 --- 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. *

- * 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; /** * (Internal use only) - 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 * diff --git a/docs/API-Events.md b/docs/API-Events.md index edfecadf..ecb7bcbe 100644 --- 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—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 | diff --git a/docs/API.md b/docs/API.md index f6babedf..1a5e7dc4 100644 --- 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—v2.2.8_ | ❌ | | v1.x | _v1.0—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. + +
Targeting older versions -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.
## 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 - net.william278 - husksync + net.william278.husksync + husksync-PLATFORM VERSION provided @@ -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' } ``` @@ -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 { diff --git a/docs/Custom-Data-API.md b/docs/Custom-Data-API.md index ec71c916..0a0c12b9 100644 --- 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. diff --git a/gradle.properties b/gradle.properties index 2e829de1..2cc12ca1 100644 --- 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