1 Introduction

The OSGi Enterprise Expert Group (EEG) is chartered to define the technical requirements and specifications to tailor and extend the OSGi framework to address information technology software infrastructure use cases found in enterprise scenarios.

The EEG technical areas of concern include:

  • Scaling, including multi-container and multi-process environments

  • Distributed and/or federated service model for:

    • Multiple OSGi frameworks

    • External, heterogeneous systems

  • Requirements for extensions to the OSGi publish/find/bind service model

  • Enterprise-class life cycle and configuration management

  • Integration of established Java EE technology into OSGi

This specification is based on OSGi Core Release 7. The specification combines previously published, as well as new, OSGi services that address the common use cases of enterprise application and application server developers. It serves as a first reference point for the suggested audience when considering the use of OSGi in their environment to fulfill their own needs or to better serve the needs of their customers. This collection of services is taken from the complete set of available specifications and narrowed down to what can be relevant to the enterprise domain.

The services of the Enterprise Specification have been designed to integrate with OSGi and cooperate with each other. None of the listed service specifications is mandatory; all service specifications are optional. However, services provided must follow their specification completely.

It is not suggested, or expected, that an enterprise solution will incorporate support for all listed specifications, instead a customized subset to satisfy the requirements at hand is recommended. A solution can further include other core and compendium services that are not listed as part of the Enterprise Specification. The selection of appropriate services should be driven by requirements and use cases.

The Enterprise Specification includes the recommended specifications for a number of areas. Together they address use-cases found in the enterprise context and provide a powerful set of tools to build enterprise OSGi deployments.

These Enterprise Specification areas are described in the following sections.

1.1 Overview of Services

1.1.1 Dependency Injection Models

While the OSGi framework API is relatively simple to use, it is still considered infrastructure that can bleed into the application code of a bundle. The OSGi Enterprise Specification therefore provides Dependency Injection models. This ensures decoupling of the application code from the OSGi APIs; they provide an OSGi bundle programming model with minimal implementation dependencies and virtually no accidental complexity in the Java code.

1.1.2 Distributed Services

The OSGi framework provides a local service registry for bundles to communicate through service objects, where a service is an object that one bundle registers and another bundle looks up. The Enterprise Specification enhances this model by defining endpoints that represent services hosted in a remote systems. It allows for seamless access to remote services within the OSGi framework without changing the service layer. The remote system may or may not be based on OSGi.

The Enterprise Specification includes the specifications of:

  • Remote Services - The Remote Services specification defines a number of service properties that participating bundles can use to convey information to a distribution provider. The distribution provider creates endpoints that are accessible to remote clients or registers proxies that access services hosted external to the OSGi framework. See chapter Remote Services.

  • Remote Service Admin Service Specification - The Remote Services Admin Service Specification defines an API for the distribution provider and discovery of services in a network. A management agent can use this API to provide an actual distribution policy. This management agent can export and import services as well as discovering services in the network. See Remote Service Admin Service Specification.

  • Cluster Information Specification - This specification defines services that facilitate the discovery, introspection and management of a cluster of nodes in a networked environment. This applies to Cloud environments as well as Embedded and IoT use cases where multiple nodes are exist that need to be orchestrated into performing a coordinated set of functionalities. See Cluster Information Specification.

  • JAX-RS Whiteboard Specification - Support for the development of REST-style microservices is provided through the integration of JAX-RS technology in the JAX-RS Whiteboard Specification. This defines a model to provide microservice endpoints using the OSGi services-based whiteboard model. See JAX-RS Whiteboard Specification.

1.1.3 Web Applications and HTTP Servlets

