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 state during lifecycle.
  12  *
  13  * <p>
  14  * Marker interface for objects which are immutable. This interface should be
  15  * used directly on objects, preferably final, which are eligible for the
  16  * JSR-305 @Immutable annotation and objects implementing this interface are
  17  * required to abide to interface contract specified by @Immutable.
  18  *
  19  * <p>The reason for the existence of this interface is twofold:
  20  * unlike @Immutable, it is
  21  * visible at runtime and objects can be quickly checked for compliance using a
  22  * quick 'instanceof' check. This is useful for code which needs to capture a
  23  * point-in-time snapshot of otherwise unknown objects -- a typical example
  24  * being logging/tracing systems. Such systems would normally have to rely on
  25  * serializing the object to get a stable checkpoint. Objects marked with this
  26  * interface are guaranteed to remain stable, thus already being a checkpoint
  27  * for all intents and purposes, so aside from retaining a reference no further
  28  * action on them is necessary.
  29  *
  30  * Implementations of this interface must not change any public state during
  31  * their whole lifecycle.
  32  *
  33  * This interface is mutually exclusive with {@link Mutable} and other
  34  * {@link MutationBehaviour}s.
  35  *
  36  * @author Robert Varga <rovarga@cisco.com>
  37  * @author Tony Tkacik <ttkacik@cisco.com>
  38  *
  39  */
  40 public interface Immutable extends MutationBehaviour<Immutable> {
  41
  42 }