|
If for whatever reason, it really does seem important that we rush a way to break up "sakai.properties" into multiple files in 2.4, this Commons Configuration approach can provide that capability in a controllable and compatible way:
# sakai.properties include=db.properties include=cluster.properties loggedOutUrl=http://localhost:8080/portal ... Reference: http://jakarta.apache.org/commons/configuration/howto_properties_1_2.html This is a revised proposal that attempts to avoid any unexpected processing of properties files while allowing use of a custom list of properties files.
- If the file "propertiesfileslist.txt" is NOT found in the sakai.home directory then properties file processing will occur exactly as it does now. - If the file "propertiesfileslist.txt" is found the sakai.home directory then it wlll be read and each non comment, non empty line will treated as a file path and read as a properties file. They will be read in the order of occurrence in the file. The default processing of properties files in the sakai.home directory will not be done. The classpath occurrences of "sakai.properties" will still be read and the current processing of the "security.properties" file will still happen as it does currently. In this way the current processing of properties files will remain the default method unless someone takes explicit and obvious action to set up a different list of property files. I agree with Ray's idea on this. Having to force alphabetical filename order or create a configuration file to read your configuration files in seems like things can get hairy. A simply include directive would suffice, though I'd like a bit more flexibility in that include. The include in the Commons Configuration seems to only allow 1 include at a time. It'd be nice to be able to include an entire directory like the way apache does it:
Include /sakai/prod/*.conf --- Ref: http://httpd.apache.org/docs/2.0/mod/core.html#include The only reason for suggesting a magic file name is so that Sakai has a default place to look to find the list of files. Specifying a file name as a startup property seems fine.
It has to be possible to specify the order that files are read in order to make sure that multiple assignments to the same property will happen in a defined order and with predictable results. thought reading in all the files in a directory was a great idea until I implemented it and couldn't get Sakai to start up because of inconsistent settings. People just starting to use Sakai will shoot themselves in the foot if we read all the properties files in a directory. Does anyone have an estimate of how long it would take to take advantage of Apache Commons to control the reading of property files? I've used Apache Commons Configuration before and it was relatively straightforward. Having said that I haven't had a chance to look at the Sakai configuration pieces in depth.
The reason my Commons Configuration implementation was inadequate was because it doesn't handle overrides -- if a property-setting line shows up more than once, it assumes that the property is a list!
I absolutely agree with David about the need to support explicit ordering, and I agree with Jason that wildcards would be nice to support too. Based on my earlier work, it shouldn't take too many days to get this together, basing it on Spring's latest configuration classes. As a plus, the refactoring involved should also reduce the amount of stuff in the shared/lib area of the Components Manager. (At least it did when I tried it before. :) ) Besides everything else that's been mentioned, a number of people have asked for ways to enable or disable components on the fly, and Dan McCallum pointed out to me that we can't easily deploy binary LDAP user data providers unless we have a way to configure attribute-to-property mappings.
Trying to shoehorn _all_ these features into what looks like a Java properties file sounds pretty nightmarish. But I can see how they might be doable by a runtime-loaded XML configuration file.... Since I've already had some experience with this area of Spring, I'll get a mini-project started. If only because there wouldn't be enough time for review, I very much doubt I can get it into the official 2.5 release, but unless I get interrupted by other tasks, I might be able to have it working on a side branch by code freeze. I began work on this task with the following goals:
* Allow an arbitrary ordered list of local properties files to be loaded at startup time. * Allow wildcards in properties file names. * Enable / disable / select deployed components without changing binary distributions. * Support no-compile configuration of lists, maps, and other complex objects. * Allow optional use of DB for configuration storage to make it easier to support a configuration web app. What I've checked in at https://source.sakaiproject.org/svn/component/branches/SAK-8315 should be able to support all this, although I haven't yet constructed a test case for the DB case. The changes need to be reviewed, tested, and cleaned up before I'm ready to ask for a merge into 2.6. I'm going to have to walk away from this for at least a month, and so I'll ask the Framework WG to take a look during the hiatus. FYI - There was a BOF in Amsterdam related to this and they discussed using common's configuration.
Yes, I know -- I actually implemented a Commons Configuration integration before, as mentioned in my earlier comment.
The scheme implemented in the working branch should easily allow for plugging in a Commons Configuration properties provider, but you'd need to bear in mind that CC is not at all compatible with existing sakai.properties settings. Here's some more info from the email I sent to sakai-dev for review....
Currently Sakai code loops around a Java-embedded list of properties files, most of which are located in "${sakai.home}". The branch is backwards compatible. But behind the scenes it reads a default "sakai-configuration.xml" file and then reads a local "${sakai.home}sakai-configuration.xml" file (if one exists). That local XML configuration can change the list of default properties locations (or pick up properties from another source such as a database or JMX), define new beans, create aliases, override beans, and so on. Here are some of the source highlights for anyone who want to take a quick look around. The default "sakai-configuration.xml": https://source.sakaiproject.org/svn/component/branches/SAK-8315/component-api/component/src/config/org/sakaiproject/config/sakai-configuration.xml The test code, including runtime selection of a provider: https://source.sakaiproject.org/svn/component/branches/SAK-8315/component-impl/integration-test The test's "sakai.home" directory, complete with a local "sakai-configuration.xml": https://source.sakaiproject.org/svn/component/branches/SAK-8315/component-impl/integration-test/src/test/resources/ The Spring subclasses behind most of it: https://source.sakaiproject.org/svn/component/branches/SAK-8315/component-api/component/src/java/org/sakaiproject/util/ All these goals look functionally desirable. I have spent some time looking over the branch (with assistance from Ray) in particular with a view to its compatibility with SAK-12166. The code is for the most part very cleanly factored out, with the one exception of the case "SakaiApplicationContext" which interposes in the container startup lifecycle in a moderately intricate way. In particular it embodies the design assumption that the container which defines the core configuration bean "SakaiProperties" is the *same* container that will be preprocessed by the preprocessors it is a factory for.
I think the clarity/future stability of the code would be improved if this assumption were removed, and in one way or another the container configured by "sakai-configuration.xml" were kept distinct from the main context containing all the Sakai services. This would probably mean its becoming a parent container of the main context. In this way it would be prepared to function equally well with SAK-12166 as without it. I'm wondering though whether all the idioms we see in the sample file could be supported without some changes in this model... <bean id="org.sakaiproject.component.SakaiProperties" parent="org.sakaiproject.component.DefaultSakaiProperties"> This one is fine... simply defines a bean that will become visible in child contexts. <!-- We can override constructor arguments now. --> <bean id="org.sakaiproject.component.test.String" class="java.lang.String"> I'm a bit worried about this one - is it the intention that the sakai-configuration.xml is loaded *after* all component definitions, and hence will replace any existing definitions? In a multiple-context model this would be very awkward since it would not be clear *which* the target context was for overriding. <!-- We can override default service implementations via an alias. --> <alias name="org.sakaiproject.component.test.TestProvider2" alias="org.sakaiproject.component.test.ITestProvider"/> Alias is also worrying (see comments on SAK-12166) - I'm not clear I understand the rules on how it could work in a hierarchical context. A "BeanReferenceFactoryBean" would at least be properly visible in child contexts, but could not take priority over them. What do you think, Ray? Does it seem workable that this branch could be reworked to put sakai-configuration.xml etc. into a separate context in some way? Thank you for the careful review, Antranig. Although a JIRA comment thread isn't an ideal discussion medium, I'll try a first pass at your remarks:
AB: "All these goals look functionally desirable. I have spent some time looking over the branch (with assistance from Ray) in particular with a view to its compatibility with SAK-12166. The code is for the most part very cleanly factored out, with the one exception of the case "SakaiApplicationContext" which interposes in the container startup lifecycle in a moderately intricate way. In particular it embodies the design assumption that the container which defines the core configuration bean "SakaiProperties" is the *same* container that will be preprocessed by the preprocessors it is a factory for. I think the clarity/future stability of the code would be improved if this assumption were removed, and in one way or another the container configured by "sakai-configuration.xml" were kept distinct from the main context containing all the Sakai services. This would probably mean its becoming a parent container of the main context. In this way it would be prepared to function equally well with SAK-12166 as without it. I'm wondering though whether all the idioms we see in the sample file could be supported without some changes in this model..." My intent was to introduce as little disturbance to the current component management system as possible while getting the new required functionality. I targeted at Sakai as it works in 2.4.x and will work in 2.5.0. A radical redesign was out of scope for this task. The _existing_ Sakai component manager "embodies the design assumption" of a single GenericApplicationContext which needs to be fiddled with to get Sakai-specific features. The three bits of functionality found in "SakaiApplicationContext" have to be done by some code somewhere. Trying to insert that functionality into a hardcoded GenericApplicationContext's "refresh" cycle from _outside_ the object seems to me considerably less clean than building on documented methods which have been made available for specialization. That leaves the question as to whether my proposed implementation would make it _more_ difficult to reach an amorphous future Sakai. My answer is simple: once this change is committed, the only thing we need to keep backwards-compatible is the functionality provided by the local XML configuration file, just like we need to maintain backwards-compatibility with the functionality provided by a local "sakai.properties" file. In a more aggressive redesign, the "SakaiApplicationContext" class would very likely disappear along with many other existing classes. I wouldn't mourn it: it's just an internal implementation detail. The functionality it provides can be moved somewhere else when "somewhere else" becomes more appropriate. In Sakai as it is _now_, however, this is the most appropriate (and least destabilizing) place I could find. <!-- We can override constructor arguments now. --> AB: "I'm a bit worried about this one - is it the intention that the sakai-configuration.xml is loaded *after* all component definitions, and hence will replace any existing definitions? In a multiple-context model this would be very awkward since it would not be clear *which* the target context was for overriding." My intent is to provide a single spot at which Sakai-wide configuration can be handled by XML along the same lines it's currently handled by a flat properties file. Because of Sakai's current single-context model, this does indeed open up the possibility of overriding definitions embedded in components. In a multiple-context model, how do you intend to apply cross-component "sakai.properties" -- in particular, the bean property overriders? Do you intend to let them apply to any component-defined bean, or only to some subset? The answer may give some clues as to how more complex XML-based overriding should be handled (or disallowed). <!-- We can override default service implementations via an alias. --> <alias name="org.sakaiproject.component.test.TestProvider2" alias="org.sakaiproject.component.test.ITestProvider"/> AB: "Alias is also worrying (see comments on SAK-12166) - I'm not clear I understand the rules on how it could work in a hierarchical context. A "BeanReferenceFactoryBean" would at least be properly visible in child contexts, but could not take priority over them." Sorry, Antranig, I'm not following you. The goal of this project is to allow _external_ configuration of deployed static binaries via the local file system. (In this case, selecting which implementation bean a service ID points to.) The JavaDoc for "BeanReferenceFactoryBean" documents the "<alias>" tag as the way to achieve such functionality purely through XML. If we don't want to edit source code and rebuild, how would "BeanReferenceFactoryBean" be better? AB: "What do you think, Ray? Does it seem workable that this branch could be reworked to put sakai-configuration.xml etc. into a separate context in some way?" Sure, I could add a new layer of application context to the current component manager -- but that would add complexity while meeting no functional goal. I'd rather wait to move to a context tree until there's a reason for doing it. What matters in deciding the fate of this proposal is whether there's anything about it which would _block_ a well-motivated move to multiple contexts. So far, it seems to me the most pressing worry is how far to allow overriding of component-supplied bean definitions. I don't want to introduce any change which forever commits us to wide-open public-to-everyone name scopes. But on the other hand, we do have a proven need for centralized local configuration of statically deployed components. OK... in advance of being able to move the discussion somewhere more suitable, I will respond to some key points here:
You say: That leaves the question as to whether my proposed implementation would make it _more_ difficult to reach an amorphous future Sakai. My answer is simple: once this change is committed, the only thing we need to keep backwards-compatible is the functionality provided by the local XML configuration file, just like we need to maintain backwards-compatibility with the functionality provided by a local "sakai.properties" file. What matters in deciding the fate of this proposal is whether there's anything about it which would _block_ a well-motivated move to multiple contexts. Yes - I agree completely, and this is the only real focus of my comments. This is why I am trying to get at what you had intended the "overriding/interference" semantics to be, for your sakai-configuration.xml file. Since you say "this does indeed open up the possibility of overriding definitions embedded in components" it is raising the view that you hadn't actually pre-planned any specific semantics of this sort at all... but unfortunately as it stands you have implemented some! For a start, beans written in s-c.xml have the potential to completely displace existing beans... our current CM impl doesn't flag this as an error. So, is this "possibility" one that you consider within the scope of your proposal? Or should we take explicit steps to forbid it now, for fear we inadvertently allow semantics that we might not be able to support in the future? To answer this point: In a multiple-context model, how do you intend to apply cross-component "sakai.properties" -- in particular, the bean property overriders? Do you intend to let them apply to any component-defined bean, or only to some subset? The answer may give some clues as to how more complex XML-based overriding should be handled (or disallowed). Yes, in the multiple-context model, I am currently applying the property overriders to *all* beans encountered. This is largely by default, since all beans are considered candidates for proxying to be sent upstairs. Should we decide on a concrete proposal for "component-local" beans, this decision could be revised. So to sum up, I'm still not completely clear what you consider the role of the inhabitants of a s-c.xml file to be in the wider context, other than the SakaiProperties object itself. You had some examples of "stuff" written in that file as examples, but it wasn't clear precisely the semantics you were intending for the interaction of this "stuff" with existing beans in other contexts. On alias v BRFB - the difference to me is the behaviour in overriding. If we decide on a model whereby the contents of s-c.xml are implemented in a SAK-12166 world by putting them in a *parent* context of the entire context tree, my understanding is that BRFB would work, and that alias would not. I would be happy if disproved, however :P The key issue turns out to pivot on something that's still being worked out in SAK-12166, so Antranig and I will move to email to knock ideas (or heads) around. For those who are following here, this is the hot spot:
AB: "For a start, beans written in s-c.xml have the potential to completely displace existing beans... our current CM impl doesn't flag this as an error. So, is this "possibility" one that you consider within the scope of your proposal? Or should we take explicit steps to forbid it now, for fear we inadvertently allow semantics that we might not be able to support in the future?" The requirements _do_ assume complete displacement of "existing" beans -- or rather, of existing bean _definitions_. We want to allow deployment of binary components _which then do not get loaded_, and we want to allow local filesystem-based _creation_ of component-wide-visible beans. This is key to allowing binary distribution of LDAP and Kerberos integrations, for example. Given the component manager's current architecture, it so happens that being able to manage the "top" layer of component services is equivalent to being able to muck around with any beans configured anywhere within a component implementation. But as far as I can see, my targeted functional goals don't require access to anything other than what's visible at the top. I'm fine with a restriction that framework-wide configuration should keep hands off component internals and only create or modify definitions visible at the "parent" context level. It seems as if that constraint would allow for the most important use cases and block some of the nastiest ones. But I'm not sure how to enforce that until we actually _have_ a "parent" context level. :) Peter Knoop pointed out that my branch addresses functional goals beyond those explicitly described by this JIRA ticket. (Thanks, Peter!) For clarity's sake, I've broken them out into other JIRA feature requests and linked them to this branch.
In working through a code review from Antranig, it became clear that I needed to be explicit about a restriction I'd been taking for granted. When I wrote:
"Enable / disable / select deployed components without changing binary distributions." I didn't mean that I wanted some magical way to undo normal Spring wiring and instantiation. A better way of phrasing that bullet point would have been: "Easily support enabling, disabling, and selection of components in binary distributions." It's not the goal to erase an eagerly-loaded singleton bean that handles a component's internal logic. (This can happen in 2.4.x by another component simply defining a new bean with a conflicting ID or name. But working such havoc isn't the point of the current Sakai component manager and it's not the point of my proposed change.) The goal is to let optional lazily-loaded component implementations _be_ optional. Currently, the only way to handle component configurations and ID assignments are within the component WARs themselves; the proposed change makes it easier to allow overridable defaults. When we sooner-or-later get a distinction between component-internal and Sakai-wide Spring bean IDs (to match our current classloading distinction), "sakai-configuration.xml" can be restricted to referring to Sakai-wide IDs (to match the classloading restriction I note in The logical bulk of this branch has now been merged into my branch at SAK-12166. The container is starting and running (minus
Now merged fully with working integration tests. See the SAK-12166 thread for details.
David Haines pointed out that I missed explicitly stating a requirement:
"One question, does it log changes / overrides of configuration values? If someone has a production problem they need to be able to quickly know what the current settings of the property values actually are. If a value is set in one properties file, overridden in another and then changed via JMX but might also have been overridden by a database value it is hard to know what the final value would be. Tracking down one property file overriding another is feasible, but untracked dynamic changes that aren't logged would make it very hard to track down what the current property values are set to." I'll make sure that's taken care of before merging to the trunk. "One question, does it log changes / overrides of configuration values? If someone has a production problem they need to be able to quickly know what the current settings of the property values actually are. If a value is set in one properties file, overridden in another and then changed via JMX but might also have been overridden by a database value it is hard to know what the final value would be. Tracking down one property file overriding another is feasible, but untracked dynamic changes that aren't logged would make it very hard to track down what the current property values are set to."
After looking more closely, I don't think that will be an issue for this branch per se. As we bring in support for dynamically changing framework-wide properties, we need to require proper logging and event notification. But the Example: <bean id="org.sakaiproject.component.SakaiProperties" parent="org.sakaiproject.component.DefaultSakaiProperties"> <property name="propertiesArray"> <list merge="true"> <bean id="fileBasedProperties" class="org.springframework.beans.factory.config.PropertiesFactoryBean"> <property name="locations"> <list> <value>file:${sakai.home}sakai.properties</value> <value>file:${sakai.home}some-peculiar.properties</value> </list> </property> </bean> <bean id="dbBasedProperties" factory-bean="org.sakaiproject.component.test.dynamic.DbProperties" factory-method="getProperties"/> </list> </property> </bean> Even though that's fairly complex, we can see right away that the database property values override any duplicate properties in those two files, and that the "some-peculiar.properties" file overrides any duplicates in "sakai.properties". Quick update: Antranig and I have agreed on a general path that would prevent conflicts between this branch (which allows for central configuration of the framework's application context) and the goal of cleanly separating the current all-in-one component namespace into a container context and multiple reloadable child component contexts.
After that split happens, the sort of configuration enabled by this branch will ONLY target the container context's namespace. That means, for example, that setting aliases and creating configuration objects will only have an effect if they specify bean names that are meaningful at the framework-wide level (equivalent to OSGi services) rather than names that are fully scoped within a component context. This constraint makes good sense to me in general. Even in our current circumstances, it would be unwise to go mucking around in the internal logic of a component. Currently we have no way to _prevent_ users from doing that -- and in fact they can do it in 2.4.x via "sakai.properties" or by specifying a duplicate name in a "components.xml" file -- but that doesn't make it a good idea. Antranig asks that this "best practice" be made clear in any documentation or sample code accompanying the release, and I fully concur. I'm going to be off the network for a few days, but when I get back we should be able to merge this into trunk. I don't understand OSGI in any detail. Does this latest idea complicate the detailed configuration of implementations? DIfferent implementations could have very different configuration options which should not be in a public service API. Does this make it harder to initialize those values from a common properties file?
"DIfferent implementations could have very different configuration options which should not be in a public service API. Does this make it harder to initialize those values from a common properties file?"
Continued support for centralized local configurations seems like a requirement that any massive change to Sakai's component manager needs to take into account. But that discussion would be attached to a different JIRA issue. :) FWIW, Antranig's and my proof-of-concepts deal with the requirement by applying the container's top-level properties files to each component context separately. But there are other approaches that could work as well -- for example, we could provide some way to target particular component namespaces from XML-or-properties files -- that was just the one we used to prove it could be done at all. I can't agree more -- I think we really need to get to a point of simple configuration abstraction where we stop setting properties on implementation beans, and start setting real configuration flags, which are maintained in as backwards-compatible fashion as possible. IMHO Spring ApplicationContexts (and Sakai's thin veneer in overriding arbitrary bean properties in sakai.properties) are a terrible configuration format -- they expose far too much detail about the internal implementation, leading to breakage and incompatibility.
Thus, if an API has a set of "official" configuration options, we provide an official method (which could still leverage bean properties, just on an explicit configuration object). If implementations wish to expose configuration, they should be able to do so as well (in a manner that makes it clear that they're implementation specific -- kind of like JVM flags) but arbitrary configurations twiddling with internal implementations is scary, and I think problematic from a QA perspective. Dedicated property/configuration objects also seem to raise the interesting possibility of being able to do things like harvest JavaDoc deprecated, or other documentation tags to maintain our config-apis in the long run. Good points and good ideas, Jason. Before Antranig started work on his auto-proxying branch and we started talking about OSGi, I thought of experimenting with a central component configurer object something along the lines you describe. Getting this branch's externalized configuration support in place would help with such experimentation: for example, we could easily use internally-maintained configuration file(s) to define a translation map from old-style implementation-bean override properties to new-style configuration object properties. Again, though, that would be its own, more ambitious, JIRA task, building on but separate from this one.
Ray, I can't see anything about it in the2.6.0 release notes. Which other documentation were you refering to?
In the "Services and Framework" section of http://confluence.sakaiproject.org/display/DOC/Release+Notes+%282.6%29 , follow the link from "Support for more flexible configuration of components".
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 |
|
Task
Resolved
Major
Sakai should have more flexibilty in reading properties files.
At Stanford we solve this:
1) per-tool/package/service subdirectories of SAKAI_HOME/sakai/ The exact subdirectory and file names are injected via Spring into the tool/service.
2) per-stage property files in SVN. Stages are defined as DEV, QA, PREPROD, PROD, but are easily extended in our packaging scripts.
3) packaging scripts
Using the scripts the build engineer or QA engineer indicates the 'type' of Sakai they want to deploy. To provide deployment safety upper stage property files (say, PREPROD compared to QA) are not made available in SVN until the kit has passed the previous stage. This is formalized as a "relase to FOO" point.
This retains the namespace simplicity for developers and admins, and provides a clear set of artifacts and ritual over the development cycle.
Just 'sucking in all files found in the directory" sounds like a mess. I'll grant that the alpha sorting of property files can allow one to manage the stage of release, but the proliferation will be maddening.