Google Git
Sign in
apache / felix-site-pub / 126f1d6ae7aec6a8c1b81d684e2e4c9a0c3f3b3e / . / documentation / subprojects / apache-felix-shell.html
blob: 7f684c982f6f7bc5bf8d02df694c7f24c3f84170 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Apache Felix Shell :: Apache Felix</title>
<link rel="canonical" href="https://felix.apache.org/documentation/subprojects/apache-felix-shell.html">
<meta name="generator" content="Antora 2.3.4">
<link rel="stylesheet" href="../../_/css/site.css">
<link rel="icon" href="../../_/img/favicon.png" type="image/x-icon">
</head>
<body class="article">
<header class="header">
<nav class="navbar">
<div class="navbar-brand">
<a class="navbar-item" href="https://felix.apache.org/index.html">
<span>
<img src="../../_/img/logo.png">
</span>
</a>
<button class="navbar-burger" data-target="topbar-nav">
<span></span>
<span></span>
<span></span>
</button>
</div>
<div id="topbar-nav" class="navbar-menu">
<div class="navbar-end">
<a class="navbar-item" href="https://felix.apache.org/index.html">Home</a>
<div class="navbar-item has-dropdown is-hoverable">
<a class="navbar-link" href="#">Subprojects</a>
<div class="navbar-dropdown">
<a class="navbar-item" href="apache-felix-dependency-manager.html">Dependency Manager</a>
<a class="navbar-item" href="apache-felix-event-admin.html">Event Admin</a>
<a class="navbar-item" href="apache-felix-file-install.html">File Install</a>
<a class="navbar-item" href="apache-felix-framework.html">Framework</a>
<a class="navbar-item" href="apache-felix-gogo.html">Gogo Shell</a>
<a class="navbar-item" href="apache-felix-healthchecks.html">Health Checks</a>
<a class="navbar-item" href="apache-felix-inventory.html">Inventory</a>
<a class="navbar-item" href="apache-felix-log.html">Log</a>
<a class="navbar-item" href="apache-felix-logback.html">Logback</a>
<a class="navbar-item" href="apache-felix-maven-bundle-plugin.html">Maven bundle plugin</a>
<a class="navbar-item" href="apache-felix-maven-scr-plugin.html">Maven SCR plugin</a>
<a class="navbar-item" href="apache-felix-metatype-service.html">Metatype Service</a>
<a class="navbar-item" href="apache-felix-preferences-service.html">Preferences Service</a>
<a class="navbar-item" href="apache-felix-remote-shell.html">Remote Shell</a>
<a class="navbar-item" href="apache-felix-script-console-plugin.html">Script console plugin</a>
<a class="navbar-item" href="apache-felix-shell.html">Lightweight shell</a>
<a class="navbar-item" href="apache-felix-shell-tui.html">Shell TUI</a>
<a class="navbar-item" href="apache-felix-web-console.html">Web Console</a>
</div>
</div>
<div class="navbar-item">
<span class="control">
<a class="button is-primary" href="../downloads.html">Downloads</a>
</span>
</div>
</div>
</div>
</nav>
</header>
<div class="body">
<div class="nav-container" data-component="documentation" data-version="master">
<aside class="nav">
<div class="panels">
<div class="nav-panel-menu is-active" data-panel="menu">
<nav class="nav-menu">
<h3 class="title"><a href="../index.html">Documentation</a></h3>
<ul class="nav-list">
<li class="nav-item" data-depth="0">
<ul class="nav-list">
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../documentation.html">Documentation</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../downloads.html">Downloads</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../getting-started.html">Getting Started</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../news.html">News</a>
</li>
<li class="nav-item" data-depth="1">
<button class="nav-item-toggle"></button>
<span class="nav-text">Community</span>
<ul class="nav-list">
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../community/project-info.html">Apache Felix Project Info</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../community/contributing.html">Contributing</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../community/projects-using-felix.html">Projects Using Felix</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="1">
<button class="nav-item-toggle"></button>
<span class="nav-text">Development</span>
<ul class="nav-list">
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../development/coding-standards.html">Coding Standards</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../development/dependencies-file-template.html">DEPENDENCIES file template</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../development/provisional-osgi-api-policy.html">Provisional OSGi API Policy</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../development/release-management-nexus.html">Release Management</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../development/site-how-to.html">Site How To</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../development/using-the-osgi-compliance-tests.html">Using the OSGi Compliance Tests</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="1">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../faqs.html">FAQS</a>
<ul class="nav-list">
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../faqs/apache-felix-bundle-plugin-faq.html">Apache Felix Bundle Plugin Frequently Asked Questions</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../faqs/apache-felix-scr-plugin-faq.html">Apache Felix SCR Plugin Frequently Asked Questions</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="1">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../subprojects.html">Subprojects</a>
<ul class="nav-list">
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="apache-felix-dependency-manager.html">Apache Felix Dependency Manager</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<button class="nav-item-toggle"></button>
<span class="nav-text">Guides</span>
<ul class="nav-list">
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/migrating-from-earlier-versions.html">Apache Felix Dependency Manager - Migrating from earlier versions</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/annotations.html">Dependency Manager - Annotations</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/background.html">Dependency Manager - Background</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/bundles-and-dependencies.html">Dependency Manager - Bundles and Dependencies</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/design-patterns.html">Dependency Manager - Design Patterns</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/development.html">Dependency Manager - Development</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/history.html">Dependency Manager - History</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/javadocs.html">Dependency Manager - JavaDocs</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/migrating-from-other-solutions.html">Dependency Manager - Migrating from other solutions.</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/performance-tuning.html">Dependency Manager - Performance Tuning</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/resources.html">Dependency Manager - Resource adapters</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/whatsnew.html">Dependency Manager - What&#8217;s new in version 4?</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/dm-lambda.html">Dependency Manager Lambda</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/guides/whatsnew-r15.html">What&#8217;s New in R15</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="3">
<button class="nav-item-toggle"></button>
<span class="nav-text">Reference</span>
<ul class="nav-list">
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/component-adapter.html">Dependency Manager - Adapter</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/component-aspect.html">Dependency Manager - Aspect</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/component-bundle-adapter.html">Dependency Manager - Bundle Adapter</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/dependency-bundle.html">Dependency Manager - Bundle Dependency</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/components.html">Dependency Manager - Components</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/dependency-configuration.html">Dependency Manager - Configuration Dependency</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/dependencies.html">Dependency Manager - Dependencies</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/external-links.html">Dependency Manager - External Links</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/component-factory-configuration-adapter.html">Dependency Manager - Factory Configuration Adapter Service</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/component-resource-adapter.html">Dependency Manager - Resource Adapter</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/dependency-resource.html">Dependency Manager - Resource Dependency</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/dependency-service.html">Dependency Manager - Service Dependency</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/service-scopes.html">Dependency Manager - Service Scopes</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/component-singleton.html">Dependency Manager - Singleton Component</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/thread-model.html">Dependency Manager - Thread Model</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/reference/dm-annotations.html">Dependency Manager Annotations</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="3">
<button class="nav-item-toggle"></button>
<span class="nav-text">Tutorials</span>
<ul class="nav-list">
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/tutorials/working-with-annotations.html">Dependency Manager - Annotations</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/tutorials/getting-started.html">Dependency Manager - Getting Started</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/tutorials/leveraging-the-shell.html">Dependency Manager - Leveraging the shell</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-dependency-manager/tutorials/sample-code.html">Dependency Manager sample projects</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-event-admin.html">Apache Felix Event Admin</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-file-install.html">Apache Felix File Install</a>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="apache-felix-framework.html">Apache Felix Framework</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<a class="nav-link" href="apache-felix-framework/apache-felix-framework-bundle-cache.html">Apache Felix Framework Bundle Cache</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="apache-felix-framework/apache-felix-framework-configuration-properties.html">Apache Felix Framework Configuration Properties</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="apache-felix-framework/apache-felix-framework-faq.html">Apache Felix Framework Frequently Asked Questions</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="apache-felix-framework/apache-felix-framework-launching-and-embedding.html">Apache Felix Framework Launching and Embedding</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="apache-felix-framework/apache-felix-framework-usage-documentation.html">Apache Felix Framework Usage Documentation</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-framework-security.html">Apache Felix Framework Security</a>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="apache-felix-gogo.html">Apache Felix Gogo</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<a class="nav-link" href="apache-felix-gogo/rfc-147-overview.html">RFC 147 Overview</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-healthchecks.html">Apache Felix Health Checks</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-inventory.html">Apache Felix Inventory Printer</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-log.html">Apache Felix Log</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-logback.html">Apache Felix Logback</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-maven-bundle-plugin-bnd.html">Apache Felix Maven Bundle Plugin (BND)</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-metatype-service.html">Apache Felix Metatype Service</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-osgi-bundle-repository.html">Apache Felix OSGi Bundle Repository (OBR)</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-preferences-service.html">Apache Felix Preferences Service</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-remote-shell.html">Apache Felix Remote Shell</a>
</li>
<li class="nav-item is-current-page" data-depth="2">
<a class="nav-link" href="apache-felix-shell.html">Apache Felix Shell</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="apache-felix-shell-tui.html">Apache Felix Shell TUI</a>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="apache-felix-web-console.html">Apache Felix Web Console</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<a class="nav-link" href="apache-felix-web-console/extending-the-apache-felix-web-console.html">Extending the Apache Felix Web Console</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="apache-felix-web-console/web-console-restful-api.html">Web Console RESTful API</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="apache-felix-web-console/web-console-security-provider.html">Web Console Security Provider</a>
</li>
<li class="nav-item" data-depth="3">
<button class="nav-item-toggle"></button>
<span class="nav-text">Extensions</span>
<ul class="nav-list">
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-web-console/extending-the-apache-felix-web-console/branding-the-web-console.html">Branding the Web Console</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-web-console/extending-the-apache-felix-web-console/providing-resources.html">Providing Resources</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-web-console/extending-the-apache-felix-web-console/providing-web-console-plugins.html">Providing Web Console Plugins</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-web-console/extending-the-apache-felix-web-console/web-console-logging.html">Web Console Logging</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="apache-felix-web-console/extending-the-apache-felix-web-console/web-console-output-templating.html">Web Console Output Templating</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="nav-item" data-depth="1">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../tutorials-examples-and-presentations.html">Tutorials</a>
<ul class="nav-list">
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-application-demonstration.html">Apache Felix Application Demonstration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial.html">Apache Felix OSGi Tutorial</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-faq.html">OSGi Frequently Asked Questions</a>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<span class="nav-text">OSGI Tutorial</span>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-1.html">Apache Felix Tutorial Example 1 - Service Event Listener Bundle</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-2.html">Apache Felix Tutorial Example 2</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-2b.html">Apache Felix Tutorial Example 2b</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-3.html">Apache Felix Tutorial Example 3</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-4.html">Apache Felix Tutorial Example 4</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-5.html">Apache Felix Tutorial Example 5</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-6.html">Example 6 - Spell Checker Service Bundle</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-7.html">Example 7 - Spell Checker Client Bundle</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-8.html">Example 8 - Spell Checker Service using Service Binder</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-9.html">Example 9 - Spell Checker Service using Declarative Services</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../license.html">Apache License 2.0</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../site-map.html">Site map</a>
</li>
</ul>
</li>
</ul>
</nav>
</div>
<div class="nav-panel-explore" data-panel="explore">
<div class="context">
<span class="title">Documentation</span>
<span class="version">master</span>
</div>
<ul class="components">
<li class="component is-current">
<span class="title">Documentation</span>
<ul class="versions">
<li class="version is-current is-latest">
<a href="../index.html">master</a>
</li>
</ul>
</li>
</ul>
</div>
</div>
</aside>
</div>
<main class="article">
<div class="toolbar" role="navigation">
<button class="nav-toggle"></button>
<a href="../index.html" class="home-link"></a>
<nav class="breadcrumbs" aria-label="breadcrumbs">
<ul>
<li><a href="../index.html">Documentation</a></li>
<li><a href="../subprojects.html">Subprojects</a></li>
<li><a href="apache-felix-shell.html">Apache Felix Shell</a></li>
</ul>
</nav>
<div class="edit-this-page"><a href="https://github.com/apache/felix-antora-site/edit/main/modules/ROOT/pages/subprojects/apache-felix-shell.adoc">Edit this Page</a></div>
</div>
<div class="content">
<article class="doc">
<h1 class="page">Apache Felix Shell</h1>
<div id="preamble">
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p><a href="#_overview">Overview</a></p>
</li>
<li>
<p><a href="#_how_the_shell_service_works">How the Shell Service Works</a></p>
</li>
<li>
<p><a href="#_how_commands_work">How Commands Work</a></p>
</li>
<li>
<p><a href="#_creating_a_command">Creating a Command</a></p>
</li>
<li>
<p><a href="#_security_and_the_shell_service">Security and the Shell Service</a></p>
</li>
<li>
<p><a href="#_feedback">Feedback</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_overview"><a class="anchor" href="#_overview"></a>Overview</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In order to interact with Felix 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.
Felix defines a shell service for creating and executing arbitrary commands.
The shell service does not define a user interface, only a service API.</p>
</div>
<div class="paragraph">
<p>The benefit of the Felix shell service approach is that it is possible to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>have multiple shell user interfaces (e.g., textual and graphical),</p>
</li>
<li>
<p>add custom commands to the shell (i.e., bundles can make commands available via the shell service), and</p>
</li>
<li>
<p>use the shell service from other bundles/services.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>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.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_how_the_shell_service_works"><a class="anchor" href="#_how_the_shell_service_works"></a>How the Shell Service Works</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>package org.apache.felix.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;
}</pre>
</div>
</div>
<div class="paragraph">
<p>Using the shell service interface, it is possible to access and execute available commands.
The shell service methods perform the following functions:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>getCommands()</code> - returns an array of strings that correspond to the names of the installed shell commands.</p>
</li>
<li>
<p><code>getCommandUsage()</code> - returns the command usage string for a particular command name</p>
</li>
<li>
<p><code>getCommandDescription()</code> - returns a short description for a particular command name.</p>
</li>
<li>
<p><code>getCommandReference()</code> - returns the service reference for a particular command name.</p>
</li>
<li>
<p><code>executeCommand()</code> - executes a particular command using the specified command line and print streams.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>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:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>update 3 http://www.foo.com/bar.jar</pre>
</div>
</div>
<div class="paragraph">
<p>The shell service interprets this as an <code>update</code> 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 <code>executeCommand()</code> method of the command service (for a more detailed description of command services, see the next section).</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_how_commands_work"><a class="anchor" href="#_how_commands_work"></a>How Commands Work</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>package org.apache.felix.shell;
public interface Command
{
public String getName();
public String getUsage();
public String getShortDescription();
public void execute(String line, PrintStream out, PrintStream err);
}</pre>
</div>
</div>
<div class="paragraph">
<p>The semantics of the command service methods are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>getName()</code> - returns the name of the command;
this must not contain whitespace and must be unique.</p>
</li>
<li>
<p><code>getUsage()</code> - 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).</p>
</li>
<li>
<p><code>getShortDescription()</code> - 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).</p>
</li>
<li>
<p><code>execute()</code> - executes the command&#8217;s functionality using supplied command line and print streams.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_creating_a_command"><a class="anchor" href="#_creating_a_command"></a>Creating a Command</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The following example creates a simple version of the <code>start</code> command.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>package test;
import java.io.PrintStream;
import java.net.URL;
import java.net.MalformedURLException;
import java.util.StringTokenizer;
import org.osgi.framework.*;
import org.apache.felix.shell.ShellService;
import org.apache.felix.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 &lt;id&gt; [&lt;id&gt; ...]";
}
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() &gt;= 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");
}
}
}</pre>
</div>
</div>
<div class="paragraph">
<p>A bundle activator class is needed for packaging the command servce;
the bundle activator registers the command service in its <code>start()</code> method.
Note: You do not need one activator per command, a single activator can register any number of commands.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>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.apache.felix.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.
}
}</pre>
</div>
</div>
<div class="paragraph">
<p>To compile these classes you will need to have <code>org.apache.felix.framework-x.y.z.jar</code> and <code>org.apache.felix.shell-x.y.z.jar</code> on your class path.
Compile all of the source files using a command like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>java -cp org.apache.felix.framework-1.8.1.jar:org.apache.felix.shell-1.2.0.jar -d c:\classes *.java</pre>
</div>
</div>
<div class="paragraph">
<p>This command compiles all of the source files and outputs the generated class files into a subdirectory of the <code>c:\classes</code> directory, called test, named after the package of the source files;
for the above command to work, the <code>c:\classes</code> 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 <code>manifest.mf</code> with the following contents:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>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</pre>
</div>
</div>
<div class="paragraph">
<p>To create the bundle JAR file, issue the command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>jar cfm mystart.jar manifest.mf -C c:\classes test</pre>
</div>
</div>
<div class="paragraph">
<p>This command creates a JAR file using the manifest you created and includes all of the classes in the test directory inside of the <code>c:\classes</code> 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 <code>mystart</code> command is made available via the shell service.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_security_and_the_shell_service"><a class="anchor" href="#_security_and_the_shell_service"></a>Security and the Shell Service</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_feedback"><a class="anchor" href="#_feedback"></a>Feedback</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Subscribe to the Felix users mailing list by sending a message to <a href="mailto:users-subscribe@felix.apache.org">users-subscribe@felix.apache.org</a>;
after subscribing, email questions or feedback to <a href="mailto:users@felix.apache.org">users@felix.apache.org</a>.</p>
</div>
</div>
</div>
</article>
<aside class="toc sidebar" data-title="Contents" data-levels="2">
<div class="toc-menu"></div>
</aside>
</div>
</main>
</div>
<footer class="footer">
<p>Content licensed under AL2. UI licensed under MPL-2.0 with extensions licensed under AL2</p>
</footer>
<script src="../../_/js/site.js"></script>
<script async src="../../_/js/vendor/highlight.js"></script>
</body>
</html>