Return-Path: Delivered-To: apmail-ant-notifications-archive@minotaur.apache.org Received: (qmail 13229 invoked from network); 13 Dec 2010 14:37:07 -0000 Received: from unknown (HELO mail.apache.org) (140.211.11.3) by 140.211.11.9 with SMTP; 13 Dec 2010 14:37:07 -0000 Received: (qmail 96725 invoked by uid 500); 13 Dec 2010 14:37:07 -0000 Delivered-To: apmail-ant-notifications-archive@ant.apache.org Received: (qmail 96611 invoked by uid 500); 13 Dec 2010 14:37:05 -0000 Mailing-List: contact notifications-help@ant.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@ant.apache.org Delivered-To: mailing list notifications@ant.apache.org Received: (qmail 96600 invoked by uid 99); 13 Dec 2010 14:37:04 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 13 Dec 2010 14:37:04 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 13 Dec 2010 14:37:00 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 86E302388A32; Mon, 13 Dec 2010 14:36:38 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1045135 - in /ant/ivy/core/trunk/doc/osgi: eclipse-plugin.html osgi-mapping.html standard-osgi.html target-platform.html Date: Mon, 13 Dec 2010 14:36:38 -0000 To: notifications@ant.apache.org From: hibou@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20101213143638.86E302388A32@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: hibou Date: Mon Dec 13 14:36:38 2010 New Revision: 1045135 URL: http://svn.apache.org/viewvc?rev=1045135&view=rev Log: IVY-1241: add some documentation Added: ant/ivy/core/trunk/doc/osgi/eclipse-plugin.html ant/ivy/core/trunk/doc/osgi/osgi-mapping.html ant/ivy/core/trunk/doc/osgi/standard-osgi.html ant/ivy/core/trunk/doc/osgi/target-platform.html Added: ant/ivy/core/trunk/doc/osgi/eclipse-plugin.html URL: http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/osgi/eclipse-plugin.html?rev=1045135&view=auto ============================================================================== --- ant/ivy/core/trunk/doc/osgi/eclipse-plugin.html (added) +++ ant/ivy/core/trunk/doc/osgi/eclipse-plugin.html Mon Dec 13 14:36:38 2010 @@ -0,0 +1,36 @@ + + + + + + + + + + + + + Added: ant/ivy/core/trunk/doc/osgi/osgi-mapping.html URL: http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/osgi/osgi-mapping.html?rev=1045135&view=auto ============================================================================== --- ant/ivy/core/trunk/doc/osgi/osgi-mapping.html (added) +++ ant/ivy/core/trunk/doc/osgi/osgi-mapping.html Mon Dec 13 14:36:38 2010 @@ -0,0 +1,226 @@ + + + + + + + + + +

