• Guide Tutorials Examples Services App notes Links FAQ Forum
  • Guide
    Tutorials
    Example Projects
    Documentation
    Service Catalog
    OSGi Specifications
    App Notes
    Where to Find Stuff
    Videos
    Known Issues
    Frequently Asked Questions
  • Prev Next

    This website and its associated repositories, are deprecated and no longer supported by the OSGi Alliance. Please visit https://enroute.osgi.org for the latest supported version of OSGi enRoute.

    This enRoute v2 archive site is kept for those who do not intend to use the latest version of OSGi enRoute. If you are new to OSGi enRoute, then please start with the latest OSGi enRoute.

    JAR Wrapping Tutorial

    This tutorial is under review. Feedback appreciated (PRs on Github)

    Thumbnail for Wrapping Tutorial

    OSGi developers face a challenge when using third-party libraries that are not supplied as OSGi bundles. Though an increasing number of libraries are available from their original sources as OSGi bundles, and a large number are available as wrapped OSGi bundles from external repositories, it is still sometimes necessary to build such a wrapper ourselves. This tutorial details an approach to OSGi bundle production using bnd/bndtools/gradle.

    In this quick start we learn how to wrap a JAR to become a Bundle. Wrapping a JAR means that we need add the required OSGi manifest headers but also design the contents of the bundle. Modularity is not about fences, modularity is about what you put inside those fences and what passages you allow. The bnd tool provides an overwhelming amount of instructions and features to create the Bundle you want; this tutorial tries to shine light on what forces are in play and what tools are available.

    This tutorial teaches the wrapping from the perspective of a Bndtools user. For any command line zealots this should not be too hard to map to vi since all we do is write a bnd.bnd file in Bndtools, which is also usable in for example Maven. The key advantage of Bndtools is that it shows you the missing packages interactively. If you want to stay on the command line, then you could take a look at bnd Wrapping.

    In the coming chapters it is assumed you have a workspace ready. If you’ve no clue what we’re talking about suggest you follow the Quick Start Tutorial first.

    A disclaimer. This wrapping tutorial is about learning to use wrapping bundles inside the OSGi enRoute tool chain, it is not about learning Java, Git, nor Eclipse. It is assumed that you have basic experience with these tools and that you have at least followed the Quick Start tutorial.

    If you’re just interested in the end result, you can look at the osgi.enroute.examples.wrapping.dom4j.adapter project.

    If you have any questions about this wrapping tutorial, please discuss them in the Forum.

    Sections

    Should You?Consider alternatives to wrapping a bundle yourself, realize you do incur a long term technical debt.
    StrategyHow do we go about wrapping a bundle? What are the forces?
    Creating the Initial ProjectSetup the project with DOM4J and make an initial cut
    Adding Missing DependenciesTo ensure proper versioning we need to add the dependencies on the -buildpath
    Static linking our Dependencies (Conditional Package)In our first attempt we statically link the imported packages recursively
    Handling Dependencies on OSGi BundlesWhen a dependency is already provided as a proper bundle we should probably not include it.
    Handling Optional DependenciesSometimes dependencies are optional because they are only used when the optional dependency is present.
    Ignoring DependenciesIn rare cases a dependency is never used and can then be ignored.
    Adding Extra PackagesSince the analysis is done by code not all packages that are required are found.
    Dynamic ReferencesThe code can depend on other code but this is not detected by the analysis
    ResourcesWhen the target bundle uses resources, like translations, these should also be copied with the -includeresource instruction.
    Adding Source CodeOSGi Bundles can contain the source code in OSGI-OPT/src, this is recognized by IDEs during debugging
    Warning, Private ReferencesPrivate references are references from an exported package to a private packages. Since they can cause grief, they need to be cleaned up.
    Versioning the PackagesThe hard part, what versions should the exported packages have?
    OSGi ContractsADVANCED. Sometimes OSGi Contracts can alleviate the versioning problem.
    Service Loader Services IntegrationADVANCED. The Java Service Loader uses a file in META-INF/services to load an implementation by its implemented interface. This requires some extra work in OSGi.
    LicensesWrapping creates a copy of other peoples work, we need to take a look at how to attribute their work.
    READMEBe a good citizen and add a README to your bundle so other people don't have to guess
    ConclusionShow the final bnd.bnd file

    End

    So, you’ve finished this wrapping tutorial! What’s next?

    Well, first, since we’re still in beta, we’d love feedback. Our most favorite feedback is a pull request on the documentation. As an early user you must have run into some rough edges, outright stupidities, or you had a brilliant idea. Just go to the OSGi enRoute repository on Github. Clone it in your own account, make your changes or additions, and send a pull request. We, and others like you, highly appreciate these kind of contributions.

    If you’ve become interested in what bnd can do for you, then you could look at the wrapping with bnd chapter in the bnd manual.

    However, running into real problems is the best way to learn a technology. If you run into problems, use the Forum to ask questions and get answers.


    Prev Next
    • Copyright © 2021 OSGi™ Alliance.