Silicon Platform Upgrade

This document describes the steps to help users upgrade from Aluminium to Silicon planned platform. Refer to Managed Release Integrated (MRI) project upgrade patches for more information.

Preparation

JDK 11 Version

Silicon requires Java 11, both during compile-time and run-time. Make sure to install JDK 11 corresponding to at least openjdk-11.0.8, and that the JAVA_HOME environment variable points to the JDK directory.

InfraUtils is a MRI project

Unlike in previous releases, the InfraUtils project has joined the MRI family at the end of Aluminium Simultaneous Release cycle. Going forward it is an error to depend on any org.opendaylight.infrautils with a -SNAPSHOT version.

Version Bump

Before performing platform upgrade, do the following to bump the odlparent versions (for example, bump-odl-version):

  1. Update the odlparent version from 7.0.5 to 8.1.1. There should not be any reference to org.opendaylight.odlparent, except for 8.1.1. This includes custom feature.xml templates (src/main/feature/feature.xml), the version range should be “[8.1,9)” instead of “[8,9)”, “[5.0.3,6)” or any other variation.

bump-odl-version odlparent 7.0.5 8.1.1
  1. Update the direct yangtools version references from 5.0.5 to 6.0.5, There should not be any reference to org.opendaylight.yangtools, except for 6.0.5. This includes custom feature.xml templates (src/main/feature/feature.xml), the version range should be “[6,7)” instead of “[5,6)”.

bump-odl-version odlparent 5.0.5 6.0.5
  1. Update the MD-SAL version from 6.0.4 to 7.0.6. There should not be any reference to org.opendaylight.mdsal, except for 7.0.6.

bump-odl-version odlparent 6.0.4 7.0.6
  1. Update the Controller version from 2.0.3 to 3.0.7. There should not be any reference to org.opendaylight.controller, except for 3.0.7.

bump-odl-version odlparent 2.0.3 3.0.7
  1. Update the InfraUtils version from 1.8.0 to 1.9.6. There should not be any reference to org.opendaylight.infrautils, except for 1.9.6.

bump-odl-version odlparent 1.8.0 1.9.6

Install Dependent Projects

Before performing platform upgrade, users must also install any dependent project. To locally install a dependent project, pull and install the respective silicon-mri changes for any dependent project.

Perform the following steps to save time when locally installing any dependent project:

  • For quick install:

mvn -Pq clean install
  • If previously installed, go offline and/or use the no-snapshot-update option.

mvn -Pq -o -nsu clean install

Upgrade the ODL Parent

The following sub-section describes how to upgrade to the ODL Parent version 4. Refer to the ODL Parent Release Notes for more information.

Features

Any version range referencing version 7 of ODL Parent must be changed to “[8,9)” for ODL Parent 8.1.

<feature name="odl-infrautils-caches">
    <feature version="[8,9)">odl-guava</feature>
</feature>

ODL Parent Impacts

Enforcing maven-modernizer-plugin

ODL Parent has switched maven-modernizer-plugin to enforcing mode and upgraded the rules to reflect Java 11 requirement. The enforcement can be switched off on a per-artifact basis using:

<properties>
    <odlparent.modernizer.enforce>false</odlparent.modernizer.enforce>
</properties>

YANG Tools Impacts

SchemaContext is being retired (continued)

After many years of development and incremental updates, this release marks the start of the transition away from SchemaContext. The object model exposed by it is problematic in more ways than one. The replacement construct is EffectiveModelContext, which operates on EffectiveStatement and its related interfaces. EffectiveModelContext retains its SchemaContext trait for the duration of the transition and can be directly used in that capacity. Users are encouraged to update their interfaces to accept and give out EffectiveModelContext instances.

In this release this effort resulted in removal of SchemaContextProvider interface and vast majority of sites now require an EffectiveModelContext.

Illegal YANG pattern statements are rejected

YANG parser will no longer silently ignore syntactically-illegal patterns. This may flush out new non-compliant models. For further details see the corresponding issue

MD-SAL Impacts

Binding DTOs enforce non-null keys

Binding DTOs (data transfer objects), created through builders for a keyed list now properly enforce non-null key attributes. This means any code that fails to properly set up either withKey() or individual component leaf values will throw a NullPointerException like this:

In order to resolve this, check the model involved. It will look something like this:

What the exception is indicating that the NodeBuilder does not have id set, so the resulting Node cannot be constructed, because it has to have a NodeKey for which id is mandatory.

