Cloud computing is a continuing trend in the IT industry. Due to its service model which embraces dynamism as opposed to masking it, OSGi appears to be an ideal base for building scalable and dependable applications for the cloud where changes in the deployment, network topology, and service availability are the norm rather than the exception. One of the possible scenarios for OSGi to be successfully applied to cloud computing is using it in a Platform as a Service (PaaS) spirit. Users write their bundles and can deploy them to a provided OSGi instance running in the cloud. This, however, requires the platform provider to expose the OSGi management API to the end user and make them available through a network protocol. One of the popular approaches in cloud computing to remote communication is the use of RESTful web services.
Representational State Transfer (REST) is the architectural style of the world wide web. It can be described as a set of constraints that govern the interactions between the main components of the Internet. Recently, REST style interaction has gained popularity as a architecture for web services (RESTful web services), mainly to overcome the perceived complexity and verbosity of SOAP-based web services. This specification describes a REST interface for framework management, client-side Java and JavaScript APIs, and an extension mechanism through which other bundles can contribute their own RESTful management APIs and make them discoverable by clients.
-
Client-Server - A separation of concern between the entity responsible for the user-interaction (client) and the other entity (server) responsible for data storage. For instance, in the original world wide web the browser is the client rendering and presenting the content delivered by one or more web servers. As a result, web content becomes more portable and content providers more scalable.
-
Stateless - State is entirely kept at the client side. Therefore, every request must contain all state required for the server to accomplish the transaction and deliver content. The main rationale behind this design constraint is to again improve the scalability since in a pure stateless design the server resources are not burdened with maintaining any client state. Another perceived advantage is that the failure models of stateless interactions is simpler and fault tolerance easier to achieve.
-
Cacheable - Content marked as cacheable can be temporarily stored and used to immediately answer future equivalent requests and improve efficiency and reduce network utilization and access latencies. Due to the end-to-end principle, caches can be placed where necessary, e.g., at the client (forward-proxy), at the server side (backward-proxy), or somewhere in-between for example in a content delivery network. Content marked as non-cacheable must be freshly retrieved with every request even in the presence of caches.
-
Layered - Layering introduces natural boundaries to coupling since every layer only accesses the services provided by the lower layer and provides services to the next higher layer.
-
Uniform Interface - Generality of component interfaces provides a natural decoupling of implementation and interface. REST furthermore encourages the separation of identifiable resources (addressing) and their representation (content delivery).
-
Resource - A resource is an abstract piece of information that can be addressed by a resource identifier. The mapping of a resource to a concrete set of entities can vary over time.
-
Representation - A representation is a sequence of bytes plus associated meta-data that describe the state of a resource. The data format of a representation is called the media-type. Every concrete representation of a resource is just one of arbitrarily many possible representations. The selection of a concrete representation of a resource can be made according to the media types supported by both the client and the server.
-
REST Management Service - The management service exposes a REST API for remotely managing an OSGi framework through the network in a lightweight and portable fashion.
-
Client - The client is a machine using the management service by issuing REST requests through the network. It can do so either directly or indirectly, i.e., through client-side libraries using the REST calls internally.
The manageable entities of an OSGi framework are mapped to resources accessible through resource identifiers. These identifiers are relative to the (usually externally accessible) root URL of the management service. Clients can either discover this root URL or receive it through configuration. Subsequently, a client is able to introspect the state of the framework and perform management operations.
The internal state of a framework resource is expressed and transmitted as a representation. The format of the representation is subject to a mutual agreement between client and management service regarding media types commonly supported by both endpoints. This specification describes two representation formats: JSON and XML.
The REST Management Service is not a traditional OSGi service and it does not appear in the service registry. Its purpose is to expose a management interface to clients which can perform operations on the framework through a network connection. Therefore, it is ideally suited for situations where the user of an OSGi framework does not have direct access to the machine it is running on, a typical situation in Infrastructure as a Service (IaaS) or Platform as a Service (PaaS). However, even in other domains having a lightweight and easily accessible management solution can be of benefit, e.g., for embedded devices. The advantage of REST is that it uses HTTP and therefore does usually not interfere with firewalls. Furthermore, the REST format is easily embeddable into client-side scripting technologies like JavaScript and can be consumed in web browsers.
Much of the value of the REST Management Service lies in client-side libraries which can use the REST protocol and interact with the OSGi framework through the Management Service. Therefore, this specification contains API for two clients, a Java Client API and a JavaScript Client API.
The REST Management Service comprises of a set of resources that can be retrieved and in some cases also modified through REST requests. These resources need to be made available under well-defined paths so that clients can interact with them. As the initial entry point a client receives a URL to the REST Management Service. This can be done, e.g., as part of the creation of a cloud-based OSGi framework, and the precise mechanism would be proprietary to the cloud platform used. Relative to this URL the client can access the resources through the following resource identifiers:
framework
framework/state
framework/startlevel
framework/bundles
framework/bundles/representations
framework/bundle/{bundleid}
framework/bundle/{bundleid}/state
framework/bundle/{bundleid}/startlevel
framework/bundle/{bundleid}/header
framework/services
framework/services/representations
framework/service/{serviceid}
framework/bundle/0/state
is an alias for
framework/state
Extensions to the REST Management Service can be discovered by visiting the Extensions Resource at:
extensions
For more details on the extension mechanism see Extending the REST Management Service
The bundles
, bundles/representations
,
services
, and services/representations
resources allow the use of a query parameter which specifies a filter to
restrict the result set. The filter expression follows the Core
Specifications Framework Filter Syntax; see [1] Framework Filter Syntax.
Filters on services are matched against the service attributes. The query parameter is of the form:
framework/services?filter=ldap-filter
Filters on bundles are matched against the attributes of capabilities in the respective namespaces. Filters on bundles have the form:
framework/bundles?namespace1=ldap-filter1&namespace2=ldap-filter2&...
If multiple capabilities for a given namespace are present, then a filter succeeds when one of these capabilities matches. When multiple filter expressions across namespaces are given, these are combined with the and operator.
Resources can present themselves through different representation variants. An implementation of this specification must support at least the JSON representation and the XML representation of resources. Clients can support a subset of representations. Matching the clients capabilities to understand certain representation formats with the servers supported formats follows the typical HTTP pattern of content negotiation and requires the client to set corresponding HTTP Accept headers for supported formats in the form of their media types. This specification describes the format and media types for representations in JSON and XML format in Representations.
Implementations of the REST Management Service offering different variants of representations must return the best matching variant based on the HTTP accept header. In addition, they must respect the file extensions defined for the different media types as specified in the respective IETF RFC (e.g., ".xml" as specified in IETF RFC 3032 and ".json" as specified in IETF RFC 4627). If a file extension is appended to the resource, an implementation must return the variant mandated by the file extension provided that it supports this content type.
The framework and its state is mapped to a set of different resources. Each resource is accessible through a resource identifier, as summarized in Resource Identifier Overview.
framework/startlevel
The startlevel resource represents the active start level of the framework. It supports the GET and PUT requests.
The GET request retrieves a Framework Startlevel Representation from the REST management service. The request can return the following status codes:
-
200 (OK): the request has been served successfully and the body of the response is a startlevel representation.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
The PUT request sets the target framework startlevel. The body of the request needs to be a Framework Startlevel Representation. The request can return the following status codes:
-
204 (NO CONTENT): the request was received and valid. The framework will asynchronously start to adjust the framework startlevel until the target startlevel has been reached.
-
415 (UNSUPPORTED MEDIA TYPE): the request had a media type that is not supported by the REST management service.
-
400 (BAD REQUEST): the REST management service received an IllegalArgumentException when trying to adjust the framework startlevel, e.g., because the requested startlevel was zero or negative.
framework/bundles
The bundles resource represents the list of all bundles installed on the managed framework. It supports the GET request and two syntactically different forms of POST requests which are used to install new bundles to the framework.
Results for this resource can be filtered as described in Filtering Results.
The GET request retrieves a Bundle List Representation from the REST management service. The request can return the following status codes:
-
200 (OK): the request has been served successfully and the body of the response is a bundle list representation.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
The POST request installs a new bundle to the managed framework and thereby logically appends it to the bundles resource. The new bundle to be installed is referenced by a location string which is passed as the body of the request. In order to disambiguate the request from the other form of POST, the content type must be set to text/plain. In practice, the location string is usually a URL. Since the framework will use the location retrieving the physical bundle, it needs to be accessible from the remotely managed framework and not necessarily from the managing client.
The management service implementation must check if the result of the install request matches the requested bundle since the OSGi framework will return an existing bundle object as the return value of an install call if there was already one with the same location string installed. One way of doing it is comparing the last modification timestamp. A detected collision is indicated to the requesting clients through an error code 409.
The body of the response is a Bundle Representation of the newly installed bundle. The following status codes can be returned:
-
200 (OK): the bundle has been successfully installed and the body of the response contains a Bundle Representation.
-
400 (BAD REQUEST): the REST management service received a BundleException when trying to install. The body of the message is a Bundle Exception Representation describing the reason why the installation did not succeed.
-
409 (CONFLICT): there is already a bundle installed with the same location string.
This variant of the POST request uploads the bundle as the body of the request. The media type of the request should be set to application/vnd.osgi.bundle which must be supported by all REST management services. Implementations are free to accept other media types for this request with the exception of text/plain. For instance, they can opt to additionally support application/zip or application/x-jar.
Clients should use the HTTP Content-Location field to set a bundle location. If no content location is given, REST management service implementations must generate a unique location string in order to avoid unintended collisions between unrelated bundles.
The body of the response is Bundle Representation of the newly installed bundle. The following status codes can be returned:
-
200 (OK): the bundle has been successfully installed and the body of the response contains the URI.
-
400 (BAD REQUEST): the REST management service received a BundleException when trying to install. The body of the message is a Bundle Exception Representation describing the reason why the installation did not succeed.
-
409 (CONFLICT): there is already a bundle installed with the same location string.
framework/bundles/representations
The bundles
resource returns a list of the URIs of
all bundles installed on the framework. For clients interested in the
details of multiple bundles there is also the possibility to retrieve
the bundle representation of each installed bundle with a single
request through the bundles/representations
resource.
The body of the response is a Bundle Representations List Representation. The request can return the following status codes:
Results for this resource can be filtered as described in Filtering Results.
-
200 (OK): the request has been served successfully and the body of the response is a bundle list representation.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
framework/bundle/{bundleid}
The bundle resource represents a single, distinct bundle in the system. Hence, it has to be qualified by a bundle id. The resource supports the GET, two variants of PUT, and the DELETE requests.
The GET request retrieves a Bundle Representation from the REST management service. The request can return the following status codes:
-
200 (OK): the request has been served successfully and the body of the response is a bundle representation.
-
404 (NOT FOUND): there is not bundle with the given bundle id.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
The PUT request updates the bundle with a new version, referenced by a location string which is passed as the body of the request. In order to disambiguate the request from the other form of PUT, the content type must be set to text/plain. The same rationale applies as for POST with Location String and POST with Bundle, if a location string is given it must point to a location reachable by the managed framework. If no location string is passed as the body of the request, the framework will perform an update based on the existing bundle's location string.
The body of the response is Bundle Representation of the updated bundle. The following status codes can be returned:
-
204 (NO CONTENT): the request was received and valid and the framework has issued the update.
-
400 (BAD REQUEST): the REST management service received a BundleException when trying to update. The body of the message is a Bundle Exception Representation describing the reason why the update did not succeed.
-
404 (NOT FOUND): there is not bundle with the given bundle id.
The PUT request updates the bundle with a new version, uploaded as the body of the request. The media type of the request should be set to application/vnd.osgi.bundle which must be supported by all REST management services. Implementations are free to accept other media types for this request with the exception of text/plain. For instance, they can opt to additionally support application/zip or application/x-jar.
The body of the response is Bundle Representation of the updated bundle. The following status codes can be returned:
-
204 (NO CONTENT): the request was received and valid and the framework has issued the update.
-
400 (BAD REQUEST): the REST management service received a BundleException when trying to update. The body of the message is a Bundle Exception Representation describing the reason why the update did not succeed.
-
404 (NOT FOUND): there is not bundle with the given bundle id.
The DELETE request uninstalls the bundle from the framework.
The body of the response is Bundle Representation of the uninstalled bundle, where the bundle state will be UNINSTALLED. The following status codes can be returned:
-
204 (NO CONTENT): the request was received and valid and the framework has uninstalled the bundle.
-
400 (BAD REQUEST): the REST management service received a BundleException when trying to uninstall. The body of the message is a Bundle Exception Representation describing the reason why the uninstallation did not succeed.
-
404 (NOT FOUND): there is not bundle with the given bundle id.
framework/bundle/{bundleid}/state
The bundle state resource represents the internal state of an installed bundle qualified through its bundle id. It supports the GET and PUT requests.
The GET request retrieves a Bundle State Representation from the REST management service. The request can return the following status codes:
-
200 (OK): the request has been served successfully and the body of the response is a bundle state representation.
-
404 (NOT FOUND): there is not bundle with the given bundle id.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
The PUT request sets the target state for the given bundle. This can, e.g., be state=32 for transitioning the bundle to started, or state=4 for stopping the bundle and transitioning it to resolved. The body of the request needs to be a Bundle State Representation. Not all state transitions are valid. The body of the response is the new Bundle State Representation. The request can return the following status codes:
-
200 (OK): the request was received and valid. The framework has performed a state change and the new bundle state is contained in the body.
-
400 (BAD REQUEST): the REST management service received a BundleException when trying to perform the state transition. The body of the message is a Bundle Exception Representation describing the reason why the operation did not succeed.
-
402 (PRECONDITION FAILED): the requested target state is not reachable from the current bundle state or is not a target state. An example such state is the STOPPING state.
-
404 (NOT FOUND): there is not bundle with the given bundle id.
-
415 (UNSUPPORTED MEDIA TYPE): the request had a media type that is not supported by the REST management service.
framework/bundle/{bundleid}/header
The bundle header resource represents manifest header of a bundle which is qualified by its bundle id. It can only be read through a GET request.
The GET request retrieves a Bundle Header Representation from the REST management service. The raw
header value is used unless an Accept-Language
header is
set on the HTTP request. If multiple accepted languages are set only
the first is used to localize the header. The request can return the
following status codes:
-
200 (OK): the request has been served successfully and the body of the response is a bundle header representation.
-
404 (NOT FOUND): there is not bundle with the given bundle id.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
framework/bundle/{bundleid}/startlevel
The bundle startlevel resource represents the start level of the bundle qualified by its bundle id. It supports the GET and PUT requests.
The GET request retrieves a Bundle Startlevel Representation from the REST management service. The request can return the following status codes:
-
200 (OK): the request has been served successfully and the body of the response is a bundle startlevel representation.
-
404 (NOT FOUND): there is not bundle with the given bundle id.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
The PUT request sets the target bundle startlevel. The body of
the request needs to be a Bundle Startlevel Representation, however only the startLevel
property is used. The request can return the following status
codes:
-
200 (OK): the request was received and valid. The REST management service has changed the bundle startlevel according to the target value. The body of the response is the new bundle startlevel representation.
-
400 (BAD REQUEST): either the target startlevel state involved invalid values, e.g., a startlevel smaller or equal to zero and the REST management service got an IllegalArgumentException, or the REST management service received a BundleException when trying to perform the startlevel change. In the latter case, the body of the message is a Bundle Exception Representation describing the reason why the operation did not succeed.
-
404 (NOT FOUND): there is not bundle with the given bundle id.
-
415 (UNSUPPORTED MEDIA TYPE): the request had a media type that is not supported by the REST management service.
framework/services
The services resource represents the set of all services available on the framework, optionally constrained by a filter expression. It is read-only and therefore only supports the GET request.
Results for this resource can be filtered as described in Filtering Results.
The GET request retrieves a Service List Representation from the REST management service. The request can return the following status codes:
-
200 (OK): the request has been served successfully and the body of the response is a service list representation.
-
400 (BAD REQUEST): the provided filter expression was not valid.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
framework/services/representations
The services resource returns a list of the URIs of all services registered on the framework. For clients interested in the details of multiple services there is also the possibility to retrieve the service representation of each available service with a single request through the services/representations resource. The body of the response is a Service Representations List Representation from the REST management service. The request can return the following status codes:
Results for this resource can be filtered as described in Filtering Results.
-
200 (OK): the request has been served successfully and the body of the response is a service list representation.
-
400 (BAD REQUEST): the provided filter expression was not valid.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
framework/service/{serviceid}
The service resource represents a single, distinct service in the framework. Hence, it has to be qualified by a service id. Services can only be read through the REST Management Service and therefore only support the GET request.
The GET request retrieves a Service Representation . The request can return the following status codes:
-
200 (OK): the request has been served successfully and the body of the response is a service representation.
-
404 (NOT FOUND): there is not service with the given service id.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
Content-Type:
application/org.osgi.bundle+json
{
"id":0,
"lastModified":1314999275542,
"state":32,
"symbolicName":"org.eclipse.osgi",
"version":"3.7.0.v20110613"
}
Content-Type:
application/org.osgi.bundles+json
[bundleURI, bundleURI, ..., bundleURI]
Content-Type:
application/org.osgi.bundles.representations+json
[BUNDLE REPRESENTATION, BUNDLE REPRESENTATION, ..., BUNDLE REPRESENTATION]
Content-Type:
application/org.osgi.bundlestate+json
{
"state":32
"options":1
}
The options are used in start or stop calls. Valid options include, e.g., Bundle.START_TRANSIENT and Bundle.START_ACTIVATION_POLICY.
Content-Type:
application/org.osgi.bundleheader+json
{
key:value,
key:value,
...
key:value
}
Content-Type:
application/org.osgi.frameworkstartlevel+json
{
"startLevel":6,
"initialBundleStartLevel":4
}
Content-Type:
application/org.osgi.bundlestartlevel+json
{
"startLevel":6
"activationPolicyUsed":true
"persistentlyStarted":false
}
Content-Type:
application/org.osgi.service+json
{
"id":10,
"properties":
{
"prop1":"val1",
"prop2":2.82,
...
"prop3":true
},
"bundle":bundleURI,
"usingBundles":[bundleURI, bundleURI, ... bundleURI]
}
Note: service properties are converted to
JSON-supported data types where possible: "string"
,
number or boolean (true|false)
. If there is no conversion
to JSON data types is possible the toString()
result is
used as a string value.
Content-Type:
application/org.osgi.service+xml
<service>
<id>10</id>
<properties>
<property name="prop1" value="val1"/>
<property name="prop2" type="Float" value="2.82"/>
...
<property name="prop3" type="Boolean" value="true"/>
</properties>
<bundle>bundleURI</bundle>
<usingBundles>
<bundle>bundleURI</bundle>
<bundle>bundleURI</bundle>
...
<bundle>bundleURI</bundle>
</usingBundles>
</service>
Note: service properties are represented
using the same method as used for the property
XML
element in the Declarative Services specification, see Property and Properties Elements. Service
properties that cannot be represented using the supported data types,
will be represented as String values obtained via the
toString()
method.
Content-Type:
application/org.osgi.services+json
[serviceURI, serviceURI, ..., serviceURI]
Content-Type:
org.osgi.services.representations+json
[SERVICE REPRESENTATION, SERVICE REPRESENTATION, ..., SERVICE REPRESENTATION]
Content-Type:
application/org.osgi.bundleexception+json
{
"typecode": 5,
"message": "BundleException: Bundle activation error"
}
The REST service can be used by a variety of clients directly. In addition this specification describes Client APIs built over this REST protocol to facilitate use from Java and JavaScript clients.
The Java Client provides a Java API over the REST API providing a convenient and portable way to use this API from a Java application.
To use the Java Client, obtain the RestClientFactory service. Create a client by providing the root URL of the REST service, for example:
RestClientFactory restClientFactory = ... // from Service Registry
RestClient restClient = restClientFactory.createRestClient(
new URI("http://localhost:8080/restendpoint"));
// Now we can start interacting
Collection<String> bundles = restClient.getBundlePaths();
BundleDTO newBundle = restClient.installBundle(bundleLocation, bundleStream);
restClient.startBundle(newBundle.id);
The more details on the Java Client can be found in the org.osgi.service.rest.client API documentation section.
This specification also describes a JavaScript client to the REST Management service. This client makes it easy to manage an OSGi framework from any JavaScript environment, including Web Browsers.
The JavaScript client follows the promises
programming style; the request is made asynchronously and a
success()
or failure()
callback is made when
the response arrives.
To use the JavaScript client create an instance of
OSGiRestClient
providing the root URL of the REST service.
var client = new OSGiRestClient('http://localhost:8080/restendpoint');
client.installBundle({
success : function(res) {
// Start the bundle once the install has finished
client.startBundle(res.id);
},
failure : function(httpCode, res) {
// handle failure
}
});
More details on the JavaScript Client can be found in the JavaScript Client API API documentation section.
This specification describes a REST-based management interface for Core Framework functionality. Other services in the framework might also benefit from management access through REST. This can involve services specified by the OSGi Working Group as part of the Core or Compendium Specifications but also application-specific functionality provided by the developer. It is desirable to expose such management services as extensions of the REST Management Service.
This REST service can be implemented by using various technologies such as Java Servlets, Restlet, JAX-RS, and others. Therefore, it might not always be possible to integrate extensions at the implementation level because they might use other underlying technologies to implement their REST interface. Defining a format for delegating requests between the REST Management Service and extensions would furthermore necessarily expose implementation details and is therefore not feasible either. As a consequence, this specification only describes how to logically integrate extensions with the REST Management Service. Implementations of this specification might offer mechanisms for tighter integration for the case that extensions are developed using the same underlying technology.
The main purpose of the extension mechanism is to advertise
extensions to the core REST implementation, which makes them discoverable
for clients. This mechanism can be used to check if a REST interface
exists for a specific service. This is done through the Extensions Resource which
contains a description and a path for every extension currently available.
Implementations that want to contribute their extensions to the REST
Management Service can do so by registering the RestApiExtension
service using the [4] Whiteboard Pattern.
The extension interface is only a marker and the relevant information is
exposed through the NAME, URI_PATH and optionally SERVICE properties. Note that it is the responsibility of
the extension to ensure that the endpoint announced via the
RestApiExtension
service is actually present. The Whiteboard
service does not realize the extension endpoint; it purely announces it to
the main REST implementation for inclusion in the Extensions
Resource.
In order to be discoverable REST interface extensions to OSGi Core
or Compendium services must use their canonical package name as advertised
name. E.g., the name of the REST interface for the User Admin must be
org.osgi.service.useradmin
. This way, a client is able to
check if there is a given extension available on a host. User-defined
extensions should use the package name of the service they provide
management capabilities for.
extensions
The extensions resource enumerates all extensions currently registered through the Whiteboard Pattern. It is read-only and therefore only supports the GET request.
The GET request retrieves a Extensions Representation . The request can return the following status codes:
-
200 (OK): the request has been served successfully and the body of the response is a extension list representation.
-
406 (NOT ACCEPTABLE): the REST management service does not support any of the requested representations.
Content-Type:
application/org.osgi.extensions+json
[ { "name" : "org.osgi.service.event", "path" : "contributions/eventadmin",
"service" : 12 }, ... ]
The namespace for XML representations is:
http://www.osgi.org/xmlns/rest/v1.0.0
The recommended prefix for this namespace is
rest
.
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:rest="http://www.osgi.org/xmlns/rest/v1.0.0"
targetNamespace="http://www.osgi.org/xmlns/rest/v1.0.0"
elementFormDefault="unqualified"
attributeFormDefault="unqualified"
version="1.0.0">
<annotation>
<documentation xml:lang="en">
This is the XML Schema for
XML representations used by
the REST Management Service
Specification.
</documentation>
</annotation>
<element name="bundle" type="rest:Tbundle">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.bundle+xml content type.
</documentation>
</annotation>
</element>
<complexType name="Tbundle">
<all>
<element name="id" type="long" />
<element name="lastModified" type="long" />
<element name="state" type="integer" />
<element name="symbolicName" type="string" />
<element name="version" type="string" />
</all>
</complexType>
<element name="bundles" type="rest:Tbundles">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.bundles+xml and
application/org.osgi.bundles.representations+xml content
types.
</documentation>
</annotation>
</element>
<complexType name="Tbundles">
<choice>
<element name="uri" type="string" minOccurs="0"
maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.bundles+xml content type.
</documentation>
</annotation>
</element>
<element name="bundle" type="rest:Tbundle"
minOccurs="0" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.bundles.representations+xml
content type.
</documentation>
</annotation>
</element>
</choice>
</complexType>
<element name="bundleState" type="rest:TbundleState">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.bundlestate+xml content type.
</documentation>
</annotation>
</element>
<complexType name="TbundleState">
<all>
<element name="state" type="integer" />
<element name="options" type="integer" />
</all>
</complexType>
<element name="bundleHeader" type="rest:TbundleHeader">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.bundleheader+xml content type.
</documentation>
</annotation>
</element>
<complexType name="TbundleHeader">
<sequence>
<element name="entry" minOccurs="0" maxOccurs="unbounded">
<complexType>
<attribute name="key" type="string" use="required" />
<attribute name="value" type="string" use="required" />
</complexType>
</element>
</sequence>
</complexType>
<element name="frameworkStartLevel" type="rest:TframeworkStartLevel">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.frameworkstartlevel+xml content
type.
</documentation>
</annotation>
</element>
<complexType name="TframeworkStartLevel">
<all>
<element name="startLevel" type="integer" />
<element name="initialBundleStartLevel" type="integer" />
</all>
</complexType>
<element name="bundleStartLevel" type="rest:TbundleStartLevel">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.bundlestartlevel+xml content type.
</documentation>
</annotation>
</element>
<complexType name="TbundleStartLevel">
<all>
<element name="startLevel" type="integer" />
<element name="activationPolicyUsed" type="boolean" />
<element name="persistentlyStarted" type="boolean" />
</all>
</complexType>
<element name="service" type="rest:Tservice">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.service+xml content type.
</documentation>
</annotation>
</element>
<complexType name="Tservice">
<all>
<element name="id" type="long" />
<element name="properties">
<complexType>
<sequence>
<element name="property" minOccurs="0"
maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="name"
type="string" use="required" />
<attribute name="value"
type="string" use="optional" />
<attribute name="type"
default="String" use="optional">
<simpleType>
<restriction
base="string">
<enumeration
value="String" />
<enumeration
value="Long" />
<enumeration
value="Double" />
<enumeration
value="Float" />
<enumeration
value="Integer" />
<enumeration
value="Byte" />
<enumeration
value="Character" />
<enumeration
value="Boolean" />
<enumeration
value="Short" />
</restriction>
</simpleType>
</attribute>
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
</complexType>
</element>
<element name="bundle" type="string" />
<element name="usingBundles">
<complexType>
<sequence>
<element name="bundle" type="string"
minOccurs="0" maxOccurs="unbounded" />
</sequence>
</complexType>
</element>
</all>
</complexType>
<element name="services" type="rest:Tservices">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.services+xml and
application/org.osgi.services.representations+xml
content types.
</documentation>
</annotation>
</element>
<complexType name="Tservices">
<choice>
<element name="uri" type="string" minOccurs="0"
maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.services+xml content type.
</documentation>
</annotation>
</element>
<element name="service" type="rest:Tservice"
minOccurs="0" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.services.representations+xml
content type.
</documentation>
</annotation>
</element>
</choice>
</complexType>
<element name="bundleexception" type="rest:Tbundleexception">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.bundleexception+xml content type.
</documentation>
</annotation>
</element>
<complexType name="Tbundleexception">
<all>
<element name="typecode" type="integer" />
<element name="message" type="string" />
</all>
</complexType>
<element name="extensions" type="rest:Textensions">
<annotation>
<documentation xml:lang="en">
Representation for the
application/org.osgi.extensions+xml content type.
</documentation>
</annotation>
</element>
<complexType name="Textensions">
<sequence>
<element name="extension" minOccurs="0" maxOccurs="unbounded">
<complexType>
<all>
<element name="name" type="string" />
<element name="path" type="string" />
<element name="service" type="long" minOccurs="0" />
</all>
</complexType>
</element>
</sequence>
</complexType>
</schema>
The schema is also available in digital form from [3] OSGi XML Schemas.
An implementation of this specification must provide the osgi.implementation
capability with name osgi.rest
. This capability can be used
by provisioning tools and during resolution to ensure that a REST
Management implementation is present to handle REST requests defined in
this specification. The capability must also declare a uses constraint
on the org.osgi.service.rest
package:
Provide-Capability: osgi.implementation;
osgi.implementation="osgi.rest";
uses:="org.osgi.service.rest";
version:Version="1.0"
This capability must follow the rules defined for the osgi.implementation Namespace.
A bundle providing the RestClientFactory service as described by this specification must
inform tools about this service by providing the osgi.service
capability representing this service. This capability must also declare
a uses constraint for the org.osgi.service.rest.client
package:
Provide-Capability: osgi.service;
objectClass:List<String>="org.osgi.service.rest.client.RestClientFactory";
uses:="org.osgi.service.rest.client"
This capability must follow the rules defined for the osgi.service Namespace.
Like any externally visible management interface, the REST interface exposes privileged operations and hence requires access control. Since REST builds upon the HTTP(s) protocol, authentication mechanisms and encryption can be applied the same way as usually done for web servers: they can be layered below the REST protocol. E.g., confidentiality of the transmitted commands can be ensured by using HTTPS as the underlying transport. Authentication can be added by requiring, e.g., basic authentication prior to accepting a REST command. The REST interface should only be implemented by a trusted bundle. Implementations of this specification require all Admin Permissions and all Service Permissions.
Rest Service Package Version 1.0.
-
RestApiExtension
- Marker interface for registering extensions to the Rest API service.
Marker interface for registering extensions to the Rest API service.
The REST service provides a RESTful interface to clients that need to manage an OSGi framework through a network connection. Other components running on the same framework can contribute their own specific REST interface and make it available and discoverable by registering this marker service using the Whiteboard pattern.
Integration of third-party REST interfaces with the framework REST service on the implementation level might not always be possible since it requires knowledge about the underlying implementation and an extension mechanism on that level. Specific technologies such as servlets might support this but the REST service could as well be implemented without the use of a supporting abstraction layer and not offer extensibility.
Using this marker service, the REST service includes the advertised service in the Extensions Resource, allowing clients to discover it and use the extension's functionality.
This service property describes the package name of the technology
manageable by this REST API extension. Services specified in OSGi
specifications must use their canonical package name as the name.
Third-party technologies should also use their package names. The type of this
property is java.lang.String
and the property is mandatory.
This service property refers to the id of the service the REST API
extension provides management capabilities for. This can be useful if more
than one service of a given type is present in the framework. For example
if more than one Http Service is available this property is used to
associate a REST extension managing the Http Service with a specific
service instance.
The type of the property is
java.lang.Long
and the property is optional; if the REST
extension is not directly associated with a service in the service
registry, the property should not be set.
This service property describes a URI to the REST extension on this local
machine. It is either an fully qualified URI with a different port if no
integration with the framework REST service is possible or a relative URI
implicitly using the same port if integration is possible.
The type of this property is
java.lang.String
and the property is mandatory.
Rest Service Client Package Version 1.0.
-
RestClient
- A Java client API for a REST service endpoint. -
RestClientFactory
- Factory to construct new REST client instances.
A Java client API for a REST service endpoint.
Provides a Java client API for accessing and managing a remote OSGi framework through the REST API. Implementations of this interface will usually take the URL to the remote REST Management Service instance as an argument in their constructor. Further arguments might be needed, for example, if the cloud provider requires URL signing.
Consumers of this API must not implement this type
Addresses the bundle by its identifier.
Retrieve the bundle representation for a given bundle Id.
A BundleDTO for the requested bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
Retrieve the bundle representation for a given bundle path.
A BundleDTO for the requested bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Get the header for a bundle given by its bundle Id.
Returns the map of headers entries.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
Get the header for a bundle given by its URI path.
Returns the map of headers entries.
Exception
– An exception representing a failure in the underlying
REST call.
Get the bundles currently installed on the managed framework.
Returns a collection of the bundle URIs in the form of Strings. The URIs are relative to the REST API root URL and can be used to retrieve bundle representations.
Exception
– An exception representing a failure in the underlying
REST call.
Get the bundle representations for all bundles currently installed in the managed framework.
Returns a collection of BundleDTO objects.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Get the start level for a bundle given by its bundle Id.
Returns a BundleStartLevelDTO describing the current start level of the bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
Get the start level for a bundle given by its URI path.
Returns a BundleStartLevelDTO describing the current start level of the bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Get the state for a given bundle Id.
Returns the current bundle state as defined in (@link org.osgi.framework.Bundle}.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
Get the state for a given bundle path.
Returns the current bundle state as defined in (@link org.osgi.framework.Bundle}.
Exception
– An exception representing a failure in the underlying
REST call.
Retrieves the current framework start level.
Returns the current framework start level in the form of a FrameworkStartLevelDTO.
Exception
– An exception representing a failure in the underlying
REST call.
Gets a collection of URI paths to all installed services.
Returns a collection of URI paths to the installed services.
Exception
– An exception representing a failure in the underlying
REST call.
Passes a filter to restrict the result set.
Gets a collection of URI paths to all installed services.
Returns a collection of URI paths to the installed services.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the service by its identifier.
Get the service representation for a service given by its service Id.
The service representation as ServiceReferenceDTO.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the service by its URI path.
Get the service representation for a service given by its URI path.
The service representation as ServiceReferenceDTO.
Exception
– An exception representing a failure in the underlying
REST call.
Get the service representations for all services.
Returns the service representations in the form of ServiceReferenceDTO objects.
Exception
– An exception representing a failure in the underlying
REST call.
Passes a filter to restrict the result set.
Get the service representations for all services.
Returns the service representations in the form of ServiceReferenceDTO objects.
Exception
– An exception representing a failure in the underlying
REST call.
Passes the location string to retrieve the bundle content from.
Install a new bundle given by an externally reachable location string, typically describing a URL.
Returns the BundleDTO of the newly installed bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Passes the location string to be used to install the new bundle.
Passes the input stream to a bundle.
Install a new bundle given by an InputStream to a bundle content.
Returns the BundleDTO of the newly installed bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
The target start level.
Set the start level for a bundle given by its bundle Id.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
The target start level.
Exception
– An exception representing a failure in the underlying
REST call.
set the framework start level to this target.
Sets the current framework start level.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Start a bundle given by its bundle Id.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
Start a bundle given by its URI path.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Passes additional options as defined in org.osgi.framework.Bundle.start(int)
Start a bundle given by its bundle Id.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
Passes additional options as defined in org.osgi.framework.Bundle.start(int)
Start a bundle given by its URI path.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Stop a bundle given by its bundle Id.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
Stop a bundle given by its URI path.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Passes additional options as defined in org.osgi.framework.Bundle.stop(int)
Stop a bundle given by its bundle Id.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
Passes additional options as defined in org.osgi.framework.Bundle.stop(int)
Stop a bundle given by its URI path.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Uninstall a bundle given by its bundle Id.
Returns the BundleDTO of the uninstalled bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its URI path.
Uninstall a bundle given by its URI path.
Returns the BundleDTO of the uninstalled bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Updates a bundle given by its bundle Id using the bundle-internal update location.
Returns the BundleDTO of the updated bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
The URL whose content is to be used to update the bundle.
Updates a bundle given by its URI path using the content at the specified URL.
Returns the BundleDTO of the updated bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Addresses the bundle by its identifier.
Passes an input stream to the new bundle content.
Updates a bundle given by its bundle Id and passing the new bundle content in the form of an InputStream.
Returns the BundleDTO of the updated bundle.
Exception
– An exception representing a failure in the underlying
REST call.
Factory to construct new REST client instances. Each instance is specific to a REST service endpoint.
Implementations can choose to extend this interface to add additional creation methods, where additional arguments are needed for request signing, etc.
In OSGi environments, this factory is registered as a service.
Consumers of this API must not implement this type
REST JavaScript Client API Version 1.0
-
OSGiRestClient
- A JavaScript client API for accessing and managing a remote OSGi framework through the REST API. -
OSGiRestCallback
- Callback object provided to theOSGiRestClient
functions. Invoked on completion of the remote invocation.
JavaScript does not support the concept of interfaces and therefore implementations of the JavaScript client specification can provide objects of any type as long as they conform to the to the signatures described in this specification.
To facilitate documenting the JavaScript APIs Web IDL is used; see [2] Web IDL. This clarifies the accepted arguments and return types for otherwise untyped functions. Web IDL is only used for documentation purposes and has no bearing on the implementation of this API.
Note: some data types in Web IDL have slightly
different names than commonly used in languages like Java or JavaScript.
For example a String
is called DOMString
and the
equivalent of a Java long
is called long long
.
Additionally, when a representation as defined in this specification is
passed to one of the JavaScript client APIs this representation is
provided as a JavaScript object. Following the recommendations for mapping
these to Web IDL, these JavaScript Object parameters are described using
the dictionary
data type. For more information see the Web
IDL specification.
Provides a JavaScript client API for accessing and managing a remote OSGi framework through the REST API. Implementations will provide a proprietary constructor to create objects of this signature. Once created the object can be used from JavaScript environments to manage the framework.
The bundle, either the numeric bundle ID or the bundle URI path.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
representation as JavaScript object.
Get the Bundle representation of a specific bundle.
The bundle, either the numeric bundle ID or the bundle URI path.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
Header representation as JavaScript object.
Get the Bundle Header representation of a specific bundle.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
Representations List representation as JavaScript object.
List the bundles details.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
List representation as JavaScript object.
List the bundles.
The bundle, either the numeric bundle ID or the bundle URI path.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
Start Level representation as JavaScript object.
Get the Bundle Start Level representation of a specific bundle.
The bundle, either the numeric bundle ID or the bundle URI path.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
State representation as JavaScript object.
Get the Bundle State representation of a specific bundle.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the
Framework Start Level representation as JavaScript object.
Obtain the Framework Start Level.
The service, either the numeric service ID or the service URI path.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the
Service representation as JavaScript object.
Get a service representation.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the
Service Representations List representation as JavaScript
object.
Get all services representations.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the
Service List representation as JavaScript object.
Get all services URIs.
The Bundle to install, either represented as a URL or as an ArrayBuffer of
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
representation of the newly installed Bundle. This parameter is
optional.
Install a bundle from a URI or by value.
The bundle, either the numeric bundle ID or the bundle URI path.
A Bundle Start Level representation dictionary with the desired state.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the
resulting Framework Start Level representation as JavaScript object.
This parameter is optional.
Change the Framework Start Level and/or initial bundle start level.
The bundle, either the numeric bundle ID or the bundle URI path.
Bundle State representation dictionary with the desired state.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the
resulting Bundle Start Level representation as JavaScript object. This
parameter is optional.
Change the Bundle Start Level and/or other options defined in the Bundle Start Level representation.
Framework Start Level representation dictionary with the desired state.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the
resulting Framework Start Level representation as JavaScript object.
This parameter is optional.
Change the Framework Start Level and/or initial bundle start level.
The bundle, either the numeric bundle ID or the bundle URI path.
The options passed to the bundle's start method as a number. This parameter is optional.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
State representation as JavaScript object. This parameter is
optional.
Start a bundle.
The bundle, either the numeric bundle ID or the bundle URI path.
The options passed to the bundle's start method as a number. This parameter is optional.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
State representation as JavaScript object. This parameter is
optional.
Stop a bundle.
The bundle, either the numeric bundle ID or the bundle URI path.
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
representation of the uninstalled Bundle. This parameter is
optional.
Uninstall a bundle.
The bundle, either the numeric bundle ID or the bundle URI path.
The Bundle to update, either represented as a URL or as an ArrayBuffer of
The callbacks invoked on completion of the remote invocation. On
success the success()
callback is invoked with the Bundle
representation of the updated Bundle. This parameter is
optional.
Update a bundle from a URI or by value.
Objects implementing this signature are provided by users of the
OSGiRestClient
as callbacks. One of the callback functions is
invoked on completion of a REST invocation.
The result of the invocation. The type of this parameter is depends on the function being invoked. It can be found in the documentation of the function.
Called when the invocation completes successfully.
[2]Web IDLhttp://www.w3.org/TR/WebIDL/
[3]OSGi XML Schemashttps://docs.osgi.org/xmlns/
[4]Whiteboard Patternhttps://docs.osgi.org/whitepaper/whiteboard-pattern/