Apache Felix Shell

...

• Overview
• How the Shell Service Works|
• How Commands Work
• Creating a Command
• Security and the Shell Service
• Feedback

Anchor
overview overview

Overview

...

The remainder of this document describes how the shell service works and how to create custom commands for it. 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.

How the Shell Service Works

The Felix 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 Felix 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:

...

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.

How Commands Work

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.ungovernedapache.osgi.servicefelix.shell;

public interface Command
{
    public String getName();
    public String getUsage();
    public String getShortDescription();
    public void execute(String line, PrintStream out, PrintStream err);
}

...

• getName() - returns the name of the command; this must not contain whitespace and must be unique.
• getUsage() - returns the usage string of the command; this should be one line and as short as possible (this is used for generating the help command output).
• getShortDescription() - returns a short description of the command; this should be one line and as short as possible (this is used for generating the help command output).
• execute() - executes the command's functionality using supplied command line and print streams.

Creating a Command

The following example creates a simple version of the start command.

...

To compile these classes you will need to have the framework.jar file org.apache.felix.framework-x.y.z.jar and org.apache.felix.shell-x.y.z.jar on your class path. Compile all of the source files using a command like:

java -cp org.apache.felix.framework-1.8.1.jar:org.apache.felix.shell-1.2.0.jar -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.apache.felix.shell,org.osgi.framework

To create the bundle JAR file, issue the command:

...

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 Felix and install and start the bundle created by the above command. By doing so, the new mystart command is made available via the shell service.

Security and 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 the corresponding service permission. Security handling may change in future release after some experience is gained through usage.

Feedback

Subscribe to the Felix users mailing list by sending a message to users-subscribe@felix.apache.org; after subscribing, email questions or feedback to users@felix.apache.org.