yang/yang-data-codec-binfmt/src/main/java/org/opendaylight/yangtools/yang/data/codec/binfmt/NormalizedNodeStreamVersion.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.codec.binfmt;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.io.DataOutput;
  12 import java.math.BigInteger;
  13 import org.eclipse.jdt.annotation.NonNullByDefault;
  14 import org.opendaylight.yangtools.yang.common.Uint64;
  15 import org.opendaylight.yangtools.yang.data.api.schema.ValueNode;
  16
  17 /**
  18  * Enumeration of all stream versions this implementation supports on both input and output.
  19  */
  20 @Beta
  21 @NonNullByDefault
  22 public enum NormalizedNodeStreamVersion {
  23     /**
  24      * Original stream version, as shipped in OpenDaylight Lithium simultaneous release. The caveat here is that this
  25      * version has augmented in OpenDaylight Oxygen to retrofit a non-null representation of the empty type.
  26      */
  27     LITHIUM {
  28         /**
  29          * {@inheritDoc}
  30          *
  31          * @deprecated This version is a historic one and should not be used in code. It does not support current
  32          *             mapping of {@code Uint8} et al. and hence results in a stream which needs to be further adapted
  33          *             to current definition of LeafNode.
  34          */
  35         @Deprecated
  36         @Override
  37         public NormalizedNodeDataOutput newDataOutput(final DataOutput output) {
  38             return new LithiumNormalizedNodeOutputStreamWriter(output);
  39         }
  40     },
  41     /**
  42      * Updated stream version, as shipped in OpenDaylight Neon SR2 release. Improves identifier encoding over
  43      * {@link #LITHIUM}, so that QName caching is more effective.
  44      */
  45     NEON_SR2 {
  46         /**
  47          * {@inheritDoc}
  48          *
  49          * @deprecated This version is a historic one and should not be used in code. It does not support current
  50          *             mapping of {@code Uint8} et al. and hence results in a stream which needs to be further adapted
  51          *             to current definition of LeafNode.
  52          */
  53         @Deprecated
  54         @Override
  55         public NormalizedNodeDataOutput newDataOutput(final DataOutput output) {
  56             return new NeonSR2NormalizedNodeOutputStreamWriter(output);
  57         }
  58     },
  59     /**
  60      * First shipping in Sodium SR1. Improved stream coding to eliminate redundancies present in {@link #NEON_SR2}.
  61      * Supports {@code Uint8} et al. as well as {@link BigInteger}.
  62      */
  63     SODIUM_SR1 {
  64         @Override
  65         public NormalizedNodeDataOutput newDataOutput(final DataOutput output) {
  66             return new SodiumSR1DataOutput(output);
  67         }
  68     },
  69     /**
  70      * First shipping is Magnesium. Does not support {@link BigInteger} mirroring it being superseded by {@link Uint64}
  71      * in {@link ValueNode#body()}.
  72      */
  73     MAGNESIUM {
  74         @Override
  75         public NormalizedNodeDataOutput newDataOutput(final DataOutput output) {
  76             return new MagnesiumDataOutput(output);
  77         }
  78     };
  79
  80     /**
  81      * Return the current runtime version. Guaranteed to not throw {@link UnsupportedOperationException} from
  82      * {@link #newDataOutput(DataOutput)}.
  83      *
  84      * @return Current runtime version.
  85      */
  86     public static NormalizedNodeStreamVersion current() {
  87         return MAGNESIUM;
  88     }
  89
  90     /**
  91      * Creates a new {@link NormalizedNodeDataOutput} instance that writes to the given output.
  92      *
  93      * @param output the DataOutput to write to
  94      * @return a new {@link NormalizedNodeDataOutput} instance
  95      * @throws NullPointerException if {@code output} is null
  96      * @throws UnsupportedOperationException if this version cannot be created in this runtime
  97      */
  98     public abstract NormalizedNodeDataOutput newDataOutput(DataOutput output);
  99 }