Current Enterprise Java architectures almost always require support for web technologies in the form of Java Servlets or Web Applications. The Enterprise Specification includes three complementary service specifications in support of web technologies.

  • Web Applications Specification - The Web Application specification provides support for web applications written to the Servlet 2.5 specification as well as the JSP 2.1 specification. This specification details how web applications packaged as a WAR or as bundles (WABs) can be installed into an OSGi framework, as well as how this application can use OSGi services. See Web Applications Specification.

  • Http Service Specification - Bundle developers typically need to develop communication and user interface solutions for standard technologies such as HTTP, HTML, XML, and servlets. The Http Service supports two standard techniques for this purpose: registering servlets and registering resources. See Http Service Specification.

  • Http Whiteboard Specification - The [1] Whiteboard Pattern pattern has shown to be a powerful and flexible mechanism for registering customized functionality with a container. The Http Whiteboard Specification allows the registration of Servlets, Servlet Filters, Resources and Servlet-related listeners via the Whiteboard pattern, providing a convenient approach to working with servlets to the Http Service Specification. See Http Whiteboard Specification.

1.1.4 Asynchronous Processing and Event models

A number of specifications focus specifically on asynchronous programming and executing of components, as well as the sending and receiving of events.

  • Event Admin Service Specification - The Event Admin service provides an inter-bundle communication mechanism. It is based on a event publish and subscribe model, popular in many message based systems. See Event Admin Service Specification.

  • Asynchronous Service Specification - Asynchronous processing can be the key to scalability for large enterprise applications, especially under heavy load. OSGi Services have traditionally followed the Java interface-based design which by default provides synchronous semantics. The Asynchronous Services specification adds an asynchronous programming model to new and existing OSGi services. See Asynchronous Service Specification.

  • Promises Specification - Many JavaScript applications use Promises-based APIs to facilitate asynchronous processing of a workflow in which executions are time consuming or subject to waiting for I/O operations. The Promises specification defines a Promises API for use in OSGi applications. The Promises API is used by other specifications, such as the Asynchronous Services specification, but can also be used independently. See Promises Specification.

  • Push Stream Specification - This specification defines a library supporting the handling of push-based event streams. It focuses on reactive programming and builds on the Promises specification. As with Promises, the Push Streams can be used both inside an OSGi framework as well as outside. See Push Stream Specification.

1.1.5 Management and Configuration services

Support for managing the servers and their applications is essential to all enterprise systems. The Enterprise Specification includes several services addressing the need to manage the framework from the outside as well as configuring individual bundles and applications from within the OSGi framework.

1.1.6 Naming and Directory services

Naming and directory services are well established and useful tools in enterprise applications. The Enterprise Specification includes the:

  • JNDI Services Specification - The Java Naming and Directory Interface (JNDI) is a registry technology in Java applications, both in the Java SE and Java EE space. JNDI provides a vendor-neutral set of APIs that allow clients to interact with a naming service. See JNDI Services Specification.

1.1.7 Database Access

There are multiple approaches available to model and persist data in databases. The Enterprise Specification includes support for the common technologies:

1.1.8 Transaction Support

The support for transactions in Java is well defined outside of the OSGi specification. The Enterprise Specification includes the:

  • JTA Transaction Services Specification - This specification provides the User Transaction, Transaction Manager, and Synchronization Registry services, which are based on their counterparts in the Java EE™ JTA Specifications. These services can be used to demarcate transaction boundaries, enlists durable and volatile resources, and provides transactional aware code to influence the outcome of a transaction and synchronize with the ending of a transaction. See JTA Transaction Services Specification.

  • Transaction Control Service Specification - This specification adds a concise and convenient programming model to work with ACID Transactions. Rather than taking a purely declarative approach as is done in some other Transaction solutions, the Transaction Control Service Specification defines a simple programming model to execute specific parts of code under transactional scope. It works very well with Java™ lambdas. See Transaction Control Service Specification.

1.1.9 Miscellaneous Supporting Services

