Plugin Internal Error

PlatformHub throws multiple errors during the initialisation and configuration of the Microkernel. These errors are meant to help developers to properly configure their plugins. However, there are times when a plugin will need to communicate an error that has occurred when processing a request from another plugin.

The PluginInternalError allow plugins to implement their own custom errors and send them to other plugins. This error is recoverable so plugins receiving this error can catch and handle it respectively.

When To Use PluginInternalError

The PluginInternalError can be used in a scenario where a plugin need to send an error to another plugin. An example of this scenario could be for a network plugin send an HTTP response error to the plugins that are interested in the that specific network call.

Another scenario could be a journey plugin that allow form inputs and submit the values to a domain model plugin to verify the validity of the values, the domain model plugin can then use the PluginInternalError to send a corresponding error back to the journey plugin if any of the input values fails the validation.

The plugin error can also be handled to show information to the user in case something goes wrong while performing some actions. For example, the form input scenario can be used to show a message to the user when one of the input values fail to the validation so the user know what went wrong.

Implementing a Custom Plugin Error

Implementing a custom plugin error for your plugin is quite simple. All you have to do is inherit the PluginInternalError abstract class and implement the abstract members. The PluginInternalError abstract class itself also inherits from RuntimeException so you get access to the members of RuntimeException that you can override (i.e. message to add a custom message for the error).

Looking at the example scenario for the form input, we can implement a sealed class that inherit PluginInternalError to cover the different error types. For example a login form for entering username and password, below is an example of how to implement a custom plugin error for this scenario.

sealed class LoginError : PluginInternalError() {
    data class InvalidUsername(
        override val errorCode: Int = 1,
        override val message: String = "Your message here",
        override val payload: JSONObject? = null
    ): LoginError()

     data class InvalidPassword(
        override val errorCode: Int = 2,
        override val message: String = "Your message here",
        override val payload: JSONObject? = null
    ): LoginError()
}

As seen in the example code above how easy to implement a custom error. In this case we implement a login error with two different error types, one for username and the other for password. Each of the error types then override the abstract fields from PluginInternalError.

The Abstract Fields

• Error Code: This is useful if you want to send specific code related to the error. This is especially useful for network responses where you can send an HTTP code along with the error.
• Message: This is to allow adding a message to the error to describe what went wrong. The message field is inherited from RuntimeException so you have to explicitly override it otherwise it would become optional.
• Payload: Payload allows you to send any optional data along with the error.

Sending The Custom Error

The custom error can be sent with PlatformHub event stream to allow it to be broadcast to any plugin interested in it. Below is an example of how you can sent the example LoginError above to other plugins.

class ExamplePlugin: Plugin(...) {
    
    override fun publish(eventStream: BaseMessage.EventStream): SharedFlow<EventStreamOutput> {
        return when(eventStream.messageName) {
            "ValidateUsername" -> flow {
                emit(
                    EventStreamOutput(
                        error = LoginError.InvalidUsername,
                        correlationMessage = message
                    )
                )
            }.shareIn(coroutineScope, SharingStarted.WhileSubscribed())
        }
    }

    ...
}

In the above example code, we are sending the username error for the message ValidateUsername so any plugin listening to this message will receive the username error in the form of PluginInternalError since the username error also conform to the PluginInternalError abstract class. Once the error is received, it is up to the receiving plugin to handle it how ever they want.

For a live usage example, you can check the PlatformHub library sample app. It has an example implementation of the PluginInternalError.