In order to interact with Oscar, it is necessary to have some sort of interactive shell that allows you to issue commands to the framework and to obtain information from it. The OSGi specification does not define how an OSGi framework should provide this interactivity. Oscar defines a shell service for creating and executing arbitrary commands. The shell service does not define a user interface, only a service API.
The benefit of the Oscar shell service approach is that it is possible to:
The remainder of this document describes how the shell service works and how to create custom commands for the shell service. This document does not describe how to use the command shell, nor does it describe the text-based or GUI-based user interfaces that are available for the shell service.
The Oscar shell service is intended to be a simple, but extensible shell service that can have multiple user interface implementations, all of which are independent from the Oscar framework. The shell service is currently not intended to be sophisticated, rather it is just a mechanism to execute commands. The shell service maintains a list of command services, each of which have a unique command name. The shell service is defined by the following service interface:
package org.ungoverned.osgi.service.shell;
public interface ShellService
{
public String[] getCommands();
public String getCommandUsage(String name);
public String getCommandDescription(String name);
public ServiceReference getCommandReference(String name);
public void executeCommand(
String commandLine, PrintStream out, PrintStream err)
throws Exception;
}
Using the shell service interface, it is possible to access and execute available commands. The shell service methods perform the following functions:
Most of the shell service methods require no explanation except for the executeCommand() method. Even though this method is the most complex, it is still fairly simplistic. The assumption of the shell service is that a command line will be typed by the user (or perhaps constructed by a GUI) and passed into it for execution. The shell service interprets the command line in a very simplistic fashion; it takes the leading string of characters terminated by a space character (not including it) and assumes that this leading token is the command name. Consider the following command line:
update 3 http://www.foo.com/bar.jar
The shell service interprets this as an update command and will search for a command service with the same name. If a corresponding command service is not found, then it will print an error message to the error print stream. If a corresponding command service is found, then it will pass the entire command line string and the print streams into the executeCommand() method of the command service (for a more detailed description of command services, see the next section).
Notice that there is no method to add commands to the shell service interface. This is because commands are implemented as OSGi services and the shell service listens for service events and when a command service registers/unregisters it automatically updates its list of commands accordingly.
All commands available in the shell service are implemented as OSGi services. The advantage of this approach is two-fold: the shell service can leverage OSGi service events to maintain its list of available commands and the set available commands is dynamically extendable by installed bundles. The command service interface is defined as follows:
package org.ungoverned.osgi.service.shell;
public interface Command
{
public String getName();
public String getUsage();
public String getShortDescription();
public void execute(String line, PrintStream out, PrintStream err);
}
The semantics of the command service methods are:
The following example creates a simple version of the start command.
package test;
import java.io.PrintStream;
import java.net.URL;
import java.net.MalformedURLException;
import java.util.StringTokenizer;
import org.osgi.framework.*;
import org.ungoverned.osgi.service.shell.ShellService;
import org.ungoverned.osgi.service.shell.Command;
public class MyStartCommandImpl implements Command
{
private BundleContext m_context = null;
public MyStartCommandImpl(BundleContext context)
{
m_context = context;
}
public String getName()
{
return "mystart";
}
public String getUsage()
{
return "mystart <id> [<id> ...]";
}
public String getShortDescription()
{
return "start bundle(s).";
}
public void execute(String s, PrintStream out, PrintStream err)
{
StringTokenizer st = new StringTokenizer(s, " ");
// Ignore the command name.
st.nextToken();
// There should be at least one bundle id.
if (st.countTokens() >= 1)
{
while (st.hasMoreTokens())
{
String id = st.nextToken().trim();
try {
long l = Long.valueOf(id).longValue();
Bundle bundle = m_context.getBundle(l);
if (bundle != null)
{
bundle.start();
}
else
{
err.println("Bundle ID " + id + " is invalid.");
}
} catch (NumberFormatException ex) {
err.println("Unable to parse id '" + id + "'.");
} catch (BundleException ex) {
if (ex.getNestedException() != null)
err.println(ex.getNestedException().toString());
else
err.println(ex.toString());
} catch (Exception ex) {
err.println(ex.toString());
}
}
}
else
{
err.println("Incorrect number of arguments");
}
}
}
A bundle activator class is needed for packaging the command servce; the bundle activator registers the command service in its start() method. Note: You do not need one activator per command, a single activator can register any number of commands.
package test;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
public class MyStartActivator implements BundleActivator
{
private transient BundleContext m_context = null;
public void start(BundleContext context)
{
m_context = context;
// Register the command service.
context.registerService(
org.ungoverned.osgi.service.shell.Command.class.getName(),
new MyStartCommandImpl(m_context), null);
}
public void stop(BundleContext context)
{
// Services are automatically unregistered so
// we don't have to unregister the factory here.
}
}
To compile these classes you will need to have the oscar.jar and osgi.jar files included on your class path. Compile all of the source files using a command like:
java -d c:\classes *.java
This command compiles all of the source files and outputs the generated class files into a subdirectory of the c:\classes directory, called test, named after the package of the source files; for the above command to work, the c:\classes directory must exist. Once you have compiled all of the above classes, you need to create a bundle JAR file of the generated package directory. The bundle JAR file needs a manifest, so create a file called manifest.mf with the following contents:
Bundle-Name: My Start Command Bundle-Description: A 'start' command for the shell service. Bundle-Activator: test.MyStartActivator Bundle-ClassPath: . Import-Package: org.ungoverned.osgi.service.shell
To create the bundle JAR file, issue the command:
jar cfm mystart.jar manifest.mf -C c:\classes test
This command creates a JAR file using the manifest you created and includes all of the classes in the test directory inside of the c:\classes directory. Once the bundle JAR file is created, you are ready to add the command service to the shell service; simply start Oscar an install and start the bundle created by the above command. By doing so, the new mystart command is made available via the shell service.
The shell service security handling is quite simple, all security is handled by the standard OSGi framework mechanisms. For example, if a bundle should not be able to register a shell service, then it should not be given permission to import the org.ungoverned.oscar.service.shell package. Security handling may change in future release after some experience is gained through usage.
If you have comments or suggestions, feel free to contact me at heavy@ungoverned.org.
Richard S. Hall