0
# Exception Items
1

2
Special parameter values that have different thresholds than the default rule. `ParamFlowItem` allows you to configure different limits for specific parameter values, enabling VIP user handling, special case parameters, and fine-grained parameter-based flow control.
3

4
## Capabilities
5

6
### Basic Item Creation
7

8
Creates exception items for specific parameter values with custom thresholds.
9

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

16
/**
17
 * Constructor with all parameters
18
 * @param object the parameter value as string
19
 * @param count the threshold count for this parameter value
20
 * @param classType the class type of the parameter
21
 */
22
public ParamFlowItem(String object, Integer count, String classType);
23
```
24

25
**Usage Example:**
26

27
```java
28
// Create exception item manually
29
ParamFlowItem item = new ParamFlowItem("VIP_USER", 50, String.class.getName());
30

31
// Or create with default constructor and set properties
32
ParamFlowItem item2 = new ParamFlowItem();
33
item2.setObject("ADMIN_USER")
34
     .setCount(100)
35
     .setClassType(String.class.getName());
36
```
37

38
### Static Factory Method
39

40
Creates exception items using a type-safe factory method.
41

42
```java { .api }
43
/**
44
 * Create a new parameter flow item with type safety
45
 * @param object the parameter value object
46
 * @param count the threshold count for this parameter value
47
 * @param <T> the type of the parameter
48
 * @return new ParamFlowItem instance
49
 * @throws IllegalArgumentException if object is null
50
 */
51
public static <T> ParamFlowItem newItem(T object, Integer count);
52
```
53

54
**Usage Example:**
55

56
```java
57
// Type-safe creation for different parameter types
58
ParamFlowItem stringItem = ParamFlowItem.newItem("VIP_USER", 50);
59
ParamFlowItem intItem = ParamFlowItem.newItem(12345, 25);
60
ParamFlowItem longItem = ParamFlowItem.newItem(999999L, 75);
61

62
// Class type is automatically set based on the object type
63
System.out.println(stringItem.getClassType()); // java.lang.String
64
System.out.println(intItem.getClassType());    // java.lang.Integer
65
System.out.println(longItem.getClassType());   // java.lang.Long
66
```
67

68
### Parameter Value Configuration
69

70
Configures the specific parameter value that should receive special treatment.
71

72
```java { .api }
73
/**
74
 * Set the parameter value as string representation
75
 * @param object the parameter value
76
 * @return this item for method chaining
77
 */
78
public ParamFlowItem setObject(String object);
79

80
/**
81
 * Get the parameter value
82
 * @return parameter value as string
83
 */
84
public String getObject();
85
```
86

87
**Usage Example:**
88

89
```java
90
// Configure different types of parameter values
91
ParamFlowItem userItem = new ParamFlowItem()
92
    .setObject("admin@company.com")  // Email-based parameter
93
    .setCount(100);
94

95
ParamFlowItem productItem = new ParamFlowItem()
96
    .setObject("PRODUCT_12345")      // Product ID parameter
97
    .setCount(200);
98

99
ParamFlowItem numericItem = new ParamFlowItem()
100
    .setObject("999")                // Numeric parameter as string
101
    .setCount(50);
102
```
103

104
### Threshold Configuration
105

106
Sets the custom threshold for the specific parameter value.
107

108
```java { .api }
109
/**
110
 * Set the threshold count for this parameter value
111
 * @param count the threshold count
112
 * @return this item for method chaining
113
 */
114
public ParamFlowItem setCount(Integer count);
115

116
/**
117
 * Get the threshold count
118
 * @return threshold count
119
 */
120
public Integer getCount();
121
```
122

123
**Usage Example:**
124

125
```java
126
// Different thresholds for different user types
127
ParamFlowItem regularUser = new ParamFlowItem()
128
    .setObject("REGULAR_USER")
129
    .setCount(10);  // 10 QPS for regular users
130

131
ParamFlowItem vipUser = new ParamFlowItem()
132
    .setObject("VIP_USER")
133
    .setCount(50);  // 50 QPS for VIP users
134

135
ParamFlowItem premiumUser = new ParamFlowItem()
136
    .setObject("PREMIUM_USER")
137
    .setCount(100); // 100 QPS for premium users
138
```
139

140
### Class Type Configuration
141

142
Specifies the Java class type of the parameter for proper type conversion.
143

144
```java { .api }
145
/**
146
 * Set the class type of the parameter
147
 * @param classType the fully qualified class name
148
 * @return this item for method chaining
149
 */
