= How to add library dependencies to your OSGi bundle app =

Nearly all apps require functionality provided by third party libraries to do things like parse JSON, make HTTP requests, or do high-performance mathematical computations. This guide will explain how to add your library dependencies to your app. 

/!\ '''Important: Do not depend on Cytoscape's third party libraries.''' Cytoscape's core bundles depend on third party libraries and are included with  Cytoscape. You may find that your app also happens to depend on the same libraries. Your app should ''not'' depend on Cytoscape's third party libraries. Your app ought to include the library in its bundle even if the same library is provided by Cytoscape. Cytoscape's third party libraries are part of its implementation. These libraries could change in minor version updates of Cytoscape and would break your app.

== Configuring your Maven pom file ==

We'll assume that you are using Maven to build your app and that you are listing all third party library dependencies (along with Cytoscape API dependencies) in your Maven pom file.

=== Tell maven-bundle-plugin to embed your dependencies ===

Configure `maven-build-plugin` (shown below) so that it ''embeds'' your dependencies with your bundle jar. By embedding, the dependencies will be included in your bundle jar in tact. This is different from shading, which combines jars into one single jar file.

{{{
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.felix</groupId>
      <artifactId>maven-bundle-plugin</artifactId>
      <version>2.3.7</version>
      <extensions>true</extensions>
      <configuration>
        <instructions>
          <Bundle-SymbolicName>${bundle.symbolicName}</Bundle-SymbolicName>
          <Bundle-Version>${project.version}</Bundle-Version>
          <Bundle-Name>${bundle.name}</Bundle-Name>
          <Private-Package>${bundle.namespace}.internal.*,${bundle.namespace}.impl.*</Private-Package>
          <Export-Package>${bundle.namespace}</Export-Package>
          <Bundle-Activator>${bundle.namespace}.internal.CyActivator</Bundle-Activator>

          <Embed-Dependency>*;scope=!provided|test;groupId=!org.cytoscape</Embed-Dependency>
          <Embed-Transitive>true</Embed-Transitive>
          <Import-Package>*;resolution:=optional</Import-Package>
        </instructions>
      </configuration>
    </plugin>
  </plugins>
</build>
}}}

The most important lines are the `Embed-Dependency`, `Embed-Transitive`, and `Import-Package` directives.

=== Update the scope for Cytoscape & OSGi API dependencies ===

Set the scope to `provided` for all Cytoscape and OSGi API dependencies, like so:
{{{
<dependency>
  <groupId>org.osgi</groupId>
  <artifactId>org.osgi.core</artifactId>
  <version>4.2.0</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>org.cytoscape</groupId>
  <artifactId>service-api</artifactId>
  <version>${cytoscape.api.version}</version>
  <scope>provided</scope>
</dependency>
}}}

This will tell the `maven-bundle-plugin` to not include the Cytoscape and OSGi API dependencies with your bundle jar. Your app won't obviously need them when loaded with Cytoscape.

=== Mark your third party library dependencies as optional ===

Mark your third party library dependencies as optional, like so:

{{{
<dependency>
  <groupId>org.apache.commons</groupId>
  <artifactId>com.springsource.org.apache.commons.httpclient</artifactId>
  <version>3.1.0</version>
  <optional>true</optional>
</dependency>
}}}

This tells OSGi that packages needed by transitive dependencies do not need to be fulfilled for your app to work.

At this point you should be able to run `mvn clean install` successfully and get an OSGi bundle app with your third party library dependencies included.

== Tips ==

=== Ensure that library dependencies were included ===

After building your app, you can see if all the libraries you expect were included by running this command:
{{{
unzip -l target/MyApp.jar | grep jar
}}}
This command will print out the names of all libraries included in your app.

=== Debugging your app ===

If your app won't load in Cytoscape, you should see first if the issue is OSGi related. To do so:

 1. Run Cytoscape from the command line.
 1. After Cytoscape has started, the command line will have an OSGi prompt. Run the `osgi:list` command. This will print out all bundles and their ID  numbers. If your app bundle's status is `Active`, that means OSGi was successfully able to load your app.
 1. If OSGi could not load your app, try reloading it: `osgi:reload <id-number>`. This will print an error message explaining the underlying problem.
 1. Try the `osgi:headers <id-number>` command. This will print out a list of all packages your app expects and whether the package requirement was met.