Release 1.0.2 (#11)

Author: rainbowdashlabs

.github/workflows/javadocs.yml

@@ -25,7 +25,7 @@ jobs:
           echo "Creating .nojekyll to have Github pages deploy html as is:"
           touch .nojekyll
       - name: Deploy
-        uses: JamesIves/github-pages-deploy-action@v4.4.0
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages # The branch the action should deploy to.
           folder: build/docs/javadoc # The folder the action should deploy.

.github/workflows/publish_to_nexus.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3.0.2
+      - uses: actions/checkout@v3
       - name: Set up JDK 18
         uses: actions/setup-java@v3
         with:

.github/workflows/verify.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3.0.2
+      - uses: actions/checkout@v3
       - name: Set up JDK 18
         uses: actions/setup-java@v3
         with:

Readme.md

@@ -35,25 +35,58 @@ dependencies {
 </dependency>
 ```
 
-## Usage
+## Module Creation
 
-Simply add the JacksonBukkit module to the builder of your choice.
+You can either create the `JacksonBukkit` and `JacksonPaper` module directly or use the builder for easy modification. 
+Usage of the builder is recommended.
+Builder for spigot and paper can both be accessed via the `JacksonBukkit` class.
+
+### Creating a Spigot/Bukkit Module
 
 ```java
-    ObjectMapper JSON = JsonMapper.builder()
-            .addModule(new JacksonBukkit())
-            .build();
+    ObjectMapper JSON=JsonMapper.builder()
+        .addModule(JacksonBukkit.spigot().build())
+        .build();
+```
+
+### Creating a Paper Module
 
+```java
+    ObjectMapper JSON=JsonMapper.builder()
+        .addModule(JacksonBukkit.paper().build())
+        .build();
 ```
 
+### Difference between Paper and Bukkit module
+
+Paper serializes `ItemStack`s to a Base64 encoded byte array instead of using spigots serialization.
+This will only work on paper servers and not on spigot servers. 
+The builder allows to use spigots serialization on paper servers as well, but this is not recommended. 
+
+When creating a paper plugin the `JacksonBukkit` module is no longer able to serialize `ItemStacks`.
+you need to use `JacksonPaper` in that case and make sure that you are not using legacy serialization.
+
+### More customization
+
+There are some more customizations
+
+#### Color
+
+Colors will be read and written to an object containing a value for red, green, blue and alpha by default. 
+By calling `ModuleBuilder#colorAsHex()` you can enable hex codes.
+This will attempt to read each color as a HEX string with RGBA or RGB format.
+It will also write colors as RGBA.
+
+**Warning:** As of now you can use either way, but not both at the same time. Mixing up format will cause errors.
+
 ## Supported Classes
 
 We support all classes implementing `ConfigurationSerializable`. To be precise we support the following classes:
 
 - Vector
 - BlockVector
-- Color
-- ItemStack (Serialized as Base64 encoded bytes as recommended by [paper](https://jd.papermc.io/paper/1.19/org/bukkit/inventory/ItemStack.html#serializeAsBytes()))
+- Color (Can be serialized as object or as hex string)
+- ItemStack (Serialized as map for `JacksonBukkit`. Serialized as Base64 encoded bytes for `JacksonPaper`)
 - PotionEffect
 - FireworkEffect
 - Pattern
@@ -65,4 +98,4 @@ We support all classes implementing `ConfigurationSerializable`. To be precise w
 
 - NamespacedKey
 - OfflinePlayer
-- Inventory via InventoryWrapper class
+- Inventory via `InventoryWrapper` class

build.gradle.kts

@@ -4,13 +4,13 @@ plugins {
     java
     `maven-publish`
     `java-library`
-    id("com.diffplug.spotless") version "6.16.0"
+    id("com.diffplug.spotless") version "6.17.0"
     id("de.chojo.publishdata") version "1.2.4"
     id("io.papermc.paperweight.userdev") version "1.5.3"
 }
 
 group = "de.eldoria"
-version = "1.0.1"
+version = "1.0.2"
 
 repositories {
     mavenCentral()

src/main/java/de/eldoria/jacksonbukkit/JacksonBukkit.java

@@ -9,13 +9,16 @@
 import com.fasterxml.jackson.databind.Module;
 import com.fasterxml.jackson.databind.module.SimpleDeserializers;
 import com.fasterxml.jackson.databind.module.SimpleSerializers;
+import de.eldoria.jacksonbukkit.builder.JacksonBukkitBuilder;
+import de.eldoria.jacksonbukkit.builder.JacksonPaperBuilder;
 import de.eldoria.jacksonbukkit.deserializer.AttributeModifierDeserializer;
 import de.eldoria.jacksonbukkit.deserializer.BlockVectorDeserializer;
 import de.eldoria.jacksonbukkit.deserializer.BoundingBoxDeserializer;
+import de.eldoria.jacksonbukkit.deserializer.BukkitItemStackDeserializer;
 import de.eldoria.jacksonbukkit.deserializer.ColorDeserializer;
 import de.eldoria.jacksonbukkit.deserializer.FireworkEffectDeserializer;
+import de.eldoria.jacksonbukkit.deserializer.HexColorDeserializer;
 import de.eldoria.jacksonbukkit.deserializer.InventoryDeserializer;
-import de.eldoria.jacksonbukkit.deserializer.ItemStackDeserializer;
 import de.eldoria.jacksonbukkit.deserializer.LocationDeserializer;
 import de.eldoria.jacksonbukkit.deserializer.NamespacedKeyDeserializer;
 import de.eldoria.jacksonbukkit.deserializer.PatternDeserializer;
@@ -26,10 +29,11 @@
 import de.eldoria.jacksonbukkit.serializer.AttributeModifierSerializer;
 import de.eldoria.jacksonbukkit.serializer.BlockVectorSerializer;
 import de.eldoria.jacksonbukkit.serializer.BoundingBoxSerializer;
+import de.eldoria.jacksonbukkit.serializer.BukkitItemStackSerializer;
 import de.eldoria.jacksonbukkit.serializer.ColorSerializer;
 import de.eldoria.jacksonbukkit.serializer.FireworkEffectSerializer;
+import de.eldoria.jacksonbukkit.serializer.HexColorSerializer;
 import de.eldoria.jacksonbukkit.serializer.InventorySerializer;
-import de.eldoria.jacksonbukkit.serializer.ItemStackSerializer;
 import de.eldoria.jacksonbukkit.serializer.LocationSerializer;
 import de.eldoria.jacksonbukkit.serializer.NamespacedKeySerializer;
 import de.eldoria.jacksonbukkit.serializer.PatternSerializer;
@@ -73,9 +77,57 @@
  *     <li>{@link OfflinePlayer}
  *     <li>{@link Inventory} via {@link InventoryWrapper}
  * </ul>
- * <p>
  */
 public class JacksonBukkit extends Module {
+    private final boolean hexColors;
+
+    /**
+     * Create a new JacksonBukkit module.
+     *
+     * @param hexColors true to serialize colors as hex by default
+     */
+    public JacksonBukkit(boolean hexColors) {
+        this.hexColors = hexColors;
+    }
+
+    /**
+     * Create a new JacksonPaper module.
+     */
+    public JacksonBukkit() {
+        hexColors = false;
+    }
+
+    /**
+     * Create a new builder for a {@link JacksonBukkit} module for use with spigot.
+     * <p>
+     * If you are using paper you should use the {@link #paper()} builder.
+     *
+     * @return builder instance
+     */
+    public static JacksonBukkitBuilder bukkit() {
+        return new JacksonBukkitBuilder();
+    }
+
+    /**
+     * Create a new builder for a {@link JacksonBukkit} module for use with spigot.
+     * <p>
+     * If you are using paper you should use the {@link #paper()} builder.
+     *
+     * @return builder instance
+     */
+    public static JacksonBukkitBuilder spigot() {
+        return new JacksonBukkitBuilder();
+    }
+
+    /**
+     * Create a new builder for a {@link JacksonPaper} module for use with paper.
+     *
+     * @return builder instance
+     */
+    public static JacksonPaperBuilder paper() {
+        return new JacksonPaperBuilder();
+    }
+
     @Override
     public String getModuleName() {
         return "JacksonBukkit";
@@ -89,10 +141,25 @@ public Version version() {
     @Override
     public void setupModule(SetupContext context) {
         SimpleSerializers serializers = new SimpleSerializers();
+        addSerializer(serializers);
+
+        SimpleDeserializers deserializers = new SimpleDeserializers();
+        addDeserializer(deserializers);
+
+        context.addSerializers(serializers);
+        context.addDeserializers(deserializers);
+    }
+
+    /**
+     * Add serializer to the serializers
+     *
+     * @param serializers serializers
+     */
+    protected void addSerializer(SimpleSerializers serializers) {
         serializers.addSerializer(Vector.class, new VectorSerializer());
         serializers.addSerializer(BlockVector.class, new BlockVectorSerializer());
-        serializers.addSerializer(Color.class, new ColorSerializer());
-        serializers.addSerializer(ItemStack.class, new ItemStackSerializer());
+        serializers.addSerializer(Color.class, hexColors ? new HexColorSerializer() : new ColorSerializer());
+        serializers.addSerializer(ItemStack.class, new BukkitItemStackSerializer());
         serializers.addSerializer(NamespacedKey.class, new NamespacedKeySerializer());
         serializers.addSerializer(PotionEffect.class, new PotionEffectSerializer());
         serializers.addSerializer(FireworkEffect.class, new FireworkEffectSerializer());
@@ -102,12 +169,18 @@ public void setupModule(SetupContext context) {
         serializers.addSerializer(Location.class, new LocationSerializer());
         serializers.addSerializer(OfflinePlayer.class, new PlayerSerializer());
         serializers.addSerializer(InventoryWrapper.class, new InventorySerializer());
+    }
 
-        SimpleDeserializers deserializers = new SimpleDeserializers();
+    /**
+     * Add deserializer to the deserializers
+     *
+     * @param deserializers deserializers
+     */
+    protected void addDeserializer(SimpleDeserializers deserializers) {
         deserializers.addDeserializer(Vector.class, new VectorDeserializer());
         deserializers.addDeserializer(BlockVector.class, new BlockVectorDeserializer());
-        deserializers.addDeserializer(Color.class, new ColorDeserializer());
-        deserializers.addDeserializer(ItemStack.class, new ItemStackDeserializer());
+        deserializers.addDeserializer(Color.class, hexColors ? new HexColorDeserializer() : new ColorDeserializer());
+        deserializers.addDeserializer(ItemStack.class, new BukkitItemStackDeserializer());
         deserializers.addDeserializer(NamespacedKey.class, new NamespacedKeyDeserializer());
         deserializers.addDeserializer(PotionEffect.class, new PotionEffectDeserializer());
         deserializers.addDeserializer(FireworkEffect.class, new FireworkEffectDeserializer());
@@ -117,8 +190,5 @@ public void setupModule(SetupContext context) {
         deserializers.addDeserializer(Location.class, new LocationDeserializer());
         deserializers.addDeserializer(OfflinePlayer.class, new PlayerDeserializer());
         deserializers.addDeserializer(InventoryWrapper.class, new InventoryDeserializer());
-
-        context.addSerializers(serializers);
-        context.addDeserializers(deserializers);
     }
 }

src/main/java/de/eldoria/jacksonbukkit/JacksonPaper.java

@@ -0,0 +1,93 @@
+/*
+ *     SPDX-License-Identifier: MIT
+ *
+ *     Copyright (C) EldoriaRPG Team and Contributor
+ */
+package de.eldoria.jacksonbukkit;
+
+import com.fasterxml.jackson.databind.module.SimpleDeserializers;
+import com.fasterxml.jackson.databind.module.SimpleSerializers;
+import de.eldoria.jacksonbukkit.deserializer.PaperItemStackDeserializer;
+import de.eldoria.jacksonbukkit.entities.InventoryWrapper;
+import de.eldoria.jacksonbukkit.serializer.PaperItemStackSerializer;
+import org.bukkit.Color;
+import org.bukkit.FireworkEffect;
+import org.bukkit.Location;
+import org.bukkit.NamespacedKey;
+import org.bukkit.OfflinePlayer;
+import org.bukkit.attribute.AttributeModifier;
+import org.bukkit.block.banner.Pattern;
+import org.bukkit.configuration.serialization.ConfigurationSerializable;
+import org.bukkit.inventory.Inventory;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.potion.PotionEffect;
+import org.bukkit.util.BlockVector;
+import org.bukkit.util.BoundingBox;
+import org.bukkit.util.Vector;
+
+/**
+ * Class adding support for classes implementing {@link ConfigurationSerializable}.
+ *
+ * <ul>
+ *     <li>{@link Vector}
+ *     <li>{@link BlockVector}
+ *     <li>{@link Color}
+ *     <li>{@link ItemStack}
+ *     <li>{@link PotionEffect}
+ *     <li>{@link FireworkEffect}
+ *     <li>{@link Pattern}
+ *     <li>{@link BoundingBox}
+ *     <li>{@link AttributeModifier}
+ *     <li>{@link Location}
+ * </ul>
+ * <p>
+ * It also provides some additional serialization for:
+ * <ul>
+ *     <li>{@link NamespacedKey}
+ *     <li>{@link OfflinePlayer}
+ *     <li>{@link Inventory} via {@link InventoryWrapper}
+ * </ul>
+ */
+public class JacksonPaper extends JacksonBukkit {
+    private final boolean legacyItemStackSerialization;
+
+    /**
+     * Create a new JacksonPaper module.
+     *
+     * @param hexColors                    true to serialize colors as hex by default
+     * @param legacyItemStackSerialization true to use spigot based serialization
+     */
+    public JacksonPaper(boolean hexColors, boolean legacyItemStackSerialization) {
+        super(hexColors);
+        this.legacyItemStackSerialization = legacyItemStackSerialization;
+    }
+
+    /**
+     * Create a new JacksonPaper module.
+     */
+    public JacksonPaper() {
+        super();
+        legacyItemStackSerialization = false;
+    }
+
+    @Override
+    public String getModuleName() {
+        return "JacksonPaper";
+    }
+
+    @Override
+    protected void addDeserializer(SimpleDeserializers deserializers) {
+        super.addDeserializer(deserializers);
+        if (!legacyItemStackSerialization) {
+            deserializers.addDeserializer(ItemStack.class, new PaperItemStackDeserializer());
+        }
+    }
+
+    @Override
+    protected void addSerializer(SimpleSerializers serializers) {
+        super.addSerializer(serializers);
+        if (!legacyItemStackSerialization) {
+            serializers.addSerializer(ItemStack.class, new PaperItemStackSerializer());
+        }
+    }
+}

src/main/java/de/eldoria/jacksonbukkit/builder/JacksonBukkitBuilder.java

@@ -0,0 +1,18 @@
+/*
+ *     SPDX-License-Identifier: MIT
+ *
+ *     Copyright (C) EldoriaRPG Team and Contributor
+ */
+package de.eldoria.jacksonbukkit.builder;
+
+import de.eldoria.jacksonbukkit.JacksonBukkit;
+
+/**
+ * Class to build a {@link JacksonBukkit} module.
+ */
+public class JacksonBukkitBuilder extends ModuleBuilder<JacksonBukkitBuilder, JacksonBukkit> {
+    @Override
+    public JacksonBukkit build() {
+        return new JacksonBukkit(hexColors);
+    }
+}