Services providing solutions to common infrastructure requirements include:

  • Log Service Specification - Provides a general purpose message logger for the OSGi framework. See Log Service Specification.

  • XML Parser Service Specification - Addresses how the classes defined in JAXP can be used in an OSGi framework. See XML Parser Service Specification.

  • Service Loader Mediator Specification - Addresses common problems of bundles that rely on the JRE provided Service Loader API to load custom Service Provider Implementations. This specification describes how to use the service registry for lookup of Service Providers as well as a solution for existing code to continue functioning using Service Loader API in a OSGi environment. See Service Loader Mediator Specification.

  • Coordinator Service Specification - The Coordinator service provides a mechanism for multiple parties to collaborate on a common task without a priori knowledge of who will collaborate in that task. The service provides a rendezvous for an initiator to create a Coordination where collaborators can decide to participate. When the Coordination is ended, all participants are informed. See Coordinator Service Specification.

  • Converter Specification - The Converter Specification provides a uniform API to convert a given Java object into a myriad of other representations. Conversions include from untyped data, such as a configuration map, into a typed instance such as an annotation or interface. Or between various types of scalars, arrays or collections. The converter can also be customized to perform domain-specific conversions. See Converter Specification.

1.2 Application and Provisioning Support

The term 'application' may mean different things to different people, therefore, rather than defining what an application is, the OSGi specification provides a set of enabling services and specifications to aid in the definition, composition, deployment, and governance of a group of bundles and resources in an OSGi environment. The specifications are essential building blocks and provide from low level resolution to higher level composition abstractions that a management agent can use to build the necessary tools for managing OSGi applications.

  • Repository Service Specification - The Repository specification provides a standard API to access (possibly remote) repositories. Resources can be obtained from the repository by specifying declarative requirements, which might include for example 'provide all resources that export a given package' or 'provide the bundle with the given symbolic name and version', but can also be used with any other generic capabilities. While the Repository API can be used on its own, in conjunction with the Resolver Specification it provides the capability to manage retrieval of external resources during the resolution process. Typically one or multiple repositories provide the metadata for the Resolver service to draw the resolution from. A management agent can then use the repositories to apply the result of the resolution. See Repository Service Specification.

  • Subsystem Service Specification - The core framework defines the life cycle of bundles and their relationships, but it is missing the ability to define a common life cycle and scoping rules for a set of bundles that are conceptually tied together. The Subsystems Specification provides the ability not only to group multiple bundles into a single manageable entity, but furthermore include arbitrary resources in this grouping. This allows for complete isolation as well as various sharing models of code, services, and resources through a management agent. See Subsystem Service Specification.

1.3 Reader Level

This specification is written for the following audiences:

  • Application developers

  • Framework and system service developers (system developers)

  • Architects

This specification assumes that the reader has at least one year of practical experience in writing Java programs. Experience with enterprise systems and server-environments is a plus. Application developers must be aware that the OSGi environment is significantly more dynamic than traditional desktop or server environments.

System developers require a very deep understanding of Java. At least three years of Java coding experience in a system environment is recommended. A Framework implementation will use areas of Java that are not normally encountered in traditional applications. Detailed understanding is required of class loaders, garbage collection, Java 2 security, and Java native library loading.

Architects should focus on the introduction of each subject. This introduction contains a general overview of the subject, the requirements that influenced its design, and a short description of its operation as well as the entities that are used. The introductory sections require knowledge of Java concepts like classes and interfaces, but should not require coding experience.

Most of these specifications are equally applicable to application developers and system developers.

1.4 Version Information

This document is the Enterprise Specification for the OSGi Enterprise Release 7.

1.4.1 OSGi Core Release 7

This specification is based on the OSGi Core Release 7. This specification can be downloaded from:

https://docs.osgi.org/specification/

1.4.2 Component Versions

Components in this specification have their own specification version, independent of this specification. The following table summarizes the packages and specification versions for the different subjects.

Table 1.1 Packages and versions

Item Package Version
100 Remote Services - Version 1.1
101 Log Service Specification

org.osgi.service.log

org.osgi.service.log.admin

org.osgi.service.log.stream

Version 1.4
102 Http Service Specification org.osgi.service.http Version 1.2
104 Configuration Admin Service Specification

org.osgi.service.cm

org.osgi.service.cm.annotations

Version 1.6
105 Metatype Service Specification

org.osgi.service.metatype

org.osgi.service.metatype.annotations

