Load Spring Boot Properties From a JSON File

1. Introduction

Use external configuration properties is quite a common pattern.

And, one of the most common questions is the ability to change the behavior of our application in multiple environments – such as development, test, and production – without having to change the deployment artifact.

In this tutorial, we’ll focus on how you can load properties from JSON files in a Spring Boot application.

2. Loading Properties in Spring Boot

Spring and Spring Boot have strong support for loading external configurations – you can find a great overview of the basics in this article.

Since this support mainly focuses on .properties and .yml files – working with JSON typically needs extra configuration.

We’ll assume that the basic features are well known – and will focus on JSON specific aspects, here.

3. Load Properties via Command Line

We can provide JSON data in the command line in three predefined formats.

First, we can set the environment variable SPRING_APPLICATION_JSON in a UNIX shell:

$ SPRING_APPLICATION_JSON='{"environment":{"name":"production"}}' java -jar app.jar

The provided data will be populated into the Spring Environment. With this example, we’ll get a property environment.name with the value “production”.

Also, we can load our JSON as a System property, for example:

$ java -Dspring.application.json='{"environment":{"name":"production"}}' -jar app.jar

The last option is to use a simple command line argument:

$ java -jar app.jar --spring.application.json='{"environment":{"name":"production"}}'

With the last two approaches, the spring.application.json property will be populated with the given data as unparsed String.

These are the most simple options to load JSON data into our application. The drawback of this minimalistic approach is the lack of scalability.

Loading huge amount of data in the command line can be cumbersome and error-prone.

4. Load Properties via PropertySource Annotation

Spring Boot provides a powerful ecosystem to create configuration classes through annotations.

First of all, we define a configuration class with some simple members:

public class JsonProperties {

    private int port;

    private boolean resend;

    private String host;

   // getters and setters

}

We can provide the data in the standard JSON format in an external file (let’s name it configprops.json):

{
  "host" : "[email protected]",
  "port" : 9090,
  "resend" : true
}

Now we have to connect our JSON file to the configuration class:

@Component
@PropertySource(value = "classpath:configprops.json")
@ConfigurationProperties
public class JsonProperties {
    // same code as before
}

We have a loose coupling between the class and the JSON file. This connection is based on strings and variable names. Therefore we don’t have a compile-time check but we can verify the bindings with tests.

Because the fields should be populated by the framework, we need to use an integration test.

For a minimalistic setup, we can define the main entry point of the application:

@SpringBootApplication
@ComponentScan(basePackageClasses = { JsonProperties.class})
public class ConfigPropertiesDemoApplication {
    public static void main(String[] args) {
        new SpringApplicationBuilder(ConfigPropertiesDemoApplication.class).run();
    }
}

Now we can create our integration test:

@RunWith(SpringRunner.class)
@ContextConfiguration(
  classes = ConfigPropertiesDemoApplication.class)
public class JsonPropertiesIntegrationTest {

    @Autowired
    private JsonProperties jsonProperties;

    @Test
    public void whenPropertiesLoadedViaJsonPropertySource_thenLoadFlatValues() {
        assertEquals("[email protected]", jsonProperties.getHost());
        assertEquals(9090, jsonProperties.getPort());
        assertTrue(jsonProperties.isResend());
    }
}

As a result, this test will generate an error. Even loading the ApplicationContext will fail with the following cause:

ConversionFailedException: 
Failed to convert from type [java.lang.String] 
to type [boolean] for value 'true,'

The loading mechanism successfully connects the class with the JSON file through the PropertySource annotation. But the value for the resend property is evaluated as “true,” (with a comma), which cannot be converted to a boolean.

Therefore, we have to inject a JSON parser into the loading mechanism. Fortunately, Spring Boot comes with the Jackson library and we can use it through PropertySourceFactory.

5. Using PropertySourceFactory to Parse JSON

We have to provide a custom PropertySourceFactory with the capability of parsing JSON data:

public class JsonPropertySourceFactory 
  implements PropertySourceFactory {
	
    @Override
    public PropertySource<?> createPropertySource(
      String name, EncodedResource resource)
          throws IOException {
        Map readValue = new ObjectMapper()
          .readValue(resource.getInputStream(), Map.class);
        return new MapPropertySource("json-property", readValue);
    }
}

