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