Spring Boot 3 JSON message converter for kjson.

Many users of the kjson library will seek to use the library in conjunction with the Spring Framework. The kjson-spring3 library provides a JSON converter class that will use kjson as the serialization / deserialization mechanism.

This library is a copy of the kjson-spring library, converted to Spring Boot 3.x and Spring 6.x.

NOTE: Version 7.1.1 of this library uses the Spring Boot Auto-Configuration mechanism, meaning that the references to component scanning in the notes below may be ignored (and will be removed from future versions).

To direct a Spring Boot 3 application to use kjson for serialization and deserialization of HTTP(S) requests and responses, simply include the kjson-spring3 library in the build, and then ensure that the io.kjson.spring package is included in the Spring component scan:

@ComponentScan("io.kjson.spring")

or:

@ComponentScan(basePackageClasses = [JSONSpring::class])

or, when using Spring XML configuration:

    <context:component-scan base-package="io.kjson.spring"/>

Note that the default Spring behaviour is to scan the package in which the @ComponentScan (or @SpringBootApplication) occurs. When one or more packages or classes are specified on a @ComponentScan, only the specified package(s) will be scanned; to retain the default behaviour, the current package must be also specified, along with io.kjson.spring.

The kjson serialization and deserialization functions all take an optional JSONConfig object. The JSONConfig to be used by the kjson-spring3 library may be provided in the usual Spring manner:

@Configuration
open class SpringAppConfig {

    @Bean open fun jsonConfig(): JSONConfig {
        return JSONConfig {
            allowExtra = true
        }
    }

}

This example shows just the allowExtra option being set; any of the configuration options, including custom serialization and deserialization, may be used. If no JSONConfig is provided, the JSONConfig.defaultConfig will be used.

Client REST calls using the RestTemplate class can also make use of the kjson serialization and deserialization functions. When the RestTemplate is obtained from the default RestTemplateBuilder, it will be configured with all of the HttpMessageConverter instances currently configured – that will include the kjson converter added during auto-configuration.

The following line will get the default RestTemplateBuilder:

    @Autowired lateinit var restTemplateBuilder: RestTemplateBuilder

And then, the following will get a RestTemplate with the converters configured in the RestTemplateBuilder:

        val restTemplate = restTemplateBuilder.build()

Alternatively, the RestTemplate may be constructed with the converter specified explicitly:

    @Autowired lateinit var jsonSpring: JSONSpring

and:

        val restTemplate = RestTemplate(listOf(jsonSpring))

kjson-spring can be configured to log all messages processed by the JSON converter, input and output. To make use of this functionality, the jsonLogFactory must be configured, as follows:

    @Bean open fun jsonLogFactory(): LoggerFactory<*> = DynamicLoggerFactory(Level.DEBUG)

The LoggerFactory in this case is from the log-front-api library; this is a logging façade library which will delegate to any of a number of implementations. The example above uses the DynamicLoggerFactory class from the log-front library, and this implementation uses slf4j if those classes are present (they generally are in a Spring application), or the Java Logging framework if a configuration file for that system is specified, or if no other logging mechanism is available, logs to the standard output.

For the majority of users who do not wish to learn another logging library, the example above will meet most requirements (the Level.Debug in the example is the default level to be used by Logger objects created by this LoggerFactory).

The name of the Logger may also be specified:

    @Bean open fun jsonLogName(): String = "JSON Logging"

The default name is the name of the class instantiating the Logger, which in this case is io.kjson.spring.JSONSpring.

When logging JSON content, it is often important to ensure that Personally Identifiable Information (PII) is not included in the logged data. The logging functionality of kjson-spring allows the specification of an optional "exclude" set of property names. The values of properties with these names will be replaced by **** in the logs, wherever they appear in a JSON structure.

    @Bean open fun jsonLogExclude(): Collection<String> = setOf("creditCardNumber", "licenceNumber")

The latest version of the library is 7.5 (the version number of this library matches the version of kjson with which it was built), and it may be obtained from the Maven Central repository.

This version was built using version 6.1.3 of Spring, and version 3.2.2 of Spring Boot.

    <dependency>
      <groupId>io.kjson</groupId>
      <artifactId>kjson-spring3</artifactId>
      <version>7.5</version>
    </dependency>

    implementation 'io.kjson:kjson-spring3:7.5'

    implementation("io.kjson:kjson-spring3:7.5")

Peter Wall

2024-02-14