Version 1.4
107 User Admin Service Specification org.osgi.service.useradmin Version 1.1
110 Initial Provisioning Specification org.osgi.service.provisioning Version 1.2
112 Declarative Services Specification

org.osgi.service.component

org.osgi.service.component.annotations

org.osgi.service.component.propertytypes

org.osgi.service.component.runtime

org.osgi.service.component.runtime.dto

Version 1.4
113 Event Admin Service Specification

org.osgi.service.event

org.osgi.service.event.annotations

org.osgi.service.event.propertytypes

Version 1.4
122 Remote Service Admin Service Specification

org.osgi.service.remoteserviceadmin

org.osgi.service.remoteserviceadmin.namespace

Version 1.1
123 JTA Transaction Services Specification - Version 1.0
124 Management Model Specification for JMX™ Technology org.osgi.jmx1 Version 1.1
125 Data Service Specification for JDBC™ Technology org.osgi.service.jdbc Version 1.0
126 JNDI Services Specification org.osgi.service.jndi Version 1.0
127 JPA Service Specification

org.osgi.service.jpa

org.osgi.service.jpa.annotations

Version 1.1
128 Web Applications Specification - Version 1.0
130 Coordinator Service Specification org.osgi.service.coordinator Version 1.0
132 Repository Service Specification org.osgi.service.repository Version 1.1
133 Service Loader Mediator Specification org.osgi.service.serviceloader Version 1.0
134 Subsystem Service Specification org.osgi.service.subsystem Version 1.1
135 Common Namespaces Specification

org.osgi.namespace.contract

org.osgi.namespace.extender

org.osgi.namespace.implementation

org.osgi.namespace.service

org.osgi.namespace.unresolvable

Version 1.2
137 REST Management Service Specification

org.osgi.service.rest

org.osgi.service.rest.client

Version 1.0
138 Asynchronous Service Specification

org.osgi.service.async

org.osgi.service.async.delegate

Version 1.0
140 Http Whiteboard Specification

org.osgi.service.http.whiteboard

org.osgi.service.http.whiteboard.annotations

org.osgi.service.http.whiteboard.propertytypes

org.osgi.service.http.context

org.osgi.service.http.runtime

org.osgi.service.http.runtime.dto

Version 1.1
147 Transaction Control Service Specification

org.osgi.service.transaction.control

org.osgi.service.transaction.control.jdbc

org.osgi.service.transaction.control.jpa

org.osgi.service.transaction.control.recovery

Version 1.0
148 Cluster Information Specification

org.osgi.service.clusterinfo

org.osgi.service.clusterinfo.dto

Version 1.0
150 Configurator Specification

org.osgi.service.configurator

org.osgi.service.configurator.annotations

org.osgi.service.configurator.namespace

Version 1.0
151 JAX-RS Whiteboard Specification

org.osgi.service.jaxrs.runtime

org.osgi.service.jaxrs.runtime.dto

org.osgi.service.jaxrs.whiteboard

org.osgi.service.jaxrs.whiteboard.annotations

org.osgi.service.jaxrs.whiteboard.propertytypes

org.osgi.service.jaxrs.client

Version 1.0
152 CDI Integration Specification

org.osgi.service.cdi

org.osgi.service.cdi.annotations

org.osgi.service.cdi.propertytypes

org.osgi.service.cdi.reference

org.osgi.service.cdi.runtime

org.osgi.service.cdi.runtime.dto

org.osgi.service.cdi.runtime.dto.template

Version 1.0
702 XML Parser Service Specification org.osgi.util.xml Version 1.0
705 Promises Specification

org.osgi.util.promise

org.osgi.util.function

Version 1.1
706 Push Stream Specification

org.osgi.util.pushstream

Version 1.0
707 Converter Specification org.osgi.util.converter Version 1.0

When a component is represented in a bundle, a version attribute is needed in the declaration of the Import-Package or Export-Package manifest headers.

1.4.3 Note

  1. The org.osgi.jmx sub-packages are individually versioned to be aligned with the service they manage.

1.5 References

1.6 Changes