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 //@jdk.Exported 47 public class SocketFlow { 48 49 private static final int UNSET = -1; 50 @Native public static final int NORMAL_PRIORITY = 1; 51 @Native public static final int HIGH_PRIORITY = 2; 52 53 private int priority = NORMAL_PRIORITY; 54 55 private long bandwidth = UNSET; 56 57 private Status status = Status.NO_STATUS; 58 59 private SocketFlow() {} 60 61 /** 62 * Enumeration of the return values from the SO_FLOW_SLA 63 * socket option. Both setting and getting the option return 64 * one of these statuses, which reflect the state of socket's 65 * flow. 66 */ 67 // @jdk.Exported 68 public enum Status { 69 /** 70 * Set or get socket option has not been called yet. Status 71 * values can only be retrieved after calling set or get. 72 */ 73 NO_STATUS, 74 /** 75 * Flow successfully created. 76 */ 77 OK, 78 /** 79 * Caller has no permission to create flow. 80 */ 81 NO_PERMISSION, 82 /** 83 * Flow can not be created because socket is not connected. 84 */ 85 NOT_CONNECTED, 86 /** 87 * Flow creation not supported for this socket. 88 */ 89 NOT_SUPPORTED, 90 /** 91 * A flow already exists with identical attributes. 92 */ 93 ALREADY_CREATED, 94 /** 95 * A flow is being created. 96 */ 97 IN_PROGRESS, 98 /** 99 * Some other unspecified error. 100 */ 101 OTHER 102 } 103 104 /** 105 * Creates a new SocketFlow that can be used to set the SO_FLOW_SLA 106 * socket option and create a socket flow. 107 */ 108 public static SocketFlow create() { 109 return new SocketFlow(); 110 } 111 112 /** 113 * Sets this SocketFlow's priority. Must be either NORMAL_PRIORITY 114 * HIGH_PRIORITY. If not set, a flow's priority is normal. 115 * 116 * @throws IllegalArgumentException if priority is not NORMAL_PRIORITY or 117 * HIGH_PRIORITY. 118 */ 119 public SocketFlow priority(int priority) { 120 if (priority != NORMAL_PRIORITY && priority != HIGH_PRIORITY) { 121 throw new IllegalArgumentException("invalid priority"); 122 } 123 this.priority = priority; 124 return this; 125 } 126 127 /** 128 * Sets this SocketFlow's bandwidth. Must be greater than or equal to zero. 129 * A value of zero drops all packets for the socket. 130 * 131 * @throws IllegalArgumentException if bandwidth is less than zero. 132 */ 133 public SocketFlow bandwidth(long bandwidth) { 134 if (bandwidth < 0) { 135 throw new IllegalArgumentException("invalid bandwidth"); 136 } else { 137 this.bandwidth = bandwidth; 138 } 139 return this; 140 } 141 142 /** 143 * Returns this SocketFlow's priority. 144 */ 145 public int priority() { 146 return priority; 147 } 148 149 /** 150 * Returns this SocketFlow's bandwidth. 151 * 152 * @return this SocketFlow's bandwidth, or {@code -1} if status is not OK. 153 */ 154 public long bandwidth() { 155 return bandwidth; 156 } 157 158 /** 159 * Returns the Status value of this SocketFlow. NO_STATUS is returned 160 * if the object was not used in a call to set or get the option. 161 */ 162 public Status status() { 163 return status; 164 } 165 } 166
