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

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