1 /*

     2  * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package jdk.net;

    27 

    28 import java.lang.annotation.Native;

    29 

    30 /**

    31  * Represents the service level properties for the platform specific socket

    32  * option {@link ExtendedSocketOptions#SO_FLOW_SLA}.

    33  * <p>

    34  * The priority and bandwidth parameters must be set before

    35  * setting the socket option.

    36  * <p>

    37  * When the {@code SO_FLOW_SLA} option is set then it may not take effect

    38  * immediately. If the value of the socket option is obtained with

    39  * {@code getOption()} then the status may be returned as {@code INPROGRESS}

    40  * until it takes effect. The priority and bandwidth values are only valid when

    41  * the status is returned as OK.

    42  * <p>

    43  * When a security manager is installed, a {@link NetworkPermission}

    44  * is required to set or get this option.

    45  *

    46  * @since 1.8

    47  */

    48 public class SocketFlow {

    49 

    50     @Native public static final int UNSET = -1;

    51     @Native public static final int NORMAL_PRIORITY = 1;

    52     @Native public static final int HIGH_PRIORITY = 2;

    53 

    54     @Native private static final int NO_STATUS_VALUE = 0;

    55     @Native private static final int OK_VALUE = 1;

    56     @Native private static final int NO_PERMISSION_VALUE = 2;

    57     @Native private static final int NOT_CONNECTED_VALUE = 3;

    58     @Native private static final int NOT_SUPPORTED_VALUE = 4;

    59     @Native private static final int ALREADY_CREATED_VALUE = 5;

    60     @Native private static final int IN_PROGRESS_VALUE = 6;

    61     @Native private static final int OTHER_VALUE = 7;

    62 

    63     /**

    64      * Enumeration of the return values from the SO_FLOW_SLA

    65      * socket option. Both setting and getting the option return

    66      * one of these statuses, which reflect the state of socket's

    67      * flow.

    68      *

    69      * @since 1.8

    70      */

    71     public enum Status {

    72         /**

    73          * Set or get socket option has not been called yet. Status

    74          * values can only be retrieved after calling set or get.

    75          */

    76         NO_STATUS(NO_STATUS_VALUE),

    77         /**

    78          * Flow successfully created.

    79          */

    80         OK(OK_VALUE),

    81         /**

    82          * Caller has no permission to create flow.

    83          */

    84         NO_PERMISSION(NO_PERMISSION_VALUE),

    85         /**

    86          * Flow can not be created because socket is not connected.

    87          */

    88         NOT_CONNECTED(NOT_CONNECTED_VALUE),

    89         /**

    90          * Flow creation not supported for this socket.

    91          */

    92         NOT_SUPPORTED(NOT_SUPPORTED_VALUE),

    93         /**

    94          * A flow already exists with identical attributes.

    95          */

    96         ALREADY_CREATED(ALREADY_CREATED_VALUE),

    97         /**

    98          * A flow is being created.

    99          */

   100         IN_PROGRESS(IN_PROGRESS_VALUE),

   101         /**

   102          * Some other unspecified error.

   103          */

   104         OTHER(OTHER_VALUE);

   105 

   106         private final int value;

   107         Status(int value) { this.value = value; }

   108 

   109         static Status from(int value) {

   110             if      (value == NO_STATUS.value)       return NO_STATUS;

   111             else if (value == OK.value)              return OK;

   112             else if (value == NO_PERMISSION.value)   return NO_PERMISSION;

   113             else if (value == NOT_CONNECTED.value)   return NOT_CONNECTED;

   114             else if (value == NOT_SUPPORTED.value)   return NOT_SUPPORTED;

   115             else if (value == ALREADY_CREATED.value) return ALREADY_CREATED;

   116             else if (value == IN_PROGRESS.value)     return IN_PROGRESS;

   117             else if (value == OTHER.value)           return OTHER;

   118             else     throw new InternalError("Unknown value: " + value);

   119         }

   120     }

   121 

   122     private int priority = NORMAL_PRIORITY;

   123     private long bandwidth = UNSET;

   124     private Status status = Status.NO_STATUS;

   125 

   126     /**

   127      * Creates a new SocketFlow that can be used to set the SO_FLOW_SLA

   128      * socket option and create a socket flow.

   129      */

   130     public static SocketFlow create() {

   131         return new SocketFlow();

   132     }

   133 

   134     private SocketFlow() { }

   135 

   136     /**

   137      * Sets this SocketFlow's priority. Must be either NORMAL_PRIORITY

   138      * HIGH_PRIORITY. If not set, a flow's priority is normal.

   139      *

   140      * @throws IllegalArgumentException if priority is not NORMAL_PRIORITY or

   141      *         HIGH_PRIORITY.

   142      */

   143     public SocketFlow priority(int priority) {

   144         if (priority != NORMAL_PRIORITY && priority != HIGH_PRIORITY)

   145             throw new IllegalArgumentException("invalid priority :" + priority);

   146         this.priority = priority;

   147         return this;

   148     }

   149 

   150     /**

   151      * Sets this SocketFlow's bandwidth. Must be greater than or equal to zero.

   152      * A value of zero drops all packets for the socket.

   153      *

   154      * @throws IllegalArgumentException if bandwidth is less than zero.

   155      */

   156     public SocketFlow bandwidth(long bandwidth) {

   157         if (bandwidth < 0)

   158             throw new IllegalArgumentException("invalid bandwidth: " + bandwidth);

   159         this.bandwidth = bandwidth;

   160         return this;

   161     }

   162 

   163     /**

   164      * Returns this SocketFlow's priority.

   165      */

   166     public int priority() {

   167         return priority;

   168     }

   169 

   170     /**

   171      * Returns this SocketFlow's bandwidth.

   172      *

   173      * @return this SocketFlow's bandwidth, or {@code -1} if status is not OK.

   174      */

   175     public long bandwidth() {

   176         return bandwidth;

   177     }

   178 

   179     /**

   180      * Returns the Status value of this SocketFlow. NO_STATUS is returned

   181      * if the object was not used in a call to set or get the option.

   182      */

   183     public Status status() {

   184         return status;

   185     }

   186 

   187     void status(int status) {

   188         this.status = Status.from(status);

   189     }

   190 

   191     @Override

   192     public String toString() {

   193         StringBuilder sb = new StringBuilder(super.toString());

   194         sb.append(" [ priority=").append(priority())

   195           .append(", bandwidth=").append(bandwidth())

   196           .append(", status=").append(status())

   197           .append(" ]");

   198         return sb.toString();

   199     }

   200 }