text: /*
   * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  package jdk.net;
  
  import java.lang.annotation.Native;
  
  /**
   * Represents the service level properties for the platform specific socket
   * option {@link ExtendedSocketOptions#SO_FLOW_SLA}.
   * <p>
   * The priority and bandwidth parameters must be set before
   * setting the socket option.
   * <p>
   * When the {@code SO_FLOW_SLA} option is set then it may not take effect
   * immediately. If the value of the socket option is obtained with
   * {@code getOption()} then the status may be returned as {@code INPROGRESS}
   * until it takes effect. The priority and bandwidth values are only valid when
   * the status is returned as OK.
   * <p>
   * When a security manager is installed, a {@link NetworkPermission}
   * is required to set or get this option.
   *
   * @since 1.8
   */
  public class SocketFlow {
  
      @Native public static final int UNSET = -1;
      @Native public static final int NORMAL_PRIORITY = 1;
      @Native public static final int HIGH_PRIORITY = 2;
  
      @Native private static final int NO_STATUS_VALUE = 0;
      @Native private static final int OK_VALUE = 1;
      @Native private static final int NO_PERMISSION_VALUE = 2;
      @Native private static final int NOT_CONNECTED_VALUE = 3;
      @Native private static final int NOT_SUPPORTED_VALUE = 4;
      @Native private static final int ALREADY_CREATED_VALUE = 5;
      @Native private static final int IN_PROGRESS_VALUE = 6;
      @Native private static final int OTHER_VALUE = 7;
  
      /**
       * Enumeration of the return values from the SO_FLOW_SLA
       * socket option. Both setting and getting the option return
       * one of these statuses, which reflect the state of socket's
       * flow.
       *
       * @since 1.8
       */
      public enum Status {
          /**
           * Set or get socket option has not been called yet. Status
           * values can only be retrieved after calling set or get.
           */
          NO_STATUS(NO_STATUS_VALUE),
          /**
           * Flow successfully created.
           */
          OK(OK_VALUE),
          /**
           * Caller has no permission to create flow.
           */
          NO_PERMISSION(NO_PERMISSION_VALUE),
          /**
           * Flow can not be created because socket is not connected.
           */
          NOT_CONNECTED(NOT_CONNECTED_VALUE),
          /**
           * Flow creation not supported for this socket.
           */
          NOT_SUPPORTED(NOT_SUPPORTED_VALUE),
          /**
           * A flow already exists with identical attributes.
           */
          ALREADY_CREATED(ALREADY_CREATED_VALUE),
          /**
           * A flow is being created.
           */
          IN_PROGRESS(IN_PROGRESS_VALUE),
          /**
           * Some other unspecified error.
           */
          OTHER(OTHER_VALUE);
  
          private final int value;
          Status(int value) { this.value = value; }
  
          static Status from(int value) {
              if      (value == NO_STATUS.value)       return NO_STATUS;
              else if (value == OK.value)              return OK;
              else if (value == NO_PERMISSION.value)   return NO_PERMISSION;
              else if (value == NOT_CONNECTED.value)   return NOT_CONNECTED;
              else if (value == NOT_SUPPORTED.value)   return NOT_SUPPORTED;
              else if (value == ALREADY_CREATED.value) return ALREADY_CREATED;
              else if (value == IN_PROGRESS.value)     return IN_PROGRESS;
              else if (value == OTHER.value)           return OTHER;
              else     throw new InternalError("Unknown value: " + value);
          }
      }
  
      private int priority = NORMAL_PRIORITY;
      private long bandwidth = UNSET;
      private Status status = Status.NO_STATUS;
  
      /**
       * Creates a new SocketFlow that can be used to set the SO_FLOW_SLA
       * socket option and create a socket flow.
       */
      public static SocketFlow create() {
          return new SocketFlow();
      }
  
      private SocketFlow() { }
  
      /**
       * Sets this SocketFlow's priority. Must be either NORMAL_PRIORITY
       * HIGH_PRIORITY. If not set, a flow's priority is normal.
       *
       * @throws IllegalArgumentException if priority is not NORMAL_PRIORITY or
       *         HIGH_PRIORITY.
       */
      public SocketFlow priority(int priority) {
          if (priority != NORMAL_PRIORITY && priority != HIGH_PRIORITY)
              throw new IllegalArgumentException("invalid priority :" + priority);
          this.priority = priority;
          return this;
      }
  
      /**
       * Sets this SocketFlow's bandwidth. Must be greater than or equal to zero.
       * A value of zero drops all packets for the socket.
       *
       * @throws IllegalArgumentException if bandwidth is less than zero.
       */
      public SocketFlow bandwidth(long bandwidth) {
          if (bandwidth < 0)
              throw new IllegalArgumentException("invalid bandwidth: " + bandwidth);
          this.bandwidth = bandwidth;
          return this;
      }
  
      /**
       * Returns this SocketFlow's priority.
       */
      public int priority() {
          return priority;
      }
  
      /**
       * Returns this SocketFlow's bandwidth.
       *
       * @return this SocketFlow's bandwidth, or {@code -1} if status is not OK.
       */
      public long bandwidth() {
          return bandwidth;
      }
  
      /**
       * Returns the Status value of this SocketFlow. NO_STATUS is returned
       * if the object was not used in a call to set or get the option.
       */
      public Status status() {
          return status;
      }
  
      void status(int status) {
          this.status = Status.from(status);
      }
  
      @Override
      public String toString() {
          StringBuilder sb = new StringBuilder(super.toString());
          sb.append(" [ priority=").append(priority())
            .append(", bandwidth=").append(bandwidth())
            .append(", status=").append(status())
            .append(" ]");
          return sb.toString();
      }
  }
  