opendaylight/md-sal/sal-clustering-commons/src/main/java/org/opendaylight/controller/cluster/datastore/node/utils/stream/MagnesiumPathArgument.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.controller.cluster.datastore.node.utils.stream;
   9
  10 /**
  11  * Path Argument types used in Magnesium encoding. These are encoded as a single byte, three bits of which are reserved
  12  * for PathArgument type itself:
  13  * <pre>
  14  *   7 6 5 4 3 2 1 0
  15  *  +-+-+-+-+-+-+-+-+
  16  *  |         | Type|
  17  *  +-+-+-+-+-+-+-+-+
  18  * </pre>
  19  * There are five type defined:
  20  * <ul>
  21  *   <li>{@link #AUGMENTATION_IDENTIFIER}, which additionally holds the number of QName elements encoded:
  22  *     <pre>
  23  *        7 6 5 4 3 2 1 0
  24  *       +-+-+-+-+-+-+-+-+
  25  *       |  Count  |0 0 0|
  26  *       +-+-+-+-+-+-+-+-+
  27  *     </pre>
  28  *     Where count is coded as an unsigned integer, with {@link #AID_COUNT_1B} and {@link #AID_COUNT_2B} and
  29  *     {@link #AID_COUNT_4B} indicating extended coding with up to 4 additional bytes. This byte is followed by
  30  *     {@code count} {@link MagnesiumValue} QNames.
  31  *     <pre>
  32  *       7 6 5 4 3 2 1 0
  33  *      +-+-+-+-+-+-+-+-+
  34  *      |0 0 0| Q |0 0 1|
  35  *      +-+-+-+-+-+-+-+-+
  36  *     </pre>
  37  *     Where QName coding is achieved via {@link #QNAME_DEF}, {@link #QNAME_REF_1B}, {@link #QNAME_REF_2B} and
  38  *     {@link #QNAME_REF_4B}.
  39  *   </li>
  40  *   <li>{@link #NODE_IDENTIFIER_WITH_PREDICATES}, which encodes a QName same way NodeIdentifier does:
  41  *     <pre>
  42  *       7 6 5 4 3 2 1 0
  43  *      +-+-+-+-+-+-+-+-+
  44  *      | Size| Q |0 1 0|
  45  *      +-+-+-+-+-+-+-+-+
  46  *      </pre>
  47  *      but additionally encodes number of predicates contained using {@link #SIZE_0} through {@link #SIZE_4}. If that
  48  *      number cannot be expressed, {@link #SIZE_1B}, {@value #SIZE_2B} and {@link #SIZE_4B} indicate number and format
  49  *      of additional bytes that hold number of predicates.
  50  *
  51  *      <p>
  52  *      This is then followed by the specified number of QName/Object key/value pairs based on {@link MagnesiumValue}
  53  *      encoding.
  54  *   </li>
  55  *   <li>{@link #NODE_WITH_VALUE}, which encodes a QName same way NodeIdentifier does:
  56  *     <pre>
  57  *       7 6 5 4 3 2 1 0
  58  *      +-+-+-+-+-+-+-+-+
  59  *      |0 0 0| Q |0 1 1|
  60  *      +-+-+-+-+-+-+-+-+
  61  *     </pre>
  62  *     but is additionally followed by a single encoded value, as per {@link MagnesiumValue}.
  63  *   </li>
  64  *   <li>{@link #MOUNTPOINT_IDENTIFIER}, which encodes a QName same way NodeIdentifier does:
  65  *     <pre>
  66  *       7 6 5 4 3 2 1 0
  67  *      +-+-+-+-+-+-+-+-+
  68  *      |0 0 0| Q |1 0 0|
  69  *      +-+-+-+-+-+-+-+-+
  70  *     </pre>
  71  *   </li>
  72  * </ul>
  73  */
  74 final class MagnesiumPathArgument {
  75     // 3 bits reserved for type...
  76     static final byte AUGMENTATION_IDENTIFIER         = 0x00;
  77     static final byte NODE_IDENTIFIER                 = 0x01;
  78     static final byte NODE_IDENTIFIER_WITH_PREDICATES = 0x02;
  79     static final byte NODE_WITH_VALUE                 = 0x03;
  80     static final byte MOUNTPOINT_IDENTIFIER           = 0x04;
  81
  82     // ... leaving three values currently unused
  83     // 0x05 reserved
  84     // 0x06 reserved
  85     // 0x07 reserved
  86
  87     static final byte TYPE_MASK                       = 0x07;
  88
  89     // In case of AUGMENTATION_IDENTIFIER, top 5 bits are used to encode the number of path arguments, except last three
  90     // values. This means that up to AugmentationIdentifiers with up to 28 components have this length encoded inline,
  91     // otherwise we encode them in following 1 (unsigned), 2 (unsigned) or 4 (signed) bytes
  92     static final byte AID_COUNT_1B                    = (byte) 0xE8;
  93     static final byte AID_COUNT_2B                    = (byte) 0xF0;
  94     static final byte AID_COUNT_4B                    = (byte) 0xF8;
  95     static final byte AID_COUNT_MASK                  = AID_COUNT_4B;
  96     static final byte AID_COUNT_SHIFT                 = 3;
  97
  98     // For normal path path arguments we can either define a QName reference or follow a 1-4 byte reference.
  99     static final byte QNAME_DEF                       = 0x00;
 100     static final byte QNAME_REF_1B                    = 0x08; // Unsigned
 101     static final byte QNAME_REF_2B                    = 0x10; // Unsigned
 102     static final byte QNAME_REF_4B                    = 0x18; // Signed
 103     static final byte QNAME_MASK                      = QNAME_REF_4B;
 104
 105     // For NodeIdentifierWithPredicates we also carry the number of subsequent path arguments. The case of 0-4 arguments
 106     // is indicated directly, otherwise there is 1-4 bytes carrying the reference.
 107     static final byte SIZE_0                          = 0x00;
 108     static final byte SIZE_1                          = 0x20;
 109     static final byte SIZE_2                          = 0x40;
 110     static final byte SIZE_3                          = 0x60;
 111     static final byte SIZE_4                          = (byte) 0x80;
 112     static final byte SIZE_1B                         = (byte) 0xA0;
 113     static final byte SIZE_2B                         = (byte) 0xC0;
 114     static final byte SIZE_4B                         = (byte) 0xE0;
 115     static final byte SIZE_MASK                       = SIZE_4B;
 116     static final byte SIZE_SHIFT                      = 5;
 117
 118     private MagnesiumPathArgument() {
 119
 120     }
 121 }