OSGi Core Release 8 is now final and published

The specifications, reference implementations, and compliance tests for OSGi Core Release 8 have been approved as final by the members of the OSGi Alliance as one of the final actions of the OSGi Alliance as we transition the mission to the OSGi Working Group at the Eclipse Foundation.

You can find the online version of the Core Release 8 specification on the OSGi Specification Project Documentation website. A PDF version is also available for download. Javadoc is also available and the artifacts are now available on Maven Central.

As part of the mission transfer to the OSGi Working Group, the work will of course be done in open source projects. So I have recently submitted project proposals at Eclipse to form the OSGi Specification Project and the OSGi Technology Project. The OSGi Specification Project will be responsible for OSGi specification development and evolution and will take direction from the OSGi Working Group as a specification project under the Eclipse Foundation Specification Process. The OSGi Technology Project will host OSGi technology-related (non-specification) projects like the exciting osgi-test project we recently presented at EclipseCon 2020.

One of the immediate results of moving the mission to Eclipse is that we have now made the OSGi git repositories public. Check out the OSGi GitHub organization and, in particular, the OSGi Specification Project Build repository.

Finally, I would like to encourage everyone to consider joining the OSGi Working Group and get involved in continuing to evolve the OSGi specifications. Your company can join and individuals can also join as well. Work on Compendium Release 8 was well underway in the OSGi Alliance when we started the mission transfer to the OSGi Working Group at the Eclipse Foundation and we will get right back at it once we get the OSGi Working Group and OSGi Specification Project bootstrapped at Eclipse. I hope to see you there!

OSGi R7 Highlights: Java 9 Support

With the Java 9 release, the Java Platform Module System (JPMS) is a major feature that impacts many areas of the Java Platform.  The JPMS is used to modularize the class libraries provided by the Java Platform.  In addition, it has been proposed that the JPMS can be used by developers to modularize their own applications, although the OSGi Alliance cautions against its use here.

Meanwhile the OSGi Core specification has provided a stable platform for developing modular Java applications for well over 17 years.  The OSGi Core R7 specification continues this tradition by providing updates to the OSGi Core specification which are fully compatible with previous versions of the OSGi Core specification.  OSGi Core R7 Framework implementations will be able to run on top of Java 9 without requiring any changes to existing OSGi application bundles (assuming no internal packages from the Java platform are being used).

The OSGi Core R7 specification has a couple of new features that build upon some features new to Java 9.  This includes support for multi-release JARs and runtime discovery of packages provided by the JPMS modules loaded by the platform.  First I will tell you about the multi-release JAR support.

Multi-Release JAR Support

Java 9 introduces a new type of JAR called a multi-release JAR.  A multi-release JAR file allows for a single JAR to support multiple major versions of the Java platform. For example, a multi-release JAR file can depend on both the Java 8 and Java 9 major platform releases, where some class depend on APIs in Java 8 and other class depend on APIs in Java 9.

The purpose of multi-release JARs is to support alternative implementation of select classes to deal with changes in the visible APIs of the Java platform.  That is, it is not meant as a means to supply new function or new API on different Java platform versions. As a best practice new APIs should be released in an updated version of an existing bundle or released as part of a new bundle.

The OSGi Core R7 specification adds support for multi-release JAR files. An OSGi bundle file can be a multi-release JAR by adding the following manifest header to the bundle manifest:

 Multi-Release: true

Any JAR included on the bundle class path can also be independently declared as a multi-release JAR by including the same manifest header:

  Multi-Release: true

in its own JAR manifest. For example, an OSGi bundle can include third-party multi-release JARs on its own bundle classpath. In this case the third-party multi-release JARs will be loaded as multi-release JARs by the OSGi Framework even if the bundle JAR itself is not a multi-release JAR.

When a JAR on the bundle class path is a multi-release JAR, then the Framework must search the JAR's versioned directories when attempting to locate a class or resource in the JAR. For more information on how classes and resources are loaded from multi-release JARs see the multi-release JAR documentation.

