data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/RootApplyStrategy.java

   1 /*
   2  * Copyright (c) 2014 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.yang.data.tree.impl;
   9
  10 import com.google.common.collect.ForwardingObject;
  11 import java.util.Objects;
  12
  13 /**
  14  * Represents a {@link ModificationApplyOperation} which is rooted at conceptual
  15  * top of data tree.
  16  *
  17  * <p>
  18  * This implementation differs from other implementations in this package that
  19  * is not immutable, but may be upgraded to newer state if available by
  20  * explicitly invoking {@link #upgradeIfPossible()} and also serves as factory
  21  * for deriving snapshot {@link RootApplyStrategy} which will not
  22  * be affected by upgrade of original one.
  23  *
  24  * <p>
  25  * There are two variations of this {@link ModificationApplyOperation}:
  26  * <ul>
  27  * <li>
  28  * <b>Upgradable</b> - operation may be upgraded to different backing
  29  * implementation by invoking {@link #upgradeIfPossible()}.</li>
  30  * <li><b>Not Upgradable</b> - operation is immutable, invocation of
  31  * {@link #upgradeIfPossible()} is no-op and method {@link #snapshot()} returns
  32  * pointer on same object.
  33  * </ul>
  34  * <h3>Upgradable Root Modification Operation</h3>
  35  * Upgradable Root Modification Operation may be created using:
  36  * <ul>
  37  * <li> {@link #from(ModificationApplyOperation)} with other upgradable root
  38  * modification as an argument
  39  * <li>using factory {@link LatestOperationHolder} which instantiates Upgradable
  40  * Root Modification Operations and provides an option to set latest
  41  * implementation.
  42  * </ul>
  43  *
  44  * <p>
  45  * Upgradable root operation is never upgraded to latest operation
  46  * automatically, but client code must explicitly invoke
  47  * {@link #upgradeIfPossible()} to get latest implementation.
  48  *
  49  * <p>
  50  * Note: This is helpful for implementing
  51  * {@link org.opendaylight.yangtools.yang.data.tree.api.DataTreeModification}
  52  * which may be derived from
  53  * {@link org.opendaylight.yangtools.yang.data.tree.api.DataTree} before
  54  * update of schema and user actually writes data after schema update. During
  55  * update user did not invoked any operation.
  56  */
  57 abstract class RootApplyStrategy extends ForwardingObject {
  58
  59     static RootApplyStrategy from(final ModificationApplyOperation resolver) {
  60         return new NotUpgradableRootApplyStrategy(resolver);
  61     }
  62
  63     @Override
  64     protected abstract ModificationApplyOperation delegate();
  65
  66     @Override
  67     public final boolean equals(final Object obj) {
  68         return Objects.equals(delegate(), obj);
  69     }
  70
  71     @Override
  72     public final int hashCode() {
  73         return Objects.hashCode(delegate());
  74     }
  75
  76     @Override
  77     public final String toString() {
  78         return Objects.toString(delegate());
  79     }
  80
  81     /**
  82      * Creates a snapshot from this modification, which may have separate
  83      * upgrade lifecycle and is not affected by upgrades.
  84      *
  85      * <p>
  86      * Newly created snapshot uses backing implementation of this modification.
  87      *
  88      * @return Derived {@link RootApplyStrategy} with separate
  89      *         upgrade lifecycle.
  90      */
  91     abstract RootApplyStrategy snapshot();
  92
  93     /**
  94      * Upgrades backing implementation to latest available, if possible.
  95      *
  96      * <p>
  97      * Latest implementation of {@link RootApplyStrategy} is
  98      * managed by {@link LatestOperationHolder} which was used to construct this
  99      * operation and latest operation is updated by
 100      * {@link LatestOperationHolder#setCurrent(ModificationApplyOperation)}.
 101      */
 102     abstract void upgradeIfPossible();
 103 }