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