<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="install.jdbc.driver" xml:lang="en"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:mml="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>Install a JDBC driver</title>
  </info>

  <para>This document describes the process to transform a
  <acronym>JDBC</acronym> driver jar file into an <trademark>OSGi</trademark>
  bundle suitable for usage in JOnAS.</para>

  <para>It targets a developer audience. Some <trademark>OSGi</trademark>
  vocabulary is used in this document.</para>

  <note>
    <para>This howto has been tested using
    <interfacename>DataSource</interfacename> provided using a Resource
    Adapter.</para>
  </note>

  <section>
    <title>Why creating an OSGi bundle ?</title>

    <para>JOnAS is performing an automatic bundle generation during startup
    for jars found in <filename
    class="directory">$JONAS_ROOT/lib/ext/</filename> and <filename
    class="directory">$JONAS_BASE/lib/ext/</filename>. That means that the jar
    file dropped into the <filename>lib/ext/</filename> directory will be
    analyzed and appropriate entries will be added in the MANIFEST of the jar.
    </para>

    <para>Theses new entries are <trademark>OSGi</trademark> related
    attributes (<literal>Bundle-SymbolicName</literal>,
    <literal>Bundle-ClassPath</literal>, <literal>Import-Package</literal>,
    <literal>Export-Package</literal>, ...). They describe what the bundle is
    (symbolic name, ...), what it requires from the system
    (<literal>Import-Package</literal>) and what it gives to the system
    (<literal>Export-Package</literal>). Concretely the Import-Package entry
    contains a list of package that are necessary in order to have a working
    bundle and the Export-Package is also a list of packages "offered" to the
    system.</para>

    <para>By default, JOnAS use very simple directives to generate a bundle
    that should <emphasis>mostly</emphasis> work:</para>

    <itemizedlist>
      <listitem>
        <para>Every package required by the code in the jar file is placed in
        the Import-Package list, <emphasis>with a resolution:=optional
        attribute</emphasis>. That means that, during startup (when the bundle
        is installed then started), the <trademark>OSGi</trademark> framework
        will try to resolve as much required packages as possible, but if some
        are missing, there will be no failures. At the end, the bundle is
        ready to be used, but it's possible that it won't work as a really
        needed package could not be found during the resolution.</para>
      </listitem>

      <listitem>
        <para>Every package provided by the original jar file is placed in the
        <literal>Export-Package</literal> list. That means that all the
        classes that are in the jar file are potentially visible from other
        part of the server. This is bad for modularity.</para>
      </listitem>

      <listitem>
        <para><literal>Bundle-SymbolicName</literal> is simply the jar file
        short name.</para>
      </listitem>
    </itemizedlist>

    <para>Creating a handmade bundle with controled content will also avoid
    seeing that kind of traces during JOnAS start-up sequence:</para>

    <screen>07/09/09 12:26:22 (I) ExtensionLoaderComponent.__start : Some jars have been found in [&lt;JONAS_ROOT&gt;\lib\ext, &lt;JONAS_BASE&gt;\lib\ext].
                                                         They have been transformed into bundles (see &lt;JONAS_BASE&gt;\work\ext-bundles directory).
                                                         This is NOT the prefered way to extends JOnAS libraries, prefer to use carefully
                                                         created and tested bundles, and place them in your deploy/ directory.
07/09/09 12:26:22 (I) ExtensionLoaderComponent.__start : file:/&lt;JONAS_BASE&gt;/work/ext-bundles/ojdbc14.jar installed as a bundle.
07/09/09 12:26:22 (I) ExtensionLoaderComponent.__start : file:/&lt;JONAS_BASE&gt;/work/ext-bundles/mysql-connector-java-3.1.10-bin.jar installed as a bundle.</screen>
  </section>

  <section>
    <title>Using Bnd to generate an OSGi bundle</title>

    <para>Bnd is a bundle generation tool. It helps a lot the developer of
    <trademark>OSGi</trademark> bundles by automating MANIFEST generation and
    bundle content creation.</para>

    <para>The <link linkend="bnd.references">references section</link>
    contains links to some Bnd documentations and examples that a user should
    read to better understand the Bnd philisophy.</para>

    <para>This howto focus on practical operations to be done to transform a
    jar file containing a <acronym>JDBC</acronym> driver into a suitable
    <trademark>OSGi</trademark> bundle.</para>

    <section>
      <title>Installing Bnd</title>

      <para>Bnd can be downloaded here: <link
      xlink:href="http://www.aqute.biz/Code/Download">http://www.aqute.biz/Code/Download</link>.</para>

      <para>This is an all-in-one executable jar file (sources can be seen in
      <filename class="directory">/OSGI-OPT/src/</filename> ).</para>

      <para>It can be executed using the following command line:</para>

      <para><screen><prompt>&gt;$ </prompt><userinput>java -jar bnd.jar
