<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>Quick Start for NetBeans Platform with OSGi</title>
        <link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css"/>
        <meta name="AUDIENCE" content="NBUSER"/>
        <meta name="TYPE" content="ARTICLE"/>
        <meta name="EXPIRES" content="N"/>
        <meta name="indexed" content="y"/>
        <meta name="description"
              content="A short guide to getting started with the NetBeans Platform."/>
      <!--      Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. -->
        <!--     Use is subject to license terms.-->
    </head>
    <body>

        <h1>NetBeans Platform Quick Start Using OSGi</h1>

        <p>This document is a quick demonstration of how to integrate OSGi
            bundles in a NetBeans Platform application.
        </p>

        <p>
            The focus of the tutorial is a "hello world" scenario based on the <a href="http://www.aqute.biz/Code/Download#sudoku">Sudoku Game
            by Peter Kriens</a>. You import the OSGi bundles constituting the Sudoku Game,
            together with the related required Equinox bundles. When the application is
            deployed, the following application is available in the web browser:
        </p>

        <p><img width="400" height="300" src="http://netbeans.dzone.com/sites/all/files/sudokugame-4.png"/></p>

        <p>Once you have gone through this simple scenario, more useful scenarios
            are listed in the Further Reading section at the end of this tutorial.</p>

        <p><b>Contents</b></p>
        <p><img src="../images/articles/69/netbeans-stamp69.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 6.5, 6.7, 6.8" title="Content on this page applies to NetBeans IDE 6.5, 6.7, 6.8"/></p>
        <ul class="toc">
            <li><a href="#setup">Setting Up the Environment</a></li>
            <li><a href="#create">Creating the Application</a></li>
            <li><a href="#import">Importing the OSGi Bundles</a></li>
            <li><a href="#run">Running the Application</a></li>
            <li><a href="#further">Further Reading</a></li>
        </ul>

        <p><b>To follow this tutorial, you need the software and resources listed in the following table.</b></p>

        <table>
            <tbody>
                <tr>
                    <th class="tblheader" scope="col">Software or Resource</th>
                    <th class="tblheader" scope="col">Version Required</th>
                </tr>
                <tr>
                    <td class="tbltd1"><a href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td>
                    <td class="tbltd1">version 6.9</td>
                </tr>
                <tr>
                    <td class="tbltd1"><a href="http://java.sun.com/javase/downloads/index.jsp">Java Developer Kit (JDK)</a></td>
                    <td class="tbltd1">Version 6 or</td>
                </tr>
                <tr>
                    <td class="tbltd1"><a href="http://download.eclipse.org/equinox">Equinox</a></td>
                    <td class="tbltd1"></td>
                </tr>
                <tr>
                    <td class="tbltd1"><a href="http://www.aqute.biz/Code/Download#sudoku">Sudoku Game</a></td>
                    <td class="tbltd1"></td>
                </tr>
            </tbody>
        </table>

        <p><strong class="notes">Note:</strong> You do not need to download a separate version
            of the NetBeans Platform to develop applications for the NetBeans Platform.
            Typically, you develop the applications and modules in the NetBeans IDE and
            then only include the modules that are necessary to run the NetBeans Platform and your application.
        </p>


        <!-- ===================================================================================== -->

        <h2><a name="setup"></a>Setting Up the Environment</h2>
        <p>Aside from downloading the software listed above, you need to take some steps to
            prepare your environment, as described below.</p>

        <ol>

            <li>Create a new folder in your filesystem on disk.</li>
            <li>From the Equinox distribution, put the following into the folder:
                <ul><li>javax.servlet_xxx.jar</li>
                    <li>org.eclipse.equinox.ds_xxx.jar</li>
                    <li>org.eclipse.equinox.http_xxx.jar</li>
                    <li>org.eclipse.equinox.util_xxx.jar</li>
                    <li>org.eclipse.osgi.services_xxx.jar</li>
                    <li>org.eclipse.osgi_xxx.jar</li></ul>

            </li>
            <li>Put the two Sudoku JARs into the folder, where the JARs above are found:
                <ul><li>aQute.sudoku.jar</li>
                    <li>aQute.webrpc.jar</li></ul>
            </li>
        </ol>

        <p>Now you have the OSGi bundles you will import available in a centralized location,
            from where you will integrate them into your application.</p>

        <h2><a name="create"></a>Creating the Application</h2>
        <p>Once you have all the required OSGi bundles available,
            create your new NetBeans Platform application, as described below.</p>

        <ol>
            <li><p>Choose File | New Project and choose to
                    create a NetBeans Platform application atop Equinox, via the Equinox template:</p>

                <p><img src="http://netbeans.dzone.com/sites/all/files/sudokugame-5.png"/></p>
                <p>Click Next.</p>
            </li>

            <li><p>Specify a name for the application, as shown below.</p>

                <p><img src="http://netbeans.dzone.com/sites/all/files/sudokugame-3.png"/></p>

                <p>Click Finish.</p></li>

            <li>You can run the application that results from the
                above template, you'll see an application containing a window,
                displaying all the NetBeans modules and OSGi bundles that make up your application.</li>

        </ol>

        <h2><a name="import"></a>Importing the OSGi Bundles</h2>
        <p>Aside from downloading the software listed above, you need to take some steps to
            prepare your environment, as described below.</p>


        <ol>
            <li><p>Right-click the application in the Projects window, choose Properties, go
                    to the Libraries tab, click "Add Cluster" and then browse to the folder
                    where the above JARs are found. Then a wizard opens that lets you convert
                    the JARs to a 'cluster', i.e., a set of related modules/bundles that will
                    be incorporated into your application:</p>

                <p><img src="http://netbeans.dzone.com/sites/all/files/sudokugame-1.png"/></p></li>

            <li>As shown above, set all imported OSGi bundles to "Enabled", so that they will
                be loaded and available at the time the application starts.</li>

            <li>When you click Finish, the "platform.properties"
                configuration file will have been updated.
                It should look something like this:

                <pre class="examplecode">cluster.path.extra=netbinox:\../../path/to/my/nbsudokugame/folder
