0
# Parameter Flow Rules
1

2
Configuration objects that define how parameter flow control should behave. `ParamFlowRule` specifies which parameters to monitor, thresholds, control behaviors, and exception handling for hot spot parameter flow control.
3

4
## Capabilities
5

6
### Basic Rule Creation
7

8
Creates parameter flow rules for monitoring specific parameters in method calls.
9

10
```java { .api }
11
/**
12
 * Default constructor for parameter flow rule
13
 */
14
public ParamFlowRule();
15

16
/**
17
 * Constructor with resource name
18
 * @param resourceName the resource name to monitor
19
 */
20
public ParamFlowRule(String resourceName);
21
```
22

23
**Usage Example:**
24

25
```java
26
// Create rule for monitoring user service
27
ParamFlowRule rule = new ParamFlowRule("userService");
28

29
// Or create empty rule and set resource later
30
ParamFlowRule rule2 = new ParamFlowRule();
31
rule2.setResource("productService");
32
```
33

34
### Parameter Index Configuration
35

36
Specifies which parameter position to monitor in the method arguments.
37

38
```java { .api }
39
/**
40
 * Set the parameter index to monitor
41
 * @param paramIdx parameter index (0-based)
42
 * @return this rule for method chaining
43
 */
44
public ParamFlowRule setParamIdx(Integer paramIdx);
45

46
/**
47
 * Get the parameter index
48
 * @return parameter index
49
 */
50
public Integer getParamIdx();
51
```
52

53
**Usage Example:**
54

55
```java
56
// Monitor the first parameter (index 0)
57
ParamFlowRule rule = new ParamFlowRule("userService")
58
    .setParamIdx(0);
59

60
// Monitor the second parameter (index 1)  
61
ParamFlowRule productRule = new ParamFlowRule("productService")
62
    .setParamIdx(1);
63

64
// For method: processUser(String userId, String productId)
65
// paramIdx=0 monitors userId, paramIdx=1 monitors productId
66
```
67

68
### Threshold Configuration
69

70
Sets the flow control threshold for parameter values.
71

72
```java { .api }
73
/**
74
 * Set the threshold count
75
 * @param count the threshold count
76
 * @return this rule for method chaining
77
 */
78
public ParamFlowRule setCount(double count);
79

80
/**
81
 * Get the threshold count
82
 * @return threshold count
83
 */
84
public double getCount();
85
```
86

87
**Usage Example:**
88

89
```java
90
// Allow maximum 5 requests per second for each parameter value
91
ParamFlowRule rule = new ParamFlowRule("userService")
92
    .setParamIdx(0)
93
    .setCount(5);
94

95
// Allow 100 requests per second for product queries
96
ParamFlowRule productRule = new ParamFlowRule("productService")
97
    .setParamIdx(0)
98
    .setCount(100);
99
```
100

101
### Grade Configuration
102

103
Specifies the metric type for flow control (QPS or thread count).
104

105
```java { .api }
106
/**
107
 * Set the threshold type of flow control (0: thread count, 1: QPS)
108
 * @param grade the grade type
109
 * @return this rule for method chaining
110
 */
111
public ParamFlowRule setGrade(int grade);
112

113
/**
114
 * Get the threshold type
115
 * @return grade type
116
 */
117
public int getGrade();
118
```
119

120
**Usage Example:**
121

122
```java
123
import com.alibaba.csp.sentinel.slots.block.RuleConstant;
124

125
// QPS-based flow control (default)
126
ParamFlowRule qpsRule = new ParamFlowRule("userService")
127
    .setParamIdx(0)
128
    .setCount(10)
129
    .setGrade(RuleConstant.FLOW_GRADE_QPS);
130

131
// Thread count-based flow control
132
ParamFlowRule threadRule = new ParamFlowRule("heavyService")
133
    .setParamIdx(0)
134
    .setCount(5)
135
    .setGrade(RuleConstant.FLOW_GRADE_THREAD);
136
```
137

138
### Control Behavior Configuration
139

140
Configures traffic shaping behavior when flow control is triggered.
141

142
```java { .api }
143
/**
144
 * Set traffic shaping behavior
145
 * @param controlBehavior the control behavior
146
 * @return this rule for method chaining
147
 */
148
public ParamFlowRule setControlBehavior(int controlBehavior);
149

150
/**
151
 * Get the control behavior
152
 * @return control behavior
153
 */
154
public int getControlBehavior();
155
```
156

157
**Usage Example:**
158

159
```java
160
import com.alibaba.csp.sentinel.slots.block.RuleConstant;
161

162
// Default behavior - direct rejection
163
ParamFlowRule defaultRule = new ParamFlowRule("userService")
164
    .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_DEFAULT);
165

166
// Rate limiting with queuing
167
ParamFlowRule rateLimitRule = new ParamFlowRule("userService")
168
    .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_RATE_LIMITER)
169
    .setMaxQueueingTimeMs(500);
170
```
171

172
### Burst and Duration Configuration
173

174
Configures burst handling and time window settings.
175

176
```java { .api }
177
/**
178
 * Set burst count for handling traffic spikes
179
 * @param burstCount burst count
180
 * @return this rule for method chaining
181
 */
182
public ParamFlowRule setBurstCount(int burstCount);
183

184
/**
185
 * Set duration in seconds for the time window
186
 * @param durationInSec duration in seconds
187
 * @return this rule for method chaining
188
 */
189
public ParamFlowRule setDurationInSec(long durationInSec);
190

191
/**
192
 * Set maximum queuing time in milliseconds
193
 * @param maxQueueingTimeMs max queuing time
194
 * @return this rule for method chaining
195
 */
196
public ParamFlowRule setMaxQueueingTimeMs(int maxQueueingTimeMs);
197
```
198

