Spring Boot Integration

Sophon provides extensive support for Spring, but does not require you to use Spring in order to use Sophon. All components can be configured programmatically and do not require Spring on the classpath. However, if you do use Spring, much of the configuration is made easier with the use of Spring’s annotation support. Sophon provides Spring Boot starters on the top of that, so you can benefit from auto-configuration as well.

The following table shows which Spring Boot versions are supported by each Sophon version:

Sophon Version Spring Boot 2 Spring Boot 3 Spring Boot 4

4.0 - 4.6

✓

4.7 - 4.12

✓

✓

4.13

✓

✓

✓

Auto-configuration

Sophon’s Spring Boot auto-configuration is by far the easiest option to get started configuring your Sophon components. By simply declaring dependency to sophon-spring-boot-starter, Sophon will automatically configure the infrastructure components (command bus, event bus, query bus), as well as any component required to run and store aggregates and sagas.

JPA and persistence contexts

With Spring Data-JPA, a JPA Persistence Context is automatically configured. Sophon’s Spring Boot Autoconfiguration module will make sure Sophon’s JPA Entities are automatically registered with this default context. Since 4.6.0. we use the jakarta.persistence namespace by default, for backwards compatibility classes using the javax.persistence are available in the new legacyjpa namespace.

However, when you explicitly include certain packages, for example using an @EntityScan annotation, this autoconfiguration will not happen anymore. If you then wish to use JPA based components from Sophon, you will need to make sure the right Entities are registered.

To register Sophon’s JPA Entities, include the relevant packages, as described below:

  • org.sophonhq.sophon.eventhandling.tokenstore contains the entities necessary for the TokenStore used by Event Processors.

  • org.sophonhq.sophon.modelling.saga.repository.jpa contains the entities necessary to persist Sagas

  • org.sophonhq.sophon.eventsourcing.eventstore.jpa contains the entities necessary for the JPA Event Storage engine, when using a relational database as the Event Store.

Demystifying Sophon Spring Boot Starter

With a lot of things happening in the background, it sometimes becomes difficult to understand how an annotation or just including a dependency enables so many features.

Auto configuration with Spring Boot 2

sophon-spring-boot-starter follows general Spring boot convention in structuring the starter. It depends on sophon-spring-boot-autoconfigure which holds concrete implementation of Sophon auto-configuration. When Sophon Spring Boot application starts up, it looks for a file named spring.factories in the classpath. This file is located in the META-INF directory of sophon-spring-boot-autoconfigure module:

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  org.sophonhq.sophon.springboot.autoconfig.MetricsAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.MicrometerMetricsAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.EventProcessingAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.AvroSerializerAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.SophonAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.SophonTimeoutAutoConfiguration, \
  org.sophonhq.sophon.springboot.autoconfig.SophonJobRunrAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.SophonDbSchedulerAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.legacyjpa.JpaJavaxAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.legacyjpa.JpaJavaxEventStoreAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.JpaAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.JpaEventStoreAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.JdbcAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.TransactionAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.NoOpTransactionAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.InfraConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.InterceptorAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.ObjectMapperAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.CBORMapperAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.XStreamAutoConfiguration,\
  org.sophonhq.sophon.springboot.autoconfig.SophonTracingAutoConfiguration, \
  org.sophonhq.sophon.springboot.autoconfig.OpenTelemetryAutoConfiguration, \
  org.sophonhq.sophon.springboot.autoconfig.SecurityAutoConfiguration

This file maps different configuration classes which a Sophon Spring Boot application will try to apply. So, as per this snippet, Spring Boot will try to apply all the configuration classes, like SophonAutoConfiguration, JpaAutoConfiguration, …

Auto configuration with Spring Boot

sophon-spring-boot-starter follows general Spring boot convention in structuring the starter. It depends on sophon-spring-boot-autoconfigure which holds concrete implementation of Sophon auto-configuration. When Sophon Spring Boot application starts up, it looks for a file named org.springframework.boot.autoconfigure.AutoConfiguration.imports in the classpath. This file is located in the META-INF/spring directory of sophon-spring-boot-autoconfigure module:

org.sophonhq.sophon.springboot.autoconfig.AvroSerializerAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.SophonAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.SophonTimeoutAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.SophonDbSchedulerAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.SophonJobRunrAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.SophonTracingAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.EventProcessingAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.InfraConfiguration
org.sophonhq.sophon.springboot.autoconfig.InterceptorAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.JdbcAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.legacyjpa.JpaJavaxAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.legacyjpa.JpaJavaxEventStoreAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.JpaAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.JpaEventStoreAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.MetricsAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.MicrometerMetricsAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.NoOpTransactionAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.ObjectMapperAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.CBORMapperAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.OpenTelemetryAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.SecurityAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.TransactionAutoConfiguration
org.sophonhq.sophon.springboot.autoconfig.XStreamAutoConfiguration

This file maps different configuration classes which a Sophon Spring Boot application will try to apply. So, as per this snippet, Spring Boot will try to apply all the configuration classes, like SophonAutoConfiguration, JpaAutoConfiguration, …

Whether these configuration classes will be applied or not, it will depend on conditions defined on these classes:

  • SophonAutoConfiguration configures the Command Bus, Query Bus, Event Store/Event Bus and other Sophon components. These components will be initialized only if they are not in the Spring Application context already, eg. @ConditionalOnMissingBean(EventBus.class).

Sophon Spring Boot auto-configuration is not intrusive. It will define only Spring components that you haven’t already explicitly defined in the application context. This allows you to completely override the auto-configured beans by defining your own in one of the @Configuration classes.

Specific Sophon (Spring) component configurations will be explained in detail in the following sections of this guide.

Spring event on startup finished

When using Spring to automatically wire everything, sometimes there is a need to know when all the (Command, Event and Query) handlers have been registered to their respective buses. To support this an SophonStartedEvent Spring event is published when the Configuration module has fully started.

Customizing the Jackson3Serializer

To customize the ObjectMapper used by the Jackson3Serializer, SophonAutoConfiguration will look for a bean of type Jackson3SerializerCustomizer. When found, it is given the Builder used to construct the ObjectMapper allowing you to customize it before it is constructed. For example:

public class SerializerConfiguration {
    @Bean
    public Jackson3SerializerCustomizer customizer() {
        return builder -> {
            builder.enable(StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION);
        };
    }
}