</userinput></screen></para>

      <note>
        <para>Bnd requires a 1.5 JVM (at minimum, also works with 1.6).</para>
      </note>

      <note>
        <para>Later in this article, a command named <command>bnd</command> is
        used. It refers to a shell script that could looks like the
        following:</para>

        <para><screen>#!/bin/sh
java -jar /path/to/your/bnd.jar $*
</screen></para>
      </note>
    </section>

    <section>
      <title>Default jar wrapping</title>

      <para>Bnd provides a utility wrapping mode. Here is a quote from the Bnd
      documentation:</para>

      <para><quote>The wrap command takes an existing JAR file and guesses the
      manifest headers that will make this JAR useful for an OSGi Service
      Platform.</quote></para>

      <para>Looks promising :) In fact, this mode the one used by JOnAS when a
      library is placed in <filename class="directory">lib/ext/</filename>. If
      the jar in lib/ext/ had already been transformed and tested as a bundle,
      it's probably safe to use it as is (transformed bundle are in <filename
      class="directory">&lt;JONAS_BASE&gt;/work/bundle-ext/</filename>).</para>

      <para>The following command show how to use it using a MySQL driver
      jar:</para>

      <para><screen><prompt>&gt;$ </prompt><userinput>bnd wrap mysql-connector-java-5.1.8-bin.jar
</userinput><computeroutput>mysql-connector-java-5.1.8-bin 239 0
One warning
1 : Superfluous export-package instructions: [org, com, com.mysql.jdbc.jdbc2, org.gjt, org.gjt.mm, com.mysql.jdbc.integration, com.mysql]
</computeroutput></screen>This command has created a
      <filename>mysql-connector-java-5.1.8-bin.bar</filename> file that is an
      <trademark>OSGi</trademark> bundle. It can be placed in <filename
      class="directory">&lt;JONAS_BASE&gt;/deploy/</filename> and renamed with
      a <filename class="extension">.jar</filename> extension and then JOnAS
      will automatically deploy it.</para>

      <para>As a side note, here is what is imported and exported from the
      MySQL bundle after wrapping (this output can be useful for advanced
      users):</para>

      <para><screen><prompt>&gt;$ </prompt><userinput>bnd print -impexp mysql-connector-java-5.1.8-bin.bar</userinput><computeroutput>
[IMPEXP]
Import-Package
  com.mchange.v2.c3p0                   {resolution:=optional}
  javax.naming                          {resolution:=optional}
  javax.naming.spi                      {resolution:=optional}
  javax.net                             {resolution:=optional}
  javax.net.ssl                         {resolution:=optional}
  javax.sql                             {resolution:=optional}
  javax.transaction.xa                  {resolution:=optional}
  javax.xml.parsers                     {resolution:=optional}
  javax.xml.stream                      {resolution:=optional}
  javax.xml.transform                   {resolution:=optional}
  javax.xml.transform.dom               {resolution:=optional}
  javax.xml.transform.sax               {resolution:=optional}
  javax.xml.transform.stax              {resolution:=optional}
  javax.xml.transform.stream            {resolution:=optional}
  org.apache.commons.logging            {resolution:=optional}
  org.apache.log4j                      {resolution:=optional}
  org.jboss.resource.adapter.jdbc       {resolution:=optional}
  org.jboss.resource.adapter.jdbc.vendor{resolution:=optional}
  org.w3c.dom                           {resolution:=optional}
  org.xml.sax                           {resolution:=optional}
  org.xml.sax.helpers                   {resolution:=optional}
