================================== 2023.09 Potassium Platform Upgrade ================================== This document describes the steps to help users upgrade from Argon to Potassium platform. Refer to `Managed Snapshot Integrated (MSI) project `_ upgrade patches for more information and hints for solutions to common problems not explicitly listed here. .. contents:: Contents Preparation ----------- JDK 17 Version ^^^^^^^^^^^^^^ 2023.09 Potassium, requires Java 17, both during compile-time and run-time. Make sure to install JDK 17 corresponding to at least ``openjdk-17.0.7``, and that the JAVA_HOME environment variable points to the JDK directory. 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 12.0.3 to 13.0.4. There should not be any reference to **org.opendaylight.odlparent**, except for 13.0.4. This includes custom feature.xml templates (``src/main/feature/feature.xml``), the version range should be "[13,14)" instead of "[11,12)", "[5.0.3,6)" or any other variation. .. code-block:: shell bump-odl-version odlparent 12.0.3 13.0.4 2. Update the direct yangtools version references from 10.0.4 to 11.0.1, There should not be any reference to **org.opendaylight.yangtools**, except for 11.0.1. This includes custom feature.xml templates (``src/main/feature/feature.xml``), the version range should be "[11,12)" instead of "[10,11)". .. code-block:: shell bump-odl-version yangtools 10.0.4 11.0.1 3. Update the MD-SAL version from 11.0.7 to 12.0.1. There should not be any reference to **org.opendaylight.mdsal**, except for 12.0.1. .. code-block:: shell bump-odl-version mdsal 11.0.7 12.0.1 4. Update the Controller version from 7.0.4 to 8.0.1. There should not be any reference to **org.opendaylight.controller**, except for 8.0.1. .. code-block:: shell bump-odl-version controller 7.0.4 8.0.1 5. Update the InfraUtils version from 5.0.3 to 6.0.2. There should not be any reference to **org.opendaylight.infrautils**, except for 6.0.2. .. code-block:: shell bump-odl-version infrautils 5.0.3 6.0.2 6. Update the AAA version from 0.17.7 to 0.18.1. There should not be any reference to **org.opendaylight.aaa**, except for 0.18.1. .. code-block:: shell bump-odl-version aaa 0.17.7 0.18.1 7. Update the NETCONF version from 5.0.4 to 6.0.3. There should not be any reference to **org.opendaylight.netconf**, except for 6.0.3. .. code-block:: shell bump-odl-version netconf 5.0.4 6.0.3 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 `potassium-mri `_ changes for any dependent project. Perform the following steps to save time when locally installing any dependent project: * For quick install: .. code-block:: shell mvn -Pq clean install * If previously installed, go offline and/or use the no-snapshot-update option. .. code-block:: shell mvn -Pq -o -nsu clean install Upgrade the ODL Parent ---------------------- The following sub-section describes how to upgrade to the ODL Parent version 13. Refer to the `ODL Parent Release Notes `_ for more information. Features ^^^^^^^^ Any version range referencing version 11 of ODL Parent must be changed to “[13,14)” for ODL Parent 13. .. code-block:: xml odl-guava ODL Parent Impacts ------------------ Upstream declarations removed ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The declaration of ``commons-lang`` dependency has been removed. Default annotation declarations removed ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``odlparent`` no longer declares ``spotbugs-annotations``, ``org.eclipse.jdt.annotation`` and ``modernizer-maven-annotations`` as ``provided`` dependencies. Downstreams will need to introduce these annotations as appropriate. YANG Tools Impacts ------------------ ``AugmentationIdentifer`` and ``AugmentationNode`` removed ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The class hierarchy of ``NormalizedNode`` has been updated to not contain augmented nodes in a separate ``AugmentationNode``, but rather keep them directly in the node being augmented. This results in a flatter NormalizedNode structure and makes constructing structures involving augmentations and reconciling them with ``EffectiveModelContext`` much more straightforward. See `YANGTOOLS-568 `__ for details. RFC7952 and RFC8528 support integrated into ``yang-data`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The interfaces supporting RFC7952 YANG annotations have been integrated into ``yang-data-api`` and ``yang-data-util`` artifacts. This rendered ``rfc7952-data-api`` and ``rfc7952-data-util`` artifacts empty and thus these have been removed. See `YANGTOOLS-1489 `__ for details. The interfaces supporting RFC8528 YANG schema mounts have been integrated into ``yang-data-api`` and ``yang-data-util`` artifacts. This rendered ``rfc8528-data-api`` and ``rfc8528-data-util`` artifacts empty and thus these have been removed. See `YANGTOOLS-1172 `__ for details. As part of these changes, following API changes have also been done in order to ease using these interfaces: * ``NormalizedNodeStreamWriterExtension`` has been renamed to ``NormalizedNodeStreamWriter.Extension`` * ``StreamWriterMetadataExtension`` has been renamed to ``NormalizedNodeStreamWriter.MetadataExtension`` * ``StreamWriterMountPointExtension`` has been renamed to ``NormalizedNodeStreamWriter.MountPointExtension`` * ``MountPointIdentifier`` has been removed with ``NormalizedMountPoint`` exposing its ``MountPointLabel`` directly Finally, the result of ``NormalizedNodeStreamWriter`` is now a combined structure, ``NormalizationResult``, which combines a mandatory ``NormalizedNode`` data tree, an optional ``NormalizedMetadata`` and an optional ``NormalizedMountPoints`` tree. For the purposes of receiving this the result, ``NormalizedNodeResult`` has been replaced with ``NormalizationResultHolder``. ``DataSchemaContextNode`` replaced with ``DataSchemaContext`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``yang.data.util.DataSchemaContextNode`` has been completely revamped and renamed to ``DataSchemaContext``. It is now an interface implemented completely internally, with a proper interface hierarchy. Implementations of these interfaces are given out by ``DataSchemaContextTree``. The resulting API is much easier to figure out and use, especially with proper documentation and naming not overlapping with other parts of YANG Tools. See `YANGTOOLS-1413 `__ for details. ``ExtensibleObject`` has been reworked ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This interface no longer exposes a ``ClassToInstanceMap``, but rather provides direct lookup and enumeration methods. Users need to be updated from performing .. code-block:: java ExtensibleObject obj; var extension = obj.getExtensions().getInstance(ExtensionType.class); to instead doing .. code-block:: java ExtensibleObject obj; var extension = obj.extension(ExtensionType.class); See `YANGTOOLS-1509 `__ for details. ``UsesNode.getRefines()`` exposes only descendant paths ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The return type was changed to return ``Set`` instead of ``Map``. Users relying on accessing target nodes need to perform the resolution themselves. See `YANGTOOLS-1518 `__ for details. ``YangTextSchemaSources`` is a ``CharSource`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``yang.model.api.repo.YangTextSchemaSource`` now operates on a stream of characters, not bytes. All users which instantiate sources from byte streams must specify the character set used. See `YANGTOOLS-1508 `__ for details. MD-SAL Impacts -------------- ``InstanceIdentifierBuilder`` renamed to ``InstanceIdentifier.Builder`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A long-standing bug, where a ``KeyedInstanceIdentifier`` could not be safely returned from ``InstanceIdentifierBuilder`` was fixed. As part of this fix, ``InstanceIdentifierBuilder`` was renamed to be an inner class, ``InstanceIdentifier.Builder``. There is also a corresponding ``InstanceIdentifier.KeyedBuilder``. See `MDSAL-798 `__ for details. ``BindingReflections.getModuleInfo()`` has moved ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This reflection-based method was moved to ``BindingRuntimeHelpers`` class, as all its users already interact with ``mdsal-binding-runtime-spi``. See `MDSAL-803 `__ for details. Convenience model artifacts removed ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The aggregating multi-module RFCs have been removed. Users declaring a dependency on any of ``rfc6991``, ``rfc8294``, ``rfc8342``, ``rfc8345``, ``rfc8346``, ``rfc8348``, ``rfc8349``, ``rfc8519``, ``rfc8520``, ``rfc8542``, ``rfc8776`` or ``rfc8795`` need to now update these references to individual modules' artifacts. See `MDSAL-823 `__ for details. ``BindingMapping`` moved ^^^^^^^^^^^^^^^^^^^^^^^^ ``binding.spec.naming.BindingMapping`` has been renamed and moved to ``yang.binding.contract.Naming``. See `MDSAL-804 `__ for details. ``IetfInetUtil.INSTANCE`` and ``IetfYangUtil.INSTANCE`` removed ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``IetfInetUtil`` and ``IetfYangUtil`` have been refactored so they now expose static utility methods not encapsulated in an object instance. All references to ``INSTANCE`` need to be removed: .. code-block:: java byte[] bytes; IetfYangUtil.INSTANCE.macAddressFor(bytes); becomes .. code-block:: java byte[] bytes; IetfYangUtil.macAddressFor(bytes); See `MDSAL-804 `__ for details. Binding ``Identifiable`` and ``Identifier`` renamed ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``yang.binding.Identifer`` has been renamed to ``yang.binding.Key`` and ``yang.binding.Identifiable`` has been renamed to ``yang.binding.KeyAware``. This change prevents confusion with ``yangtools.concepts`` interfaces with the same name. See `MDSAL-830 `__ for details. Controller Impacts ------------------ None.