common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Immutable.java

   1 /*
   2  * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.yangtools.concepts;
   9
  10 /**
  11  * Immutable Object - object does not change its externally-observable state during its lifetime.
  12  *
  13  * <p>
  14  * Marker interface for objects which are immutable. This interface should be used directly on objects, preferably
  15  * final, which are eligible for the JSR-305 {@code javax.annotation.concurrent.Immutable} annotation and objects
  16  * implementing this interface are required to abide to interface contract specified by {@code @Immutable}.
  17  *
  18  * <p>
  19  * The reason for the existence of this interface is twofold: unlike {@code @Immutable}, it is visible at runtime and
  20  * objects can be quickly checked for compliance using an 'instanceof' check. This is useful for code which needs to
  21  * capture a point-in-time snapshot of otherwise unknown objects -- a typical example being logging/tracing systems.
  22  * Such systems would normally have to rely on serializing the object to get a stable checkpoint. Objects marked with
  23  * this interface are guaranteed to remain stable, thus already being a checkpoint for all intents and purposes, so
  24  * aside from retaining a reference no further action on them is necessary.
  25  *
  26  * <p>
  27  * Implementations of this interface must not change any public state during their entire lifetime.
  28  *
  29  * <p>
  30  * This interface is mutually exclusive with {@link Mutable} and other {@link MutationBehaviour}s.
  31  *
  32  * @author Robert Varga
  33  * @author Tony Tkacik
  34  */
  35 public non-sealed interface Immutable extends MutationBehaviour<Immutable> {
  36     // Marker interface only
  37 }