PropertyFiles
From APIDesign
| Line 1: | Line 1: | ||
Many systems store their configuration in some form of [[PropertyFiles|property files]]. Files which contain string ''key/value'' mappings. This is indeed an example from the [[APITypes]], as changes to these values influence behaviour of those systems. This may seem much more trivial form of an [[API]] than [[Java]] classes and their signatures and in some way it is, however the rules of proper [[APIDesignPatterns|API Design]] are still applicable: one needs to keep [[BackwardCompatibility]], be ready for [[API]] [[evolution]], etc. | Many systems store their configuration in some form of [[PropertyFiles|property files]]. Files which contain string ''key/value'' mappings. This is indeed an example from the [[APITypes]], as changes to these values influence behaviour of those systems. This may seem much more trivial form of an [[API]] than [[Java]] classes and their signatures and in some way it is, however the rules of proper [[APIDesignPatterns|API Design]] are still applicable: one needs to keep [[BackwardCompatibility]], be ready for [[API]] [[evolution]], etc. | ||
| + | |||
| + | ===== Bundle Manifest Troubles ===== | ||
One commonly used ''property file'' in [[Java]] is the [[JAR]] manifest. It contains ''tag/value'' mappings for one main and many per entry sections. Many systems including [[NetBeans Runtime Container]] or [[OSGi]] recognize values of their own tags and based on them prepare runtime environment for the classes contained in the [[JAR]] file. Recently I was playing a bit with [[Felix]] and was trying to create a bundle (a [[JAR]] with [[OSGi]] manifest) that will require another bundle: | One commonly used ''property file'' in [[Java]] is the [[JAR]] manifest. It contains ''tag/value'' mappings for one main and many per entry sections. Many systems including [[NetBeans Runtime Container]] or [[OSGi]] recognize values of their own tags and based on them prepare runtime environment for the classes contained in the [[JAR]] file. Recently I was playing a bit with [[Felix]] and was trying to create a bundle (a [[JAR]] with [[OSGi]] manifest) that will require another bundle: | ||
| Line 19: | Line 21: | ||
</source> | </source> | ||
| - | After adding it, everything started to behave as expected. The bundle is now rejected, as the ''Require-Bundle'' dependency cannot be satisfied. It is easy to use an [[API]] if you resolve your problems by asking author of the specification. However this is probably not really scalable and there | + | After adding it, everything started to behave as expected. The bundle is now rejected, as the ''Require-Bundle'' dependency cannot be satisfied. It is easy to use an [[API]] if you resolve your problems by asking author of the specification. However this is probably not really scalable and there seems to be something wrong with the [[OSGi]] manifest [[API]]. |
| + | |||
| + | ===== Ready for [[Evolution]] ===== | ||
| + | |||
| + | An important rule when designing an [[API]] is to prepare it for [[evolution]]. Why? Because first version is never perfect, you will always need to release subsequent ones to fix bugs and provide new enhancements. | ||
| + | |||
| + | It is sometimes hard to remind ourselves of the need for [[evolution]], especially when we are about the release the first version. We feel we did our best. We believe we created the most ingenious [[API]] on the Earth. It is hard to remind ourselves that the same [[API]] is also supposed to be ''imperfect''. This requires a little bit of [[Doublethink]]. Still we need to do it, otherwise we and our [[API]] users will be in deep problems in the future - as my [[OSGi]] manifest adventure shows. | ||
| + | |||
| + | When the [[OSGi]] team designed its first specification, it did the best possible job. It defined few manifest tags and described how they shall be interpreted, it also prescribed that unknown tags (for example those provided by other systems) shall be ignored. So far so good, it is always easy to create the first version... | ||
| + | |||
| + | However later they needed to add the '''Require-Bundle''' tag. At that point it became clear that there is need for [[evolution]]. It is necessary to indicate whether the [[API]] user wants to use new [[OSGi]] specification (which understands the enhanced set of tags) or the old one (where '''Require-Bundle''' has no meaning). What can we do? Well, we need to version the property/manifest file! That is why the specification now defines the '''Bundle-ManifestVersion''' tag. Since now, every new specification release which adds new tags will boost the manifest version number to let the [[API]] user properly indicate which set of tags shall be recognized. | ||
| + | |||
| + | However, it is too late! As the '''Bundle-ManifestVersion''' tag was not introduced in the first version of the specification, it can only be optional, not required. If it is missing, the [[OSGi]] framework cannot refuse the [[JAR]], it needs to assume that it is old [[JAR]] written against the first version. Sometimes the assumption is wrong, and then poor users like me (who forget to add '''Bundle-ManifestVersion''' tag) cannot stop wondering what is going on! | ||
| + | |||
| + | If the specification was ready for [[evolution]] since its first version, it would require presence of | ||
| + | |||
| + | <source lang="text"> | ||
| + | Bundle-ManifestVersion: 1 | ||
| + | </source> | ||
| + | |||
| + | in each bundle. Without this tag, the bundle would be rejected. The [[API]] users would be forced to specify which version they are wanting to use and all my troubles described above would be prevented. | ||
| + | What is the takeaway? When you design an [[API]] based on [[PropertyFiles]], don't forget to include a version identifier in it. Only then your [[API]] becomes ready for [[evolution]]. | ||
| + | <comments/> | ||
[[Category:APITypes]] | [[Category:APITypes]] | ||
Revision as of 10:46, 16 December 2008
Many systems store their configuration in some form of property files. Files which contain string key/value mappings. This is indeed an example from the APITypes, as changes to these values influence behaviour of those systems. This may seem much more trivial form of an API than Java classes and their signatures and in some way it is, however the rules of proper API Design are still applicable: one needs to keep BackwardCompatibility, be ready for API evolution, etc.
Bundle Manifest Troubles
One commonly used property file in Java is the JAR manifest. It contains tag/value mappings for one main and many per entry sections. Many systems including NetBeans Runtime Container or OSGi recognize values of their own tags and based on them prepare runtime environment for the classes contained in the JAR file. Recently I was playing a bit with Felix and was trying to create a bundle (a JAR with OSGi manifest) that will require another bundle:
Manifest-Version: 1.0 Require-Bundle: does.no.exists;bundle-version="[1.0,2.0)" Export-Package: org.bar Bundle-Version: 1.1.0 Bundle-SymbolicName: org.bar
As the bundle does.no.exists does not exists, I would expect the system to refuse to start the org.bar bundle. To my biggest surprise, my bundle was successfully started. I've spend few days trying to find out what is wrong. Did I make a typo? No. Did I read the OSGi specification incorrectly? Neither. Is Felix broken? Let's debug it! Or rather not, this is not cluelessness! I do not want to be an expert at Felix, I am just an OSGi API user! So what is wrong?
At the end I decided to email Richard Hall, Felix maintainer and send him my org.bar bundle. In a minute I got an answer back, as he spotted the problem immediately, the following tag was missing:
Bundle-ManifestVersion: 2
After adding it, everything started to behave as expected. The bundle is now rejected, as the Require-Bundle dependency cannot be satisfied. It is easy to use an API if you resolve your problems by asking author of the specification. However this is probably not really scalable and there seems to be something wrong with the OSGi manifest API.
Ready for Evolution
An important rule when designing an API is to prepare it for evolution. Why? Because first version is never perfect, you will always need to release subsequent ones to fix bugs and provide new enhancements.
It is sometimes hard to remind ourselves of the need for evolution, especially when we are about the release the first version. We feel we did our best. We believe we created the most ingenious API on the Earth. It is hard to remind ourselves that the same API is also supposed to be imperfect. This requires a little bit of Doublethink. Still we need to do it, otherwise we and our API users will be in deep problems in the future - as my OSGi manifest adventure shows.
When the OSGi team designed its first specification, it did the best possible job. It defined few manifest tags and described how they shall be interpreted, it also prescribed that unknown tags (for example those provided by other systems) shall be ignored. So far so good, it is always easy to create the first version...
However later they needed to add the Require-Bundle tag. At that point it became clear that there is need for evolution. It is necessary to indicate whether the API user wants to use new OSGi specification (which understands the enhanced set of tags) or the old one (where Require-Bundle has no meaning). What can we do? Well, we need to version the property/manifest file! That is why the specification now defines the Bundle-ManifestVersion tag. Since now, every new specification release which adds new tags will boost the manifest version number to let the API user properly indicate which set of tags shall be recognized.
However, it is too late! As the Bundle-ManifestVersion tag was not introduced in the first version of the specification, it can only be optional, not required. If it is missing, the OSGi framework cannot refuse the JAR, it needs to assume that it is old JAR written against the first version. Sometimes the assumption is wrong, and then poor users like me (who forget to add Bundle-ManifestVersion tag) cannot stop wondering what is going on!
If the specification was ready for evolution since its first version, it would require presence of
Bundle-ManifestVersion: 1
in each bundle. Without this tag, the bundle would be rejected. The API users would be forced to specify which version they are wanting to use and all my troubles described above would be prevented.
What is the takeaway? When you design an API based on PropertyFiles, don't forget to include a version identifier in it. Only then your API becomes ready for evolution.
<comments/>
Follow
