Hello, OSGi!

Overview

This section shows an OSGi variant of running the Hello, world!. You need at least Version 3.7.1 of Eclipse to run it. If you have Eclipse already installed, check the "About Eclipse" box.

The example consists of the following steps:

  • Install the Cumulocity client libraries as OSGi runtime in Eclipse.
  • Configure an OSGi plugin project in Eclipse for your agent.
  • Write the agent code.
  • Run the agent.

Install the client libraries

Here are the steps for configuring Eclipse and downloading the required client software:

  • Go to the "Preferences" menu and select "Plug-in Development", "Target Platform". Click "Add...".
  • Ensure that "Nothing: Start with an empty target definition." is selected and click "Next". Type "Cumulocity runtime" into the "Name" field. Click "Add...".
  • Select "Software Site" and click "Next".
  • To make the Cumulocity runtime repository available, click "Add...", use "Cumulocity repository" as "Name" and "http://download.cumulocity.com/p2/repository" as "Location". Click "Ok".
  • Ensure that the "Cumulocity repository" is selected in the "Work with" drop-down list. Check "Cumulocity" and click "Finish". Select "Finish" again to leave the dialog. Now check the "Cumulocity runtime" entry in the "Target definitions" list and click "Ok".
  • This procedure has to be carried out once per Eclipse workspace.

Cumulocity configured as OSGi runtime

Please do not use "Install New Software" to download the client software. This would install the client as part of your running IDE. Install the SDK target platforms separately using the "Target Platform" preferences as described above.

If you would like to install a particular version of the Cumulocity OSGi runtime, please use http://download.cumulocity.com/p2/repository-version (replace "version" with the actual version, e.g., "5.9.0").

Set up an agent project

Select "New", "Project", "Plug-in Project". Use, for example, "c8y.helloagent" as project name, check "an OSGi framework", click "Next" and "Finish". (Click "Yes" to change perspective if asked.)

The manifest editor opens up. Click on the "Dependencies" tab and use the rightmost "Add" button under "Imported Packages" to add the following dependencies.

  • c8y
  • com.cumulocity.rest.representation
  • com.cumulocity.rest.representation.inventory
  • com.cumulocity.sdk.client
  • com.cumulocity.sdk.client.inventory
  • com.cumulocity.model.authentication
  • org.slf4j
  • org.svenson

Save the manifest file.

Write the agent code

Select the Activator class in src/c8y.helloagent/Activator.java. Paste the following code into the "start" method, after any code auto-generated by Eclipse:

Platform platform = new PlatformImpl("<<your URL>>", new CumulocityCredentials("<<user>>", "<<password>>"));
InventoryApi inventory = platform.getInventoryApi();
ManagedObjectRepresentation mo = new ManagedObjectRepresentation();
mo.setName("Hello, OSGi!");
mo.set(new IsDevice());
mo = inventory.create(mo);
System.out.println("URL: " + mo.getSelf());

Replace "<<yourUrl>>", "<<yourUser>>" and "<<yourPassword>>" with your URL (e.g., "https://myurl.cumulocity.com"), username and password. Right-click in the editor and select "Source", "Organize Imports". For an explanation of what the code does, see the basic "Hello, world!".

Run the agent

Run your agent by right-clicking the "c8y.helloagent" project and select "Run as", "OSGi Framework". After a short while, you should see the URL of the created managed object on the console:

URL: https://<<your URL>>/inventory/managedObjects/<<ID>>

Got an error message? Check the troubleshooting section.

Improve the agent

Now that you have done your first step, check out the Section Developing Java client or examine the full examples.

Updating the software

If you need to update or re-load the client software, follow these steps:

  • Open the "Target Platform" page in preferences, select the "Cumulocity runtime" and click "Edit".
  • Select the link in the location list and click "Edit".
  • Select "Work with the list of software sites", select "Cumulocity repository" and click "Reload". Click "Ok", "Finish" and "Finish" again to leave the dialog.
  • Click "Reload" in the target platform list and "Ok" to leave the preferences dialog.
  • You may need to re-create your run configuration. I.e., go to "Run", "Run Configurations" and double-click "OSGi Framework" to create a new run configuration, if you have problems.