ant-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hi...@apache.org
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 GMT
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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.    
+-->
+<html>
+<head>
+	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+	<script type="text/javascript">var xookiConfig = {level: 1};</script>	
+	<script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+	<textarea id="xooki-source">
+
+This page describes how to build an Eclipse&#153; plugin with Apache Ivy&#153; and
its OSGi&#153; capabilities.
+
+TODO
+
+	</textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>

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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.    
+-->
+<html>
+<head>
+	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+	<script type="text/javascript">var xookiConfig = {level: 1};</script>	
+	<script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+	<textarea id="xooki-source">
+
+This page is a description of how OSGi&#153; dependencies are mapped into Apacge Ivy&#153;
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>
+	</textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>

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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.    
+-->
+<html>
+<head>
+	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+	<script type="text/javascript">var xookiConfig = {level: 1};</script>	
+	<script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+	<textarea id="xooki-source">
+
+This page describes how to build an OSGi&#153; webapp with with Apache Ivy&#153;.
+
+TODO
+
+	</textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>

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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.    
+-->
+<html>
+<head>
+	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+	<script type="text/javascript">var xookiConfig = {level: 1};</script>	
+	<script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+	<textarea id="xooki-source">
+
+Building an OSGi&#153; bundle with standard tools like <tt>javac</tt> and
a classpath computed by Apache Ivy&#153; can be erroneous as these tools doesn't take
into account the package visibility enforced by the OSGi metadata. Then switching to OSGi
dedicated tools like the Eclipse&#153; JTD can be prefered. This kind of tools still need
a "target platform", a set of jars against to compile and then later run. A target platform
can be easily managed with Ivy and its OSGi capabilities.
+
+TODO
+
+	</textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>



Mime
View raw message