blob: 56b4a0b81771d3dfdf8147f0c1204a4bcd5ffba9 [file] [log] [blame]
<!doctype html>
<html class="no-js" lang="en" dir="ltr">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title>NetBeans Platform Quick Start Using OSGi</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="NetBeans Platform Quick Start Using OSGi - Apache NetBeans">
<meta name="author" content="Apache NetBeans">
<meta name="description" content="NetBeans Platform Quick Start Using OSGi - Apache NetBeans">
<meta name="keywords" content="Apache NetBeans Platform, Platform Tutorials, NetBeans Platform Quick Start Using OSGi">
<meta name="generator" content="Apache NetBeans">
<link rel="stylesheet" href="../../../../_/css/font-awesome.min.css">
<link rel="alternate" type="application/atom+xml" title="Apache NetBeans Blog" href="https://netbeans.apache.org/blogs/atom" />
<link rel="stylesheet" href="../../../../_/css/highlightjs/default.min.css">
<link rel="stylesheet" href="../../../../_/css/netbeans.css">
<link rel="apple-touch-icon" sizes="180x180" href="../../../../_/images/fav/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="../../../../_/images/fav/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="../../../../_/images/fav/favicon-16x16.png">
<link rel="manifest" href="../../../../_/images/fav/site.webmanifest">
<link rel="mask-icon" href="../../../../_/images/fav/safari-pinned-tab.svg" color="#5bbad5">
<meta name="msapplication-TileColor" content="#ffc40d">
<meta name="theme-color" content="#ffffff">
<link href="../../../../_/css/font-open-sans.css" rel="stylesheet">
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
</head>
<body>
<div class="title-bar" data-responsive-toggle="responsive-menu" data-hide-for="medium">
<button type="button" data-toggle="responsive-menu"><i style='font-size: 32px; color: #fff; padding: 8px' class='fa fa-bars'></i></button>
<div class="title-bar-title">Apache NetBeans</div>
</div>
<div class="top-bar" id="responsive-menu">
<div class='top-bar-left'>
<a class='title' href="../../../../index.html"><img src='../../../../_/images/apache-netbeans.svg' style='padding: 8px; height: 48px;'> Apache NetBeans</a>
</div>
<div class="top-bar-right">
<ul class="vertical medium-horizontal menu" data-responsive-menu="drilldown medium-dropdown">
<li> <input id="search-input" type="text" placeholder="Search the docs"> </li>
<li> <a href="../../../../front/main/community">Community</a> </li>
<li> <a href="../../../../front/main/participate">Participate</a> </li>
<li> <a href="../../../../front/main/blogs">Blog</a></li>
<li> <a href="../../../../front/main/help">Get Help</a> </li>
<li> <a href="https://plugins.netbeans.apache.org/">Plugins</a> </li>
<li> <a href="../../../../front/main/download">Download</a> </li>
</ul>
</div>
</div>
<!-- src/templates/news -->
<section class="hero news alternate">
<div class='grid-container'>
<div class='cell'>
<div class="annotation">Latest release</div>
<h1>Apache NetBeans 27</h1>
<p><a class="button success" href="../../../../front/main/download/nb27">Download</a></p>
</div>
</div>
</section>
<div class='grid-container main-content tutorial'>
<h1 class="sect0">NetBeans Platform Quick Start Using OSGi</h1>
<div class="sectionbody">
<div class="admonitionblock note">
<table>
<tbody><tr>
<td class="icon"><i class="fa icon-note" title="Note"></i></td>
<td class="content">This tutorial needs a review.
You can <a href="https://github.com/apache/netbeans-antora-tutorials/edit/main/modules/ROOT/pages/tutorials/nbm-osgi-quickstart.adoc" title="Edit this tutorial in github">edit it in GitHub </a>
following these <a href="../../../../tutorial/main/kb/docs/contributing">contribution guidelines.</a></td>
</tr></tbody>
</table>
</div>
</div>
<div id="toc" class="toc">
<div id="toctitle"></div>
<ul class="sectlevel1">
<li><a href="#_setting_up_the_environment">Setting Up the Environment</a></li>
<li><a href="#_creating_the_application">Creating the Application</a></li>
<li><a href="#_importing_the_osgi_bundles">Importing the OSGi Bundles</a></li>
<li><a href="#_running_the_application">Running the Application</a></li>
<li><a href="#_further_reading">Further Reading</a></li>
</ul>
</div>
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This document is a quick demonstration of how to integrate OSGi bundles in a NetBeans Platform application.</p>
</div>
<div class="paragraph">
<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>
</div>
<div class="imageblock">
<div class="content">
<img src="../../_images/tutorials/sudokugame-4.png" alt="sudokugame 4">
</div>
</div>
<div class="paragraph">
<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>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_setting_up_the_environment"><a class="anchor" href="#_setting_up_the_environment"></a>Setting Up the Environment</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Aside from downloading the software listed above, you need to take some steps to prepare your environment, as described below.</p>
</div>
<div class="olist arabic">
<ol class="arabic" start="1">
<li>
<p>Create a new folder in your filesystem on disk.</p>
</li>
</ol>
</div>
<div class="olist arabic">
<ol class="arabic" start="2">
<li>
<p>From the Equinox distribution, put the following into the folder:</p>
<div class="ulist">
<ul>
<li>
<p>javax.servlet_xxx.jar</p>
</li>
<li>
<p>org.eclipse.equinox.ds_xxx.jar</p>
</li>
<li>
<p>org.eclipse.equinox.http_xxx.jar</p>
</li>
<li>
<p>org.eclipse.equinox.util_xxx.jar</p>
</li>
<li>
<p>org.eclipse.osgi.services_xxx.jar</p>
</li>
<li>
<p>org.eclipse.osgi_xxx.jar</p>
</li>
</ul>
</div>
</li>
</ol>
</div>
<div class="olist arabic">
<ol class="arabic" start="3">
<li>
<p>Put the two Sudoku JARs into the folder, where the JARs above are found:</p>
<div class="ulist">
<ul>
<li>
<p>aQute.sudoku.jar</p>
</li>
<li>
<p>aQute.webrpc.jar</p>
</li>
</ul>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<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>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_creating_the_application"><a class="anchor" href="#_creating_the_application"></a>Creating the Application</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Once you have all the required OSGi bundles available, create your new NetBeans Platform application, as described below.</p>
</div>
<div class="olist arabic">
<ol class="arabic" start="1">
<li>
<p>Choose File | New Project and choose to create a NetBeans Platform application atop Equinox, via the Equinox template:</p>
</li>
</ol>
</div>
<div class="imageblock">
<div class="content">
<img src="../../_images/tutorials/sudokugame-5.png" alt="sudokugame 5">
</div>
</div>
<div class="paragraph">
<p>Click Next.</p>
</div>
<div class="olist arabic">
<ol class="arabic" start="2">
<li>
<p>Specify a name for the application, as shown below.</p>
</li>
</ol>
</div>
<div class="imageblock">
<div class="content">
<img src="../../_images/tutorials/sudokugame-3.png" alt="sudokugame 3">
</div>
</div>
<div class="paragraph">
<p>Click Finish.</p>
</div>
<div class="olist arabic">
<ol class="arabic" start="3">
<li>
<p>You can run the application that results from the above template, you&#8217;ll see an application containing a window, displaying all the NetBeans modules and OSGi bundles that make up your application.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_importing_the_osgi_bundles"><a class="anchor" href="#_importing_the_osgi_bundles"></a>Importing the OSGi Bundles</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Aside from downloading the software listed above, you need to take some steps to prepare your environment, as described below.</p>
</div>
<div class="olist arabic">
<ol class="arabic" start="1">
<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>
</li>
</ol>
</div>
<div class="imageblock">
<div class="content">
<img src="../../_images/tutorials/sudokugame-1.png" alt="sudokugame 1">
</div>
</div>
<div class="olist arabic">
<ol class="arabic" start="2">
<li>
<p>As shown above, set all imported OSGi bundles to "Enabled", so that they will be loaded and available at the time the application starts.</p>
</li>
</ol>
</div>
<div class="olist arabic">
<ol class="arabic" start="3">
<li>
<p>When you click Finish, the "platform.properties" configuration file will have been updated. It should look something like this:</p>
</li>
</ol>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">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</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The first line above points to the folder you created earlier.
</td>
</tr>
</table>
</div>
<div class="olist arabic">
<ol class="arabic" start="4">
<li>
<p>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:</p>
</li>
</ol>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">run.args.extra=--nosplash -J-Dorg.osgi.service.http.port=8080</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_running_the_application"><a class="anchor" href="#_running_the_application"></a>Running the Application</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The application is now ready to be deployed, as described below.</p>
</div>
<div class="olist arabic">
<ol class="arabic" start="1">
<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>
</li>
</ol>
</div>
<div class="imageblock">
<div class="content">
<img src="../../_images/tutorials/sudokugame-6_0.png" alt="sudokugame 6 0">
</div>
</div>
<div class="paragraph">
<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&#8230;&#8203; except for the few JARs required by the OSGi integration: bootstrap, startup, filesystems, module system, utilities, and lookup.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">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</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then you will have a non-GUI application, i.e., a server application, well suited for modular web development.</p>
</div>
<div class="olist arabic">
<ol class="arabic" start="2">
<li>
<p>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:</p>
</li>
</ol>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">http://localhost:8080/rpc/sudoku/index.html</code></pre>
</div>
</div>
<div class="paragraph">
<p>Congratulations, you have integrated your first OSGi bundles into a NetBeans Platform application.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_further_reading"><a class="anchor" href="#_further_reading"></a>Further Reading</h2>
<div class="sectionbody">
<div class="paragraph">
<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>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="http://www.osgi.org/blog/2006_09_01_archive.html">Peter Kriens and the Sudoku Game</a></p>
</li>
<li>
<p><a href="http://wiki.apidesign.org/wiki/NetbinoxTutorial">Jaroslav Tulach and Netbinox</a></p>
</li>
<li>
<p>Toni Epple&#8217;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></p>
</li>
<li>
<p>Gunnar Reinseth&#8217;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>)</p>
</li>
<li>
<p>Also read <a href="http://java.dzone.com/news/new-cool-tools-osgi-developers">New Cool Tools for OSGi Developers</a></p>
</li>
</ul>
</div>
</div>
</div>
<section class='tools'>
<ul class="menu align-center">
<li><a title="Facebook" href="https://www.facebook.com/NetBeans"><i class="fa fa-md fa-facebook"></i></a></li>
<li><a title="Twitter" href="https://twitter.com/netbeans"><i class="fa fa-md fa-twitter"></i></a></li>
<li><a title="Github" href="https://github.com/apache/netbeans"><i class="fa fa-md fa-github"></i></a></li>
<li><a title="YouTube" href="https://www.youtube.com/user/netbeansvideos"><i class="fa fa-md fa-youtube"></i></a></li>
<li><a title="Atom Feed" href="https://netbeans.apache.org/blogs/atom"><i class="fa fa-mf fa-rss"></i></a></li>
<li><a title="Slack" href="https://tinyurl.com/netbeans-slack-signup/"><i class="fa fa-md fa-slack"></i></a></li>
<li><a title="Issues" href="https://github.com/apache/netbeans/issues"><i class="fa fa-mf fa-bug"></i></a></li>
</ul>
<ul class="menu align-center">
<li><a href="https://github.com/apache/netbeans-antora-tutorials/edit/main/modules/ROOT/pages/tutorials/nbm-osgi-quickstart.adoc" title="See this page in github"><i class="fa fa-md fa-edit"></i> See this page in GitHub.</a></li>
</ul>
</section>
</div>
<div class='grid-container incubator-area' style='margin-top: 64px'>
<div class='grid-x grid-padding-x'>
<div class='large-auto cell text-center'>
<a href="https://www.apache.org/">
<img style="height: 60px" title="Apache Software Foundation" src="../../../../_/images/asf_logo_wide.svg" />
</a>
</div>
<div class='large-auto cell text-center'>
<a href="https://www.apache.org/events/current-event.html">
<img style="width:234px; height: 60px;" title="Apache Software Foundation current event" src="https://www.apache.org/events/current-event-234x60.png"/>
</a>
</div>
</div>
</div>
<footer>
<div class="grid-container">
<div class="grid-x grid-padding-x">
<div class="large-auto cell">
<h1><a href="../../../../front/main/about">About</a></h1>
<ul>
<li><a href="../../../../front/main/community/who">Who's Who</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="https://www.apache.org/security/">Security</a></li>
</ul>
</div>
<div class="large-auto cell">
<h1><a href="../../../../front/main/community">Community</a></h1>
<ul>
<li><a href="../../../../front/main/community/mailing-lists">Mailing lists</a></li>
<li><a href="../../../../front/main/community/committer">Becoming a committer</a></li>
<li><a href="../../../../front/main/community/events">NetBeans Events</a></li>
<li><a href="https://www.apache.org/events/current-event.html">Apache Events</a></li>
</ul>
</div>
<div class="large-auto cell">
<h1><a href="../../../../front/main/participate">Participate</a></h1>
<ul>
<li><a href="../../../../front/main/participate/submit-pr">Submitting Pull Requests</a></li>
<li><a href="../../../../front/main/participate/report-issue">Reporting Issues</a></li>
<li><a href="../../../../front/main/participate/#documentation">Improving the documentation</a></li>
</ul>
</div>
<div class="large-auto cell">
<h1><a href="../../../../front/main/help">Get Help</a></h1>
<ul>
<li><a href="../../../../front/main/help/#documentation">Documentation</a></li>
<li><a href="../../../../wiki/main/wiki">Wiki</a></li>
<li><a href="../../../../front/main/help/#support">Community Support</a></li>
<li><a href="../../../../front/main/help/commercial-support">Commercial Support</a></li>
</ul>
</div>
<div class="large-auto cell">
<h1><a href="../../../../front/main/download">Download</a></h1>
<ul>
<li><a href="../../../../front/main/download">Releases</a></li>
<li><a href="https://plugins.netbeans.apache.org/">Plugins</a></li>
<li><a href="../../../../front/main/download/#_daily_builds_and_building_from_source">Building from source</a></li>
<li><a href="../../../../front/main/download/#_older_releases">Previous releases</a></li>
</ul>
</div>
</div>
</div>
</footer>
<div class='footer-disclaimer'>
<div class="footer-disclaimer-content">
<p>Copyright &copy; 2017-2025 <a href="https://www.apache.org">The Apache Software Foundation</a>.</p>
<p>Licensed under the Apache <a href="https://www.apache.org/licenses/">license</a>, version 2.0</p>
<div style='max-width: 40em; margin: 0 auto'>
<p>Apache, Apache NetBeans, NetBeans, the Apache feather logo and the Apache NetBeans logo are trademarks of <a href="https://www.apache.org">The Apache Software Foundation</a>.</p>
<p>Oracle and Java are registered trademarks of Oracle and/or its affiliates.</p>
<p>The Apache NetBeans website conforms to the <a href="https://privacy.apache.org/policies/privacy-policy-public.html">Apache Software Foundation Privacy Policy</a></p>
</div>
</div>
</div>
<script src="../../../../_/js/vendor/lunr.js"></script>
<script src="../../../../_/js/search-ui.js" id="search-ui-script" data-site-root-path="../../../.." data-snippet-length="100" data-stylesheet="../../../../_/css/search.css"></script>
<script async src="../../../../search-index.js"></script>
<script src="../../../../_/js/vendor/jquery.min.js"></script>
<script src="../../../../_/js/vendor/what-input.min.js"></script>
<script src="../../../../_/js/vendor/foundation.min.js"></script>
<script src="../../../../_/js/vendor/jquery.colorbox-min.js"></script>
<script src="../../../../_/js/netbeans.js"></script>
<script>
$(function(){ $(document).foundation(); });
</script>
<script src="../../../../_/js/vendor/highlight.min.js"></script>
<script>
document.addEventListener('DOMContentLoaded', (event) => {
document.querySelectorAll('pre code').forEach((el) => {
hljs.highlightElement(el);
});
});
</script>
</body>
</html>