| <html><head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
| <title>5.4 Specifying automatic version expansion of imported packages based on a pattern</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="Bundlor User Guide"><link rel="up" href="ch05.html" title="5. Manifest Templates"><link rel="prev" href="ch05s03.html" title="5.3 Specifying property placeholders"><link rel="next" href="ch05s05.html" title="5.5 Example Bundlor Manifest Template"><!--Begin Google Analytics code--><script type="text/javascript"> | |
| var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); | |
| document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); | |
| </script><script type="text/javascript"> | |
| var pageTracker = _gat._getTracker("UA-2728886-3"); | |
| pageTracker._setDomainName("none"); | |
| pageTracker._setAllowLinker(true); | |
| pageTracker._trackPageview(); | |
| </script><!--End Google Analytics code--></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.4 Specifying automatic version expansion of imported packages based on a pattern</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s03.html">Prev</a> </td><th width="60%" align="center">5. Manifest Templates</th><td width="20%" align="right"> <a accesskey="n" href="ch05s05.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="manifest.template.version.expansion"></a>5.4 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="5.3 Specifying property placeholders">Section 5.3, “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="d0e961"></a><p class="title"><b>Table 5.2. Expansion Pattern Symbols</b></p><div class="table-contents"><table summary="Expansion Pattern Symbols" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Symbol</th><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Description</th><th style="border-bottom: 1.0pt solid ; ">Location Allowed</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">=</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Use the same value from the variable.</td><td style="border-bottom: 1.0pt solid ; "> | |
| Valid only in the first three segments (major, minor, micro) of the version pattern. | |
| </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">[+/-]n</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "> | |
| 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 style="border-bottom: 1.0pt solid ; "> | |
| Valid only in the first three segments (major, minor, micro) of the version pattern. | |
| </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">n</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "> | |
| 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 style="border-bottom: 1.0pt solid ; "> | |
| Valid only in the first three segments (major, minor, micro) of the version pattern. | |
| </td></tr><tr><td style="border-right: 1.0pt solid ; ">Any legal qualifier value</td><td style="border-right: 1.0pt solid ; ">Substitute this value for the one in the variable.</td><td style="">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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="manifest.template.format.version.naming"></a>5.4.1 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><!--Begin LoopFuse code--><script src="http://loopfuse.net/webrecorder/js/listen.js" type="text/javascript"></script><script type="text/javascript"> | |
| _lf_cid = "LF_48be82fa"; | |
| _lf_remora(); | |
| </script><!--End LoopFuse code--><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch05s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.3 Specifying property placeholders </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 5.5 Example Bundlor Manifest Template</td></tr></table></div></body></html> |