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