Changes:

  onCustomEvent() <- registering custom events
  onMapping() <-  custom mappings
  check out 'CustomMappingExample'

  more gifs has been added
  exceptions are more explicit

Author: jwdeveloper

API/src/main/java/io/github/jwdeveloper/tiktok/exceptions/TikTokMessageMappingException.java

@@ -26,15 +26,20 @@
 /**
  * Happens when incoming data from TikTok can not be mapped to TikTokEvent's
  */
-public class TikTokMessageMappingException extends TikTokLiveException
-{
-    public TikTokMessageMappingException(Class<?> inputClazz, Class<?> outputClass, Throwable throwable)
-    {
-        super("Unable to handle mapping from class: " + inputClazz.getSimpleName() + " to class " + outputClass.getSimpleName(),throwable);
+public class TikTokMessageMappingException extends TikTokLiveException {
+    public TikTokMessageMappingException(Class<?> inputClazz, Class<?> outputClass, Throwable throwable) {
+        super("Unable to handle mapping from class: " + inputClazz.getSimpleName() + " to class " + outputClass.getSimpleName(), throwable);
     }
 
-    public TikTokMessageMappingException(Class<?> inputClazz, Class<?> outputClass, String message)
-    {
-        super("Unable to handle mapping from class: " + inputClazz.getSimpleName() + " to class " + outputClass.getSimpleName()+": "+message);
+    public TikTokMessageMappingException(Class<?> inputClazz, Class<?> outputClass, String message) {
+        super("Unable to handle mapping from class: " + inputClazz.getSimpleName() + " to class " + outputClass.getSimpleName() + ": " + message);
+    }
+
+    public TikTokMessageMappingException(Class<?> inputClazz, String message, Throwable throwable) {
+        super("Unable to handle mapping from class: " + inputClazz.getSimpleName() + ": " + message, throwable);
+    }
+
+    public TikTokMessageMappingException(String message, Throwable throwable) {
+        super( message, throwable);
     }
 }

API/src/main/java/io/github/jwdeveloper/tiktok/live/builder/EventsBuilder.java

@@ -38,7 +38,12 @@
 
 public interface EventsBuilder<T> {
 
-    T onCustomEvent(EventConsumer<CustomEvent> event);
+    /**
+     *  Method used to register own custom events
+     * @param eventClazz event class
+     * @param event action
+     */
+    <E extends TikTokEvent> T onCustomEvent(Class<E> eventClazz, EventConsumer<E> event);
 
     T onRoomInfo(EventConsumer<TikTokRoomInfoEvent> event);
 
@@ -52,6 +57,7 @@ public interface EventsBuilder<T> {
 
 
     T onGiftCombo(EventConsumer<TikTokGiftComboEvent> event);
+
     T onGift(EventConsumer<TikTokGiftEvent> event);
 
     T onQuestion(EventConsumer<TikTokQuestionEvent> event);
@@ -68,7 +74,7 @@ public interface EventsBuilder<T> {
 
     T onShare(EventConsumer<TikTokShareEvent> event);
 
-  //  T onChest(EventConsumer<TikTokChestEvent> event);
+    //  T onChest(EventConsumer<TikTokChestEvent> event);
 
     T onLivePaused(EventConsumer<TikTokLivePausedEvent> event);
 
@@ -83,9 +89,8 @@ public interface EventsBuilder<T> {
     T onDisconnected(EventConsumer<TikTokDisconnectedEvent> event);
 
     T onError(EventConsumer<TikTokErrorEvent> event);
-    T onEvent(EventConsumer<TikTokEvent> event);
-
 
+    T onEvent(EventConsumer<TikTokEvent> event);
 
 
     // TODO Figure out how those events works

API/src/main/java/io/github/jwdeveloper/tiktok/live/builder/LiveClientBuilder.java

@@ -23,20 +23,60 @@
 package io.github.jwdeveloper.tiktok.live.builder;
 
 import io.github.jwdeveloper.tiktok.ClientSettings;
+import io.github.jwdeveloper.tiktok.data.events.common.TikTokEvent;
 import io.github.jwdeveloper.tiktok.listener.TikTokEventListener;
 import io.github.jwdeveloper.tiktok.live.LiveClient;
+import io.github.jwdeveloper.tiktok.mappers.TikTokMapper;
 
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
+import java.util.function.Function;
 
 public interface LiveClientBuilder extends EventsBuilder<LiveClientBuilder> {
-    LiveClientBuilder configure(Consumer<ClientSettings> consumer);
 
+    /**
+     * This method is triggered after default mappings are registered
+     * It could be used to OVERRIDE behaviour of mappings and implement custom behaviour
+     *
+     * Be aware if for example you override WebcastGiftEvent, onGiftEvent() will not be working
+     *
+     * @param onCustomMappings lambda method
+     * @return
+     */
+    LiveClientBuilder onMapping(Consumer<TikTokMapper> onCustomMappings);
+
+
+    /**
+     * Configuration of client settings
+     * @see ClientSettings
+     * @param onConfigure
+     * @return
+     */
+    LiveClientBuilder configure(Consumer<ClientSettings> onConfigure);
+
+    /**
+     * @see TikTokEventListener
+     * Adding events listener class, its fancy way to register events without using lamda method
+     * but actual method in class that implements TikTokEventListener
+     * @return
+     */
     LiveClientBuilder addListener(TikTokEventListener listener);
 
+    /**
+     *
+     * @return LiveClient object
+     */
     LiveClient build();
 
+    /**
+     *
+     * @return LiveClient object and connects to TikTok live
+     */
     LiveClient buildAndConnect();
 
+    /**
+     *
+     * @return LiveClient object and connects to TikTok live asynchronously
+     */
     CompletableFuture<LiveClient> buildAndConnectAsync();
 }

API/src/main/java/io/github/jwdeveloper/tiktok/mappers/TikTokMapper.java

@@ -0,0 +1,73 @@
+package io.github.jwdeveloper.tiktok.mappers;
+
+import com.google.protobuf.GeneratedMessageV3;
+import io.github.jwdeveloper.tiktok.data.events.common.TikTokEvent;
+
+import java.util.List;
+import java.util.function.Function;
+
+public interface TikTokMapper {
+
+
+    /**
+     * Triggered when `sourceClass` is mapped,
+     * input is bytes that are coming from TikTok in `sourceClass` packet
+     * output is TikTok event we want to create
+     * <p>
+     * bytesToEvent(WebcastGiftMessage.class, bytes ->
+     * {
+     * var giftMessage = WebcastGiftMessage.parseFrom(bytes);
+     * var giftName = giftMessage.getGift().getName();
+     * return new TikTokEvent(Gift.ROSE, giftMessage);
+     * })
+     *
+     * @param sourceClass protocol buffer webcast class
+     * @param onMapping   lambda function that is triggered on mapping. takes as input ProtocolBuffer object and as output TikTokEvent
+     */
+    void bytesToEvent(Class<? extends GeneratedMessageV3> sourceClass, Function<byte[], TikTokEvent> onMapping);
+
+    void bytesToEvents(Class<? extends GeneratedMessageV3> sourceClass, Function<byte[], List<TikTokEvent>> onMapping);
+
+
+    /**
+     * In case you found some TikTok message that has not Webcast class use this method
+     *
+     * @param messageName Name of TikTok data event
+     * @param onMapping   lambda function that is triggered on mapping. takes as input ProtocolBuffer object and as output TikTokEvent
+     */
+    void bytesToEvent(String messageName, Function<byte[], TikTokEvent> onMapping);
+
+    void bytesToEvents(String messageName, Function<byte[], List<TikTokEvent>> onMapping);
+
+
+    /**
+     * This method can be used to override default mapping for
+     * certain TikTok incoming data message. For this example
+     * we are overriding WebcastGiftMessage and retuning CustomGiftEvent
+     * instead of TikTokGiftEvent
+     * <p>
+     * webcastObjectToEvent(WebcastGiftMessage.class, webcastGiftMessage ->
+     * {
+     * var giftName = webcastGiftMessage.getGift().getName();
+     * var user = webcastGiftMessage.getUser().getNickname();
+     * return new CustomGiftEvent(giftName, user);
+     * })
+     *
+     * @param sourceClass ProtocolBuffer class that represent incoming custom data, hint class should starts with Webcast prefix
+     * @param onMapping   lambda function that is triggered on mapping. takes as input ProtocolBuffer object and as output TikTokEvent
+     */
+    <T extends GeneratedMessageV3> void webcastObjectToEvent(Class<T> sourceClass, Function<T, TikTokEvent> onMapping);
+
+    <T extends GeneratedMessageV3> void webcastObjectToEvents(Class<T> sourceClass, Function<T, List<TikTokEvent>> onMapping);
+
+    /**
+     * Triggered when `sourceClass` is mapped,
+     * looking for constructor in `outputClass` with one parameter that is of type `sourceClass`
+     * and created instance of object from this constructor
+     *
+     * @param sourceClass protocol buffer webcast class
+     * @param outputClass TikTok event class
+     */
+    void webcastObjectToConstructor(Class<? extends GeneratedMessageV3> sourceClass, Class<? extends TikTokEvent> outputClass);
+
+}

API/src/main/java/io/github/jwdeveloper/tiktok/utils/CancelationToken.java

@@ -0,0 +1,56 @@
+package io.github.jwdeveloper.tiktok.utils;
+
+import java.nio.file.Path;
+import java.util.Map;
+import java.util.TreeMap;
+
+public class ProtoBufferFileGenerator {
+
+
+    public static String generate(ProtoBufferObject protoBuffObj, String name) {
+
+        var sb = new StringBuilder();
+        var offset = 2;
+        sb.append("message ").append(name).append(" { \n");
+
+        var objects = new TreeMap<String, ProtoBufferObject>();
+        var objectCounter = 0;
+        for (var entry : protoBuffObj.getFields().entrySet()) {
+            var index = entry.getKey();
+            var field = entry.getValue();
+            var fieldName = field.type.toLowerCase() + "Value";
+            var value = field.value;
+            if (field.value instanceof ProtoBufferObject object) {
+                fieldName += objectCounter;
+                value = "";
+                objects.put(fieldName,object);
+                objectCounter++;
+
+            }
+            for (var i = 0; i < offset; i++) {
+                sb.append(" ");
+            }
+            sb.append(field.type).append(" ").append(fieldName)
+                    .append(" ")
+                    .append("=")
+                    .append(" ")
+                    .append(index)
+                    .append(";")
+                    .append(" //")
+                    .append(value)
+                    .append("\n");
+        }
+        sb.append(" \n");
+        for(var object : objects.entrySet())
+        {
+            var structure = generate(object.getValue(),object.getKey());
+            sb.append(structure);
+        }
+
+
+        sb.append(" \n");
+        sb.append("} \n");
+        return sb.toString();
+    }
+
+}

API/src/main/java/io/github/jwdeveloper/tiktok/utils/ProtoBufferFileGenerator.java

@@ -0,0 +1,31 @@
+package io.github.jwdeveloper.tiktok.utils;
+
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonObject;
+
+public class ProtoBufferJsonGenerator {
+    public static JsonObject genratejson(ProtoBufferObject protoBuffObj) {
+
+        JsonObject jsonObject = new JsonObject();
+        for (var entry : protoBuffObj.getFields().entrySet()) {
+            var fieldName = entry.getKey() + "_" + entry.getValue().type;
+            if (entry.getValue().value instanceof ProtoBufferObject protoObj)
+            {
+                JsonObject childJson = genratejson(protoObj);
+                jsonObject.add(fieldName, childJson);
+                continue;
+            }
+
+            var value = entry.getValue().value.toString();
+            jsonObject.addProperty(fieldName, value);
+        }
+
+        return jsonObject;
+    }
+
+    public static String generate(ProtoBufferObject protoBufferObject) {
+        var json = genratejson(protoBufferObject);
+        var gson = new GsonBuilder().setPrettyPrinting().create();
+        return gson.toJson(json);
+    }
+}