opendaylight/md-sal/cds-access-api/src/main/java/org/opendaylight/controller/cluster/access/ABIVersion.java

   1 /*
   2  * Copyright (c) 2016 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.controller.cluster.access;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.annotations.VisibleForTesting;
  12 import com.google.common.base.Preconditions;
  13 import java.io.DataInput;
  14 import java.io.DataOutput;
  15 import java.io.IOException;
  16 import javax.annotation.Nonnull;
  17 import org.opendaylight.yangtools.concepts.WritableObject;
  18
  19 /**
  20  * Enumeration of all ABI versions supported by this implementation of the client access API.
  21  *
  22  * @author Robert Varga
  23  */
  24 @Beta
  25 public enum ABIVersion implements WritableObject {
  26     // NOTE: enumeration values need to be sorted in asceding order of their version to keep Comparable working
  27
  28     /**
  29      * Version which is older than any other version. This version exists purely for testing purposes.
  30      */
  31     @VisibleForTesting
  32     TEST_PAST_VERSION(0),
  33
  34     /**
  35      * Initial ABI version, as shipped with Boron Simultaneous release.
  36      */
  37     // We seed the initial version to be the same as DataStoreVersions.BORON-VERSION for compatibility reasons.
  38     BORON(5),
  39
  40     /**
  41      * Version which is newer than any other version. This version exists purely for testing purposes.
  42      */
  43     @VisibleForTesting
  44     TEST_FUTURE_VERSION(65535);
  45
  46     private final short value;
  47
  48     ABIVersion(final int intVersion) {
  49         Preconditions.checkArgument(intVersion >= 0 && intVersion <= 65535);
  50         value = (short) intVersion;
  51     }
  52
  53     /**
  54      * Return the unsigned short integer identifying this version.
  55      *
  56      * @return Unsigned short integer identifying this version
  57      */
  58     public short shortValue() {
  59         return value;
  60     }
  61
  62     /**
  63      * Return the codebase-native ABI version. This version is the default version allocated to messages at runtime.
  64      * Conversion to previous versions may incur additional overhead (such as object allocation).
  65      *
  66      * @return Current {@link ABIVersion}
  67      */
  68     public static @Nonnull ABIVersion current() {
  69         return BORON;
  70     }
  71
  72     /**
  73      * Return the {@link ABIVersion} corresponding to an unsigned short integer. This method is provided for callers
  74      * which provide their own recovery strategy in case of version incompatibility.
  75      *
  76      * @param s Short integer as returned from {@link #shortValue()}
  77      * @return {@link ABIVersion}
  78      * @throws FutureVersionException if the specified integer identifies a future version
  79      * @throws PastVersionException if the specified integer identifies a past version which is no longer supported
  80      */
  81     public static @Nonnull ABIVersion valueOf(final short s) throws FutureVersionException, PastVersionException {
  82         switch (Short.toUnsignedInt(s)) {
  83             case 0:
  84             case 1:
  85             case 2:
  86             case 3:
  87             case 4:
  88                 throw new PastVersionException(s, BORON);
  89             case 5:
  90                 return BORON;
  91             default:
  92                 throw new FutureVersionException(s, BORON);
  93         }
  94     }
  95
  96     @Override
  97     public void writeTo(final DataOutput out) throws IOException {
  98         out.writeShort(value);
  99     }
 100
 101     /**
 102      * Read an {@link ABIVersion} from a {@link DataInput}. This method is provided for callers which do not have
 103      * a recovery strategy for dealing with unsupported versions.
 104      *
 105      * @param in Input from which to read
 106      * @return An {@link ABIVersion}
 107      * @throws IOException If read fails or an unsupported version is encountered
 108      */
 109     public static @Nonnull ABIVersion readFrom(final @Nonnull DataInput in) throws IOException {
 110         final short s = in.readShort();
 111         try {
 112             return valueOf(s);
 113         } catch (FutureVersionException | PastVersionException e) {
 114             throw new IOException("Unsupported version", e);
 115         }
 116     }
 117 }