Seal ItemOrder and MutationBehaviour

[yangtools.git] / common / concepts / src / main / java / org / opendaylight / yangtools / concepts / Immutable.java

diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Immutable.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Immutable.java
index 1339979982903a09ae1d16ce501ee94ebba10aa9..eb0134777e95b5c6894f4af3e94d464342c4af69 100644 (file)
--- a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Immutable.java
+++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Immutable.java
@@ -8,35 +8,30 @@
 package org.opendaylight.yangtools.concepts;
 
 /**
- * Immutable Object - object does not change its state during lifecycle.
- * 
+ * Immutable Object - object does not change its externally-observable state during its lifetime.
+ *
+ * <p>
+ * Marker interface for objects which are immutable. This interface should be used directly on objects, preferably
+ * final, which are eligible for the JSR-305 {@code javax.annotation.concurrent.Immutable} annotation and objects
+ * implementing this interface are required to abide to interface contract specified by {@code @Immutable}.
+ *
+ * <p>
+ * The reason for the existence of this interface is twofold: unlike {@code @Immutable}, it is visible at runtime and
+ * objects can be quickly checked for compliance using an 'instanceof' check. This is useful for code which needs to
+ * capture a point-in-time snapshot of otherwise unknown objects -- a typical example being logging/tracing systems.
+ * Such systems would normally have to rely on serializing the object to get a stable checkpoint. Objects marked with
+ * this interface are guaranteed to remain stable, thus already being a checkpoint for all intents and purposes, so
+ * aside from retaining a reference no further action on them is necessary.
+ *
  * <p>
- * Marker interface for objects which are immutable. This interface should be
- * used directly on objects, preferably final, which are eligible for the
- * JSR-305 @Immutable annotation and objects implementing this interface are
- * required to abide to interface contract specified by @Immutable. 
- * 
- * <p>The reason for the existence of this interface is twofold: 
- * unlike @Immutable, it is
- * visible at runtime and objects can be quickly checked for compliance using a
- * quick 'instanceof' check. This is useful for code which needs to capture a
- * point-in-time snapshot of otherwise unknown objects -- a typical example
- * being logging/tracing systems. Such systems would normally have to rely on
- * serializing the object to get a stable checkpoint. Objects marked with this
- * interface are guaranteed to remain stable, thus already being a checkpoint
- * for all intents and purposes, so aside from retaining a reference no further
- * action on them is necessary.
- * 
- * Implementations of this interface must not change any public state during
- * their whole lifecycle.
- * 
- * This interface is mutually exclusive with {@link Mutable} and other
- * {@link MutationBehaviour}s.
- * 
- * @author Robert Varga <rovarga@cisco.com>
- * @author Tony Tkacik <ttkacik@cisco.com>
- * 
+ * Implementations of this interface must not change any public state during their entire lifetime.
+ *
+ * <p>
+ * This interface is mutually exclusive with {@link Mutable} and other {@link MutationBehaviour}s.
+ *
+ * @author Robert Varga
+ * @author Tony Tkacik
  */
-public interface Immutable extends MutationBehaviour<Immutable> {
-
+public non-sealed interface Immutable extends MutationBehaviour<Immutable> {
+    // Marker interface only
 }