1 ==========================
2 Magnesium Platform Upgrade
3 ==========================
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>`_
10 .. contents:: Contents
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.
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>`_):
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.
36 bump-odl-version odlparent 5.0.2 6.0.3
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)".
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.
49 rpl -R 0.14.0-SNAPSHOT 3.0.0
54 rpl -R 2.6.0-SNAPSHOT 3.0.0
56 Install Dependent Projects
57 ^^^^^^^^^^^^^^^^^^^^^^^^^^
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*.
63 Perform the following steps to save time when locally installing
64 any dependent project:
72 * If previously installed, go offline and/or use the
73 no-snapshot-update option.
77 mvn -Pq -o -nsu clean install
79 Upgrade the ODL Parent
80 ----------------------
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>`_
90 Any version range referencing version 5 of ODL Parent must be changed
91 to “[6,7)” for ODL Parent 6.
95 <feature name="odl-infrautils-caches">
96 <feature version="[6,7)">odl-guava</feature>
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/>`_.
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/>`_.
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.
133 <groupId>com.google.code.findbugs</groupId>
134 <artifactId>jsr305</artifactId>
135 <version>3.0.2</version>
136 <optional>true</optional>
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:
149 <odlparent.checkstyle.enforce>false</odlparent.checkstyle.enforce>
152 Optionally, remove old configuration bits that enable enforcement by
153 deleting the following block:
158 <groupId>org.apache.maven.plugins</groupId>
159 <artifactId>maven-checkstyle-plugin</artifactId>
161 <propertyExpansion>checkstyle.violationSeverity=error</propertyExpansion>
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:
175 <odlparent.spotbugs.enforce>false</odlparent.spotbugs.enforce>
178 Optionally, also remove any old configuration bits that enable enforcement
179 by removing the following block:
184 <groupId>com.github.spotbugs</groupId>
185 <artifactId>spotbugs-maven-plugin</artifactId>
187 <failOnError>true</failOnError>
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:
198 @SuppressFBWarnings(value = "UPM_UNCALLED_PRIVATE_METHOD",
199 justification = "https://github.com/spotbugs/spotbugs/issues/811")
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:
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)
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:
238 <odlparent.modernizer.enforce>true</odlparent.modernizer.enforce>
244 YangInstanceIdentifier
245 ^^^^^^^^^^^^^^^^^^^^^^
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
252 * one for a single pair
253 * one for all other cases
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.
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.
276 As detailed in JIRA, this change modifies the types used as LeafNode
277 changes in the case of *uint* types.
288 - org.opendaylight.yangtools.yang.common.Uint8
291 - org.opendaylight.yangtools.yang.common.Uint16
294 - org.opendaylight.yangtools.yang.common.Uint32
296 - java.math.BigInteger
297 - org.opendaylight.yangtools.yang.common.Uint64
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.
312 To keep naming consistent, the following classes were renamed:
314 * AnyXmlSchemaNode renamed to AnyxmlSchemaNode
315 * AnyDataSchemaNode renamed to AnydataSchemaNode
316 * AnyDataNode renamed to AnydataNode
317 * AnyXmlNode renamed to DOMSourceAnyxmlNode
322 Runtime Bindings DTOs
323 ^^^^^^^^^^^^^^^^^^^^^
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:
334 interface SomeObject extends DataObject {
335 List<Other> getOther();
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
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.
354 Previously, a construct that appeared as:
370 Foo foo = new Foo(1);
371 Bar bar = new Bar(1);
372 assertEquals(foo, bar);
374 Would fail the assertion. However, now it succeeds.
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.
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:
399 A *long* corresponding to the value is acquired as:
403 long bar = foo.getBar().toJava();
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:
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
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.
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:
429 imports static org.opendaylight.yangtools.yang.common.UintConversions.fromJava;
431 Uint64 zero = fromJava(BigInteger.ZERO);
432 Uint8 one = fromJava((short) 1);
433 Uint16 two = fromJava(2);
434 Uint32 three = fromJava(3L);
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.
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.