Developer Guide: Working with Configurations

@Entity
@Table(name = "mqtt_broker_configuration")
@EntityListeners(AuditingEntityListener.class)   // populates created/updated audit fields
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class MqttBrokerConfiguration {

    @Id
    @SmartIdGeneration                            // MySQL identity / Oracle sequence, auto-detected
    @Column(name = "id")
    private Long id;

    @Column(name = "host", nullable = false, length = 255)
    private String host;

    @Column(name = "port", nullable = false)
    private Integer port;

    @CreatedDate    @Column(name = "created_at", updatable = false) private LocalDateTime createdAt;
    @CreatedBy      @Column(name = "created_by", updatable = false) private String createdBy;
    @LastModifiedDate @Column(name = "updated_at")                  private LocalDateTime updatedAt;
    @LastModifiedBy   @Column(name = "updated_by")                  private String updatedBy;

    @Version
    @Column(name = "entity_version", nullable = false)
    private Integer version;
}

public interface MqttBrokerConfigurationRepository
        extends JpaRepository<MqttBrokerConfiguration, Long> {

    // Singleton accessor -- deterministic ordering, never relies on a hardcoded id
    Optional<MqttBrokerConfiguration> findTopByOrderByIdAsc();
}

@Value
@Builder
@Schema(description = "MQTT broker configuration payload")
public class MqttBrokerConfigurationRequestDto {

    @NotBlank
    @Schema(description = "Broker host")
    String host;

    @NotNull
    @Min(1) @Max(65535)
    @Schema(description = "Broker port")
    Integer port;
}

@Component
@RequiredArgsConstructor
public class MqttBrokerConfigurationMapper {

    public MqttBrokerConfigurationSnapshotDto toSnapshot(MqttBrokerConfiguration entity) {
        return MqttBrokerConfigurationSnapshotDto.builder()
                .host(entity.getHost())
                .port(entity.getPort())
                .generatedAt(Instant.now())
                .build();
    }

    // The shape that consumers receive from Hazelcast / REST.
    // Reuse an existing type from com.friendly:shared-dto when one fits.
    public MqttBrokerConfig toSharedConfiguration(MqttBrokerConfiguration entity) {
        return new MqttBrokerConfig(entity.getHost(), entity.getPort());
    }
}

@Service
@RequiredArgsConstructor
@Slf4j
public class MqttBrokerConfigurationService {

    private final MqttBrokerConfigurationRepository repository;
    private final MqttBrokerConfigurationMapper mapper;
    private final MqttBrokerConfigurationCacheService cacheService;

    @Transactional(readOnly = true)
    public MqttBrokerConfigurationSnapshotDto getConfiguration() {
        return mapper.toSnapshot(loadSingleton());
    }

    @Transactional
    @Auditable(
            operation = AuditOperation.UPDATE,
            context   = "MqttBrokerConfiguration",
            id        = "'mqtt-broker'",                       // SpEL; constant for a singleton
            entity    = MqttBrokerConfiguration.class,
            group     = "Provisioning",                        // UI tree grouping
            labelKey  = "audit.entity.mqtt_broker_configuration",
            icon      = "settings")
    public MqttBrokerConfigurationSnapshotDto updateConfiguration(MqttBrokerConfigurationRequestDto request) {
        MqttBrokerConfiguration entity = loadSingleton();
        entity.setHost(request.getHost());
        entity.setPort(request.getPort());
        repository.save(entity);
        scheduleCacheRefresh();
        return mapper.toSnapshot(entity);
    }

    private MqttBrokerConfiguration loadSingleton() {
        return repository.findTopByOrderByIdAsc()
                .orElseThrow(() -> FriendlyException.errorWithDescription(
                        ConfigsErrorCode.MQTT_BROKER_CONFIGURATION_NOT_FOUND, "singleton configuration"));
    }

    private void scheduleCacheRefresh() {
        AfterCommitExecutor.executeAfterCommit(
                cacheService::refreshCache, "MqttBrokerConfiguration cache refresh");
    }
}

@Service
@Slf4j
public class MqttBrokerConfigurationCacheService
        extends AbstractIListCacheService<MqttBrokerConfig> {

    private final MqttBrokerConfigurationRepository repository;
    private final MqttBrokerConfigurationMapper mapper;

    @Autowired
    public MqttBrokerConfigurationCacheService(HazelcastInstance hazelcastInstance,
                                               MqttBrokerConfigurationRepository repository,
                                               MqttBrokerConfigurationMapper mapper) {
        super(hazelcastInstance);
        this.repository = repository;
        this.mapper = mapper;
    }

    // Test constructor: inject a mock IList directly
    public MqttBrokerConfigurationCacheService(IList<MqttBrokerConfig> cache,
                                               MqttBrokerConfigurationRepository repository,
                                               MqttBrokerConfigurationMapper mapper) {
        super(cache);
        this.repository = repository;
        this.mapper = mapper;
    }

    @Override
    protected String cacheName() {
        return CacheNames.MQTT_BROKER_CONFIGURATION;     // see Step 7
    }

    @Override
    @Transactional(readOnly = true)
    public MqttBrokerConfig refreshCache() {
        MqttBrokerConfig snapshot = mapper.toSharedConfiguration(
                repository.findTopByOrderByIdAsc()
                        .orElseThrow(() -> FriendlyException.errorWithDescription(
                                ConfigsErrorCode.MQTT_BROKER_CONFIGURATION_NOT_FOUND, "singleton configuration")));
        IListCacheWriter.replaceSnapshot(cache, snapshot);   // atomic set(0,..) — never empty
        return snapshot;
    }

    public MqttBrokerConfig getConfiguration() {
        return IListCacheReader.getFirstOrNull(cache);
    }
}

// in CacheNames.java
public static final String MQTT_BROKER_CONFIGURATION = "mqtt-broker-configuration";

@RestController
@RequestMapping("/mqtt-broker/configuration")
@RequiredArgsConstructor
@Validated
@Tag(name = "MQTT Broker Configuration", description = "CRUD and import/export")
public class MqttBrokerConfigurationController {

    private final MqttBrokerConfigurationService service;

    @GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
    @Operation(summary = "Get MQTT broker configuration")
    @ApiResponse(responseCode = "200", description = "Configuration snapshot")
    public MqttBrokerConfigurationSnapshotDto getConfiguration() {
        return service.getConfiguration();
    }

    @PutMapping(consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    @Operation(summary = "Update MQTT broker configuration")
    public MqttBrokerConfigurationSnapshotDto update(
            @Valid @RequestBody MqttBrokerConfigurationRequestDto request) {
        return service.updateConfiguration(request);
    }
}

# consumer service config
hazelcast-client:
  cluster-name: dev
  network:
    cluster-members:
      - configs-service-host:5701

@Component
@RequiredArgsConstructor
public class ProvisionPortalConfigConsumer {

    private final HazelcastInstance client;

    public DeviceConfiguration current() {
        IList<DeviceConfiguration> cache =
                client.getList("provision-portal-configuration");   // CacheNames constant value
        return cache.isEmpty() ? null : cache.get(0);               // snapshot is always at index 0
    }
}

curl -s http://configs-service-host:8080/configs-service/provision-portal/configuration \
     -H "Authorization: Bearer <jwt>"