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

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