disabled.modules.extra=org.netbeans.libs.felix
cluster.path=\
    ${nbplatform.active.dir}/harness:\
    ${nbplatform.active.dir}/platform:\
    ${cluster.path.extra}
disabled.modules=\
    org.jdesktop.layout,\
    org.netbeans.api.visual,\
    org.netbeans.core.execution,\
    org.netbeans.core.multiview,\
    org.netbeans.insane,\
    org.netbeans.libs.felix,\
    org.netbeans.libs.jsr223,\
    org.netbeans.modules.apisupport.harness,\
    org.netbeans.modules.apisupport.tc.cobertura,\
    org.netbeans.modules.autoupdate.services,\
    org.netbeans.modules.autoupdate.ui,\
    org.netbeans.modules.core.kit,\
    org.netbeans.modules.favorites,\
    org.netbeans.modules.jellytools.platform,\
    org.netbeans.modules.jemmy,\
    org.openide.compat,\
    org.openide.execution,\
    org.openide.options,\
    org.openide.util.enumerations
nbplatform.active=default</pre>


                <p><b>Note:</b> The first line above points to the folder you created earlier.</p></li>

            <li>Then add this line to the "project.properties" configuration file of the application,
                which specifies that no splash screen will be shown
                and the port for deployment of the application:

                <pre class="examplecode">run.args.extra=--nosplash -J-Dorg.osgi.service.http.port=8080</pre></li>
        </ol>

        <h2><a name="run"></a>Running the Application</h2>

        <p>The application is now ready to be deployed, as described below.</p>

        <ol>

            <li><p>Run the application! All the OSGi bundles and NetBeans modules in your application
                will be deployed. The application for viewing the deployed OSGi bundles and NetBeans
                modules is deployed too, giving you a desktop application to monitor what is
                currently deployed, which is quite handy:</p>

                <p><img src="http://netbeans.dzone.com/sites/all/files/sudokugame-6_0.png"/></p>

            <p>Alternatively, delete the whole module that provides the window above. Then remove all
                the modules that are required by the above window, i.e., remove the window system,
                actions system, and everything else... except for the few JARs required by the OSGi
                integration: bootstrap, startup, filesystems, module system, utilities, and lookup.
            </p>

            <pre class="examplecode">cluster.path.extra=netbinox:\../../path/to/my/nbsudokugame/folder
disabled.modules.extra=org.netbeans.libs.felix
cluster.path=\
    ${nbplatform.active.dir}/harness:\
    ${nbplatform.active.dir}/platform:\
    ${cluster.path.extra}
