Allow other ways to recognize events than by class type in JpaEventPublication

[daniel-frak]

The problem

I would like to make the event outbox completely independent of my classes, so that I can always safely rename and move classes between packages without having to create migrations for the event_publication table.

Currently, two columns within that table are dependent on class information:

• listener_id,
• event_type.

listener_id is easily solvable by always declaring a custom id in @TransactionalEventListener.

Unfortunately, event_type is hardcoded as Class<T> in EventSerializer, JpaEventPublicationRepository and JpaEventPublication itself.

I could probably work around EventSerializer and JpaEventPublicationRepository via some casting shenanigans. However, Hibernate will throw an exception when it tries to retrieve a JpaEventPublication with an eventType class that is not on the class path, so there currently seems to be no path to a solution.

Use case example

I created the following annotation in my project, which I'm using along with a custom EventSerializer:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface OutboxEventMapper {
    String id();
    Class<?> domain();
    Class<?> outbox();
}

It allows me to very simply declare mappers between my internal domain events and their outbox DTOs, e.g.,:

@OutboxEventMapper(
        id = "FileBackupFinishedEvent",
        domain = FileBackupFinishedEvent.class,
        outbox = FileBackupFinishedOutboxEvent.class
)
@Mapper(unmappedSourcePolicy = ReportingPolicy.IGNORE)
public interface FileBackupFinishedOutboxEventMapper {

    FileBackupFinishedOutboxEvent toOutbox(FileBackupFinishedEvent domain);

    FileBackupFinishedEvent toDomain(FileBackupFinishedOutboxEvent outbox);
}

I would like to be able to use the id property to identify which domain event class to deserialize an outbox event into.

Suggested solution

I think the best solution would be to abstract away the eventType as a string and allow clients to provide their own resolvers for it.

[odrotbohm]

Let's take a step back, please. Spring Modulith doesn't ship any outbox itself. I assume you're referring to the Event Publication Registry, which captures event publications for application-internal handling. For that, event_type captures the domain event type. It's not hard-coded to JpaEventPublication. The latter is an implementation detail to persist the event plus information about the target listener. EventSerializer is an abstraction to turn an instance of whatever the event_type is into a (persistence-)serializable format and back.

We currently don't support any customizations of the way that event publications get persisted, except EventSerializer defining the payload format. One reason for that is that the change in type would also need to be reflected in the PublicationTargetIdentifier. I.e., even if you got the refactored type instantiated, we wouldn't even find the correct listener to invoke, as the identifier for the method would contain the new parameter type while the database contains the former.

[daniel-frak]

Thanks for taking the time to answer and explain.

Let's take a step back, please. Spring Modulith doesn't ship any outbox itself. I assume you're referring to the Event Publication Registry, which captures event publications for application-internal handling.

Yes, I'm referring to the Event Publication Registry. I consider the event_publication table to be an outbox, but it does require a database, so fair point.

It's not hard-coded to JpaEventPublication. The latter is an implementation detail to persist the event plus information about the target listener.

It's a good point. I should have focused more on the EventPublication class in my original message.

We currently don't support any customizations of the way that event publications get persisted, except EventSerializer defining the payload format. One reason for that is that the change in type would also need to be reflected in the PublicationTargetIdentifier. I.e., even if you got the refactored type instantiated, we wouldn't even find the correct listener to invoke, as the identifier for the method would contain the new parameter type while the database contains the former.

I'm not sure if PublicationTargetIdentifier is a big issue in this case - while the default listener does contain the class name, this is easily "fixed" by providing a custom listener id. Assuming that path, by the time I got my refactored type instantiated, the class type will be the same as the class type expected by the listener (as the EventSerializer and listener must share the same codebase and instance for deserialization to even happen), so no issues there. Am I missing something important here? I do concede that the solution wouldn't work without using custom listener ids but those can either be forced via validation when using custom event types, or become the responsibility of the client to always define.

The bottom line is I think that there is great value to decoupling the event publication from package and class names, so that refactorings are much safer. I believe this change would greatly reduce the risks of using Modulith events, especially since the depth of the coupling is not clear from the surface-level interface interactions with the API. The event type is, I believe, the only place where the decoupling currently cannot be achieved.

As a minimal solution, I think adding String eventType to EventPublication and providing a strategy interface to define it would work. JpaEventPublicationRegistry could then use that eventType instead of event.getClass(). Dealing with eventListenerId would become the client's responsibility. Let me know if I'm missing some crucial issues with this.

Of course, an out-of-the-box solution which allows for first-class event type ids would be even better, as every Modulith application could benefit from stable event types without extra code. I understand that might require substantial changes to the codebase, though.

What do you think?