<!--
  ~ Copyright 2009 the original author or authors.
  ~
  ~ Licensed 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.
  -->
<chapter id='osgi_plugin' xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The OSGi Plugin</title>
    <para>The OSGi plugin provides a factory method to create an
        <apilink class="org.gradle.api.plugins.osgi.OsgiManifest"/> object. <literal>OsgiManifest</literal> extends
        <apilink class="org.gradle.api.java.archives.Manifest"/>. To learn more
        about generic manifest handling, see <xref linkend="sub:manifest"/>. If the Java plugins is applied, the OSGi plugin
        replaces the manifest object of the default jar with an <literal>OsgiManifest</literal> object. The replaced manifest
        is merged into the new one.
    </para>
    <para>The OSGi plugin makes heavy use of Peter Kriens <ulink url='http://www.aqute.biz/Bnd/Bnd'>BND tool</ulink>.
    </para>

    <section>
        <title>Usage</title>
        <para>To use the OSGi plugin, include the following in your build script:</para>
        <sample id="useOsgiPlugin" dir="osgi" title="Using the OSGi plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
    </section>

    <section>
        <title>Implicitly applied plugins</title>
        <para>Applies the Java base plugin.</para>
    </section>

    <section>
        <title>Tasks</title>
        <para>This plugin does not add any tasks.</para>
    </section>

    <section>
        <title>Dependency management</title>
        <para>TBD</para>
    </section>

    <section>
        <title>Convention object</title>

        <para>The OSGi plugin adds the following convention object: <apilink class="org.gradle.api.plugins.osgi.OsgiPluginConvention"/>
        </para>
        <section>
            <title>Convention properties</title>

            <para>The OSGi plugin does not add any convention properties to the project.
            </para>
        </section>
        <section>
            <title>Convention methods</title>

            <para>The OSGi plugin adds the following methods. For more details, see the API documentation of the convention
                object.
            </para>
            <table>
                <title>OSGi methods</title>
                <thead>
                    <tr>
                        <td>Method</td>
                        <td>Return Type</td>
                        <td>Description</td>
                    </tr>
                </thead>
                <tr>
                    <td>osgiManifest()</td>
                    <td>
                        <apilink class="org.gradle.api.plugins.osgi.OsgiManifest"/>
                    </td>
                    <td>Returns an OsgiManifest object.</td>
                </tr>
                <tr>
                    <td>osgiManifest(Closure cl)</td>
                    <td>
                        <apilink class="org.gradle.api.plugins.osgi.OsgiManifest"/>
                    </td>
                    <td>Returns an OsgiManifest object configured by the closure.</td>
                </tr>
            </table>
        </section>
    </section>
    <section>
        <para>The classes in the classes dir are analyzed regarding their package dependencies and the packages they expose.
            Based on this the <emphasis>Import-Package</emphasis> and the <emphasis>Export-Package</emphasis> values of the
            OSGi Manifest are calculated. If the classpath contains jars with an OSGi bundle, the bundle
            information is used to specify version information for the <emphasis>Import-Package</emphasis>
            value. Beside the explicit properties of the <literal>OsgiManifest</literal> object you can add instructions.
        </para>
        <sample id="osgi" dir="userguide/tutorial/osgi" title="Configuration of OSGi MANIFEST.MF file">
            <sourcefile file="build.gradle" snippet="configure-jar"/>
        </sample>
        <para>The first argument of the instruction call is the key of the property. The other arguments form the value.
            To learn more about the available instructions have a look at the <ulink url='http://www.aqute.biz/Bnd/Bnd'>BND tool</ulink>.</para>
    </section>
</chapter>