We can provide this factory to load our configuration class. For that, we have to reference the factory from the PropertySource annotation:

@Configuration
@PropertySource(
  value = "classpath:configprops.json", 
  factory = JsonPropertySourceFactory.class)
@ConfigurationProperties
public class JsonProperties {

    // same code as before

}

As a result, our test will pass. Furthermore, this property source factory will happily parse list values also.

So now we can extend our configuration class with a list member (and with the corresponding getters and setters):

private List<String> topics;
// getter and setter

We can provide the input values in the JSON file:

{
    // same fields as before
    "topics" : ["spring", "boot"]
}

We can easily test the binding of list values with a new test case:

@Test
public void whenPropertiesLoadedViaJsonPropertySource_thenLoadListValues() {
    assertThat(
      jsonProperties.getTopics(), 
      Matchers.is(Arrays.asList("spring", "boot")));
}

5.1. Nested Structures

Dealing with nested JSON structures isn’t an easy task. As the more robust solution, the Jackson library’s mapper will map the nested data into a Map. 

So we can add a Map member to our JsonProperties class with getters and setters:

private LinkedHashMap<String, ?> sender;
// getter and setter

In the JSON file we can provide a nested data structure for this field:

{
  // same fields as before
   "sender" : {
     "name": "sender",
     "address": "street"
  }
}

Now we can access the nested data through the map:

@Test
public void whenPropertiesLoadedViaJsonPropertySource_thenNestedLoadedAsMap() {
    assertEquals("sender", jsonProperties.getSender().get("name"));
    assertEquals("street", jsonProperties.getSender().get("address"));
}

6. Using a Custom ContextInitializer

If we’d like to have more control over the loading of properties, we can use custom ContextInitializers.

This manual approach is more tedious. But, as a result, we’ll have full control of loading and parsing the data.

We’ll use the same JSON data as before, but we’ll load into a different configuration class:

@Configuration
@ConfigurationProperties(prefix = "custom")
public class CustomJsonProperties {

    private String host;

    private int port;

    private boolean resend;

    // getters and setters

}

Note that we don’t use the PropertySource annotation anymore. But inside the ConfigurationProperties annotation, we defined a prefix.

In the next section, we’ll investigate how we can load the properties into the ‘custom’ namespace.

6.1. Load Properties into a Custom Namespace

To provide the input for the properties class above, we’ll load the data from the JSON file and after parsing we’ll populate the Spring Environment with MapPropertySources:

