Eclipse Development

This page is intended for Java developers that work on Nepomuk Components using the Eclipse IDE.

Related

• VersionManagement
• DeclarativeServicesInOsgi
• ServletsInOsgi
• JspPagesInOsgi
• EclipseVisualEditor

If you have troubles, if you have worries:

• EclipseDevelopmentProblemsAndFixes

Getting started with Eclipse for Nepomuk

You need

• Eclipse 3.2 (or higher, such as 3.3)
• Subversion plugin for Eclipse
• Java 1.5

Add this SVN repository URL to Eclipse:

• https://dev.nepomuk.semanticdesktop.org/repos/trunk/java/

You need to check out two projects from SVN:

• org.semanticdesktop.nepomuk.server.product
• EclipseTargetPlatform2.0

Using the Eclipse Target Platform to run and develop Nepomuk

Now you got the essential projects to run and develop Nepomuk. EclipseTargetPlatform2.0 contains a complete installation of the Nepomuk Java components, it is a collection of OSGI bundles. You can theoretically run Nepomuk from this platform (but you can't because we removed a few files).

Target platform bundles are put into different folders:

• eclipse32 - Eclipse 3.2 platform itself.
• external - external dependencies, i.e. libraries that Nepomuk project uses without any modifications.
• shared - common Nepomuk components.
• server - Nepomuk components specific for server side.
• client - Nepomuk components specific for client (PSEW) side.

Three pre-selected sets are provided:

• server.target - include eclipse32, external, shared and server bundles. Use it for Nepomuk server development.
• client.target - include eclipse32, external, shared and client bundles. Use it for PSEW development.
• client-host.target - same as client.target, but using Eclipse platform provided with Eclipse IDE instead of bundles from Nepomuk SVN.

You now need to set Eclipse to use this platform for development and running Nepomuk.

In EclipseTargetPlatform2.0 project, double-click on server.target file, and then click on Make this target the current target platform:

Alternatively, you can go to Window > Preferences window, select Plug-in development > Target Platform. Specify location of target platform, for example EclipseTargetPlatform2.0/server/eclipse, and click Reload.

If target platform is changed later (for example, after updating from SVN), just go to the same configuration window and click Reload.

Start Nepomuk-OSGI

You should have now two projects in your workspace, and have the Eclipse TargetPlatform set to the right place. now start Nepomuk by

• double-click on the org.semanticdesktop.nepomuk.server.product file in the project of the same name
• click on Launch the product

Interact with Nepomuk-OSGI services

The console will show the OSGI console, something like this:

osgi> .... starting this and that ....
osgi>

If only the osgi> prompt shows up and no further initialization happens, check paths in the ETP2.0 project.

Enter some wise commands and see what happens:

osgi>start org.semanticdesktop.nepomuk.comp.rdfrepository
osgi>help
osgi>bundles

To see the SOAP services, go to this address in your webbrowser. If the XFIRE service started correctly, it will show you all registered SOAP objects and their WSDL files.

• http://localhost:8181/soap

Stopping Nepomuk-OSGI

go to the OSGI console and type this, to safely shutdown the OSGI runtime and close all services appropriately. System.exit() is bad for you.

osgi>close

If you want to change individual components you can checkout the bundles as projects, these will then take precedence over the bundles in the TargetPlatform? (if not, check the right boxes on the plugins tab of the run menu!)

Guides

Create a new Nepomuk Component

To create a nepomuk component using eclipse and OSGI, you need to create a plugin for the component code.

NOTE: Older version of this page also told you to create a feature, this is NOT necessary, and can be ignored.

Create a new Project using new... plugin development ... Plug-In Project.

Choose the default options:

For your first plug-in you can use this "Hello World!" template to get a working plug-in example:

As a last step add this new feature to the run configuration of the nepomuk product by ticking the box in the run config:

Don't forget to save all modifications before you continue.

When you now start the Nepomuk product, then the new plug-in will be existing in the OSGi framework:

osgi> status
...
167	update@.../eclipse-workspace-3.2/org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx/
  RESOLVED    org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx_1.0.0
...
osgi>

You can now start that plug-in manually by typing

osgi> start org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx
Hello World!!

osgi> status
...
167	update@.../eclipse-workspace-3.2/org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx/
  ACTIVE      org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx_1.0.0
...
osgi> stop org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx
Goodbye World!!

osgi> 

This plug-in was just started (the org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx.Activator.start(BundleContext) method was called by the OSGi framework).

This works well for testing your plugin on your own, if you want it to be available to other people you need to add it as a dependency to the nepomuk.server.feature.

If you also want your plug-in to be started on startup sequence, edit the config.ini file in the org.semanticdesktop.nepomuk.server.app project and like this:

...
osgi.bundles=...,\
 ...,\
 org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx@5:start,\
 ...
...

Which means that on startup level 5 this plug-in is started. Make sure your Run / Debug configuration has the "Clear the configuration are before launching" option checked. See "The Nepomuk product doesn't start at all" problem at the bottom of this page.

And then press the "Launch the product" button again and a new Run / Debug configuration will be generated by Eclipse automatically. The Nepomuk product now starts with the new configuration (config.ini).

Adding dependencies to other components

You need 3rd Party libraries? Like JUnit or logging? You use OSGI dependencies, don't copy/paste Jar files, they may all be here already. Your nepomuk component / eclipse plugin will have dependencies on other Nepomuk plugins and on other libraries like JUnit or logging. To add dependencies, don't use the "Project Properties, Build-Path, add Jar" options in the Java project. Use the manifest editor instead, opening the file

/META-INF/MANIFEST.MF

It will allow you to add bundle and package dependencies.

NEVER put jar libraries into your own OSGi bundles. Adding dependencies using Jars causes major problems when packaging the services, and unless you are 100% sure what you are doing, wrap external dependencies as OSGi bundles.

• see below at EclipseDevelopment#Bundlingexternaldependencies

It is recommended to use package imports, instead of bundle dependences. Mikhail and Leo propose the following rules:

• dependencies on bundles created by NEPOMUK should be defined as bundle imports. Example: Import-Bundle: org.semanticdesktop.services.
• dependencies on the third-party libraries (packaged as bundles) is better to put in package imports. Example: Import-Package: org.osgi.framework
• implementations of APIs should be accessed as services. You should not have dependencies on org.semanticdesktop.nepomuk.comp.rdfrepository but rather use the services bundle defining the interface and get the service implementation via the middleware.

So we distinguish between

• pure interface bundle: org.semanticdesktop.services (there is no implementations here!) - imported via bundle dependency
• third party package - a third party library like lucene, junit, servlets (javax.servlet) - imported via package dependency
• implementation bundles - contains implementations of interfaces defined in a pure interface bundle. All implemented services are registered in the OSGi platform. This implementation depends directly on the pure interface bundle via bundle dependence, may have additional imports using bundle or package dependency.
• client bundle - a client bundle; depends directly on the pure interface bundle; Access to the service implementation using OSGi. (So it contains no dependencies on implementation bundles)

One of situations where Require-Bundle is necessary is described here http://osdir.com/ml/ide.eclipse.equinox.devel/2006-03/msg00100.html

Also read http://www2.osgi.org/wiki/uploads/Conference/OSGiBestPractices.pdf It provides a lot of tips regarding using OSGi.

Re-exporting dependencies. A useful feature of OSGI is to re-export dependencies. When your plugin A uses the plugin X and its classes in its interface, users of your plugin A will need to also depend on X. To make it simpler, you can import X and "re-export" it, so that users automatically import X when importing A. There is a button for this in eclipse, when you click on a plugin dependency's options, this gets written to the manifest:

                            // RE-EXPORT
org.semweb4j.rdf2go.impl.base;visibility:=reexport,

Register Services / Provide Interfaces to other OSGi components using Activators

In order to provide services to other OSGi components you first need to define a Java interface (plug-in project org.semanticdesktop.services), as well as an implementation (plug-in project org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx):

package org.semanticdesktop.services.xxxxxxxxxxxxx;

@NepomukType(type="http://www.semanticdesktop.org/wsdl/YYYY/MM/DD/Xxxxxxxxxxxxx.wsdl")
@WebService(targetNamespace="http://semanticdesktop.org/services/xxxxxxxxxxxxx", name="Xxxxxxxxxxxxx")
public interface Xxxxxxxxxxxxx {
        public String echo(String msg);
}

Add this package to the list of "Exported Packages" under the "Runtime" area of the plug-in configuration.

package org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx;

import org.semanticdesktop.services.xxxxxxxxxxxxx.Xxxxxxxxxxxxx;

@WebService(targetNamespace="http://semanticdesktop.org/services/xxxxxxxxxxxxx", name="Xxxxxxxxxxxxx")
public class XxxxxxxxxxxxxImpl implements Xxxxxxxxxxxxx {
        public XxxxxxxxxxxxxImpl() { }
        public String echo(String msg) { return msg; }
}

Notice that you have to add the imported package to the "Imported Packages" list under the "Dependencies" area of the plug-in configuration. Now, in the "org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx" plug-in project an instance of this implementation will be provided to other OSGi components:

package org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

import org.semanticdesktop.services.xxxxxxxxxxxxx.Xxxxxxxxxxxxx;
import org.semanticdesktop.nepomuk.middleware.clientlibrary.osgi.OSGIRegistry;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Activator implements BundleActivator {
        private Xxxxxxxxxxxxx xxx = null;
        private final static Logger log = LoggerFactory.getLogger(Activator.class);
        private OSGIRegistry registry =null;

        public void start(BundleContext context) throws Exception {
                System.out.println("Hello World!!");

                xxx = new XxxxxxxxxxxxxImpl();

                ServiceReference sr = context.getServiceReference(OSGIRegistry.class.getName());
                if (sr==null) { 
                  log.error("Could not find Nepomuk Registry - aborting.");
                  throw new Exception("No Nepomuk registry found");
                }
                registry=(OSGIRegistry)context.getService(sr);

                registry.registerService(Xxxxxxxxxxxxx.class, xxx, "Xxxxxxxxxxxxx");            
        }
        
        public void stop(BundleContext context) throws Exception {
                System.out.println("Goodbye World!!");
        }
}

Start the Nepomuk product and see that this service is registered:

osgi> status
...
{org.semanticdesktop.nepomuk.comp.xxxxxxxxxxxxx.XxxxxxxxxxxxxImpl}={service.id=36}
...

osgi>

Now add a second plug-in (org.semanticdesktop.nepomuk.comp.yyyyyyyyyyyyy) and its feature (org.semanticdesktop.nepomuk.comp.yyyyyyyyyyyyy.feature) which wants to use this service:

package org.semanticdesktop.nepomuk.comp.yyyyyyyyyyyyy;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;

import org.semanticdesktop.services.xxxxxxxxxxxxx.Xxxxxxxxxxxxx;

public class Activator implements BundleActivator {
        public void start(BundleContext context) throws Exception {
                ServiceReference sr = context.getServiceReference(Xxxxxxxxxxxxx.class.getName());
                Xxxxxxxxxxxxx xxx = (Xxxxxxxxxxxxx)context.getService(sr);
                String e = xxx.echo("testing, if its working");
                System.out.println("received " + e);
        }

        public void stop(BundleContext context) throws Exception {
        }
}

In order to have this plug-in knowing about the interface Xxxxxxxxxxxxx you again need to add the imported package to the "Imported Packages" list under the "Dependencies" area of the plug-in configuration.

At this point make sure your Run / Debug configuration has the "Clear the configuration are before launching" option checked. See "The Nepomuk product doesn't start at all" problem at the bottom of this page.

There is another way to use services using "declarative services", but its not implemented yet in eclipse, so off-topic for us, it seems:

• DeclarativeServicesInOsgi

Exporting your Plugin

When you have finished writing your plugin, you have to export it to the EclipseTargetPlatform. Exporting includes compiling, packaging, and version numbers (this is all done automatically). The exporting step is important to get your plugin into the nightly build and to have it available as proper OSGi bundle.

read EclipseTargetPlatform about exporting your plugin.

Bundling external dependencies

Convert libraries into a plugin of its own, extracting all classes from the jar (or from several jars that make a library). Eclipse can do it using wizard at File > New > Project > Plug-in development > Plug-in from existing JAR archive. There are also other tools like Bnd http://www.aqute.biz/Code/Bnd. Besides, an OSGi bundle packaged as a jar without any embedded jars can still be used as a normal jar archive to use without Eclipse/OSGi.

You find many examples of such packaged libraries in our external folder in ETP.

More about NEPOMUK Development

Once you have Eclipse working, go back to the NepomukTutorial to learn about how to program with the services, fix bugs, create JSP pages, or develop your own services.

Problems and Fixes

Moved to separate wiki-page at EclipseDevelopmentProblemsAndFixes