docs/release-notes/upgrade-process.rst

   1 ==========================
   2 Magnesium Platform Upgrade
   3 ==========================
   4
   5 This document describes the steps to help users upgrade to the
   6 Magnesium planned platform. Refer to `Managed Release Integrated (MRI)
   7 project <https://git.opendaylight.org/gerrit/q/topic:magnesium-mri>`_
   8 for more information.
   9
  10 .. contents:: Contents
  11
  12 Preparation
  13 -----------
  14
  15 JDK 11 Version
  16 ^^^^^^^^^^^^^^
  17
  18 Magnesium requires Java 11, both during compile-time and run-time.
  19 Make sure to install JDK 11 corresponding to at least openjdk-11.0.4,
  20 and that the JAVA_HOME environment variable is points to the JDK directory.
  21
  22 Version Bump
  23 ^^^^^^^^^^^^
  24
  25 Before performing platform upgrade, do the following to bump the odlparent
  26 versions (for example, `bump-odl-version <https://github.com/skitt/odl-tools/blob/master/bump-odl-version>`_):
  27
  28 1. Update the odlparent version from 5.0.2 to 6.0.3. There should
  29    not be any reference to **org.opendaylight.odlparent**, except
  30    for other 6.0.3. This includes custom feature.xml templates
  31    (src/main/feature/feature.xml), the version range there should
  32    be "[6,7)" instead of "[5,6)", "[5.0.2,6)" or any other variation.
  33
  34  .. code-block:: none
  35
  36   bump-odl-version odlparent 5.0.2 6.0.3
  37
  38 2. Update the direct yangtools version references from 3.0.5 to 4.0.3,
  39    There should not be any reference to **org.opendaylight.yangtools**,
  40    except for 4.0.2. This includes custom feature.xml templates
  41    (src/main/feature/feature.xml), the version range there should
  42    be "[4,5)" instead of "[3,4)".
  43
  44 3. Update the MDSAL version from 4.0.6 to 5.0.6. There should not be
  45    any reference to **org.opendaylight.mdsal**, except for 5.0.6.
  46
  47  .. code-block:: none
  48
  49   rpl -R 0.14.0-SNAPSHOT 3.0.0
  50
  51 or
  52  .. code-block:: none
  53
  54   rpl -R 2.6.0-SNAPSHOT 3.0.0
  55
  56 Install Dependent Projects
  57 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  58
  59 Before performing platform upgrade, users must also install
  60 any dependent project. To locally install a dependent project,
  61 pull and install the respective `magnesium-mri <https://git.opendaylight.org/gerrit/q/topic:magnesium-mri>`_ changes for any dependent project. At the minimum, pull and install *controller*.
  62
  63 Perform the following steps to save time when locally installing
  64 any dependent project:
  65
  66 * For quick install:
  67
  68  .. code-block:: none
  69
  70   mvn -Pq clean install
  71
  72 * If previously installed, go offline and/or use the
  73   no-snapshot-update option.
  74
  75  .. code-block:: none
  76
  77   mvn -Pq -o -nsu clean install
  78
  79 Upgrade the ODL Parent
  80 ----------------------
  81
  82 The following sub-section describes how to upgrade to
  83 the ODL Parent version 4. Refer to the `ODL Parent Release Notes
  84 <https://github.com/opendaylight/odlparent/blob/6.0.x/docs/NEWS.rst#version-600>`_
  85 for more information.
  86
  87 Features
  88 ^^^^^^^^
  89
  90 Any version range referencing version 5 of ODL Parent must be changed
  91 to “[6,7)” for ODL Parent 6.
  92
  93  .. code-block:: none
  94
  95    <feature name="odl-infrautils-caches">
  96        <feature version="[6,7)">odl-guava</feature>
  97    </feature>
  98
  99 JDK 11
 100 ^^^^^^
 101
 102 Any artifacts referencing odlparent-6 will only build with JDK11 or later.
 103 The build was validated with openjdk-11.0.4, which is currently the lowest
 104 supported version. This allows OpenDaylight components to use APIs introduced
 105 in Java versions 9-11, such as VarHandles, StackWalker, Cleaner, etc. Note
 106 that installing Java 11 removes several components (refer to, `JEP 320
 107 <https://openjdk.java.net/jeps/320>`_. A summary of the API
 108 differences can be found in the java-almanac project (refer to, `Java API
 109 <https://javaalmanac.io/jdk/11/apidiff/8/>`_.
 110
 111 Furthermore, Java 9 switched the default garbage collector to `G1GC
 112 <https://openjdk.java.net/jeps/248>`_ with `improvements
 113 <https://openjdk.java.net/jeps/307>`_ in Java 10. Java 11 delivered
 114 experimental `ZGC <https://openjdk.java.net/jeps/333>`_ to add to the
 115 options available. Other items can be found in the individual JDK pages;
 116 that is, `Java 9 <https://openjdk.java.net/projects/jdk9/>`_, `Java 10
 117 <https://openjdk.java.net/projects/jdk/10/>`_, `Java 11
 118 <https://openjdk.java.net/projects/jdk/11/>`_.
 119
 120 JSR305
 121 ^^^^^^
 122
 123 JSR305 (javax.annotation.Nullable and Friends) annotations are no longer
 124 declared by odlparent. Refer to a `list of removal patches
 125 <https://git.opendaylight.org/gerrit/q/topic:jsr305>`_ to check
 126 if there is an outstanding patch for a project. If not, either follow
 127 the template that is designed for a patch or explicitly provide a
 128 version declaration to each pom.xml that uses these annotations.
 129
 130  .. code-block:: none
 131
 132    <dependency>
 133      <groupId>com.google.code.findbugs</groupId>
 134      <artifactId>jsr305</artifactId>
 135      <version>3.0.2</version>
 136      <optional>true</optional>
 137    </dependency>
 138
 139 Checkstyle
 140 ^^^^^^^^^^
 141
 142 Checkstyle is now enforced by default across all artifacts. For artifacts
 143 that do not pass checkstyle, either fix them or disable enforcement by
 144 defining the following in the pom.xml:
 145
 146  .. code-block:: none
 147
 148    <properties>
 149     <odlparent.checkstyle.enforce>false</odlparent.checkstyle.enforce>
 150    </properties>
 151
 152 Optionally, remove old configuration bits that enable enforcement by
 153 deleting the following block:
 154
 155  .. code-block:: none
 156
 157   <plugin>
 158    <groupId>org.apache.maven.plugins</groupId>
 159    <artifactId>maven-checkstyle-plugin</artifactId>
 160    <configuration>
 161      <propertyExpansion>checkstyle.violationSeverity=error</propertyExpansion>
 162    </configuration>
 163   </plugin>
 164
 165 SpotBugs
 166 ^^^^^^^^
 167
 168 SpotBugs is now enforced by default across all artifacts. For artifacts that
 169 do not pass SpotBugs, either fix them or disable enforcement by defining the
 170 following in the pom.xml:
 171
 172  .. code-block:: none
 173
 174   <properties>
 175    <odlparent.spotbugs.enforce>false</odlparent.spotbugs.enforce>
 176   </properties>
 177
 178 Optionally, also remove any old configuration bits that enable enforcement
 179 by removing the following block:
 180
 181  .. code-block:: none
 182
 183   <plugin>
 184    <groupId>com.github.spotbugs</groupId>
 185    <artifactId>spotbugs-maven-plugin</artifactId>
 186    <configuration>
 187      <failOnError>true</failOnError>
 188    </configuration>
 189   </plugin>
 190
 191 In rare cases, there is a `SpotBugs issue <https://github.com/spotbugs/spotbugs/issues/811>`_
 192 where it reports false positives with Java 11 classes. There are two
 193 workaround options; either increase the method visibility to default
 194 or add the following to the affected method:
 195
 196  .. code-block:: none
 197
 198   @SuppressFBWarnings(value = "UPM_UNCALLED_PRIVATE_METHOD",
 199      justification = "https://github.com/spotbugs/spotbugs/issues/811")
 200
 201 Maven Modernizer
 202 ^^^^^^^^^^^^^^^^
 203
 204 The odlparent 6 defaults to the running modernizer-maven-plugin setup for
 205 Java 8 compliance, without enforcing zero violations. These warnings usually
 206 point towards an improvement to code quality; either using Java 8 replacements
 207 for Guava constructs or by identifying inefficient Java constructs.
 208 A typical report looks like this:
 209
 210  .. code-block:: none
 211
 212   [INFO] --- modernizer-maven-plugin:1.9.0:modernizer (modernizer) @ library ---
 213   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils$1.java:398: Prefer java.util.Objects.equals(Object, Object)
 214   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:439: Prefer java.util.Objects.requireNonNull(Object)
 215   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:440: Prefer java.util.Objects.requireNonNull(Object)
 216   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:441: Prefer java.util.Objects.requireNonNull(Object)
 217   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:468: Prefer java.util.Objects.requireNonNull(Object)
 218   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:469: Prefer java.util.Objects.requireNonNull(Object)
 219   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:470: Prefer java.util.Objects.requireNonNull(Object)
 220   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:497: Prefer java.util.Objects.requireNonNull(Object)
 221   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:498: Prefer java.util.Objects.requireNonNull(Object)
 222   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:499: Prefer java.util.Objects.requireNonNull(Object)
 223   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:529: Prefer java.util.Objects.requireNonNull(Object)
 224   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:530: Prefer java.util.Objects.requireNonNull(Object)
 225   [ERROR] /home/nite/odl/ovsdb/library/impl/src/main/java/org/opendaylight/ovsdb/lib/schema/typed/TyperUtils.java:531: Prefer java.util.Objects.requireNonNull(Object)
 226   [ERROR] /home/nite/odl/ovsdb/library/impl/src/test/java/org/opendaylight/ovsdb/lib/jsonrpc/TestClient.java:63: Prefer java.lang.String.getBytes(java.nio.charset.Charset)
 227   [ERROR] /home/nite/odl/ovsdb/library/impl/src/test/java/org/opendaylight/ovsdb/lib/jsonrpc/TestClient.java:68: Prefer java.lang.String.getBytes(java.nio.charset.Charset)
 228   [ERROR] /home/nite/odl/ovsdb/library/impl/src/test/java/org/opendaylight/ovsdb/lib/jsonrpc/TestClient.java:70: Prefer java.lang.String.getBytes(java.nio.charset.Charset)
 229   [ERROR] /home/nite/odl/ovsdb/library/impl/src/test/java/org/opendaylight/ovsdb/lib/jsonrpc/TestClient.java:80: Prefer java.lang.String.getBytes(java.nio.charset.Charset)
 230   [ERROR] /home/nite/odl/ovsdb/library/impl/src/test/java/org/opendaylight/ovsdb/lib/jsonrpc/TestClient.java:88: Prefer java.lang.String.getBytes(java.nio.charset.Charset)
 231
 232 There is no plan to enable enforcement by default in the future. If downstream
 233 wants to enable it for an artifact, do so by including it in an artifact's pom.xml:
 234
 235  .. code-block:: none
 236
 237   <properties>
 238    <odlparent.modernizer.enforce>true</odlparent.modernizer.enforce>
 239   </properties>
 240
 241 YANG Tools Impacts
 242 ------------------
 243
 244 YangInstanceIdentifier
 245 ^^^^^^^^^^^^^^^^^^^^^^
 246
 247 The YangInstanceIdentifier.NodeIdentifierWithPredicates was a final class,
 248 holding a map of QName/value pairs. This class is most often used with a
 249 single QName/value pair; thus, the yangtools-6.0.0 provides two separate
 250 specializations:
 251
 252 * one for a single pair
 253 * one for all other cases
 254
 255 This specialization saves one level of object indirection, which reduces
 256 the heap usage for single-pair case by 33-37.5%. The impact is that any
 257 code relying on NodeIdentifierWithPredicates.getClass() will break.
 258 Users are advised to switch to this instance of checks instead.
 259
 260 LeafNode Instances
 261 ^^^^^^^^^^^^^^^^^^
 262
 263 LeafNode instances are treated as transient. That is, immutable
 264 implementations of NormalizedNodeContainer do not retain any stored
 265 LeafNode instance as per of a Jira issue. Since LeafNodes are pairs
 266 (NodeIdentifier, value), they can be instantiated on demand. This saves
 267 significant amount of heap for all NormalizedNode trees, especially those
 268 that are used in a DataTree (datastore, etc.). The downside of this is
 269 that leaf identity can no longer be relied on, so any code relying on
 270 NormalizedNodeContainer.getChild() or NormalizedNodeContainer.getValue(),
 271 so returning stable LeafNode references will break.
 272
 273 LeafNode Changes
 274 ^^^^^^^^^^^^^^^^
 275
 276 As detailed in JIRA, this change modifies the types used as LeafNode
 277 changes in the case of *uint* types.
 278
 279 .. list-table::
 280    :widths: 10 20 40
 281    :header-rows: 1
 282
 283    * - **YANG Type**
 284      - **Old Java Type**
 285      - **New Java Type**
 286    * - uint8
 287      - java.lang.Short
 288      - org.opendaylight.yangtools.yang.common.Uint8
 289    * - uint16
 290      - java.lang.Integer
 291      - org.opendaylight.yangtools.yang.common.Uint16
 292    * - uint32
 293      - java.lang.Long
 294      - org.opendaylight.yangtools.yang.common.Uint32
 295    * - uint64
 296      - java.math.BigInteger
 297      - org.opendaylight.yangtools.yang.common.Uint64
 298
 299 Since NormalizedNode APIs are inherently not type-safe, they cannot
 300 be validated at compile-time, since downstreams are expected to update
 301 code accordingly. Leaf values and MD-SAL binding are validated by YANG
 302 Tools codecs, so access to malformed data can be discovered through
 303 those means. However, DataTree and components built on top of it will
 304 not perform value validation; thus, storage is not good enough of a
 305 test for compatibility. The best check is reading the entire datastore
 306 through RESTCONF, so that it forces type checks to occur and will fail
 307 when there is a mismatch.
 308
 309 Renamed Classes
 310 ^^^^^^^^^^^^^^^
 311
 312 To keep naming consistent, the following classes were renamed:
 313
 314 * AnyXmlSchemaNode renamed to AnyxmlSchemaNode
 315 * AnyDataSchemaNode renamed to AnydataSchemaNode
 316 * AnyDataNode renamed to AnydataNode
 317 * AnyXmlNode renamed to DOMSourceAnyxmlNode
 318
 319 MD-SAL Impacts
 320 --------------
 321
 322 Runtime Bindings DTOs
 323 ^^^^^^^^^^^^^^^^^^^^^
 324
 325 Runtime binding DTOs (data transfer objects) no longer return
 326 mutable lists. That is Runtime-based DTOs that are provided to
 327 DataTreeChangeListener, RPC invocations and resulting from datastore
 328 reads, no longer return collections that are mutable. For details,
 329 see the `MD-SAL issue <https://jira.opendaylight.org/browse/MDSAL-440>`_,
 330 but refer to the following to get a brief overview:
 331
 332  .. code-block:: none
 333
 334   interface SomeObject extends DataObject {
 335     List<Other> getOther();
 336   }
 337
 338 In addition, the *getOther()* method implementation no longer returns
 339 an ArrayList. This is a known bug and a divergence from the binding
 340 specification design assumptions. It is known to have been misused
 341 by the application code. Any attempt to modify this collection results
 342 in an UnsupportedOperationException error being thrown. In addition,
 343 any call sites triggering it must be updated to create a mutable copy
 344 of the list.
 345
 346 Type Wrapper
 347 ^^^^^^^^^^^^
 348
 349 Type wrapper classes establish an equality domain. As noted in the
 350 corresponding the MD-SAL issue, rules for comparing type-wrapper
 351 classes have been relaxed. This can lead to objects previously
 352 deemed as non-equal to be evaluated as equal.
 353
 354 Previously, a construct that appeared as:
 355
 356  .. code-block:: none
 357
 358   typedef foo {
 359     type int;
 360   }
 361
 362   typedef bar {
 363     type foo;
 364   }
 365
 366 Used like this:
 367
 368  .. code-block:: none
 369
 370   Foo foo = new Foo(1);
 371   Bar bar = new Bar(1);
 372   assertEquals(foo, bar);
 373
 374 Would fail the assertion. However, now it succeeds.
 375
 376 Mapping Changes
 377 ^^^^^^^^^^^^^^^
 378
 379 As noted in YANG Tools above, the value mapping was changed in the
 380 DOM domain. Since binding/DOM adaption must translate values
 381 accurately, and not reflecting that change in Binding APIs would
 382 lead to a prohibitive runtime cost. Therefore, binding codegen
 383 contract changes in the way these types are mapped, which resolves
 384 a separate issue as a side effect.
 385
 386 This impacts the getter methods the most, as they lose their ability
 387 to automatically unbox. All users are unfortunately forced to adapt
 388 to these, by calling provided a .toJava() method on the returned object.
 389 For example, given the model:
 390
 391  .. code-block:: none
 392
 393   container foo {
 394     leaf bar {
 395      type uint32;
 396      }
 397    }
 398
 399 A *long* corresponding to the value is acquired as:
 400
 401  .. code-block:: none
 402
 403    long bar = foo.getBar().toJava();
 404
 405 Most users of builders and encapsulated value types are not as affected,
 406 since the codegen generates compatibility bridge methods, which adapt old
 407 value types to new uses. Therefore, the transition is seamless. These methods
 408 are marked as @Deprecated(forRemoval = true), so their use is clearly flagged
 409 during build as the following:
 410
 411  .. code-block:: none
 412
 413   [WARNING] netconf/netconf/netconf-topology/src/test/java/org/opendaylight/netconf/topology/impl/NetconfTopologyImplTest.java:[164,26] PortNumber(java.lang.Integer) in org.opendaylight.yang.gen.v1.urn.ietf.params.xml.ns.yang.ietf.inet.types.rev130715.PortNumber has been deprecated and marked for removal
 414   [WARNING] netconf/netconf/netconf-topology/src/test/java/org/opendaylight/netconf/topology/impl/NetconfTopologyImplTest.java:[166,17] setDefaultRequestTimeoutMillis(java.lang.Long) in org.opendaylight.yang.gen.v1.urn.opendaylight.netconf.node.topology.rev150114.NetconfNodeBuilder has been deprecated and marked for removal
 415   [WARNING] netconf/netconf/netconf-topology/src/test/java/org/opendaylight/netconf/topology/impl/NetconfTopologyImplTest.java:[167,17] setBetweenAttemptsTimeoutMillis(java.lang.Integer) in org.opendaylight.yang.gen.v1.urn.opendaylight.netconf.node.topology.rev150114.NetconfNodeBuilder has been deprecated and marked for removal
 416   [WARNING] netconf/netconf/netconf-topology/src/test/java/org/opendaylight/netconf/topology/impl/NetconfTopologyImplTest.java:[168,17] setKeepaliveDelay(java.lang.Long) in org.opendaylight.yang.gen.v1.urn.opendaylight.netconf.node.topology.rev150114.NetconfNodeBuilder has been deprecated and marked for removal
 417
 418 These compatibility wrappers are not generated in case of union types, as that would run counter to MDSAL-330, where such compatibility wrappers would cause conflicts.
 419
 420 Downstream users are strongly encouraged to migrate, as these methods and constructors
 421 will be removed in Aluminum. In order to facilitate that migration, a set of
 422 fromJava() methods is provided from the
 423 org.opendaylight.yangtools.yang.common.UintConversions. These take widened
 424 Java primitive (short, int, long) or a BigInteger to produce the corresponding
 425 Uint8/Uint16/Uint32/Uint64:
 426
 427  .. code-block:: none
 428
 429   imports static org.opendaylight.yangtools.yang.common.UintConversions.fromJava;
 430
 431    Uint64 zero = fromJava(BigInteger.ZERO);
 432    Uint8 one = fromJava((short) 1);
 433    Uint16 two = fromJava(2);
 434    Uint32 three = fromJava(3L);
 435
 436   .. Note:: A proper migration should adopt these types as the replacement
 437      of the short/integer/long/biginteger in a custom structure. However,
 438      these types of conversion have a cost, especially in the case of
 439      Uint64/BigInteger conversion. Unless required, projects should
 440      eliminate the use of BigInteger in favor of Uint64, since Uint64
 441      is superior in terms of performance and memory footprint.
 442
 443 ODL Feature Removed
 444 ^^^^^^^^^^^^^^^^^^^
 445
 446 The odl-mdsal-model-draft-bierman-netconf-restconf-02 feature was removed.
 447 This feature, along with org.opendaylight.mdsal.model/ietf-restconf artifact
 448 was removed from MDSAL, but was migrated to its sole user in these patches.
 449
 450 restconf-artifacts BOM removed
 451 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 452
 453 The restconf-artifacts BOM, previously present in Sodium and from which was
 454 inherited the version of the odl-restconf-all dependency (particularly useful
 455 in Karaf feature poms declaration), is no more available.
 456 It is now part of the netconf-artifacts BOM.