This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/felix-dev.git
The following commit(s) were added to refs/heads/master by this push:
new 298450bd0a Update documentation
298450bd0a is described below
commit 298450bd0a240d17f39ffd4b9d3d2976b8b56dac
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Dec 28 13:05:28 2023 +0100
Update documentation
---
webconsole/EXTENSIONS.md | 189 ++++++++++++++++++++++++++
webconsole/README.md | 13 +-
webconsole/RESTAPI.md | 335 +++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 530 insertions(+), 7 deletions(-)
diff --git a/webconsole/EXTENSIONS.md b/webconsole/EXTENSIONS.md
new file mode 100644
index 0000000000..fc52a7a75d
--- /dev/null
+++ b/webconsole/EXTENSIONS.md
@@ -0,0 +1,189 @@
+# Extending the Apache Felix Web Console
+
+The Apache Felix Web Console is extensible in various ways.
+
+## Providing Web Console Plugins
+
+The Web Console can be extended by registering an OSGi service for the
interface `jakarta.servlet.Servlet`. The respective service is called a Web
Console Plugin or a plugin for short.
+
+The following table shows the required and optional registration properties.
+
+| Property | Description |
+|---|---|
+|`felix.webconsole.label`| A required string property with the label. The
label is also used as a path segment in the URL to address the plugin. |
+|`felix.webconsole.title`| A required string property for the title.|
+|`felix.webconsole.css`|A single string, an array of strings or a collection
of strings to be used as additional CSS resources which are automatically
included in the head of the html page for the plugin. This property is
optional.|
+
+If there are more than one plugin registered with the same label, the one with
the highest service ranking is used.
+
+Before calling the servlet the web console sets these request attributes
helping the plugin rendering the response:
+
+| Property | Description |
+|---|---|
+| `felix.webconsole.appRoot` | This request attribute of type `String`
provides the absolute path of the Web Console root. This path consists of the
servlet context path (from `ServletRequest.getContextPath()`) and the Web
Console servlet path (from `HttpServletRequest.getServletPath()`,
`/system/console` by default). This attribute can be used to provide absolute
links to resources (images, CSS, scripts, etc.) or other plugins. This request
attribute is available to client side JavaScri [...]
+| `felix.webconsole.pluginRoot` | This request attribute of type `String`
provides the absolute path of the current plugin. This path consists of the
servlet context path (from `ServletRequest.getContextPath()`), the Web Console
servlet path (from `HttpServletRequest.getServletPath()`, `/system/console` by
default) and the plugin label. This attribute can be used to provide absolute
links to the plugin itself. This request attribute is available to client side
JavaScript as the global _` [...]
+
+The most basic plugin is a plain old Servlet whose `service(ServletRequest,
ServletResponse)` method is called by the Apache Felix Web Console. For support
is provided by extending the
`org.apache.felix.webconsole.servlet.AbstractServlet` base class. In general
the first approach is the preferred option as it does not create a dependency
on web console API.
+
+### Plugin Logging
+
+The web console does not provide anything special for logging from within a
plugin. As the web console is using slf4j, it is advisable to use the same
logging mechanism. However, plugins are free to use other logging APIs.
+
+### Providing Resources
+
+All requests that are targetted at a plugin where the path starts with `/res/`
are automatically handled as requests to resources. In this case the resources
are searched inside the bundle providing the plugin.
+
+### Web Console Output Templating
+
+Templating and Internationalization support of the Web Console is based on
Java Resource Bundles loaded from the plugin bundles and is transparent to the
plugin itself.
+
+All html output generated by the plugin is filtered by the web console. This
writer filter recognizes variables of the pattern `${name}` and tries to
replace that part of the output with another string:
+
+* If a variable of that name exists, the value of that variable is used. See
Variable Resolution below.
+* Otherwise if a resource bundle provides a translated string for the name,
that string is used. See Resource Bundles below.
+* Otherwise the name itself is just placed in the output.
+
+#### Example
+
+Consider the plugin bundle provides a localization for the default german
locale `de`:
+
+```
+OSGI-INF/l10n/bundle_de.properties:
+Hello = Guten Tag
+```
+
+And the plugin defines a variable replacement and writes output with the
following code:
+
+```java
+ this.getVariableResolver().put("world", "Schweiz");
+ response.getWriter().println("${Hello} ${world}");
+```
+
+The response sent to the client whose primary locale is `de` is then filtered
to be:
+
+> Guten Tag Schweiz
+
+#### Resource Bundles
+
+Resources for the Resource Bundles is provided by the Web Console bundle on
the one hand and by the bundle providing the plugin on the other hand.
Resources are identified inside a bundle with the `Bundle-Localization`
manifest header as described in Section 3.10 Localization in the Core
Specification.
+
+This also means, that additional translations may be provided by fragment
bundles.
+
+During request processing the `Locale` of the request
(`ServletRequest.getLocale()`) is used to identify the actual resources to use.
From this information a `ResourceBundle` is constructed from a collection of
the resources provided by the plugin bundle and the resources provided by the
Web Console.
+
+#### Web Console Localization
+
+The Web Console contains a single localization file
`OSGI-INF/l10n/bundle.properties`. Fragments attached to the Web Console bundle
may provide translations for these resources. All plugins of the Web Console
itself will use a ReosurceBundle, which is only based on the localization of
the Web Console itself.
+
+#### Using Templating
+
+To use the described templating, the plugin developer may provide the
following:
+
+- Use templated strings in the generated response. Such templated strings will
be replaced with variable values or localization strings as available.
+- Set variable mappings in a `VariableResolver`. The simplest thing is to get
a default `VariableResolver` calling the
`this.getVariableResolver(ServletRequest)` method.
+- Provide localization files and optionally set the `Bundle-Localization`
header if the base file name is not the default `OSGI-INF/l10n/bundle`.
+
+## Legacy Plugin Support
+
+The Web Console supports plugins written for older versions of the Web Console
leveraging the `javax.servlet.Servlet` interface. The support requires the
`javax.servlet` API to be available at runtime as well as the Apache Felix Http
Wrappers API. If both dependencies are provided at runtime, the legacy support
is automatically enabled.
+
+For more information refer to the [legacy
plugins](https://felix.apache.org/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/providing-web-console-plugins.html).
+
+## Branding the Web Console
+
+Branding the Web Consle mainly concerns hooking into the looks of the Web
Console providing vendor-provided setup like CSS, Logo, Main Title, Vendor URL,
etc.
+
+Branding for the Web Console can be provided in two ways: By registering a
`BrandingPlugin` service or by providing a branding properties files. The Web
Console uses the branding from the `BrandingPlugin` service registered with the
highest ranking.
+
+The `BrandingPlugin` interface provides the following information used for
branding:
+
+```java
+// Returns an indicative name of the branding plugin
+// This value is used as the Window/Page title together with the
+// title of the respective plugin
+String getBrandName();
+
+// Returns the name of the product in which the web console is contained
+// and to which the web console is branded.
+String getProductName();
+
+// Returns an (absolute) URL to a web site representing the product to
+// which the web console is branded.
+String getProductURL();
+
+// Returns an absolute path to an image to be rendered as the logo of the
+// branding product.
+String getProductImage();
+
+// Returns the name of the branding product vendor.
+String getVendorName();
+
+// Returns an (absolute) URL to the web site of the branding product
+// vendor.
+String getVendorURL();
+
+// Returns an absolute path to an image to be rendered as the logo of the
+// branding product vendor.
+String getVendorImage();
+
+// Returns the absolute path to an icon to be used as the web console
+// "favicon".
+String getFavIcon();
+
+// Returns the absolute path to a CSS file to be used as the main CSS for
+// the basic admin site.
+String getMainStyleSheet();
+```
+
+If no `BrandingPlugin` service is registered, the `DefaultBrandingPlugin` is
used.
+
+The `DefaultBrandingPlugin` reads the `/META-INF/webconsole.properties` from
the web console bundle to setup the branding using the following properties:
+
+|Propery Name| Default Value | `BrandingPlugin` method name|
+|---|---|---|
+| `webconsole.brand.name`| Apache Felix Web Console| `getBrandName()`|
+| `webconsole.product.name`| Apache Felix| `getProductName()`|
+| `webconsole.product.url`|| https://felix.apache.org| `getProductURL()`|
+| `webconsole.product.image`|| /res/imgs/logo.png| `getProductImage()`|
+| `webconsole.vendor.name`| The Apache Software Foundation| `getVendorName()`|
+| `webconsole.vendor.url`| https://www.apache.org| `getVendorURL()`|
+| `webconsole.vendor.image`| /res/imgs/logo.png| `getVendorImage()`|
+| `webconsole.favicon`| /res/imgs/favicon.ico| `getFavIcon()`|
+| `webconsole.stylesheet`| /res/ui/webconsole.css| `getMainStyleSheet()`|
+
+_Note:_ The `/META-INF/webconsole.properties` file is not contained in the
Apache Felix Web Console bundle itself. It may be provided by a Fragment Bundle
attaching to the Apache Felix Web Console bundle.
+
+## Web Console Security Provider
+
+An additional service controlling the access to the web console can be
deployed by registering a service implementing the
`org.apache.felix.webconsole.spi.SecurityProvider` interface.
+
+It is possible to _require_ a SecurityProvider service to be present in order
for the Web Console to become active. This can be used to prevent bypassing the
security provider if this is provided asynchronously. To do this, the
SecurityProvider service needs to be registered with a _Service Registration_
property to identify itself:
+
+> "webconsole.security.provider.id" = "my.security.provider"
+
+Then the Web Console can be informed about the security providers it needs to
operate by setting the following _OSGi Framework_ property:
+
+> "felix.webconsole.security.providers" = "my.security.provider"
+
+With this property specified, the Web Console will not activate until the
service with the specified property is present. Local login as typically done
with `admin/password` is disabled when this property is specified.
+
+### The SecurityProvider interfacew
+
+The `SecurityProvider` interface defines three methods:
+
+```java
+boolean authorize( Object user, String role );
+
+Object authenticate( HttpServletRequest request, HttpServletResponse response
);
+
+void logout(HttpServletRequest request, HttpServletResponse response);
+```
+
+Both, the `authenticate` as well as the `logout` method are in full control of
authentication and thus have to extract the user credentials from the request
and can also fail the request.
+
+The method `authorize` is currently not used.
+
+### Sample
+
+A sample of a `SecurityProvider` service (using the legacy interface) is in
the Apache Sling implementation
[SlingWebConsoleSecurityProvider2](https://github.com/apache/sling-org-apache-sling-extensions-webconsolesecurityprovider/blob/master/src/main/java/org/apache/sling/extensions/webconsolesecurityprovider/internal/SlingWebConsoleSecurityProvider2.java).
+This implementation uses a JCR implementation to login to the repository and
thus validate the credentials.
diff --git a/webconsole/README.md b/webconsole/README.md
index 65989fc0b1..8d1600613b 100644
--- a/webconsole/README.md
+++ b/webconsole/README.md
@@ -50,7 +50,7 @@ Such framework properties will also be considered actual
default values for miss
| `felix.webconsole.password` | `password` |
| `felix.webconsole.locale` | `locale` |
-Please note that setting any of these properties as framework property makes
them visible to all bundles deployed. This is particularly to be considered in
case of the `felix.webconsole.password` property (as for authentication, the
use of a [Web Console Security
Provider](https://felix.apache.org/subprojects/apache-felix-web-console/web-console-security-provider)
is suggested anyway).
+Please note that setting any of these properties as framework property makes
them visible to all bundles deployed. This is particularly to be considered in
case of the `felix.webconsole.password` property (as for authentication, the
use of a [Web Console Security Provider](EXTENSIONS.md) is suggested anyway).
## Security
@@ -58,20 +58,19 @@ The Web Console only has very basic security at the moment
supporting only HTTP
To enhance the security of the Web Console you are strongly encouraged to
change at least the `password` for the admin user.
-As of Web Console 3.1.0 this simple user setup can be extended by providing
link:[Web Console Security
Provider](https://felix.apache.org/subprojects/apache-felix-web-console/web-console-security-provider).
-See that page for more information.
+This simple user setup can and should be extended by providing a [Web Console
Security Provider](EXTENSIONS.md). See that page for more information.
## Extending the Web Console
-The Web Console can be extended by registering an OSGi service for the
interface `jakarta.servlet.Servlet` with the service property
`felix.webconsole.label` set to the label (last segment in the URL) of the page
and `felix.webconsole.title` set to the display title of the plugin. The
respective service is called a Web Console Plugin or a plugin for short.
+The Web Console can be extended by registering an OSGi service for the
interface `jakarta.servlet.Servlet`.
-Please refer to [Extending the Apache Felix Web
Console](https://felix.apache.org/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console)
for full documentation on extending the Web Console.
+Please refer to [Extending the Apache Felix Web Console](EXTENSIONS.md) for
full documentation on extending the Web Console.
## RESTful API
While the Web Console does not have a full featured and documented REST-ful
API, most plugins try to follow REST approaches. For example the bundles plugin
is able to send information on all bundles or a single bundle.
-An attempt is made to document the current state of REST-like APIs at link
[Web Console RESTful
API](https://felix.apache.org/subprojects/apache-felix-web-console/web-console-restful-api).
+An attempt is made to document the current state of REST-like APIs at link
[Web Console RESTful API](RESTAPI.md).
## Issues
@@ -91,7 +90,7 @@ Additional plugins can be found in the [plugins
directory](https://github.com/ap
If an OSGi Configuration Admin Service is available at runtime, the
Configuration Manager plugin can be used to manage OSGi configurations. For
human readbable configuration descriptions it is advisable to also install an
OSGi Metatype service.
-The Configuration Manager is available via
`+http://localhost:8888/system/console/configMgr+`. It display all configurable
OSGi services.
+The Configuration Manager is available via
`http://localhost:8888/system/console/configMgr`. It display all configurable
OSGi services.
#### Configuration Factories
diff --git a/webconsole/RESTAPI.md b/webconsole/RESTAPI.md
new file mode 100644
index 0000000000..2ee702b476
--- /dev/null
+++ b/webconsole/RESTAPI.md
@@ -0,0 +1,335 @@
+# Web Console RESTful API
+
+WARNING: Please note that the APIs described on this page have not been
standardized or stabilized yet.
+As such they cannot be relied upon.
+They are merely a description of the current code.
+In future releases these APIs will be fixed to be properly RESTful.
+
+## URL Space
+
+The Web Console URL space is by default rooted at `/system/console` inside the
Servlet Context used by the web console. This default can be reconfigured,
though this is not really recommended.
+
+It is expected that the Web Console owns the complete URL space below the root
path.
+
+The next level in the URL Space of the Web Console is defined by the labels
defined by the registered Web Console plugins. For example the Bundles plugins
registers itself with the `bundles` label.
+
+## Request Methods
+
+Although the HTTP RFC defines a number of request methods and the REST
architectural style mandates to use these methods as intended by the
specification, Web Browsers in general only support the GET and POST methods.
+Moreover, firewall administrators more often than not block all HTTP methods
except GET and POST.
+For this reason the Web Console limits the used methods to just these two.
+
+## Bundles Plugin
+
+### URLs
+
+`.../bundles` : addresses all bundles in the framework
+
+`.../bundles/*id*` : addresses a single bundle in the framework.
+The `*id*` can in this case be the bundle's ID (as per
`Bundle.getBundleId()`), the bundle's symbolic name (which actually may cause
multiple bundles to be addressed), or the bundle's symbolic name and version
separated by a colon.
+Examples are `.../bundles/0`, `.../bundles/org.apache.felix.webconsole`, and
`.../bundles/org.apache.felix.webconsole:5.0.0`.
+
+### GET Requests
+
+GET requests are used to retrieve information on the bundles (or bundle)
available in the framework.
+To response formats are currently supported: regular HTML and JSON if requests
are sent with the `.json` extension;
+e.g.
+`.../bundles/0.json`.
+The HTML response is destined at browsers and is not further described here.
+
+### GET .../bundles.json
+
+Requests to this URL send back an overview of all bundles along with an
overview of all bundles (bundles existing, active, fragment, resolved,
installed)
+
+```json
+{
+ "status": "Bundle information: 84 bundles in total - all 84 bundles
active.",
+ "s": [ 84, 81, 3, 0, 0 ],
+ "data": [
+ {
+ "id": 0,
+ "name": "System Bundle",
+ "fragment": false,
+ "stateRaw": 32,
+ "state": "Active",
+ "version": "3.0.8",
+ "symbolicName": "org.apache.felix.framework",
+ "category": ""
+ },
+ ....
+ ]
+}
+```
+
+### GET .../bundles/id.json
+
+This URL returns detailed information of a bundle like the bundle headers,
imported packages, exported packages, importing bundles, registered services.
+
+```json
+{
+ "status": "Bundle information: 84 bundles in total - all 84 bundles
active.",
+ "s": [
+ 84,
+ 81,
+ 3,
+ 0,
+ 0
+ ],
+ "data": [
+ {
+ "id": 23,
+ "name": "Apache Felix Web Management Console",
+ "fragment": false,
+ "stateRaw": 32,
+ "state": "Active",
+ "version": "3.1.9.SNAPSHOT",
+ "symbolicName": "org.apache.felix.webconsole",
+ "category": "",
+ "props": [
+ {
+ "key": "Symbolic Name",
+ "value": "org.apache.felix.webconsole"
+ },
+ {
+ "key": "Version",
+ "value": "3.1.9.SNAPSHOT"
+ },
+ {
+ "key": "Bundle Location",
+ "value":
"slinginstall:org.apache.felix.webconsole-3.1.6.jar"
+ },
+ {
+ "key": "Last Modification",
+ "value": "Sun Sep 25 20:59:46 CEST 2011"
+ },
+ {
+ "key": "Bundle Documentation",
+ "value":
"http://felix.apache.org/site/apache-felix-web-console.html";
+ },
+ {
+ "key": "Vendor",
+ "value": "The Apache Software Foundation"
+ },
+ {
+ "key": "Description",
+ "value": "Web Based Management Console for OSGi
Frameworks. See http://felix.apache.org/site/apache-felix-web-console.html for
more information on this bundle."
+ },
+ {
+ "key": "Start Level",
+ "value": 5
+ },
+ {
+ "key": "Exported Packages",
+ "value": [
+ "org.apache.felix.webconsole,version=3.1.2"
+ ]
+ },
+ {
+ "key": "Imported Packages",
+ "value": [
+ "javax.servlet,version=2.5.0 from <a
href='/system/console/bundles/15'>org.apache.felix.http.jetty (15)</a>",
+ "javax.servlet.http,version=2.5.0 from <a
href='/system/console/bundles/15'>org.apache.felix.http.jetty (15)</a>",
+ "org.apache.felix.scr,version=1.6.0 from <a
href='/system/console/bundles/11'>org.apache.felix.scr (11)</a>",
+ "org.osgi.framework,version=1.5.0 from <a
href='/system/console/bundles/0'>org.apache.felix.framework (0)</a>",
+ "org.osgi.service.cm,version=1.3.0 from <a
href='/system/console/bundles/9'>org.apache.felix.configadmin (9)</a>",
+ "org.osgi.service.http,version=1.2.0 from <a
href='/system/console/bundles/15'>org.apache.felix.http.jetty (15)</a>",
+ "org.osgi.service.log,version=1.3.0 from <a
href='/system/console/bundles/6'>org.apache.sling.commons.logservice (6)</a>",
+ "org.osgi.service.metatype,version=1.1.0 from <a
href='/system/console/bundles/12'>org.apache.felix.metatype (12)</a>",
+ "org.osgi.service.packageadmin,version=1.2.0 from <a
href='/system/console/bundles/0'>org.apache.felix.framework (0)</a>",
+ "org.osgi.service.startlevel,version=1.1.0 from <a
href='/system/console/bundles/0'>org.apache.felix.framework (0)</a>"
+ ]
+ },
+ {
+ "key": "Importing Bundles",
+ "value": [
+ "<a
href='/system/console/bundles/19'>org.apache.felix.webconsole.plugins.memoryusage
(19)</a>",
+ "<a
href='/system/console/bundles/62'>org.apache.sling.commons.mime (62)</a>",
+ "<a
href='/system/console/bundles/14'>org.apache.sling.extensions.threaddump
(14)</a>",
+ "<a
href='/system/console/bundles/20'>org.apache.sling.extensions.webconsolesecurityprovider
(20)</a>",
+ "<a
href='/system/console/bundles/18'>org.apache.sling.jcr.webconsole (18)</a>"
+ ]
+ },
+ {
+ "key": "Service ID <a
href='/system/console/services/369'>369</a>",
+ "value": [
+ "Types:
org.apache.felix.webconsole.ConfigurationPrinter"
+ ]
+ },
+ {
+ "key": "Service ID <a
href='/system/console/services/370'>370</a>",
+ "value": [
+ "Types:
org.apache.felix.webconsole.ConfigurationPrinter"
+ ]
+ },
+ {
+ "key": "Service ID <a
href='/system/console/services/371'>371</a>",
+ "value": [
+ "Types:
org.apache.felix.webconsole.ConfigurationPrinter"
+ ]
+ },
+ {
+ "key": "Service ID <a
href='/system/console/services/372'>372</a>",
+ "value": [
+ "Types:
org.apache.felix.webconsole.ConfigurationPrinter"
+ ]
+ },
+ {
+ "key": "Service ID <a
href='/system/console/services/373'>373</a>",
+ "value": [
+ "Types:
org.apache.felix.webconsole.ConfigurationPrinter"
+ ]
+ },
+ {
+ "key": "Service ID <a
href='/system/console/services/374'>374</a>",
+ "value": [
+ "Types:
org.apache.felix.webconsole.ConfigurationPrinter"
+ ]
+ },
+ {
+ "key": "Service ID <a
href='/system/console/services/375'>375</a>",
+ "value": [
+ "Types:
org.apache.felix.webconsole.ConfigurationPrinter"
+ ]
+ },
+ {
+ "key": "Service ID <a
href='/system/console/services/376'>376</a>",
+ "value": [
+ "Types: org.osgi.service.cm.ManagedService,
org.osgi.service.metatype.MetaTypeProvider",
+ "Service PID:
org.apache.felix.webconsole.internal.servlet.OsgiManager",
+ "Description: OSGi Management Console Configuration
Receiver",
+ "Vendor: The Apache Software Foundation"
+ ]
+ },
+ {
+ "key": "Service ID <a
href='/system/console/services/453'>453</a>",
+ "value": [
+ "Types:
org.apache.felix.webconsole.ConfigurationPrinter"
+ ]
+ },
+ {
+ "key": "Manifest Headers",
+ "value": [
+ "Bnd-LastModified: 1316977184980",
+ "Build-Jdk: 1.6.0_13",
+ "Built-By: fmeschbe",
+ "Bundle-Activator:
org.apache.felix.webconsole.internal.OsgiManagerActivator",
+ "Bundle-Description: Web Based Management Console for
OSGi Frameworks. See http://felix.apache.org/site/apache-felix-web-console.html
for more information on this bundle.",
+ "Bundle-DocURL:
http://felix.apache.org/site/apache-felix-web-console.html";,
+ "Bundle-License:
http://www.apache.org/licenses/LICENSE-2.0.txt";,
+ "Bundle-ManifestVersion: 2",
+ "Bundle-Name: Apache Felix Web Management Console",
+ "Bundle-SymbolicName: org.apache.felix.webconsole",
+ "Bundle-Vendor: The Apache Software Foundation",
+ "Bundle-Version: 3.1.9.SNAPSHOT",
+ "Created-By: Apache Maven Bundle Plugin",
+ "DynamicImport-Package:
org.apache.felix.bundlerepository, org.osgi.service.obr",
+ "Export-Package: org.apache.felix.webconsole;
uses:=\"javax.servlet, org.osgi.framework, javax.servlet.http\";
version=\"3.1.2\"",
+ "Import-Package: javax.servlet; version=\"2.4\",
javax.servlet.http; version=\"2.4\", org.apache.felix.scr;
resolution:=optional; version=\"1.0\", org.apache.felix.shell;
resolution:=optional, org.apache.felix.webconsole; version=\"3.1.2\",
org.osgi.framework, org.osgi.service.cm; resolution:=optional,
org.osgi.service.condpermadmin; resolution:=optional,
org.osgi.service.deploymentadmin; resolution:=optional, org.osgi.service.http,
org.osgi.service.log; resoluti [...]
+ "Manifest-Version: 1.0",
+ "Tool: Bnd-0.0.255"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+```
+
+### POST Requests
+
+To update the bundles the `action` request parameter is used to indicate the
action:
+
+`install` : Installs (or updates) and optionally starts one or more bundles.
+Parameters:
+
+* `bundlestart` -- whether to start newly installed bundles or not.
+Has no influence on updated bundles.
+* `bundlestartlevel` -- the start level to set on newly installed bundles.
+Has no influence on updated bundles.
+* `bundlefile` -- one or more uploaded files being the bundles to install or
update.
+The manifests in the bundles are inspected to see whether any bundle is an
update or new install.
+* `refreshPackages` -- whether to call
`PackageAdmin.refreshPackages(Bundle[])` with the installed/updated bundles
after installation/update.
+
+`start` : Starts the bundle addressed by the request URL.
+
+`stop` : Stops the bundle addressed by the request URL.
+
+`refresh` : Calls `PackageAdmin.refreshPackages(Bundle[])` with the bundle as
its sole argument thus forcing the bundle to be rewired. The bundle is required
to be addressed by the request URL.
+
+`update` : Calls `Bundle.update()` on the bundle addressed by the request URL
or tries to update the bundle through the OBR.
+
+`uninstall` : Calls `Bundle.uninstall()` on the bundle addressed by the
request URL. After the installation the framework must be refreshed (see
`refreshPackages` above).
+
+`refreshPackages` : Calls `PackageAdmin.refreshPackages(Bundle[])` with a
`null` argument thus refreshing all pending bundles.
+This action does not require a bundle in the URL and just ignores if one is
provided.
+
+The response on those actions requiring a bundle is a simple JSON response:
+
+```json
+{
+ "fragment": -- whether the bundle is a fragement
+ "stateRaw": -- the state code of the bundle after executing the action
+}
+```
+
+Since some bundle operations take place asynchronously a short delay of 800ms
is inserted before preparing and sending the response.
+
+The response on those actions not taking a bundle is the bundle overview of
the bundles in the framework as if requesting `.../bundles.json`.
+Again a delay of 800ms is inserted since some operations are executed
asynchronously.
+
+## Services Plugin
+
+TBD
+
+## Configuration Admin Plugin
+
+The Configuration Admin Plugin can be accessed directly by sending POST
requests to it.
+
+### POST Requests
+
+Configuration handling is done based on the PID of the configuration.
+Each POST can either contain the PID as a suffix like `../PID` or with the
parameter `pid`.
+The parameter `pidFilter` might contain an additional filter expression.
+For the action to execute, the following options are tested, one after the
other.
+As soon as one is executed, the request is processed.
+
+#### Create
+
+If the parameter ``create``is sent, a new configuration with the PID is
created.
+The value of the parameter is not evaluated.
+
+#### Apply
+
+If the parameter `apply` is sent, the configuration is changed.
+The value of the parameter is not evaluated.
+The parameter `factoryPid` might contain the factory pid.
+The parameter `propertyList` contains a comma-separated list of all
configuration property names that will be changed by this POST.
+For each name, the value of the corresponding request parameter is used to set
the value.
+If such a parameter is missing, the property is not changed.
+Any existing property not listed in the property list will be removed from the
configuration.
+
+For example to use `curl` to apply a configuration the following command line
can be used:
+
+> curl -u admin:admin -X POST -d "apply=true" -d "propertylist=foo,bar" -d
"foo=51" -d "bar=hello"
http://localhost:8080/system/console/configMgr/com.acme.MyPid
+
+If the configuration contains property where the names clash with the commands
of the rest api like `apply` or `propertyList` the request parameter name must
be prefixed with a dollar sign:
+
+> curl -u admin:admin -X POST -d "apply=true" -d "propertylist=update" -d
"$update=yes" http://localhost:8080/system/console/configMgr/com.acme.mypid
+
+To create a factory configuration, the special PID `[Temporary PID replaced by
real PID upon save]` must be used, URL encoded.
+So to create a new factory configuration for a factoryPid
`com.acme.MyFactoryPid` the following can be used:
+
+> curl -u admin:admin -X POST -d "apply=true" -d "propertylist=name" -d
"name=mycfg" -d "factoryPid=com.acme.MyFactoryPid"
http://localhost:8080/system/console/configMgr/%5BTemporary%20PID%20replaced%20by%20real%20PID%20upon%20save%5D
+
+#### Delete
+
+If the parameters `apply` and `delete` are sent, the configuration is removed.
+The values of the parameters is not evaluated.
+
+Example using `curl`:
+
+> curl -u admin:admin -X POST -d "apply=true" -d "delete=true"
http://localhost:8080/system/console/configMgr/com.acme.MyPid
+
+#### Unbind
+
+If the parameter `unbind` is sent, the configuration is unbind.
