---
title: Fuse Bundle Overview
--- name:overview
# Fuse Bundles

--- name:content pipeline:ssp,markdown

{:toc}

# Fuse Bundle Overview

This document hopes to explain what Fuse Bundles (or FABs) are and how you use them.

## Why Fuse Bundles?

Fuse Bundles are designed to make it very easy for application developers to create applications that can be deployed in OSGi containers or  web containers so that its:-

* easy to deploy and control which classes are shared across deployment units
* there's a common model of class loaders across your build tool (e.g. Maven), your IDE (e.g. with Maven integration) and container with few surprises
* developers can focus on getting things done rather than fighting OSGi metadata or struggling with OSGi specific metadata generation tools.

For more detail see the [motivations behind creating Fuse Bundles](background.html)

## What is a Fuse Bundle?
    
${include("/bundle/_what-is-fab.md")}

## Installing a FAB

In your OSGi container such as [Fuse ESB](http://fusesource.com/products/enterprise-servicemix/) or [Apache Karaf](http://karaf.apache.org/) with the Fuse bundle feature installed - you can then install any FAB as if it were a WAR or Karaf feature.

${include("/bundle/_install-command.md")}

## How does it work?

When a FAB is installed it is converted into a valid OSGi bundle dealing with its transitive dependencies.

To do this the _pom.xml_ is extracted from the jar and used to figure out, by default, the non-optional and non-test transitive dependencies for the FAB to be able to create the OSGi bundle so that it fully respects the _pom.xml_ dependencies.

So when you deploy a FAB into an OSGi container it is transformed into a regular OSGi bundle which other OSGi bundles or FABs can work with. A FAB can depend on any number of regular jars or actual OSGi bundles.

By default when you install a FAB into a container all its transient dependencies are also installed (if they are not already) so things just work as you'd expect.

## Configuration

There are a number of optional manifest headers you can use to help configure how the _pom.xml_ transitive dependencies are included in a FAB.

### Configure the sharing of classes

The default in FAB is to use simple flat class loaders - like building a WAR using Maven - rather than using complex shared class loaders. Typically flat class loaders tend to just work in your IDE, build tool and then your container. Class loader problems typically occur when you try to share classes across different deployments; so FABs aim to just work by default; but then let you optimise things later to improve your sharing as and when you need it rather than forcing you to think about sharing issues for all dependencies and deployment units up front.

However we often want to share code across deployment units. For example you may wish to share slf4j, Apache Camel or Spring across a number of deployment units to avoid having to load that code multiple times in memory for the same JVM.

So to share a dependency (and its transitive dependencies) you just declare a dependency with a **provided** scope in your _pom.xml_. e.g.

{pygmentize:: xml}
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-core</artifactId>
  <version>\${camel-version}</version>
  <scope>provided</scope>
</dependency>
{pygmentize}

This is the same approach you use when building a WAR using Maven to avoid things like the servlet API or JSP being included inside the WAR.

### FAB-Provided-Dependency

An alternative approach to the _&lt;scope&gt;provided&lt;/scope&gt;_ XML is to use the jar manifest header **FAB-Provided-Dependency** which denotes which artefacts (transitively) should be shared across deployment units. This header, like most FAB headers, uses a simple concise syntax which supports wildcards.

The syntax lets you specify zero to many artifacts as follows

{pygmentize:: text}
FAB-Provided-Dependency: groupId:artifactId someGroup:someArtifact
{pygmentize}
    
You can use wildcards for the groupId or artifactId. So for example if you wish to share all Apache Camel and Spring dependencies (transitively) in your FAB just add this

{pygmentize:: text}
FAB-Provided-Dependency: org.apache.camel:* org.springframework:*
{pygmentize}

which some find a little simpler and more DRY than using the _&lt;scope&gt;provided&lt;/scope&gt;_ XML on every dependency to be shared



### FAB-Dependency-Require-Bundle

Specifies a list of artefacts which should not use the regular OSGi mechanism of importing packages, but instead should use the OSGi **Require-Bundle** directive.

By default the packages are imported from shared dependencies using the OSGi **Import-Package** directive for all artefacts not selected via the **FAB-Dependency-Require-Bundle** expression.


### FAB-Include-Optional-Dependency

Optional dependencies are marked in a _pom.xml_ using the _&lt;optional&gt;true&lt;/optional&gt;_ XML on a dependency.

By default optional dependencies are excluded in a FAB. To explicitly include them you need to add them with the **FAB-Include-Optional-Dependency** manifest entry.

So to include all optional dependencies use

{pygmentize:: text}
FAB-Include-Optional-Dependency: *:*
{pygmentize}


## What are the drawbacks?

None :). Fuse Bundles create regular valid OSGi bundles and they provide a nice simple abstraction so you don't need to work with OSGi metadata; but if you really want to you can either still write OSGi bundles by hand, reuse existing OSGi bundles or reuse FABs in other OSGi bundles or put OSGi metadata explicitly into your FAB.