Export-Package
  com.mysql.jdbc                        
  com.mysql.jdbc.configs                
  com.mysql.jdbc.exceptions             
  com.mysql.jdbc.exceptions.jdbc4       
  com.mysql.jdbc.integration.c3p0       
  com.mysql.jdbc.integration.jboss      
  com.mysql.jdbc.interceptors           
  com.mysql.jdbc.jdbc2.optional         
  com.mysql.jdbc.log                    
  com.mysql.jdbc.profiler               
  com.mysql.jdbc.util                   
  org.gjt.mm.mysql</computeroutput></screen></para>
    </section>

    <section>
      <title>Advanced wrapping</title>

      <para>This section is for lib/ext/ bundles that cannot be installed with
      the default process or address developers wanting to control exactky
      their bundle's content.</para>

      <para>The wrap command's default values can be changed using a property
      file:</para>

      <para><programlisting>Import-Package: !com.mchange.v2.c3p0,\                     <co
            xml:id="import.package" />
                !org.jboss.*,\
                javax.transaction.*;version=1.1,\          <co
            xml:id="specify.version" />
                *;resolution:=optional                     <co
            xml:id="final.star" />

Export-Package: !com.mysql.jdbc.integration.*,\            <co
            xml:id="excluding.export.package" />
                *;version=5.1.8                            <co
            xml:id="set.package.version" />

Bundle-Version 5.1.8                                       <co
            xml:id="bundle.version" />

Bundle-SymbolicName MySQL Connector/J                      <co
            xml:id="bundle.symbolic.name" />
</programlisting><calloutlist>
          <callout arearefs="import.package">
            <para>Inside JOnAS, the c3p0 and jboss related packages don't have
            to be imported (they are not even exported, so the dependencies
            can never be resolved). Using the '!' prefix exclude them.</para>
          </callout>

          <callout arearefs="specify.version">
            <para>Specify a version for this required package (not optional).
            The bundle will be installed only if a package with the correct
            version is exported.</para>
          </callout>

          <callout arearefs="final.star">
            <para>The trainling '*' is required. If omitted, Bnd will not
            discover the imported packages of the jar.</para>
          </callout>

          <callout arearefs="excluding.export.package">
            <para>Similar to Import-Package exclusions, Bnd can avoid
            exporting some packages that are part of the original jar by
            prefixing their package name with '!'</para>
          </callout>

          <callout arearefs="set.package.version">
            <para>That line indicates to Bnd that all exported packages will
            be "tagged" with a particular version. It's a good practice to
            always have a version on exported packages.</para>
          </callout>

          <callout arearefs="bundle.version">
            <para>By default, the value will be '0'. For consistency, it
            should be set accordingly to the version of the driver.</para>
          </callout>

          <callout arearefs="bundle.symbolic.name">
            <para>By default, the value will be the jar file name.</para>
          </callout>
        </calloutlist>This file can then be used on the command line:</para>

      <para><screen><prompt>&gt;$ </prompt><userinput>bnd wrap -properties mysql-connector-java-5.1.8-bin.bnd mysql-connector-java-5.1.8-bin.jar
</userinput><computeroutput>mysql-connector-java-5.1.8-bin 239 728542
</computeroutput></screen><note>
          <para>That section was only an example of an advanced bundle
          generation. the import/export directives shown above may not be
          suitable for your own bundle. It is advised to read the links
          provided in the <link linkend="bnd.references">references
          section</link> to better understand and see other capabilities of
          Bnd.</para>
        </note></para>
    </section>
  </section>

  <section>
    <title xml:id="bnd.references">References</title>

    <orderedlist>
      <listitem>
        <para>Bnd: <link xlink:href="http://www.aqute.biz/Code/Bnd">Bundle
        Tool</link></para>
      </listitem>

      <listitem>
        <para>Example: <link
        xlink:href="http://www.aqute.biz/Code/BndHibernate">Using Bnd To Do a
        Quick Wrap of Hibernate</link></para>
      </listitem>

      <listitem>
        <para>SpringSource: <link
        xlink:href="http://blog.springsource.com/2008/02/18/creating-osgi-bundles/">Creating
        OSGi bundles</link></para>
      </listitem>

      <listitem>
        <para>Documentation: <link
        xlink:href="http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html">Maven
        bundle Plugin</link> (<link xlink:arcrole=""
        xlink:href="http://felix.apache.org/site/apache-felix-bundle-plugin-faq.html">FAQ</link>)</para>
      </listitem>

      <listitem>
        <para><link xlink:href="http://www.aqute.biz/Code/Download">Download
        Bnd</link></para>
      </listitem>
    </orderedlist>
  </section>
</chapter>
