packetcable-driver/src/main/java/org/pcmm/gates/IGateSpec.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;
  10
  11 import org.pcmm.base.IPCMMBaseObject;
  12
  13 /**
  14  * GateSpec describes specific authorization parameters defining a Gate (i.e., QoS limits, timers, etc.).
  15  *
  16  * From the Packetcable Multimedia specification section 6.1.4
  17  *
  18  * The GateSpec describes some high-level attributes of the Gate, and contains information regarding the treatment of
  19  * other objects specified in the Gate message. Information contained in a GateSpec is outlined below.
  20  *
  21  * * SessionClassID
  22  * * Direction
  23  * * AUTHORIZED Timer
  24  * * RESERVED Timer
  25  * * Committed Timer
  26  * * Committed Recovery Timer
  27  * * DSCP/TOS Overwrite
  28  * * DSCP/TOS Mask
  29  *
  30  * SessionClassID provides a way for the Application Manager and the Policy Server to group Gates into different
  31  * classes with different authorization characteristics. For example, one could use the SessionClassID to represent
  32  * some prioritization or preemption scheme that would allow either the Policy Server or the CMTS to preempt a preauthorized
  33  * Gate in favor of allowing a new Gate with a higher priority to be authorized.
  34  *
  35  * Direction indicates whether the Gate is for an upstream or downstream flow. Depending on this direction, the CMTS
  36  * MUST reserve and activate the DOCSIS flows accordingly. For Multicast Gates the CMTS needs to only support
  37  * flows or gates in the downstream direction.
  38  *
  39  * AUTHORIZED Timer limits the amount of time the authorization must remain valid before it is reserved (see
  40  * Section 6.2).
  41  *
  42  * RESERVED Timer limits the amount of time the reservation must remain valid before the resources are committed (see
  43  * Section 6.2).
  44  *
  45  * Committed Timer limits the amount of time a committed service flow may remain idle.
  46  *
  47  * Committed Recovery Timer limits the amount of time that a committed service flow can remain without a
  48  * subsequent refresh message from the PS/AM once the PS/AM has been notified of inactivity (see Section 6.2).
  49  * DSCP/TOS Overwrite field can be used to overwrite the DSCP/TOS field of packets associated with the DOCSIS
  50  * Service Flow that corresponds to the Gate. This field may be unspecified in which case the DSCP/TOS field in the
  51  * packet is not over-written by the CMTS. This field may be used in both the upstream and downstream directions.
  52  * The CMTS MUST support DSCP/TOS overwrite for upstream gates. The CMTS MAY support DSCP/TOS
  53  * overwrite for downstream gates. If DSCP/TOS is enabled in a downstream gate and the CMTS does not support that
  54  * function, then the field is ignored. The manner in which the CMTS interprets the DSCP/TOS Overwrite & Mask
  55  * fields and transforms it into the corresponding DOCSIS Service Flow Parameters is defined in Section 6.4.2.5.
  56  */
  57 public interface IGateSpec extends IPCMMBaseObject {
  58
  59     /**
  60      * The S-Type for Gate Specifications
  61      */
  62     byte STYPE = 1;
  63
  64     /**
  65      * <p>
  66      * Direction indicates whether the Gate is for an upstream or downstream
  67      * flow. Depending on this direction, the CMTS MUST reserve and activate the
  68      * DOCSIS flows accordingly. For Multicast Gates the CMTS needs to only
  69      * support flows or gates in the downstream direction.
  70      * </p>
  71      *
  72      *
  73      */
  74     enum Direction {
  75
  76         UPSTREAM((byte) 1), DOWNSTREAM((byte) 0);
  77
  78         Direction(byte value) {
  79             this.value = value;
  80         }
  81
  82         public byte getValue() {
  83             return value;
  84         }
  85
  86         @Override
  87         public String toString() {
  88             switch (value) {
  89             case 1:
  90                 return "Upstream";
  91             default:
  92                 return "Downstream";
  93             }
  94         }
  95
  96         private byte value;
  97
  98         public static Direction valueOf(byte v) {
  99             switch (v) {
 100             case 0:
 101                 return Direction.DOWNSTREAM;
 102             case 1:
 103                 return Direction.UPSTREAM;
 104             default:
 105                 throw new IllegalArgumentException("not supported value");
 106             }
 107         }
 108
 109     }
 110
 111     /**
 112      * <p>
 113      * provides a way for the Application Manager and the Policy Server to group
 114      * Gates into different classes with different authorization
 115      * characteristics. For example, one could use the SessionClassID to
 116      * represent some prioritization or preemption scheme that would allow
 117      * either the Policy Server or the CMTS to preempt a pre-authorized Gate in
 118      * favor of allowing a new Gate with a higher priority to be authorized.
 119      * </p>
 120      *
 121      * @return session class ID;
 122      */
 123     ISessionClassID getSessionClassID();
 124
 125     /**
 126      *
 127      * @return direction.
 128      */
 129     Direction getDirection();
 130
 131     /**
 132      *
 133      * sets the flow direction.
 134      */
 135     void setDirection(Direction direction);
 136
 137     /**
 138      * AUTHORIZED Timer limits the amount of time the authorization must remain
 139      * valid before it is reserved
 140      *
 141      * @return time in ms;
 142      */
 143     short getTimerT1();
 144
 145     /**
 146      * RESERVED Timer limits the amount of time the reservation must remain
 147      * valid before the resources are committed
 148      *
 149      * @return time in ms;
 150      */
 151     short getTimerT2();
 152
 153     /**
 154      * Committed Timer limits the amount of time a committed service flow may
 155      * remain idle.
 156      *
 157      * @return time in ms;
 158      */
 159     short getTimerT3();
 160
 161     /**
 162      * Committed Recovery Timer limits the amount of time that a committed
 163      * service flow can remain without a subsequent refresh message from the
 164      * PS/AM once the PS/AM has been notified of inactivity
 165      *
 166      * @return time in ms;
 167      */
 168     short getTimerT4();
 169
 170     /**
 171      *
 172      * @return DSCP/TOS
 173      */
 174     byte getDSCP_TOSOverwrite();
 175
 176     /**
 177      *
 178      * @return - the mask
 179      */
 180     byte getDSCP_TOSMask();
 181
 182 }