| ←Older revision |
Revision as of 10:46, 16 December 2008 |
| 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 is something wrong with the [[OSGi]] manifest [[API]]. | + | 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]] |