packetcable-driver/src/main/java/org/pcmm/gates/impl/BEEnvelop.java

   1 /*
   2  * (c) 2015 Cable Television Laboratories, Inc.  All rights reserved.
   3  */
   4
   5 package org.pcmm.gates.impl;
   6
   7 import com.google.common.primitives.Bytes;
   8 import org.umu.cops.stack.COPSMsgParser;
   9
  10 import java.util.ArrayList;
  11 import java.util.List;
  12
  13 /**
  14  * Class for use as member to the ITrafficProfile#BestEffortService class.
  15  */
  16 public class BEEnvelop {
  17
  18     public static final byte DEFAULT_TRAFFIC_PRIORITY = 0;
  19
  20     public static final int DEFAULT_MAX_TRAFFIC_BURST = 3044;
  21
  22     /**
  23      * Traffic Priority is a 1-byte unsigned integer field specifying the relative priority assigned to the Service Flow
  24      * in comparison with other flows. This field is fully defined in section C.2.2.5.1 of [1]. A default Traffic
  25      * Priority of SHOULD be used if a specific Traffic Priority value is not required.
  26      */
  27     private final byte trafficPriority;
  28
  29     /**
  30      * Request/Transmission Policy is a 4-byte bit field as defined in section C.2.2.6.3. A default Request/Transmission
  31      * policy of 0 SHOULD be used if a specific Request/Transmission Policy value is not required.
  32      */
  33     private final int transPolicy;
  34
  35     /**
  36      * Maximum Sustained Traffic Rate is a 4-byte unsigned integer field specifying the rate parameter, in bits/sec.
  37      * A value of 0 indicates that no explicitly-enforced Maximum Sustained Rate is requested. A default Maximum
  38      * Sustained Traffic Rate of 0 SHOULD be used if a specific Maximum Sustained Traffic Rate is not required.
  39      */
  40     private final int maxSusTrafficRate;
  41
  42     /**
  43      * Maximum Traffic Burst is a 4-byte unsigned integer field specifying the token bucket size, in bytes, for a
  44      * tokenbucket-based rate limit for this Service Flow. This field is fully defined in section C.2.2.5.3 of [1].
  45      * A default Maximum Traffic Burst of 3044 bytes SHOULD be used if a specific Maximum Traffic Burst is not required.
  46      * The value of this parameter has no effect unless a non-zero value has been provided Rate parameter.
  47      */
  48     private final int maxTrafficBurst;
  49
  50     /**
  51      * Minimum Reserved Traffic Rate is a 4-byte unsigned integer field specifying the minimum rate, in bits/sec,
  52      * reserved for this Service Flow. This field is fully defined in section C.2.2.5.4. A default Mini Rate of 0 SHOULD
  53      * be used if a specific Minimum Reserved Traffic Rate is not required.
  54      */
  55     private final int minResTrafficRate;
  56
  57     /**
  58      * Assumed Minimum Reserved Traffic Rate Packet Size is a 2-byte unsigned integer field specifying an assumed
  59      * minimum packet size, in bytes, for which the Minimum Reserved Traffic Rate will be provided for this flow. This
  60      * field is fully defined in section C.2.2.5.5. A default Assumed Minimum Reserved Traffic Rate Packet Size of
  61      * 0 SHOULD be used if a specific Assumed Minimum Reserved Traffic Rate Packet size is not required. Upon receip
  62      * of a value of 0 the CMTS MUST utilize its implementation-specific default size for this parameter, not 0 bytes.
  63      */
  64     private final short assumedMinConcatBurst;
  65
  66     /**
  67      * Maximum Concatenated Burst is a 2-byte unsigned integer specifying the maximum concatenated burst (in bytes)
  68      * which a Service Flow is allowed. This field is fully defined in section C.2.2.6.1. A value of 0 means
  69      * there is no limit. A default Maximum Concatenated Burst of 1522 bytes SHOULD be used if a specific Maximum
  70      * Concatenated Burst is not required.
  71      */
  72     private final short maxConcatBurst;
  73
  74     /**
  75      * Upstream Peak Traffic Rate is a 4-byte unsigned integer specifying the Peak traffic rate (in bits per second)
  76      * which a Service Flow is allowed. This field is fully defined in section C.2.2.5.10.1.
  77      */
  78     private final int upPeakTrafficRate;
  79
  80     /*
  81      * Attribute Masks define a specific set of attributes associated with a DOCSIS 3.0 service flow. The CMTS MUST
  82      * ignore the bonded bit in the Required and Forbidden Attribute Mask objects if the cable modem associated with the
  83      * service flow is operating in pre-3.0 DOCSIS mode. The Required Attribute Mask limits the set of channels and
  84      * bonding groups to which the CMTS assigns the service flow by requiring certain attributes. This field is fully
  85      * defined in section C.2.2.3.6 of [1]. The Forbidden Attribute Mask limits the set of channels and bonding groups
  86      * to which the CMTS assigns the service flow by forbidding certain attributes. This field is fully defined in
  87      * section C.2.2.3.7. The CMTS is free to assign the service flow to any channel that satisfies the traffic profile
  88      * if no channel is available that satisfies the Required Attribute Mask and Forbidden Attribute Mask for the
  89      * service flow. The Attribute Aggregation Rule Mask provides guidance to the CMTS as to how it might use the
  90      * attribute masks of individual channels to construct a dynamic bonding group for this service flow. This field is
  91      * fully described in section "Service Flow Attribute Aggregation Rule Mask". As described in that section a default
  92      * Attribute Aggregation Rule Mask of 0 SHOULD be used if specific Attribute Aggregation Rules are not required.
  93      * The Buffer Control parameters libit the maximum queue depth of a Service Flow. The service flow buffer holds the
  94      * packets that are enqueued for transmission for the service flow. The size of the service flow buffer sets the
  95      * maximum queue depth, and upper limit on the amount of data that can be enqueued for transmission at any time by
  96      * the service flow. By providing the ability to control per-service flow buffers. the below Buffer Control
  97      * parameters provide a means of balancing throughput and latency in a standardized and configurable manner.
  98      */
  99
 100     /**
 101      * Required Attribute Mask (see explanation above)
 102      */
 103     private final int reqAttrMask;
 104
 105     /**
 106      * Forbidden Attribute Mask (see explanation above)
 107      */
 108     private final int forbidAttrMask;
 109
 110     /**
 111      * Attribute Aggregation Rule Mask (see explanation above)
 112      */
 113     private final int attrAggRuleMask;
 114
 115     /**
 116      * Minimum Buffer is a 4-byte unsigned integer parameter that defines a lower limit for the size of the buffer that
 117      * is to be provided for a service flow. This field is fully defined in section C.2.2.5.11.3. If this parameter is
 118      * omitted. The Minimum Buffer defaluts to a value of 0, which indicates that there is no lower limit.
 119      */
 120     private final int minBuffer;
 121
 122     /**
 123      * Target Buffer is a 4-byte unsigned integer parameter that defines a desired value for the size of the buffer that
 124      * is to be provided for a service flow. This field is fully defined in section C.2.2.5.11.4. If this parameter is
 125      * omitted or set to a value of 0, the device selects any buffer size within the range of the Minimum and Maximum
 126      * Buffers, via a vendor specific algorithm.
 127      */
 128     private final int targetBuffer;
 129
 130     /**
 131      * Maximum Buffer is a 4-byte unsigned integer parameter that defines an upper limit for the size of the buffer that
 132      * is to be provided for a service flow. This field is fully defined in section C.2.2.5.11.5. If this parameter is
 133      * omitted or set to a value of 0, the Maximum Buffer defaults to a value of no limit.
 134      */
 135     private final int maxBuffer;
 136
 137     /**
 138      * Constructor
 139      * @param trafficPriority - the Traffic Priority
 140      * @param transPolicy - the Requested Transmission Policy
 141      * @param maxSusTrafficRate - the Maximum Sustained Traffic Rate
 142      * @param maxTrafficBurst - the Maximum Traffic Burst Rate
 143      * @param minResTrafficRate - the Minimum Reserved Traffic Rate
 144      * @param assumedMinConcatBurst - the Assumed Minimum Reserved Traffic Rate Packet Size
 145      * @param maxConcatBurst - the Maximum Concatenated Burst
 146      * @param upPeakTrafficRate - the Upstream Peak Traffic Rate
 147      * @param reqAttrMask - the Required Attribute Mask
 148      * @param forbidAttrMask - the Forbidden Attribute Mask
 149      * @param attrAggRuleMask - the Attribute Aggregation Rule Mask
 150      * @param minBuffer - the Minimum Buffer
 151      * @param targetBuffer - the Target Buffer
 152      * @param maxBuffer - the Maximum Buffer
 153      */
 154     public BEEnvelop(byte trafficPriority, int transPolicy, int maxSusTrafficRate, int maxTrafficBurst,
 155                      int minResTrafficRate, short assumedMinConcatBurst, short maxConcatBurst, int upPeakTrafficRate,
 156                      int reqAttrMask, int forbidAttrMask, int attrAggRuleMask, int minBuffer, int targetBuffer,
 157                      int maxBuffer) {
 158         this.trafficPriority = trafficPriority;
 159         this.transPolicy = transPolicy;
 160         this.maxSusTrafficRate = maxSusTrafficRate;
 161         this.maxTrafficBurst = maxTrafficBurst;
 162         this.minResTrafficRate = minResTrafficRate;
 163         this.assumedMinConcatBurst = assumedMinConcatBurst;
 164         this.maxConcatBurst = maxConcatBurst;
 165         this.upPeakTrafficRate = upPeakTrafficRate;
 166         this.reqAttrMask = reqAttrMask;
 167         this.forbidAttrMask = forbidAttrMask;
 168         this.attrAggRuleMask = attrAggRuleMask;
 169         this.minBuffer = minBuffer;
 170         this.targetBuffer = targetBuffer;
 171         this.maxBuffer = maxBuffer;
 172     }
 173
 174     /**
 175      * Returns a List of Bytes which can be parsed back into an equivalent object. This method is generally used when
 176      * streaming this object over a Socket
 177      * @return - the byte translation of this object
 178      */
 179     public List<Byte> getBytes() {
 180         final List<Byte> byteList = new ArrayList<>();
 181         byteList.addAll(Bytes.asList(trafficPriority, (byte) 0, (byte) 0, (byte) 0));
 182         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(transPolicy)));
 183         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(maxSusTrafficRate)));
 184         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(maxTrafficBurst)));
 185         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(minResTrafficRate)));
 186         byteList.addAll(Bytes.asList(COPSMsgParser.shortToBytes(assumedMinConcatBurst)));
 187         byteList.addAll(Bytes.asList(COPSMsgParser.shortToBytes(maxConcatBurst)));
 188         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(upPeakTrafficRate)));
 189         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(reqAttrMask)));
 190         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(forbidAttrMask)));
 191         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(attrAggRuleMask)));
 192         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(minBuffer)));
 193         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(targetBuffer)));
 194         byteList.addAll(Bytes.asList(COPSMsgParser.intToBytes(maxBuffer)));
 195         return byteList;
 196     }
 197
 198     @Override
 199     public boolean equals(final Object o) {
 200         if (this == o) {
 201             return true;
 202         }
 203         if (!(o instanceof BEEnvelop)) {
 204             return false;
 205         }
 206
 207         final BEEnvelop beEnvelop = (BEEnvelop) o;
 208
 209         return trafficPriority == beEnvelop.trafficPriority && transPolicy == beEnvelop.transPolicy &&
 210                 maxSusTrafficRate == beEnvelop.maxSusTrafficRate && maxTrafficBurst == beEnvelop.maxTrafficBurst &&
 211                 minResTrafficRate == beEnvelop.minResTrafficRate &&
 212                 assumedMinConcatBurst == beEnvelop.assumedMinConcatBurst &&
 213                 maxConcatBurst == beEnvelop.maxConcatBurst && upPeakTrafficRate == beEnvelop.upPeakTrafficRate &&
 214                 reqAttrMask == beEnvelop.reqAttrMask && forbidAttrMask == beEnvelop.forbidAttrMask &&
 215                 attrAggRuleMask == beEnvelop.attrAggRuleMask && minBuffer == beEnvelop.minBuffer &&
 216                 targetBuffer == beEnvelop.targetBuffer && maxBuffer == beEnvelop.maxBuffer;
 217
 218     }
 219
 220     @Override
 221     public int hashCode() {
 222         int result = (int) trafficPriority;
 223         result = 31 * result + transPolicy;
 224         result = 31 * result + maxSusTrafficRate;
 225         result = 31 * result + maxTrafficBurst;
 226         result = 31 * result + minResTrafficRate;
 227         result = 31 * result + (int) assumedMinConcatBurst;
 228         result = 31 * result + (int) maxConcatBurst;
 229         result = 31 * result + upPeakTrafficRate;
 230         result = 31 * result + reqAttrMask;
 231         result = 31 * result + forbidAttrMask;
 232         result = 31 * result + attrAggRuleMask;
 233         result = 31 * result + minBuffer;
 234         result = 31 * result + targetBuffer;
 235         result = 31 * result + maxBuffer;
 236         return result;
 237     }
 238
 239     /**
 240      * Returns an BEEnvelop object from a byte array
 241      * @param data - the data to parse
 242      * @return - the object or null if cannot be parsed
 243      * TODO - make me more robust as RuntimeExceptions can be thrown here.
 244      */
 245     public static BEEnvelop parse(final byte[] data) {
 246         if (data.length != 52) return null;
 247         return new BEEnvelop(data[0],
 248                 COPSMsgParser.bytesToInt(data[4], data[5], data[6], data[7]),
 249                 COPSMsgParser.bytesToInt(data[8], data[9], data[10], data[11]),
 250                 COPSMsgParser.bytesToInt(data[12], data[13], data[14], data[15]),
 251                 COPSMsgParser.bytesToInt(data[16], data[17], data[18], data[19]),
 252                 COPSMsgParser.bytesToShort(data[20], data[21]),
 253                 COPSMsgParser.bytesToShort(data[22], data[23]),
 254                 COPSMsgParser.bytesToInt(data[24], data[25], data[26], data[27]),
 255                 COPSMsgParser.bytesToInt(data[28], data[29], data[30], data[31]),
 256                 COPSMsgParser.bytesToInt(data[32], data[33], data[34], data[35]),
 257                 COPSMsgParser.bytesToInt(data[36], data[37], data[38], data[39]),
 258                 COPSMsgParser.bytesToInt(data[40], data[41], data[42], data[43]),
 259                 COPSMsgParser.bytesToInt(data[44], data[45], data[46], data[47]),
 260                 COPSMsgParser.bytesToInt(data[48], data[49], data[50], data[51]));
 261     }
 262 }