public class JsonPropertyContextInitializer
 implements ApplicationContextInitializer<ConfigurableApplicationContext> {

    private static String CUSTOM_PREFIX = "custom.";

    @Override
    @SuppressWarnings("unchecked")
    public void 
      initialize(ConfigurableApplicationContext configurableApplicationContext) {
        try {
            Resource resource = configurableApplicationContext
              .getResource("classpath:configpropscustom.json");
            Map readValue = new ObjectMapper()
              .readValue(resource.getInputStream(), Map.class);
            Set<Map.Entry> set = readValue.entrySet();
            List<MapPropertySource> propertySources = set.stream()
               .map(entry-> new MapPropertySource(
                 CUSTOM_PREFIX + entry.getKey(),
                 Collections.singletonMap(
                 CUSTOM_PREFIX + entry.getKey(), entry.getValue()
               )))
               .collect(Collectors.toList());
            for (PropertySource propertySource : propertySources) {
                configurableApplicationContext.getEnvironment()
                    .getPropertySources()
                    .addFirst(propertySource);
            }
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }
}

As we can see, it requires a bit of quite complex code, but this is the price of flexibility. In the above code, we can specify our own parser and decide what to do with each entry.

In this demonstration, we just put the properties into a custom namespace.

To use this initializer we have to wire it to the application. For production use, we can add this in the SpringApplicationBuilder:

@EnableAutoConfiguration
@ComponentScan(basePackageClasses = { JsonProperties.class,
  CustomJsonProperties.class })
public class ConfigPropertiesDemoApplication {
    public static void main(String[] args) {
        new SpringApplicationBuilder(ConfigPropertiesDemoApplication.class)
            .initializers(new JsonPropertyContextInitializer())
            .run();
    }
}

Also, note that the CustomJsonProperties class has been added to the basePackageClasses.

For our test environment, we can provide our custom initializer inside of the ContextConfiguration annotation:

@RunWith(SpringRunner.class)
@ContextConfiguration(classes = ConfigPropertiesDemoApplication.class, 
  initializers = JsonPropertyContextInitializer.class)
public class JsonPropertiesIntegrationTest {

    // same code as before

}

After auto-wiring our CustomJsonProperties class, we can test the data binding from the custom namespace:

@Test
public void whenLoadedIntoEnvironment_thenFlatValuesPopulated() {
    assertEquals("[email protected]", customJsonProperties.getHost());
    assertEquals(9090, customJsonProperties.getPort());
    assertTrue(customJsonProperties.isResend());
}

6.2. Flattening Nested Structures

The Spring framework provides a powerful mechanism to bind the properties into objects members. The foundation of this feature is the name prefixes in the properties.

If we extend our custom ApplicationInitializer to convert the Map values into a namespace structure, then the framework can load our nested data structure directly into a corresponding object.

The enhanced CustomJsonProperties class:

@Configuration
@ConfigurationProperties(prefix = "custom")
public class CustomJsonProperties {

   // same code as before

    private Person sender;

    public static class Person {

        private String name;
        private String address;
 
        // getters and setters for Person class

   }

   // getters and setters for sender member

}

The enhanced ApplicationContextInitializer:

public class JsonPropertyContextInitializer 
  implements ApplicationContextInitializer<ConfigurableApplicationContext> {

    private final static String CUSTOM_PREFIX = "custom.";

    @Override
    @SuppressWarnings("unchecked")
    public void 
      initialize(ConfigurableApplicationContext configurableApplicationContext) {
        try {
            Resource resource = configurableApplicationContext
              .getResource("classpath:configpropscustom.json");
            Map readValue = new ObjectMapper()
              .readValue(resource.getInputStream(), Map.class);
            Set<Map.Entry> set = readValue.entrySet();
            List<MapPropertySource> propertySources = convertEntrySet(set, Optional.empty());
            for (PropertySource propertySource : propertySources) {
                configurableApplicationContext.getEnvironment()
                  .getPropertySources()
                  .addFirst(propertySource);
            }
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }

    private static List<MapPropertySource> 
      convertEntrySet(Set<Map.Entry> entrySet, Optional<String> parentKey) {
        return entrySet.stream()
            .map((Map.Entry e) -> convertToPropertySourceList(e, parentKey))
            .flatMap(Collection::stream)
            .collect(Collectors.toList());
    }

    private static List<MapPropertySource> 
      convertToPropertySourceList(Map.Entry e, Optional<String> parentKey) {
        String key = parentKey.map(s -> s + ".")
          .orElse("") + (String) e.getKey();
        Object value = e.getValue();
        return covertToPropertySourceList(key, value);
    }

    @SuppressWarnings("unchecked")
    private static List<MapPropertySource> 
       covertToPropertySourceList(String key, Object value) {
        if (value instanceof LinkedHashMap) {
            LinkedHashMap map = (LinkedHashMap) value;
            Set<Map.Entry> entrySet = map.entrySet();
            return convertEntrySet(entrySet, Optional.ofNullable(key));
        }
        String finalKey = CUSTOM_PREFIX + key;
        return Collections.singletonList(
          new MapPropertySource(finalKey, 
            Collections.singletonMap(finalKey, value)));
    }
}

As a result, our nested JSON data structure will be loaded into a configuration object:

@Test
public void whenLoadedIntoEnvironment_thenValuesLoadedIntoClassObject() {
    assertNotNull(customJsonProperties.getSender());
    assertEquals("sender", customJsonProperties.getSender()
      .getName());
    assertEquals("street", customJsonProperties.getSender()
      .getAddress());
}

7. Conclusion

The Spring Boot framework provides a simple approach to load external JSON data through the command line. In case of need, we can load JSON data through properly configured PropertySourceFactory.

Although, loading nested properties is solvable but requires extra care.

As always, the code is available over on GitHub.