Different implementations of a Java class for different versions of the Java platform can affect the requirements of the bundle.  For example, what packages need to be imported from the running Java platform. The R7 Framework supports supplemental manifest files that can be used to specify alternative values for the Import-Package and Require-Capability manifest headers for different versions of the Java platform.

When a bundle file is a multi-release JAR, then the Framework must also look for a supplemental manifest file, OSGI-INF/MANIFEST.MF, in the versioned directories. For example:

  META-INF/versions/9/OSGI-INF/MANIFEST.MF

The Framework finds the highest versioned manifest available in the multi-release JAR which can be applied to the running Java platform and uses the Import-Package and Require-Capability manifest headers as replacements for the values specified in the bundle's manifest.

The purpose of the supplemental manifest is to specify requirements on capabilities provided by different versions of the Java platform which are needed by the implementation classes for that Java platform version. As a best practice, the supplemental manifests should not contain additional requirements on capabilities which are not supplied by the Java platform for the Java version associated with the supplemental manifest.

For more information about multi-release JAR support you can refer to the following sections of the OSGi Core R7 specification:

1. Bundle File Multi-release JAR
2. Bundle class path Multi-release Container

Runtime Discovery of Java Platform Packages

Now that the Java platform is modularized in Java 9, the runtime can be configured to load only the modules which are required by the application.  This allows for a smaller custom runtime that is tailored to the needs of a specific application.  The set of java.* packages provide by the running Java platform is no longer constant for a specific version of the Java platform.

Bundles typically depend on different packages by using requirements specified with the Import-Package header, but as of the OSGi Core R4 specification, bundles have been prohibited from using Import-Package to specify requirements on java.* packages.  Instead bundles have used the osgi.ee namespace (or the deprecated Bundle-RequiredExecutionEnvironment header) to specify a dependency on specific versions of the Java platform. It has been assumed that the set of java.* packages available for a specific version of the Java platform is constant and therefore there is no need to specify additional requirements on specific java.* packages.

With Java 9 this is no longer a valid assumption.  With OSGi Core R7, the osgi.ee namespace should only be used to specify the minimal level of the Java platform required by the Java class bytecode level included in the bundle.  Dependencies on specific java.* packages should to be specified using the Import-Package header.

The OSGi Core R7 specification now allows bundles to use the Import-Package header to import java.* packages.  The OSGi Framework implementation is required to discover the all available java.* packages in the running Java platform and automatically provide the java.* package as a separate system packages (see the system packages configuration property).  The system bundle is the only bundle that is allowed to provide java.* packages. It is an error for normal bundles to attempt to export java.* packages using the Export-Package header.

When importing java.* packages only the package name should be specified, no other matching attributes are needed.  For example:

  Import-Package: java.sql

Note that bundle class loaders in R7 continue to have full visibility to all available java.* packages available in the running Java platform.  The class and resource loads for the java.* packages will continue to be boot delegated by the framework implementation even when the bundle does not specify any Import-Package header. The java.* package requirements are only necessary to prevent a bundle from resolving if the necessary java.* packages are not available at runtime.  For example, if a bundle must only resolve if the java.sql module is loaded.

For more information about java* package support you can refer to the following sections of the OSGi Core R7 specification:

1. Execution Environment
2. Parent Delegation 

Bundles Supporting R6 and R7 Frameworks

The OSGi Core R6 specification prohibits bundles from importing java.* packages and will throw a BundleException if such a bundle is attempted to be installed. Bundles that must work on OSGi R6 and earlier Frameworks but also want to run on R7 Frameworks have two options:

1. Do not import the java.* packages.  The bundle will continue to work on an R7 framework because java.* packages are still boot delegated by the bundle class loaders. This implies the bundle may resolve when running on Java 9 even when all the java.* packages required by the bundle are not available.
2. Package the bundle as a multi-release JAR to allow alternative values for Import-Package to be specified.

