Documentation misses chapters 4.13 and 4.14 [SPR-12107]

[spring-projects-issues]

Michael Osipov opened SPR-12107 and commented

Both chapters refer to the blog for details. That is not how a documentation should be structured. Moreover, if the documenation is read offline or on paper, that information is simply not available.

Documenation should be selfcontained.

---

Affects: 4.1 RC2

Referenced from: commits 15f496b

[spring-projects-issues]

Stéphane Nicoll commented

This has been added and will be available in a couple of hours here

[spring-projects-issues]

Michael Osipov commented

There seems to be some discrepancy between the reference and the Javadocs.

The reference says:

In addition, profiles may also be activated declaratively through the spring.profiles.active property which may be specified through system environment variables, JVM system properties, servlet context parameters in web.xml or even as an entry in JNDI (see Section 4.13.3, “PropertySource Abstraction”).

but neither [PropertySource](http://docs.spring.io/spring/docs/current/javadoc-api/index.html?org/springframework/core/env/PropertySource.html) nor [AbstractEnvironment](http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/core/env/AbstractEnvironment.html) mention JDNI.

[spring-projects-issues]

Stéphane Nicoll commented

Thanks for reviewing.

Both can optionally enable a JndiPropertySource. See Javadoc for details.

I guess that's not obvious enough? I don't see myself explaining all that there as it's pretty specific and the javadoc is extensive (and there is a link). Suggestion?

[spring-projects-issues]

Michael Osipov commented

I am sorry, this is not what I am was talking about. I was solely referring to profile activation. The according to the reference spring.profiles.active can be set as a JNDI var but the Javadocs do not mention that. They should be on par.

Maybe this is obvious to you by mentioning JndiPropertySource but it isn't to me.

[spring-projects-issues]

Stéphane Nicoll commented

what Javadoc? If you're confused, something else must be wrong. I don't really get why you insist on focusing on spring.profiles.active vs. any property. What the PropertySource abstraction explains is that you can specify any property through various ways and you can customize the precedence.

Now that this abstraction is in place, you can resolve the foo property (or spring.profiles.active)) through JNDI if you configure a PropertySource that supports JNDI - that is JndiPropertySource).

Now you got this explanation, it would probably be easier if you explain what is missing in the curent doc.

[spring-projects-issues]

Michael Osipov commented

Stéphane, I wasn't looking for an explanation but solely hinting that something is missing in the docs. You misunderstood me again. I was not referring to where properties are obtained from but solely how profiles can be activated. Reference says that I can enable profiles through JNDI but AbstractEnvironment does not mention that. Again, it is about profile activation.

[spring-projects-issues]

Stéphane Nicoll commented

Michael I got you the first time I think and I will try one more time but if that's not good enough and you know what is missing, just write what's missing and that would help me get what you're after.

I am taking the section in the doc you mentioned in your first comment. That section explains that there are two ways to enable a profile:

1. Programmatically (with a code sample that shows how do that)
2. Declaratively using the spring.profiles.active property.

Now, how I can set the property? We give a wide range of options, including JNDI with a reference to the PropertySource abstraction. That section explains you can define properties (spring.profile.active being one of them) using whatever mechanism you like (JndiPropertySource being one implemetation using JNDI to retrieve the properties).

Back to what is missing, AbstractEnvironment should not mention that simply because it can't know all the PropertySource out there. Say you create a property source that looks to an XML file in the user home directory. You can enable a profile by placing an entry in that XML file but there's no way we can know about that. In that sense, I think we covered as much as we can: once you understand PropertySource is an open interface that you can configure and/or implement, you understand you can enable a profile any way you want through that infrastructure. JNDI is just an example. To be clear, you can't enable a profile using JNDI unless you configure the relevant JndiPropertySource (just like you would do for your custom XML file)

Does that help? If not, please write down what you'd like to see.

[spring-projects-issues]

Michael Osipov commented

Stéphane, yes I was referring to declarative enabling fo profiles. The paragraph

In addition, profiles may also be activated declaratively through the spring.profiles.active property which may be specified through system environment variables, JVM system properties, servlet context parameters in web.xml or even as an entry in JNDI (see Section 5.13.3, “PropertySource Abstraction”).

is simply too shallow for my taste. Most people will prefer context params or JNDI variables. That requires more attention. Especially that regardless of the source, it is always spring.profiles.active, though the format is unusual for system env vars and JNDI vars.