150
public ParamFlowItem setClassType(String classType);
151

152
/**
153
 * Get the class type
154
 * @return class type name
155
 */
156
public String getClassType();
157
```
158

159
**Usage Example:**
160

161
```java
162
// Configure class types for different parameter types
163
ParamFlowItem stringParam = new ParamFlowItem()
164
    .setObject("VIP_123")
165
    .setClassType(String.class.getName())
166
    .setCount(50);
167

168
ParamFlowItem intParam = new ParamFlowItem()
169
    .setObject("12345")
170
    .setClassType(Integer.class.getName())  // Will be parsed as Integer
171
    .setCount(25);
172

173
ParamFlowItem longParam = new ParamFlowItem()
174
    .setObject("999999999")
175
    .setClassType(Long.class.getName())     // Will be parsed as Long
176
    .setCount(75);
177

178
ParamFlowItem boolParam = new ParamFlowItem()
179
    .setObject("true")
180
    .setClassType(Boolean.class.getName())  // Will be parsed as Boolean
181
    .setCount(100);
182
```
183

184
## Supported Parameter Types
185

186
The following Java types are supported for parameter value parsing:
187

188
- `String` - Direct string matching (default if no class type specified)
189
- `Integer` / `int` - Parsed using `Integer.parseInt()`
190
- `Long` / `long` - Parsed using `Long.parseLong()`
191
- `Double` / `double` - Parsed using `Double.parseDouble()`
192
- `Float` / `float` - Parsed using `Float.parseFloat()`
193
- `Boolean` / `boolean` - Parsed using `Boolean.parseBoolean()`
194
- `Byte` / `byte` - Parsed using `Byte.parseByte()`
195
- `Short` / `short` - Parsed using `Short.parseShort()`
196
- `Character` / `char` - Uses first character of string
197

198
## Complete Usage Example
199

200
```java
201
import com.alibaba.csp.sentinel.slots.block.flow.param.*;
202
import java.util.Arrays;
203

204
// Create parameter flow rule with multiple exception items
205
ParamFlowRule rule = new ParamFlowRule("userService")
206
    .setParamIdx(0)
207
    .setCount(10);  // Default: 10 QPS for regular users
208

209
// Create exception items for different user types
210
ParamFlowItem vipUser = ParamFlowItem.newItem("VIP_USER", 50);
211
ParamFlowItem adminUser = ParamFlowItem.newItem("ADMIN_USER", 100);
212
ParamFlowItem guestUser = ParamFlowItem.newItem("GUEST_USER", 5);
213

214
// Numeric parameter exceptions
215
ParamFlowItem highPriorityProduct = new ParamFlowItem()
216
    .setObject("12345")
217
    .setClassType(Integer.class.getName())
218
    .setCount(200);
219

220
ParamFlowItem lowPriorityProduct = new ParamFlowItem()
221
    .setObject("99999")
222
    .setClassType(Integer.class.getName())
223
    .setCount(2);
224

225
// Apply all exception items to the rule
226
rule.setParamFlowItemList(Arrays.asList(
227
    vipUser, adminUser, guestUser, highPriorityProduct, lowPriorityProduct
228
));
229

230
// Load the rule
231
ParamFlowRuleManager.loadRules(Arrays.asList(rule));
232

233
// Usage in application:
234
// processUser("VIP_USER")      -> 50 QPS limit
235
// processUser("ADMIN_USER")    -> 100 QPS limit
236
// processUser("GUEST_USER")    -> 5 QPS limit
237
// processUser("REGULAR_USER")  -> 10 QPS limit (default)
238
// processProduct(12345)        -> 200 QPS limit
239
// processProduct(99999)        -> 2 QPS limit
240
// processProduct(55555)        -> 10 QPS limit (default)
241
```
242

243
## Runtime Behavior
244

245
When a parameter flow rule is evaluated:
246

247
1. The parameter value at the specified index is extracted
248
2. The value is converted to string representation
249
3. Exception items are checked for exact matches
250
4. If a match is found, the exception item's count is used
251
5. If no match is found, the rule's default count is used
252
6. Type conversion is performed based on the configured class type
253

254
## Thread Safety
255

256
`ParamFlowItem` objects are immutable once created and configured. All getter and setter operations are thread-safe. However, you should not modify exception items after they have been added to a rule that is already loaded into `ParamFlowRuleManager`.