With that knowledge, you should examine the caller and understand how the builder is initialized.

This change will typically affect incorrect test data, as production values tend to be validated on receiver side and would report this error later down the road. For further details see this MD-SAL issue.

Augmentation tracking has been reworked

As part of larger life-cycle activities, a number of implementation details have changed to the point as to render the distinction between Augmentable and AugmentationHolder interfaces superfluous. AugmentationHolder has therefore been completely integrated into Augmentable allowing efficient implementation classes and easier augmentation tracking. For further details see this MD-SAL issue.

DOMNotificationRouter implementation has been reworked

The default implementation of router, which is used for disseminating YANG notifications inside the system, was been reimplemented. The new implementation does not use LMAX Disruptor, but rather is based on QueuedNotificationManager. For further details see this MD-SAL issue.

DOM interfaces no longer use SchemaPath identification

Interfaces for invocation of RPCs and actions, as well as publishing notifications have switched from using SchemaPath to using either QName or SchemaNodeIdentifier.Absolute. This allows more efficient invocation and removes ambiguity around relative SchemaPath being or not being allowed.

Removed packaging of draft ietf-topology extensions

As part of further cleanup, standardization and stabilization of MD-SAL interfaces, four models from draft-clemm-netmod-yang-network-topo-01 have been removed: ietf-topology-isis, ietf-topology-ospf, ietf-ted and ietf-topology-l3-unicast-igp. For further details see this MD-SAL issue.

Final release to include widened Integer/Long/BigInteger compatibility

Magnesium introduced a change in how uint8, uint16, uint32 and uint64 types are mapped to Java. Previously this would be mapped to Short, Integer, Long and BigInteger respectively. With Magnesium these are mapped to dedicated yang.common.Uint{8,16,32,64}, whose design matches general design of java.lang.Integer.

This change obviously requires some amount adaptation, which is why compatibility setter methods and constructors are generated, each of which converts the wide type to its native mapping, undoing the widening.

Such conversions are costly in terms of both CPU usage, but also cost us quite a bit in terms of class size. They also introduce ambiguity, which hinders fluent use native methods.

Compatibility methods have been deprecated for removal since their inception, and are now officially scheduled for removal in the next major release, Phosphorus. The removal is tracked in this MD-SAL issue.

Final release to include List/Map compatibility mappers

Aluminium introduced a change in how a keyed list YANG construct is mapped to Java. Previously such lists were mapped to java.util.List. This mapping resulted in incorrect equals() behavior of generated DTOs for cases the list’s ordering is not specified. Furthermore it was not possible to locate entries of such lists through their key. Corrected mapping to java.util.Map solves both problems.

A typical impacted YANG snippet would look something like:

Since the ordering is left up to the system, YANG tools uses hash maps to track such lists, resulting in inherently unstable iteration order.

If the order of entries is significant, then this needs to be expressed in the model like this:

which maps to java.util.List again.

Aluminium-generated code provides compatibility for users using List to access a Map. This layer indexes the presented list into an immutable Map and uses that value. This has both performance and correctness implications.

Since java.util.List offers a simple way of building up a set of entries without having to deal with entry keys, a migration utility is provided in the form of org.opendaylight.yangtools.yang.binding.util.BindingMap, which allows almost seamless migration, especially for unit test code.

The compatibility setters have been deprecated for removal since they inception and are now scheduled for removal. Aluminium is the last release shipping with them. They will be removed in the next release, Phosphorus. The removal is tracked in this MD-SAL issue.

Controller Impacts

Akka remote configuration

Because of the akka upgrade to 2.6.x in Silicon, remote TCP configuration changed from netty.tcp to classic.netty.tcp:

classic.netty.tcp {
  hostname = "127.0.0.1"
  port = 2550
}

Use of odl:type in Blueprint is discouraged

This property has been used for discerning between various implementations of MD-SAL services present in the OSGi service registry. As these services have been consolidated in the past couple of releases, the use of this qualifier is discouraged. While some services are advertised with this property set, it is no longer considered a binding contract and future releases, even minor, will most likely stop adding this property.

Users are advised to stop specifying this attribute when making references to OSGi services.

Akka 2.6.12

This release integrates akka-2.6.12, which is a major upgrade from previous akka-2.5.32. Most notably the auto-downing feature is no longer present and has been replaced by integrating the split-brain resolver. Please refer to clustering setup guide for required configuration updates.