199
**Usage Example:**
200

201
```java
202
// Configure rule with burst handling and custom time window
203
ParamFlowRule rule = new ParamFlowRule("userService")
204
    .setParamIdx(0)
205
    .setCount(10)              // 10 requests per second normally
206
    .setBurstCount(5)          // Allow burst of 5 extra requests
207
    .setDurationInSec(2)       // Use 2-second time window
208
    .setMaxQueueingTimeMs(200); // Queue requests for up to 200ms
209
```
210

211
### Exception Items Configuration
212

213
Configures special handling for specific parameter values.
214

215
```java { .api }
216
/**
217
 * Set the exception items of parameter; you can set threshold to a specific parameter value
218
 * @param paramFlowItemList list of exception items
219
 * @return this rule for method chaining
220
 */
221
public ParamFlowRule setParamFlowItemList(List<ParamFlowItem> paramFlowItemList);
222

223
/**
224
 * Get the exception items
225
 * @return list of exception items
226
 */
227
public List<ParamFlowItem> getParamFlowItemList();
228

229
/**
230
 * Retrieve exclusive item count for a specific parameter value
231
 * @param value the parameter value
232
 * @return exclusive count for the value, or null if not found
233
 */
234
public Integer retrieveExclusiveItemCount(Object value);
235
```
236

237
**Usage Example:**
238

239
```java
240
// Create exception items for VIP users
241
ParamFlowItem vipItem = new ParamFlowItem()
242
    .setObject("VIP_USER")
243
    .setClassType(String.class.getName())
244
    .setCount(50); // VIP users get 50 QPS instead of default 10
245

246
ParamFlowItem adminItem = new ParamFlowItem()
247
    .setObject("ADMIN_USER")
248
    .setClassType(String.class.getName())
249
    .setCount(100); // Admin users get 100 QPS
250

251
ParamFlowRule rule = new ParamFlowRule("userService")
252
    .setParamIdx(0)
253
    .setCount(10) // Default 10 QPS for regular users
254
    .setParamFlowItemList(Arrays.asList(vipItem, adminItem));
255
```
256

257
### Cluster Mode Configuration
258

259
Enables distributed parameter flow control across multiple instances.
260

261
```java { .api }
262
/**
263
 * Set cluster mode
264
 * @param clusterMode true to enable cluster mode
265
 * @return this rule for method chaining
266
 */
267
public ParamFlowRule setClusterMode(boolean clusterMode);
268

269
/**
270
 * Check if cluster mode is enabled
271
 * @return true if cluster mode is enabled
272
 */
273
public boolean isClusterMode();
274

275
/**
276
 * Set cluster configuration
277
 * @param clusterConfig cluster configuration
278
 * @return this rule for method chaining
279
 */
280
public ParamFlowRule setClusterConfig(ParamFlowClusterConfig clusterConfig);
281

282
/**
283
 * Get cluster configuration
284
 * @return cluster configuration
285
 */
286
public ParamFlowClusterConfig getClusterConfig();
287
```
288

289
**Usage Example:**
290

291
```java
292
// Configure rule for cluster mode
293
ParamFlowClusterConfig clusterConfig = new ParamFlowClusterConfig()
294
    .setFlowId(12345L)
295
    .setThresholdType(ClusterRuleConstant.FLOW_THRESHOLD_GLOBAL);
296

297
ParamFlowRule clusterRule = new ParamFlowRule("userService")
298
    .setParamIdx(0)
299
    .setCount(100)
300
    .setClusterMode(true)
301
    .setClusterConfig(clusterConfig);
302
```
303

304
## Rule Validation
305

306
Parameter flow rules are validated when loaded:
307

308
- Resource name must not be blank
309
- Count must be non-negative  
310
- Parameter index must not be null
311
- Burst count must be non-negative
312
- Duration must be positive
313
- Control behavior must be valid
314
- Cluster configuration must be valid if cluster mode is enabled
315

316
## Complete Example
317

318
```java
319
import com.alibaba.csp.sentinel.slots.block.flow.param.*;
320
import com.alibaba.csp.sentinel.slots.block.RuleConstant;
321
import java.util.Arrays;
322

323
// Create comprehensive parameter flow rule
324
ParamFlowRule rule = new ParamFlowRule("userService")
325
    .setParamIdx(0)                                    // Monitor first parameter
326
    .setCount(10)                                      // 10 QPS for regular users
327
    .setGrade(RuleConstant.FLOW_GRADE_QPS)            // Use QPS mode
328
    .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_DEFAULT) // Direct rejection
329
    .setBurstCount(3)                                  // Allow burst of 3
330
    .setDurationInSec(1);                             // 1-second window
331

332
// Add VIP user exception
333
ParamFlowItem vipException = new ParamFlowItem()
334
    .setObject("VIP_123")
335
    .setClassType(String.class.getName())
336
    .setCount(50);
337

338
rule.setParamFlowItemList(Arrays.asList(vipException));
339

340
// Load the rule
341
ParamFlowRuleManager.loadRules(Arrays.asList(rule));
342
```