| <html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Specifying automatic version expansion of imported packages based on a pattern</title><meta content="DocBook XSL Stylesheets V1.76.0" name="generator"><link rel="home" href="index.html" title="Bundlor User Guide"><link rel="up" href="ch05.html" title="Chapter 5. Manifest Templates"><link rel="prev" href="ch05s03.html" title="Specifying property placeholders"><link rel="next" href="ch05s05.html" title="Example Bundlor Manifest Template"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><td align="left" width="20%"><a accesskey="p" href="ch05s03.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="ch05s05.html">Next</a></td></tr></table><hr></div><div class="section" title="Specifying automatic version expansion of imported packages based on a pattern"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="manifest.template.version.expansion"></a>Specifying automatic version expansion of imported packages based on a pattern</h2></div></div></div><p> | |
| When you use the <code class="literal">Import-Template</code> template header to augment package imports that Bundlor | |
| generates in the manifest file, you use the <code class="literal">version</code> attribute to specify a | |
| version range of the imported package. | |
| </p><pre class="programlisting">Import-Template: | |
| org.eclipse.virgo.kernel.*;version="[1.2.0, 2.0.0)" | |
| org.apache.commons.logging;version="[1.1.1, 2.0.0)"</pre><p> | |
| The preceding example specifies that Bundlor should import the <code class="literal">org.eclipse.virgo.kernel.*</code> | |
| packages in the range <code class="literal">[1.2.0, 2.0.0)</code> and the <code class="literal">org.apache.commons.logging</code> | |
| package in the range <code class="literal">[1.1.1, 2.0.0)</code> in the generated manifest file. This works just fine for many | |
| use cases, but sometimes the use of literal versions in this manner can be restrictive. | |
| </p><p> | |
| In order to make the manifest template more dynamic and useful, you can specify that Bundlor automatically | |
| expand the package version into a version range using an expansion pattern of your choosing. The pattern | |
| uses as a base a property placeholder that you define (as described in | |
| <a class="xref" href="ch05s03.html" title="Specifying property placeholders">Specifying property placeholders</a>) and set to a valid OSGi version number. Then, based on the | |
| expansion pattern you specify, Bundlor generates a version range using the 4 parts of an OSGi version: | |
| major, minor, micro, and qualifier. | |
| </p><p> | |
| The way to tell Bundlor to automatically expand a package import version is to specify the property | |
| placeholder to the right of the <code class="literal">version</code> directive of the package in the | |
| <code class="literal">Import-Template</code> header, and then within the property placeholder, specify the pattern for | |
| both sides of the version range. The following manifest template snippet shows how to use this feature; the | |
| example is described in detail after the table. | |
| </p><pre class="programlisting">Import-Template: | |
| org.eclipse.virgo.kernel.*;version="${org.eclipse.virgo.kernel:[=.=.=.=, +1.0.0)}", | |
| org.apache.commons.logging.*;version="${org.apache.commons.logging:[=.=.=.=, =.=.+1)}"</pre><p>The following table lists the symbols you can use in the expansion pattern.</p><div class="table"><a name="N104A5"></a><p class="title"><b>Table 5.2. Expansion Pattern Symbols</b></p><div class="table-contents"><table summary="Expansion Pattern Symbols" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Symbol</th><th>Description</th><th>Location Allowed</th></tr></thead><tbody><tr><td>=</td><td>Use the same value from the variable.</td><td> | |
| Valid only in the first three segments (major, minor, micro) of the version pattern. | |
| </td></tr><tr><td>[+/-]n</td><td> | |
| Adjust the value from the variable by this amount. For example, <code class="literal">+1</code> means | |
| to add 1 to the value from the variable. | |
| </td><td> | |
| Valid only in the first three segments (major, minor, micro) of the version pattern. | |
| </td></tr><tr><td>n</td><td> | |
| Substitute this value for the one in the variable. Typically you only use this for putting | |
| in a <code class="literal">0</code>. | |
| </td><td> | |
| Valid only in the first three segments (major, minor, micro) of the version pattern. | |
| </td></tr><tr><td>Any legal qualifier value</td><td>Substitute this value for the one in the variable.</td><td>Valid only in the fourth (qualifier) segment of the version pattern.</td></tr></tbody></table></div></div><br class="table-break"><p> | |
| Based on the descriptions of the symbols, we can now understand how the examples above work. First assume | |
| that you have set the property <code class="literal">${org.eclipse.virgo.kernel}</code> to the value | |
| <code class="literal">1.2.0</code>. Based on the expansion pattern, Bundlor sets the version range of the imported | |
| <code class="literal">org.eclipse.virgo.kernel.*</code> packages to <code class="literal">[1.2.0, 2.0.0)</code>. The pattern in | |
| this case first specifies that the beginning of the version range stay exactly the same as the value of the | |
| property. The pattern then specifies that at the end of the version range, the major part of the version | |
| should be one integer larger than what the property is originally set to (<code class="literal">1</code>); the pattern | |
| then specifies that the minor and micro segments of the version both be set to <code class="literal">0</code>. | |
| </p><p> | |
| Similarly, assume that you set the <code class="literal">${org.apache.commons.logging}</code> property to | |
| <code class="literal">1.4.0</code>. Bundlor generates a version range of <code class="literal">[1.4.0, 1.4.1)</code>. Again, | |
| the beginning of the range is exactly the same as the property value. The pattern specifies that, in the end | |
| of the range, only the micro segment of the version increase by one; the major and minor segments stay the | |
| same. | |
| </p><div class="section" title="Re-using version patterns"><div class="titlepage"><div><div><h3 class="title"><a name="manifest.template.format.version.naming"></a>Re-using version patterns</h3></div></div></div><p> | |
| If you use the same version expansion pattern for several imports, you can name the pattern using the | |
| <code class="literal">Version-Patterns</code> header in the manifest template, and then use this name in the | |
| particular import of <code class="literal">Import-Template</code>. | |
| </p><p> | |
| Use the form <code class="literal"><span class="emphasis"><em>pattern.name</em></span>;pattern="<span class="emphasis"><em>pattern</em></span>"</code> | |
| to specify a named pattern, where <code class="literal">pattern.name</code> is the name of the pattern and | |
| <code class="literal">pattern</code> is the pattern, such as <code class="literal">[=.=.=.=, +1.0.0)</code>. | |
| </p><pre class="programlisting">Version-Patterns: | |
| apache;pattern="[=.=.=.=, +1.0.0)", | |
| hibernate;pattern="[=.=.=.=, =.=.+1)"</pre><p> | |
| The preceding example shows two named patterns: <code class="literal">apache</code> and | |
| <code class="literal">hibernate</code>. The <code class="literal">apache</code> pattern specifies a version range from the | |
| one provided in the property up to but not including the next major version. The | |
| <code class="literal">hibernate</code> pattern specifies a version range of the one provided up to but not | |
| including the next micro version. | |
| </p><p> | |
| To use a named pattern, simply substitute it in the <code class="literal">Import-Template</code> header in the | |
| place where you would put the in-line pattern. | |
| </p><pre class="programlisting">Import-Template: | |
| org.apache.commons.codec.*;version="${org.apache.commons.codec:apache}", | |
| org.apache.commons.logging.*;version="${org.apache.commons.logging:apache}", | |
| org.hibernate.*;version="${org.hibernate:hibernate}" | |
| org.myorg.*;version="${org.myorg:[]=.=.=.=, =.+1.0.=)}"</pre><p> | |
| In the example, the <code class="literal">apache</code> named pattern is used twice, for the two | |
| <code class="literal">org.apache</code> imports, and the <code class="literal">hibernate</code> pattern is used once. Also | |
| note that you can also include an import whose version is specified with an in-line pattern. | |
| </p></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch05s03.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="ch05.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ch05s05.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%"> </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> </td></tr></table></div></body></html> |