disabled.modules=\
    org.jdesktop.layout,\
    org.netbeans.api.annotations.common,\
    org.netbeans.api.progress,\
    org.netbeans.api.visual,\
    org.netbeans.core,\
    org.netbeans.core.execution,\
    org.netbeans.core.io.ui,\
    org.netbeans.core.multiview,\
    org.netbeans.core.nativeaccess,\
    org.netbeans.core.output2,\
    org.netbeans.core.ui,\
    org.netbeans.core.windows,\
    org.netbeans.insane,\
    org.netbeans.libs.felix,\
    org.netbeans.libs.jna,\
    org.netbeans.libs.jsr223,\
    org.netbeans.libs.junit4,\
    org.netbeans.modules.apisupport.harness,\
    org.netbeans.modules.apisupport.tc.cobertura,\
    org.netbeans.modules.applemenu,\
    org.netbeans.modules.autoupdate.services,\
    org.netbeans.modules.autoupdate.ui,\
    org.netbeans.modules.core.kit,\
    org.netbeans.modules.editor.mimelookup,\
    org.netbeans.modules.editor.mimelookup.impl,\
    org.netbeans.modules.favorites,\
    org.netbeans.modules.javahelp,\
    org.netbeans.modules.jellytools.platform,\
    org.netbeans.modules.jemmy,\
    org.netbeans.modules.keyring,\
    org.netbeans.modules.masterfs,\
    org.netbeans.modules.nbjunit,\
    org.netbeans.modules.options.api,\
    org.netbeans.modules.options.keymap,\
    org.netbeans.modules.print,\
    org.netbeans.modules.progress.ui,\
    org.netbeans.modules.queries,\
    org.netbeans.modules.sendopts,\
    org.netbeans.modules.settings,\
    org.netbeans.modules.spi.actions,\
    org.netbeans.spi.quicksearch,\
    org.netbeans.swing.outline,\
    org.netbeans.swing.plaf,\
    org.netbeans.swing.tabcontrol,\
    org.openide.actions,\
    org.openide.awt,\
    org.openide.compat,\
    org.openide.dialogs,\
    org.openide.execution,\
    org.openide.explorer,\
    org.openide.io,\
    org.openide.loaders,\
    org.openide.nodes,\
    org.openide.options,\
    org.openide.text,\
    org.openide.util.enumerations,\
    org.openide.windows
nbplatform.active=default</pre>

            <p>Then you will have a non-GUI application, i.e., a server application, well suited for modular
                web development.</p></li>

            <li>Now put this URL in the browser (optionally, use URLDisplayer.getDefault() from
                the NetBeans UI Utilities API to open the browser at the required location
                programmatically) and the "index.html" defined within the Sudoku Game is deployed,
                displayed in the browser, and you can start playing the Suduko Game:

                <pre class="examplecode">http://localhost:8080/rpc/sudoku/index.html</pre></li>

        </ol>

        <p>Congratulations, you have integrated your first OSGi bundles into a NetBeans Platform application.</p>

        <h2><a name="further"></a>Further Reading</h2>

        <p>Now that you have completed the tutorial and understand the steps to take when you want
            to reuse an OSGi bundle in your NetBeans Platform application, take a look at these
            related documents and more
            advanced scenarios:</p>

        <ul>
            <li><a href="http://www.osgi.org/blog/2006_09_01_archive.html">Peter Kriens and the Sudoku Game</a></li>
            <li><a href="http://wiki.apidesign.org/wiki/NetbinoxTutorial">Jaroslav Tulach and Netbinox</a></li>
            <li>Toni Epple's OSGi/NetBeans <a href="http://eppleton.sharedhost.de/blog/?p=662">blog entry</a> and <a href="http://eppleton.sharedhost.de/blog/?s=Frankenstein%27s+IDE">presentation</a></li>
            <li>Gunnar Reinseth's NetBeans-EMF integration (<a href="http://eclipse.dzone.com/emf-on-netbeans-rcp">part 1</a>, <a href="http://eclipse.dzone.com/emf-on-netbeans-rcp-2">part 2</a>)</li>
            <li>Also read <a href="http://java.dzone.com/news/new-cool-tools-osgi-developers">New Cool Tools for OSGi Developers</a></li>
        </ul>

    </body>

</html>