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 // Android-removed: @jdk.Exported, not present on Android.
47 // @jdk.Exported
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 
SocketFlow()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     // Android-removed: @jdk.Exported, not present on Android.
69     // @jdk.Exported
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      */
create()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      */
priority(int priority)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      */
bandwidth(long bandwidth)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      */
priority()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      */
bandwidth()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      */
status()164     public Status status() {
165         return status;
166     }
167 }
168