netbeans.apache.org/src/old_content/content/tutorials/691/nbm-osgi-quickstart.adoc

// 
//     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.
//

= NetBeans Platform Quick Start Using OSGi
:jbake-type: platform_tutorial
:jbake-tags: tutorials 
:jbake-status: published
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:icons: font
:experimental:
:description: NetBeans Platform Quick Start Using OSGi - Apache NetBeans
:keywords: Apache NetBeans Platform, Platform Tutorials, NetBeans Platform Quick Start Using OSGi

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

The focus of the tutorial is a "hello world" scenario based on the  link:http://www.aqute.biz/Code/Download#sudoku[Sudoku Game by Peter Kriens]. 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:


image::http://netbeans.dzone.com/sites/all/files/sudokugame-4.png[]

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







NOTE:  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.


== Setting Up the Environment

Aside from downloading the software listed above, you need to take some steps to prepare your environment, as described below.


[start=1]
1. Create a new folder in your filesystem on disk.

[start=2]
1. From the Equinox distribution, put the following into the folder:
* javax.servlet_xxx.jar
* org.eclipse.equinox.ds_xxx.jar
* org.eclipse.equinox.http_xxx.jar
* org.eclipse.equinox.util_xxx.jar
* org.eclipse.osgi.services_xxx.jar
* org.eclipse.osgi_xxx.jar

[start=3]
1. Put the two Sudoku JARs into the folder, where the JARs above are found:
* aQute.sudoku.jar
* aQute.webrpc.jar

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


== Creating the Application

Once you have all the required OSGi bundles available, create your new NetBeans Platform application, as described below.


[start=1]
1. Choose File | New Project and choose to create a NetBeans Platform application atop Equinox, via the Equinox template:


image::http://netbeans.dzone.com/sites/all/files/sudokugame-5.png[]

Click Next.


[start=2]
1. Specify a name for the application, as shown below.


image::http://netbeans.dzone.com/sites/all/files/sudokugame-3.png[]

Click Finish.


[start=3]
1. 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.


== Importing the OSGi Bundles

Aside from downloading the software listed above, you need to take some steps to prepare your environment, as described below.


[start=1]
1. 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:


image::http://netbeans.dzone.com/sites/all/files/sudokugame-1.png[]


[start=2]
1. As shown above, set all imported OSGi bundles to "Enabled", so that they will be loaded and available at the time the application starts.

[start=3]
1. When you click Finish, the "platform.properties" configuration file will have been updated. It should look something like this:

[source,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
----

NOTE:  The first line above points to the folder you created earlier.


[start=4]
1. 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:

[source,java]
----

run.args.extra=--nosplash -J-Dorg.osgi.service.http.port=8080
----


== Running the Application

The application is now ready to be deployed, as described below.


[start=1]
1. 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:


image::http://netbeans.dzone.com/sites/all/files/sudokugame-6_0.png[]

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.


[source,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
----

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


[start=2]
1. 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:

[source,java]
----

http://localhost:8080/rpc/sudoku/index.html
----

Congratulations, you have integrated your first OSGi bundles into a NetBeans Platform application.


== Further Reading

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:

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