0
# Sentinel Cluster Client Default
1

2
The Sentinel Cluster Client Default provides the default cluster client implementation for Sentinel's distributed flow control capabilities. It enables coordination between multiple application instances through a centralized cluster server using high-performance Netty communication.
3

4
## Package Information
5

6
- **Package Name**: sentinel-cluster-client-default
7
- **Package Type**: Maven (JAR)
8
- **Language**: Java
9
- **Group ID**: com.alibaba.csp
10
- **Artifact ID**: sentinel-cluster-client-default
11
- **Installation**: Add Maven dependency:
12

13
```xml
14
<dependency>
15
    <groupId>com.alibaba.csp</groupId>
16
    <artifactId>sentinel-cluster-client-default</artifactId>
17
    <version>1.8.8</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import com.alibaba.csp.sentinel.cluster.client.DefaultClusterTokenClient;
25
import com.alibaba.csp.sentinel.cluster.client.ClusterTokenClient;
26
import com.alibaba.csp.sentinel.cluster.client.NettyTransportClient;
27
import com.alibaba.csp.sentinel.cluster.client.config.ClusterClientConfigManager;
28
import com.alibaba.csp.sentinel.cluster.client.config.ClusterClientConfig;
29
import com.alibaba.csp.sentinel.cluster.client.config.ClusterClientAssignConfig;
30
import com.alibaba.csp.sentinel.cluster.client.codec.registry.RequestDataWriterRegistry;
31
import com.alibaba.csp.sentinel.cluster.client.codec.registry.ResponseDataDecodeRegistry;
32
import com.alibaba.csp.sentinel.command.handler.ModifyClusterClientConfigHandler;
33
import com.alibaba.csp.sentinel.command.handler.FetchClusterClientConfigHandler;
34
import com.alibaba.csp.sentinel.command.entity.ClusterClientStateEntity;
35
```
36

37
## Basic Usage
38

39
```java
40
import com.alibaba.csp.sentinel.cluster.client.DefaultClusterTokenClient;
41
import com.alibaba.csp.sentinel.cluster.client.config.ClusterClientConfigManager;
42
import com.alibaba.csp.sentinel.cluster.client.config.ClusterClientAssignConfig;
43
import com.alibaba.csp.sentinel.cluster.TokenResult;
44
import com.alibaba.csp.sentinel.cluster.TokenResultStatus;
45

46
// Configure server connection
47
ClusterClientAssignConfig assignConfig = new ClusterClientAssignConfig("localhost", 8719);
48
ClusterClientConfigManager.applyNewAssignConfig(assignConfig);
49

50
// Create and start client
51
DefaultClusterTokenClient client = new DefaultClusterTokenClient();
52
client.start();
53

54
// Request flow control tokens
55
TokenResult result = client.requestToken(12345L, 1, false);
56
if (result.getStatus() == TokenResultStatus.OK) {
57
    // Token acquired successfully
58
    System.out.println("Remaining tokens: " + result.getRemaining());
59
} else {
60
    // Token request failed or blocked
61
    System.out.println("Request failed: " + result.getStatus());
62
}
63

64
// Clean up
65
client.stop();
66
```
67

68
## Architecture
69

70
The Sentinel Cluster Client Default is built around several key components:
71

72
- **Token Client**: `DefaultClusterTokenClient` provides the main API for requesting flow control tokens from cluster servers
73
- **Transport Layer**: `NettyTransportClient` handles high-performance network communication using Netty
74
- **Configuration Management**: `ClusterClientConfigManager` manages dynamic configuration updates for server assignments and client settings
75
- **Codec System**: Request/response encoding and decoding for efficient network serialization
76
- **Command Interface**: HTTP command handlers for runtime configuration and monitoring
77

78
## Capabilities
79

80
### Cluster Token Client
81

82
Main interface for requesting flow control tokens from the cluster server. Supports regular flow control, parameterized flow control, and connection lifecycle management.
83

84
```java { .api }
85
public class DefaultClusterTokenClient implements ClusterTokenClient {
86
    public DefaultClusterTokenClient();
87
    public void start() throws Exception;
88
    public void stop() throws Exception;
89
    public int getState();
90
    public TokenServerDescriptor currentServer();
91
    public TokenResult requestToken(Long flowId, int acquireCount, boolean prioritized);
92
    public TokenResult requestParamToken(Long flowId, int acquireCount, Collection<Object> params);
93
}
94
```
95

96
[Cluster Token Client](./cluster-token-client.md)
97

