{section}
{column}

h1. Why use shared libraries ?

Some component, like the petals-bc-ejb, the petals-bc-jms and some others requires external libraries to work properly. There are three solutions to add the libraries to do so :
* add the libraries directly in the component classpath (bad)
* add the libraries to each deployed service unit (average)
* add the libraries to a shared library deployed before component startup (good)

h1. Anatomy of a shared library

h2. Content of a shared library

A shared library archive may look like this :

{noformat}
my-shared-library.zip
+ META-INF
- jbi.xml
- my-shared-library.jar
- my-jar-dependency1.jar
- my-jar-dependency2.jar
- my-jar-dependency3.jar

h2. JBI descriptor of a shared library

Here is an exemple of such files (jbi.xml file) :
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petals="http://petals.ow2.org/extensions"
xmlns:jbi="http://java.sun.com/xml/ns/jbi" version="1.0">

<jbi:shared-library class-loader-delegation="self-first" version="my-shared-library-versionXYZ">

<jbi:identification>
<jbi:name>petals-sl-ejb</jbi:name>
<jbi:description>My Shared Library vXYZ</jbi:description>
</jbi:identification>

<jbi:shared-library-class-path>
<jbi:path-element>my-shared-library.jar</jbi:path-element>
<jbi:path-element>my-jar-dependency1.jar</jbi:path-element>
<jbi:path-element>my-jar-dependency2.jar</jbi:path-element>
<jbi:path-element>my-jar-dependency3.jar</jbi:path-element>
</jbi:shared-library-class-path>

</jbi:shared-library>
</jbi:jbi>
{code}

h2. Using a shared library

Finally, to add this shared library to the component classpath you must add the following section to the JBI descriptor of the component just after the end of the "bootstrap-class-path" element :
{code:lang=xml}<shared-library>my-shared-library</shared-library>{code}

h1. Creating new shared libraries

To create a new shared library, you can proceed by hand, creating the directory structure, the {{jbi.xml}} and package the whole by yourself.
Alternatively, if every library you need is available on maven repositories, you can use the _maven-archetype-petals-jbi-shared-library_ to create a new shared library :

{noformat}
mvn archetype:create
-DarchetypeGroupId=org.ow2.petals
-DarchetypeArtifactId=maven-archetype-petals-jbi-shared-library
-DarchetypeVersion=1.3.1
-DgroupId=org.ow2.petals
-DartifactId=<service-assembly-name>
-Dversion=1.0-SNAPSHOT
{noformat}

\\
{note:title=Note}
Of course this command has been formatted. You should type it as a single line.
{note}

{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}