Overriding Default Configuration

For the core SDK only (not any of the integrations), we have this spec.

However, this spec doesn't account for things like .properties which is more idiomatic for Java applications than YAML. Because of this, our loading order needs to be based on that spec as well the locations we already have defined for the Servlet Spec.

The loading order should be as follows.

Core SDK Only

For the Core SDK only when the servlet integration is not used. Values found in later locations override values found in earlier locations:

1. classpath:com/stormpath/sdk/config/stormpath.properties. This contains the default configuration as defined here (but with everything still prefixed with 'stormpath.'). Note that this can be a .properties file if it makes our lives easier since it won't be referenced by users directly.
2. classpath:stormpath.json
3. classpath:stormpath.yaml
4. $HOME/.stormpath/apiKey.properties
5. $HOME/.stormpath/stormpath.json
6. $HOME/.stormpath/stormpath.yaml
7. System.getProperty("user.dir") + File.separator + "apiKey.properties"
8. System.getProperty("user.dir") + File.separator + "stormpath.json"
9. System.getProperty("user.dir") + File.separator + "stormpath.yaml"
10. Environment Variables (with dot notation converted to uppercase + underscore convention as described here.
11. JVM System Properties

If 2, 5 or 8 is found to exist and Jackson is not on the classpath, log a warn message that clarifies that they need to add Jackson to the classpath. If 3, 6, or 9 is found to exist and SnakeYaml is not on the classpath, log a warn message that clarifies that they need to add SnakeYaml to the classpath. If no .json or .yaml files are found, Jackson and Snake do not need to be on the classpath and everything should still 'just work'.

I suspect they very large majority of people won't care about the two dependencies. And if they do, they can <exclude> them from their Maven/Gradle config. We should have some documentation on this in our guides though so they can know that they can proactively exclude these dependencies if they want (with the caveat that we'll log a warn message if we find a respective config file).

Servlet Integration

When the servlet integration is used (but not Spring or Spring Boot). Values found in later locations override values found in earlier locations:

1. classpath:com/stormpath/sdk/config/stormpath.properties
2. classpath:com/stormpath/sdk/servlet/config/web.stormpath.properties This reflects additional web-specific default configuration. Again, this can be a .properties file if it makes our lives easier since it won't be referenced by users directly.
3. classpath:stormpath.json
4. classpath:stormpath.yaml
5. /WEB-INF/stormpath.properties
6. /WEB-INF/stormpath.json
7. /WEB-INF/stormpath.yaml
8. Servlet Context Parameters
9. $HOME/.stormpath/apiKey.properties
10. $HOME/.stormpath/stormpath.json
11. $HOME/.stormpath/stormpath.yaml
12. System.getProperty("user.dir") + File.separator + "apiKey.properties"
13. System.getProperty("user.dir") + File.separator + "stormpath.json"
14. System.getProperty("user.dir") + File.separator + "stormpath.yaml"
15. Environment Variables (with dot notation converted to uppercase + underscore convention as described here.
16. JVM System Properties

Same comments about Jackson/Snake being in the classpath.

Spring Boot

None of the above applies except for $HOME/.stormpath/apiKey.properties, which our Spring Boot integration supports today. In Spring Boot, we let Spring Boot define the config override locations and order, and users can use that.

Standard Spring

Spring-only (non Boot) users can define PropertyPlaceholderConfigurers or @PropertySource themselves. For those that want to configure their application with YAML, they can use YamlPropertiesFactoryBean.