yang/yang-data-impl/src/main/java/org/opendaylight/yangtools/yang/data/impl/schema/nodes/LazyLeafOperations.java

   1 /*
   2  * Copyright (c) 2019 PANTHEON.tech, s.r.o. 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.nodes;
   9
  10 import static com.google.common.base.Verify.verify;
  11 import static java.util.Objects.requireNonNull;
  12
  13 import com.google.common.annotations.Beta;
  14 import java.util.Collection;
  15 import java.util.Map;
  16 import java.util.Optional;
  17 import org.eclipse.jdt.annotation.NonNull;
  18 import org.eclipse.jdt.annotation.Nullable;
  19 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier;
  20 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
  21 import org.opendaylight.yangtools.yang.data.api.schema.DataContainerChild;
  22 import org.opendaylight.yangtools.yang.data.api.schema.LeafNode;
  23 import org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode;
  24 import org.opendaylight.yangtools.yang.data.impl.schema.ImmutableNodes;
  25 import org.slf4j.Logger;
  26 import org.slf4j.LoggerFactory;
  27
  28 /**
  29  * Support utilities for dealing with Maps which would normally hold {@link DataContainerChild} values, but are modified
  30  * to eliminate {@link LeafNode} instances.
  31  *
  32  * <p>
  33  * This class holds implementation logic which controls lifecycle of {@link LeafNode}s  by providing a central policy
  34  * point for how the implementation treats these nodes. There are two modes of operation:
  35  * <ul>
  36  *   <li>eager, which means leaf nodes are retained by their parent<li>
  37  *   <li>lazy, which means leaf nodes are created whenever they are queried and no attempt is made to retain them</li>
  38  * </ul>
  39  *
  40  * <p>
  41  * Selection of the mode in effect is available through {@value #EXPENDABLE_PROP_NAME} system property.
  42  */
  43 @Beta
  44 public final class LazyLeafOperations {
  45     private static final Logger LOG = LoggerFactory.getLogger(LazyLeafOperations.class);
  46
  47     // FIXME: 6.0.0: remove this knob
  48     private static final String EXPENDABLE_PROP_NAME =
  49             "org.opendaylight.yangtools.yang.data.impl.schema.nodes.lazy-leaves";
  50
  51     /**
  52      * Global enabled run-time constant. If set to true, this class will treat {@link LeafNode} and
  53      * {@link LeafSetEntryNode} as an expendable object. This constant is controlled by {@value #EXPENDABLE_PROP_NAME}
  54      * system property.
  55      */
  56     // FIXME: 6.0.0: remove this knob
  57     private static final boolean EXPENDABLE;
  58
  59     static {
  60         EXPENDABLE = Boolean.parseBoolean(System.getProperty(EXPENDABLE_PROP_NAME, "true"));
  61         if (!EXPENDABLE) {
  62             LOG.warn("Leaf nodes are treated as regular nodes. This option is deprecated and is schedule for removal.");
  63         }
  64     }
  65
  66     private LazyLeafOperations() {
  67
  68     }
  69
  70     /**
  71      * A boolean flag indicating whether leaf nodes are being treated as expendable.
  72      *
  73      * @return True if NormalizedNode implementations in this artifact are treating leaf nodes as transient, i.e. do
  74      *              not retain them.
  75      */
  76     // FIXME: 6.0.0: remove this method
  77     public static boolean isEnabled() {
  78         return EXPENDABLE;
  79     }
  80
  81     public static Optional<DataContainerChild<?, ?>> findChild(final Map<PathArgument, Object> map,
  82             final PathArgument key) {
  83         final Object value = map.get(key);
  84         return value == null ? Optional.empty() : Optional.of(decodeChild(key, value));
  85     }
  86
  87     public static @Nullable DataContainerChild<?, ?> getChild(final Map<PathArgument, Object> map,
  88             final PathArgument key) {
  89         final Object value = map.get(key);
  90         return value == null ? null : decodeChild(key, value);
  91     }
  92
  93     public static void putChild(final Map<PathArgument, Object> map, final DataContainerChild<?, ?> child) {
  94         final DataContainerChild<?, ?> node = requireNonNull(child);
  95         map.put(node.getIdentifier(), EXPENDABLE ? encodeExpendableChild(node) : node);
  96     }
  97
  98     @SuppressWarnings({ "rawtypes", "unchecked" })
  99     public static @NonNull Collection<DataContainerChild<?, ?>> getValue(final Map<PathArgument, Object> map) {
 100         return EXPENDABLE ? new LazyValues(map)
 101                 // This is an ugly cast, but it is accurate IFF all modifications are done through this class
 102                 : (Collection)map.values();
 103     }
 104
 105     static @NonNull LeafNode<?> coerceLeaf(final PathArgument key, final Object value) {
 106         verify(key instanceof NodeIdentifier, "Unexpected value %s for child %s", value, key);
 107         return ImmutableNodes.leafNode((NodeIdentifier) key, value);
 108     }
 109
 110     private static @Nullable DataContainerChild<?, ?> decodeChild(final PathArgument key, final @NonNull Object value) {
 111         return EXPENDABLE ? decodeExpendableChild(key, value) : verifyCast(value);
 112     }
 113
 114     private static @NonNull DataContainerChild<?, ?> decodeExpendableChild(final PathArgument key,
 115             @NonNull final Object value) {
 116         return value instanceof DataContainerChild ? (DataContainerChild<?, ?>) value  : coerceLeaf(key, value);
 117     }
 118
 119     private static @NonNull Object encodeExpendableChild(final @NonNull DataContainerChild<?, ?> node) {
 120         return node instanceof LeafNode ? verifyEncode(((LeafNode<?>) node).getValue()) : node;
 121     }
 122
 123     private static @NonNull Object verifyEncode(final @NonNull Object value) {
 124         verify(!(value instanceof DataContainerChild), "Unexpected leaf value %s", value);
 125         return value;
 126     }
 127
 128     private static @NonNull DataContainerChild<?, ?> verifyCast(final @NonNull Object value) {
 129         verify(value instanceof DataContainerChild, "Unexpected child %s", value);
 130         return (DataContainerChild<?, ?>)value;
 131     }
 132 }