+
+This page is a description of how OSGi™ dependencies are mapped into Apacge Ivy™ ones
+
+<u>Goal:</u> the purpose of this mapping is to transform an OSGi manifest into an ivy.xml, so Ivy can understand OSGi bundles and resolve them. We don't want to do the reverse here.
+
+<h2>Bundle Symbolic name / Ivy organisation and module</h2>
+
+In OSGi a bundle is identified by its symbolic name. In Ivy there is a notion of organisation and module name.
+
+The choosen mapping is:
+<ul>
+<li>No organisation : org=""</li>
+<li>The module name is the symbolic name</li>
+<li>an extra attribute is defining it as an OSGi bundle</li>
+</ul>
+
+<table border="1" cellspacing="1" cellpadding="4">
+<tr>
+<td> <b>OSGi</b> </td>
+<td> <b>Ivy</b> </td>
+</tr>
+<tr>
+<td> <tt>Bundle-SymbolicName: com.acme.product.plugin</tt> </td>
+<td>
+<code type="xml">
+<info organisation="" module="com.acme.product.plugin" osgi="bundle" />
+</code>
+</td>
+</tr>
+</table>
+
+<h2>Version and version range</h2>
+
+The OSGi specification is defining a version as a composition of 3 numbers and an arbitrary qualifier. This fit well into the lazy definition of Ivy. We will just have to use a special latest strategy in Ivy.
+
+Then about version range, Ivy will understand correctly fully defined range as <tt>[1.2.3,1.4.9)</tt> or <tt>(1.2.3,1.4.9]</tt>. But for OSGi version range defined as in <tt>1.2.3</tt>, it has to be transformed into <tt>[1.2.3,)</tt>
+
+<table border="1" cellspacing="1" cellpadding="4">
+<tr>
+<td> <b>OSGi</b> </td>
+<td> <b>Ivy</b> </td>
+</tr>
+<tr>
+<td> <tt>Bundle-Version: 3.3.3</tt> </td>
+<td> <tt>revision="3.3.3"</tt> </td>
+</tr>
+<tr>
+<td><tt>Require-Bundle: com.acme.product.plugin;bundle-version="3.2.1"</tt> </td>
+<td>
+<code type="xml">
+<dependency osgi="bundle" org="" name="com.acme.product.plugin" rev="[3.2.1,)" />
+</code>
+</td>
+</tr>
+</table>
+
+<h2>Ivy configurations</h2>
+
+The Ivy configuration is a notion that doesn't exist explicitely in OSGi, but some notion of the latter can be expressed with that configurations.
+
+First the mapping is defining three configurations:
+<ul>
+<li><tt>default</tt> : it will contain every required dependency (transitively)</li>
+<li><tt>optional</tt> : it will contain every optional dependency and every required depedency the the first degree dependencies.</li>
+<li><tt>transitive-optional</tt> : it will contain every optional dependency (optional transitively)</li>
+</ul>
+
+Then there will be some configurations used for the <tt>use</tt> parameter of the <tt>Import-Package</tt> OSGi manifest header. All of these kinds of configuration have their names starting with "use_". See in the next section.
+
+<h2>OSGi capabilities</h2>
+
+Generally speaking, declaring capabilities in an ivy.xml is useless (in the scope of this mapping which is to transform an OSGi manifest into an ivy.xml and not the reverse). In the resolve process we want to find the bundle which have the capability matching the expected requirement. In Ivy, if we are about to get the ivy.xml of a module, we are getting the bundle so we already have reached the requirement.
+
+So OSGi capabilities of bundles in a repo will be gathered direclty from the manifests to passed directly to the Ivy resolver, no need to express them into ivy.xml, except for the Export-Package, see the next section.
+
+<h3>Export-Package</h3>
+
+Exported package are declaring capabilities of the bundle in term of package. But they also declare dependencies between the declared package via the parameter <tt>use</tt>. These dependencies have to be declared in the ivy.xml. And we will use Ivy configurations for that.
+
+First, each exported package will be declared in the ivy.xml as a configuration. The name of the configuration will start will <tt>use_</tt> and will finished with the name of that package.
+
+Then each time an exported package is declared to use some other one, it will be mapped as a dependency between the Ivy configurations coresponding to those packages. 
+
+<table border="1" cellspacing="1" cellpadding="4">
+<tr>
+<td> <b>OSGi</b> </td>
+<td> <b>Ivy</b> </td>
+</tr>
+<tr>
+<td> <tt>Export-Package: com.acme.product.plugin.utils</tt> </td>
+<td>
+<code type="xml">
+<configuration name="use_com.acme.product.plugin.utils" extends="default" />
+</code>
+</td>
+</tr>
+<tr>
+<td> <tt>Export-Package: com.acme.product.plugin.utils,com.acme.product.plugin.common;use:=com.acme.product.plugin.utils</tt> </td> <td>
+<code type="xml">
+<configuration name="use_com.acme.product.plugin.utils" extends="default" />
+<configuration name="use_com.acme.product.plugin.common" extends="default,use_com.acme.product.plugin.utils" />
+</code> 
+</td>
+</tr>
+</table>
+
+<h2>OSGi Requirements / Ivy dependencies</h2>
+
+In OSGi there are different kind of dependencies, which is an OSGi bundle repository documentation is called a "requirement". The problem is that Ivy is understanding only one kind of requirement, so we use here some extra attribute to declare those different kind of dependency.
+
+<h3>Require-Bundle</h3>
+
+The OSGi <tt>Require-Bundle</tt> is some a requirement directly on a specific bundle. Ivy does it too. So we just use the <tt>osgi="bundle"</tt> extra attribute.
+
+If there is the OSGi <tt>resolution</tt> parameter specified to <tt>optional</tt>, then the dependency will be declared in the configuration <tt>optional</tt> and <tt>transitive-optional</tt>. Otherwise it will be declared in the <tt>default</tt> configuration.
+
+<table border="1" cellspacing="1" cellpadding="4">
+<tr>
+<td> <b>OSGi</b> </td>
+<td> <b>Ivy</b> </td>
+</tr>
+<tr>
+<td> <tt>Require-Bundle: com.acme.product.plugin;bundle-version="3.2.1"</tt> 
+</td>
+<td>
+<code type="xml">
+<dependency osgi="bundle" org="" name="com.acme.product.plugin" rev="[3.2.1,)" conf="default->default" />
+</code>
+</td>
+</tr>
+<tr>
+<td> <tt>Require-Bundle: com.acme.product.plugin;bundle-version="3.2.1";resolution:="optional"</tt> </td>
+<td>
+<code type="xml">
+<dependency osgi="bundle" org="" name="com.acme.product.plugin" rev="[3.2.1,)" conf="optional->default;transitive-optional->transitive-optional" />
+</code>
+</td>
+</tr>
+</table>
+
+<h3>Import-Package</h3>
+
+The OSGi <tt>Import-Package</tt> is some a requirement on a package of a bundle. Ivy has no notion of package. So we will use the <tt>osgi="pkg"</tt> extra attribute.
+
+If there is the OSGi <tt>resolution</tt> parameter specified to <tt>optional</tt>, then the dependency will be declared in the configuration <tt>optional</tt> and <tt>transitive-optional</tt>. Otherwise it will be declared in the <tt>default</tt> configuration.
+
+As it is an import package the configuration of the dependency will be the <tt>use_XXX</tt> one. So that transitive dependency via the use parameter will be respected in the dependency.
+
+<table border="1" cellspacing="1" cellpadding="4">
+<tr>
+<td> <b>OSGi</b> </td>
+<td> <b>Ivy</b> </td>
+</tr>
+<tr>
+<td> <tt>Import-Package: com.acme.product.plugin.utils;version="3.2.1"</tt> 
+</td>
+<td>
+<code type="xml">
+<dependency osgi="pkg" org="" name="com.acme.product.plugin.utils" rev="[3.2.1,)" conf="default->default;use_com.acme.product.plugin.utils->use_com.acme.product.plugin.utils" />
+</code>
+</td>
+</tr>
+<tr>
+<td> <tt>Import-Package: com.acme.product.plugin.utils;version="3.2.1";resolution:="optional"</tt> </td>
+<td>
+ <code type="xml">
+<dependency osgi="pkg" org="" name="com.acme.product.plugin.utils" rev="[3.2.1,)" conf="optional->default;transitive-optional->transitive-optional;use_com.acme.product.plugin.utils->use_com.acme.product.plugin.utils" />
+</code>
+</td>
+</tr>
+</table>
+
+<h2>Execution environment</h2>
+
+The OSGi <tt>Bundle-RequiredExecutionEnvironment</tt> manifest attribute is specifing is which environment the bundle is expected to run. In our problematic of dependency management it means that some of the transitive dependencies won't be resolved within the OSGi space but will be provided by the JRE. So we have to exclude from the dependency tree every requirement that will be provided by the environment. Basically it will be about excluding the packaged declared in the JRE.
+
+<table border="1" cellspacing="1" cellpadding="4">
+<tr>
+<td> <b>OSGi</b> </td>
+<td> <b>Ivy</b> </td>
+</tr>
+<tr>
+<td> <tt>Bundle-RequiredExecutionEnvironment: JavaSE-1.6</tt> </td>
+<td>
+<code type="xml">
+<dependencies>
+    <exclude org="" module="javax.accessibility" osgi="pkg" />
+    <exclude org="" module="javax.activation" osgi="pkg" />
+    <exclude org="" module="javax.activity" osgi="pkg" />
+    ...
+</dependencies>
+</code>
+</td>
+</tr>
+</table>
+

+ + + Added: ant/ivy/core/trunk/doc/osgi/standard-osgi.html URL: http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/osgi/standard-osgi.html?rev=1045135&view=auto ============================================================================== --- ant/ivy/core/trunk/doc/osgi/standard-osgi.html (added) +++ ant/ivy/core/trunk/doc/osgi/standard-osgi.html Mon Dec 13 14:36:38 2010 @@ -0,0 +1,36 @@ + + + + + + + + + + + + + Added: ant/ivy/core/trunk/doc/osgi/target-platform.html URL: http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/osgi/target-platform.html?rev=1045135&view=auto ============================================================================== --- ant/ivy/core/trunk/doc/osgi/target-platform.html (added) +++ ant/ivy/core/trunk/doc/osgi/target-platform.html Mon Dec 13 14:36:38 2010 @@ -0,0 +1,36 @@ + + + + + + + + + + + + +