A bundle that must still be able to be installed on an OSGi R6 or earlier Framework must not specify java.* packages in their main bundle manifest Import-Package header. A supplemental manifest must also be included to be able to specify java.* package imports.

This supplemental manifest must contain the original Import-Package header from the main bundle manifest as well as any java.* package required by the bundle. When running on an OSGi R6 Framework, this supplemental manifest will be ignored and therefore the bundle will install successfully as the bundle did not specify an import for the java.* packages in the main manifest.

If a bundle will always require OSGi R7 or greater Framework, there is no need to use multi-release JARs for this purpose even when the bundle must support Java 8 or earlier. This is because OSGi R7 frameworks must provide the java.* package capabilities on all Java platform versions the framework implementation supports. As long as the java.* package is available on the running Java platform, the bundle with an import for the java.* package must resolve.

I advise using option 1 here because it is by far the most simple approach.  If you really have a strong need to use this new R7 feature then I recommend you do not try to produce a single bundle version that supports both R6 and R7 Frameworks.  Instead simply release a new version of your bundle that only supports OSGi R7 or greater Frameworks.

In Summary

The OSGi Core R7 release continues the tradition by providing a stable modular platform with updates to the OSGi Core specification which are fully compatible with previous versions of the OSGi Core specification.  OSGi bundle developers can continue to develop advanced modular applications and run their applications on Java 9 without having to commit to migrating to the green initial release of JPMS.

The OSGi Core R7 specification does add new functionality in support of new features available in Java 9, such as the support for multi-release JARs and importing of java.* packages.  The OSGi specifications will continue to evolve in order to provide the necessary tools for developing advanced modular applications.

OSGi R7 Highlights: Proposed Final Draft Now Available

I am pleased to announce that the OSGi Alliance has published the Proposed Final Drafts of the OSGi Core R7 and Compendium R7 specifications. We expect that the final versions of these specifications will be published in April 2018 after OSGi Alliance member approval.

The R7 release builds upon the long history of the OSGi Alliance’s leadership in Java modularity and reflects a significant amount of effort from the technical members of the OSGi Alliance expert groups over the last 2 years. Thanks go to all of the members who have contributed to this release.

R7 represents many significant new features and capabilities and provides an open standards-based approach for a number of modern valuable and simple-to-use technologies important to Java developers.

This blog post is the start of a series of blog posts from the technical experts at the OSGi Alliance to share some of the key highlights of R7. The blog posts in this series will come out over the coming weeks and cover the following topics:

• Java 9 Support – Multi-release JAR support and runtime discovery of the packages provided by the JPMS modules loaded by the platform.
• Declarative Services – Constructor injection and component property types.
• JAX-RS – A whiteboard model for building JAX-RS microservices.
• Converter – A package for object type conversion.
• Cluster Information – Support for using OSGi frameworks in clustered environments.
• Transaction Control – An OSGi model for transaction life cycle management.
• Http Whiteboard – Updates to the Http Whiteboard model.
• Push Streams and Promises – The Promises packages is updated with new methods and an improved implementation and the new Push Streams package provides a stream programming model for asynchronously arriving events.
• Configurator and Configuration Admin – Configuration Admin is updated to support the new Configurator specification for delivering configuration data in bundles.
• LogService – A new logging API is added which supports logging levels and dynamic logging administration and a new Push Stream-based means of receiving log entries is also added.
• Bundle Annotations – Annotations that allow the developer to inform tooling on how to build bundles.
• CDI – Context and Dependency Injection support for OSGi developers.

Stay tuned and I hope you find the technical information in the blog post series useful to you as developers!

New OSGi R7 spec drafts published

In the OSGi Enterprise and Core Platform Expert Groups we are working hard on the upcoming R7 specifications, which are planned to be released later this year. Recently the OSGi Alliance published the current drafts of some these specs.

In this blog post you can read a very brief summary of what is new, for all the further details look in the drafts.
In the Enterprise draft specification - new and changed are:

• Remote services (ch 100) - has been enhanced to include new standard intents that require minimum remote service capabilities, asynchronous processing or a private remote connection.
• Declarative Services (ch 112) - this spec has received a substantial update, including delayed object reclamation, component property type enhancements and other updates.
• JPA Service (ch 127) - has been updated to support JPA 2.1, supports standard JPA 2.1 configuration properties with the EntityManagerFactoryBuilder and now specifies a number of standard Capabilities to integrate better with the Resolver.
• new Transaction Control Service (ch 147) - this new specification provides an improved mechanism to perform work in a transaction scope. It provides a higher level of abstraction than the existing JTA integration specification, and makes it really easy to write transactional code, especially when using Java 8 lambdas.
• new Configurator Specification (ch 150) - the configurator makes it possible to store configuration data for Configuration Admin driven entities in a bundle. The configuration is stored in a spec-defined format inside the bundle and can be used to configure any number of bundles, components, services or other entities via the Configuration Admin Service.
• Promises specification (ch 705) - this spec is now updated with a number of improvements including timeouts, easier exception handling and callbacks.
• new Push Streams (ch 706) -  This new spec provides a programming model similar to Java 8 pull-based streams, but then using a push model. This can be very useful for data such as events that arrives asynchronously. The data can be mapped, buffered, splitted, filtered or otherwise processed before it gets pushed to the receiver. 
• new Converter (ch 707) - This spec defines a portable converter that can convert nearly everything to nearly anything. Especially useful then converting untyped data such as a Map to a typed API such as an interface, DTO or annotation. Converters can also be customized to support user-defined types or to create deviations from standard behavior.

The Core Specification has also been updated. Besides a number of small changes and improvements - see the Changes sections in each chapter for details - the Core spec now defines new Annotations in the org.osgi.annotation.bundle package that can be used to define bundle headers from inside the Java code of your bundle. For example, these can be used to declare requirements and capabilities that your bundle could have or to declare which packages should be exported.

The R7 March 2017 drafts for the Core and Enterprise specs can now be downloaded from here: https://www.osgi.org/developer/specifications/drafts

Finally, not yet in the draft, but coming up as well are:

• Cluster Information Specification (previously known as Cloud Ecosystems), from RFC 183.
• CDI integration, you can read more about this in RFC 193.
• JAXRS integration, see RFC 217.
• HTTP Whiteboard Extensions, RFC 223.
• Resolver Service updates: RFC 224.
• Configuration Admin updates, RFC 227.

OSGi R7 early spec drafts available

Recently OSGi published the first early draft for the OSGi R7. While not all specs aimed for R7 are present yet, a few new ones have appeared that can be checked out. The new ones are:

• Chapter 147 - Transaction Control Service. This specification provides an improved mechanism to perform work in a transaction scope. It provides a higher level of abstraction than the extising JTA integration specification, which makes it really easy to write transactional code, especially when using Java 8 lambdas.
• Chapter 148 - Converter. Convert anything into everything, and back. A universal object converter which can be used to convert simple values between datatypes, but it can also be used to convert complex structures such as maps or DTOs to interfaces or annotations. Previously functionality such as this was already supported in DS, which allows you to access a component's configuration map via an annotation. Now, this can be used anywhere you like...
• Chapter 706 - Push Streams. These provide a programming model similar to Java 8 pull-based streams, but then using a push model. Useful for data such as events that arrives asynchronously. The data can be mapped, buffered, splitted, filtered or otherwise processed before it gets sent to the receiver. 

You can find the R7 early drafts at the OSGi website here: https://www.osgi.org/developer/specifications/drafts/

Opensource implementations are already starting to appear, check https://en.wikipedia.org/wiki/OSGi_Specification_Implementations for where to obtain OSGi specification implementations.

As always, these are early drafts. Things will definitely change in some of the details. If you want to learn more about these and other upcoming OSGi specifications, come and visit the OSGi Community Event at EclipseCon Europe in Ludwigsburg https://www.osgi.org/2016-osgi-community-event.