98
### Configuration Management
99

100
Dynamic configuration system for managing cluster server assignments and client settings. Supports property-based configuration updates and server change notifications.
101

102
```java { .api }
103
public final class ClusterClientConfigManager {
104
    public static void applyNewConfig(ClusterClientConfig config);
105
    public static void applyNewAssignConfig(ClusterClientAssignConfig assignConfig);
106
    public static void addServerChangeObserver(ServerChangeObserver observer);
107
    public static String getServerHost();
108
    public static int getServerPort();
109
    public static int getRequestTimeout();
110
}
111
```
112

113
[Configuration Management](./configuration.md)
114

115
### Network Transport
116

117
Low-level Netty transport client for cluster server communication. Handles connection management, reconnection logic, and request/response processing.
118

119
```java { .api }
120
public class NettyTransportClient implements ClusterTransportClient {
121
    public NettyTransportClient(String host, int port);
122
    public void start() throws Exception;
123
    public void stop() throws Exception;
124
    public boolean isReady();
125
    public ClusterResponse sendRequest(ClusterRequest request) throws Exception;
126
}
127
```
128

129
[Network Transport](./network-transport.md)
130

131
### Codec System
132

133
Request and response encoding/decoding system for efficient network serialization. Provides extensible registry for custom data types and protocols.
134

135
```java { .api }
136
public final class RequestDataWriterRegistry {
137
    public static <T> boolean addWriter(int type, EntityWriter<T, ByteBuf> writer);
138
    public static EntityWriter<Object, ByteBuf> getWriter(int type);
139
}
140

141
public final class ResponseDataDecodeRegistry {
142
    public static boolean addDecoder(int type, EntityDecoder<ByteBuf, ?> decoder);
143
    public static EntityDecoder<ByteBuf, Object> getDecoder(int type);
144
}
145
```
146

147
[Codec System](./codec-system.md)
148

149
### Command Interface
150

151
HTTP command handlers for runtime configuration and monitoring of cluster client settings and state.
152

153
```java { .api }
154
@CommandMapping(name = "cluster/client/modifyConfig", desc = "modify cluster client config")
155
public class ModifyClusterClientConfigHandler implements CommandHandler<String> {
156
    public CommandResponse<String> handle(CommandRequest request);
157
}
158

159
@CommandMapping(name = "cluster/client/fetchConfig", desc = "get cluster client config")
160
public class FetchClusterClientConfigHandler implements CommandHandler<String> {
161
    public CommandResponse<String> handle(CommandRequest request);
162
}
163
```
164

165
[Command Interface](./command-interface.md)
166

167
## Types
168

169
```java { .api }
170
// Configuration classes
171
public class ClusterClientConfig {
172
    public Integer getRequestTimeout();
173
    public ClusterClientConfig setRequestTimeout(Integer requestTimeout);
174
}
175

176
public class ClusterClientAssignConfig {
177
    public ClusterClientAssignConfig(String serverHost, Integer serverPort);
178
    public String getServerHost();
179
    public Integer getServerPort();
180
    public ClusterClientAssignConfig setServerHost(String serverHost);
181
    public ClusterClientAssignConfig setServerPort(Integer serverPort);
182
}
183

184
// Observer interface
185
public interface ServerChangeObserver {
186
    void onRemoteServerChange(ClusterClientAssignConfig assignConfig);
187
}
188

189
// Command entity for state management and HTTP command interfaces
190
public class ClusterClientStateEntity {
191
    public String getServerHost();
192
    public ClusterClientStateEntity setServerHost(String serverHost);
193
    public Integer getServerPort();
194
    public ClusterClientStateEntity setServerPort(Integer serverPort);
195
    public Integer getClientState();
196
    public ClusterClientStateEntity setClientState(Integer clientState);
197
    public Integer getRequestTimeout();
198
    public ClusterClientStateEntity setRequestTimeout(Integer requestTimeout);
199
    public ClusterClientConfig toClientConfig();
200
    public ClusterClientAssignConfig toAssignConfig();
201
}
202

203
// Constants
204
public final class ClientConstants {
205
    public static final int TYPE_PING = 0;
206
    public static final int TYPE_FLOW = 1;
207
    public static final int TYPE_PARAM_FLOW = 2;
208
    public static final int CLIENT_STATUS_OFF = 0;
209
    public static final int CLIENT_STATUS_PENDING = 1;
210
    public static final int CLIENT_STATUS_STARTED = 2;
211
}
212
```