BUG Community

Usually you will want to interact with your BUG application using a GUI, a web service, or an interface provided by a module. But sometimes you want to be able to tell an app to do something without having to create a UI or a web service. The OSGi console provides an easy way to talk to a running app, or any other OSGi bundle. This document will explain how provide new commands that can be run from the OSGi console.

The OSGi console provides a way to interact with bundles in a running OSGi system. Bundles can be installed, started, stopped, removed, queried for things like their dependencies or the services they provide. There's a tutorial on the wiki that goes into some detail about accessing and interacting with the console. To see a list of the commands that are available, connect to the OSGi console and type "help" at the prompt. The list shows the name of the command, its usage, and a brief description. It will look something like this:

          (: help
          Command Usage____________________________Description___________________________________________________________________________
          bundles [filter]                         Returns a list of bundles present in current OSGi runtime environment.                
          consumers [(bundle id | bundle name)]... Returns a list of services that each bundle consumes is currently consuming.          
          disconnect                               Disconnect the shell.                                                                 
          exit                                     Stop all bundles and shutdown OSGi runtime.                                                                                                      
          gc                                       Collects the JVM garbage.                                                             
          getprop property_name                    Print the value of an OSGi property.  These properties are provided by BundleContext. 
          headers bundleId                         Returns the headers for a given bundle.                                               
          help  [filter]                           Print table of currently available commands.                                          
          install bundle_URL                       Install a bundle from the given URL.                                                  
          listen  [on|off]                         Enable or disable the console log listener.                                           
          package imports | exports [filter]       Returns a list of packages exported or imported in current OSGi runtime environment.  
          printenv  [filter]                       Returns the system settings.                                                          
          printlog  [filter]                       Displays log messages.                                                                
          producers [(bundle id | bundle name)]... Returns a list of services that each bundle is currently offering.                    
          quit                                     Stop the shell bundle.                                                                
          re [index | ?]                           Re-execute a previous command or display command history with '?' parameter.          
          services [Object Class Filter]...        Returns a list of services present in the runtime.                                    
          ss [filter]                              Returns a short summary of bundles present in current OSGi runtime environment.       
          start (bundle_Id | bundle_name)...       Starts the specified bundle.                                                          
          stop (bundle_Id | bundle_name)...        Stops the specified bundle.                                                           
          uninstall (bundle_Id | bundle_name)...   Uninstalls the specified bundle.                                                      
          update (bundle_Id | bundle_name)...      Updates the specified bundle. 
          
          

To add commands to the OSGi console, your program must create an object that implements the IShellCommandProvider interface and register that object as an OSGi service. The class that implements IShellCommandProvider has one method, called getCommands(), that returns a list of the commands that the service will provide. The commands themselves are described by objects that implement the ICommand interface. These objects provide information about each command, including its name, its usage, a description of what the command does, and a method that is called when the command is executed.

Here's a simple example of a class that implements ICommand. The command is called "helloworld", and it will log "hello world", followed by the number of times its initialize() and execute methods were called. It will also log any arguments that were passed to the command.

import java.io.OutputStream; import java.util.List; import java.util.ArrayList; import org.osgi.framework.BundleContext; import com.buglabs.osgi.shell.ICommand; import org.osgi.service.log.LogService; public class HelloWorldCommand implements ICommand { private int execs = 0; private int inits = 0; List args = null; @Override public void execute() { execs++; Activator.getLogger().log(LogService.LOG_INFO, "helloworld execs:" + execs + " inits:" + inits); for (Object a : args) { Activator.getLogger().log(LogService.LOG_INFO, a.toString()); } } @Override public String getDescription() { return "logs \"helloworld\" and stats"; } @Override public String getName() { return "helloworld"; } @Override public String getUsage() { return "[extra args]..."; } @Override public void initialize(List arguments, OutputStream out, OutputStream err, BundleContext context) { inits++; args = new ArrayList(arguments); } @Override public boolean isValid() { return true; } }

Here's a class that implements IShellCommandProvider and provides an instance of the ICommand from above.

import java.util.List; import java.util.ArrayList; import com.buglabs.osgi.shell.IShellCommandProvider; public class HelloWorldCommandProvider implements IShellCommandProvider { private List commands; @Override public List getCommands() { if (commands == null) { commands = new ArrayList() {{ add(new HelloWorldCommand()); }}; } return commands; } }

And finally, here's a bundle activator that will add the IShellCommandProvider from above to the running OSGi instance.

import java.util.List; import java.util.ArrayList; import java.io.OutputStream; import org.osgi.framework.BundleActivator; import org.osgi.framework.BundleContext; import com.buglabs.osgi.shell.IShellCommandProvider; import com.buglabs.osgi.shell.ICommand; import org.osgi.service.log.LogService; import com.buglabs.util.LogServiceUtil; public class Activator implements BundleActivator { private static LogService logger = null; private class HelloWorldCommand implements ICommand { private int execs = 0; private int inits = 0; List args = null; public void execute() { execs++; logger.log(LogService.LOG_INFO, "helloworld execs:" + execs + " inits:" + inits); for (Object a : args) { logger.log(LogService.LOG_INFO, a.toString()); } } public String getDescription() { return "logs \"helloworld\" and stats"; } public String getName() { return "helloworld"; } public String getUsage() { return "[extra args]..."; }; public void initialize(List arguments, OutputStream out, OutputStream err, BundleContext context) { inits++; args = new ArrayList(arguments); } public boolean isValid() { return true; } } public void start(BundleContext context) throws Exception { logger = LogServiceUtil.getLogService(context); context.registerService(IShellCommandProvider.class.getName(), new HelloWorldCommandProvider(), null); } public void stop(BundleContext context) throws Exception { } public static LogService getLogger() { return logger; } }

You will need to make sure that your manifest file includes com.buglabs.osgi.shell, com.buglabs.util, and org.osgi.service.log.

HelloWorldCommandExample is a working app that uses this example code. Once you put it on a BUG (or the BUG simulator), you can go to the OSGi console and type "help" to see the "helloworld" command listed. You can then type "helloworld a b c" to see it run. When you run it you will see something like this:

          (: helloworld a b c
          03/21 10:42:25:841	 INFO   	 helloworld  execs:1 inits:1	 
          03/21 10:42:25:847	 INFO   	 a	 
          03/21 10:42:25:857	 INFO   	 b	 
          03/21 10:42:25:866	 INFO   	 c
          
          

• osgi