0
# Core API and Factory Classes
1

2
Core factory classes and property constants for creating and configuring Nacos services. These are essential components for initializing any Nacos functionality and provide the foundation for all other operations.
3

4
## Capabilities
5

6
### NacosFactory
7

8
Central factory class for creating all Nacos service instances. This is the primary entry point for obtaining ConfigService, NamingService, and LockService instances.
9

10
```java { .api }
11
/**
12
 * Main factory class for creating Nacos service instances
13
 */
14
class NacosFactory {
15
    /**
16
     * Create ConfigService with properties configuration
17
     * @param properties Configuration properties containing server address and other settings
18
     * @return ConfigService instance for configuration management
19
     * @throws NacosException If service creation fails
20
     */
21
    static ConfigService createConfigService(Properties properties) throws NacosException;
22
    
23
    /**
24
     * Create ConfigService with simple server address
25
     * @param serverAddr Nacos server address (e.g., "127.0.0.1:8848")
26
     * @return ConfigService instance for configuration management
27
     * @throws NacosException If service creation fails
28
     */
29
    static ConfigService createConfigService(String serverAddr) throws NacosException;
30
    
31
    /**
32
     * Create NamingService with server address
33
     * @param serverAddr Nacos server address (e.g., "127.0.0.1:8848")
34
     * @return NamingService instance for service discovery
35
     * @throws NacosException If service creation fails
36
     */
37
    static NamingService createNamingService(String serverAddr) throws NacosException;
38
    
39
    /**
40
     * Create NamingService with properties configuration
41
     * @param properties Configuration properties containing server address and other settings
42
     * @return NamingService instance for service discovery
43
     * @throws NacosException If service creation fails
44
     */
45
    static NamingService createNamingService(Properties properties) throws NacosException;
46
    
47
    /**
48
     * Create NamingMaintainService with server address (Deprecated)
49
     * @param serverAddr Nacos server address
50
     * @return NamingMaintainService instance for service maintenance
51
     * @throws NacosException If service creation fails
52
     * @deprecated Use NamingService instead
53
     */
54
    @Deprecated
55
    static NamingMaintainService createMaintainService(String serverAddr) throws NacosException;
56
    
57
    /**
58
     * Create NamingMaintainService with properties (Deprecated)
59
     * @param properties Configuration properties
60
     * @return NamingMaintainService instance for service maintenance
61
     * @throws NacosException If service creation fails
62
     * @deprecated Use NamingService instead
63
     */
64
    @Deprecated
65
    static NamingMaintainService createMaintainService(Properties properties) throws NacosException;
66
    
67
    /**
68
     * Create LockService with properties configuration
69
     * @param properties Configuration properties containing server address and other settings
70
     * @return LockService instance for distributed locking
71
     * @throws NacosException If service creation fails
72
     */
73
    static LockService createLockService(Properties properties) throws NacosException;
74
}
75
```
76

77
**Usage Examples:**
78

79
```java
80
import com.alibaba.nacos.api.NacosFactory;
81
import com.alibaba.nacos.api.PropertyKeyConst;
82
import java.util.Properties;
83

84
// Create services with simple server address
85
ConfigService configService = NacosFactory.createConfigService("127.0.0.1:8848");
86
NamingService namingService = NacosFactory.createNamingService("127.0.0.1:8848");
87

88
// Create services with detailed properties
89
Properties properties = new Properties();
90
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
91
properties.setProperty(PropertyKeyConst.NAMESPACE, "dev");
92
properties.setProperty(PropertyKeyConst.USERNAME, "nacos");
93
properties.setProperty(PropertyKeyConst.PASSWORD, "nacos");
94

95
ConfigService configServiceWithAuth = NacosFactory.createConfigService(properties);
96
NamingService namingServiceWithAuth = NacosFactory.createNamingService(properties);
97
LockService lockService = NacosFactory.createLockService(properties);
98

99
// Multiple server addresses for high availability
100
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "192.168.1.1:8848,192.168.1.2:8848,192.168.1.3:8848");
101
ConfigService haConfigService = NacosFactory.createConfigService(properties);
102
```
103

104
### PropertyKeyConst
105

106
Constants for property keys used in Nacos configuration. These constants ensure consistent configuration across different Nacos services.
107

108
```java { .api }
109
/**
110
 * Constants for property keys used in Nacos configuration
111
 */
112
class PropertyKeyConst {
113
    /** Nacos server address, supports multiple addresses separated by comma */
114
    static final String SERVER_ADDR = "serverAddr";
115
    
116
    /** Namespace ID for multi-tenancy support */
117
    static final String NAMESPACE = "namespace";
118
    
119
    /** Username for authentication */
120
    static final String USERNAME = "username";
121
    
122
    /** Password for authentication */
123
    static final String PASSWORD = "password";
124
    
125
    /** Access key for cloud authentication */
126
    static final String ACCESS_KEY = "accessKey";
127
    
128
    /** Secret key for cloud authentication */
129
    static final String SECRET_KEY = "secretKey";
130
    
131
    /** Context path for Nacos server */
132
    static final String CONTEXT_PATH = "contextPath";
133
    
134
    /** Cluster name for service registration */
135
    static final String CLUSTER_NAME = "clusterName";
136
    
137
    /** Character encoding for configuration content */
138
    static final String ENCODE = "encode";
139
    
140
    /** Timeout for configuration long polling in milliseconds */
141
    static final String CONFIG_LONG_POLL_TIMEOUT = "configLongPollTimeout";
142
    
143
    /** Retry interval for configuration operations in milliseconds */
144
    static final String CONFIG_RETRY_TIME = "configRetryTime";
145
    
146
    /** Maximum retry attempts */
147
    static final String MAX_RETRY = "maxRetry";
148
    
149
    /** Request timeout for configuration operations in milliseconds */
150
    static final String CONFIG_REQUEST_TIMEOUT = "configRequestTimeout";
151
    
152
    /** RAM role name for cloud authentication */
153
    static final String RAM_ROLE_NAME = "ramRoleName";
154
    
155
    /** Enable remote sync configuration */
156
    static final String ENABLE_REMOTE_SYNC_CONFIG = "enableRemoteSyncConfig";
157
    
158
    /** Endpoint for cloud mode */
159
    static final String ENDPOINT = "endpoint";
160
    
161
    /** Port offset for endpoint */
162
    static final String ENDPOINT_PORT = "endpointPort";
163
    
164
    /** Query parameters for endpoint */
165
    static final String ENDPOINT_QUERY_PARAMS = "endpointQueryParams";
166
    
167
    /** Context path for endpoint */
168
    static final String ENDPOINT_CONTEXT_PATH = "endpointContextPath";
169
    
170
    /** Cluster name for endpoint */
171
    static final String ENDPOINT_CLUSTER_NAME = "endpointClusterName";
172
    
173
    /** Refresh interval for endpoint in seconds */
174
    static final String ENDPOINT_REFRESH_INTERVAL_SECONDS = "endpointRefreshIntervalSeconds";
175
    
176
    /** Is use endpoint parsing rule */
177
    static final String IS_USE_ENDPOINT_PARSING_RULE = "isUseEndpointParsingRule";
178
    
179
    /** Is use cloud namespace parsing */
180
    static final String IS_USE_CLOUD_NAMESPACE_PARSING = "isUseCloudNamespaceParsing";
181
    
182
    /** Naming push empty protection */
183
    static final String NAMING_PUSH_EMPTY_PROTECTION = "namingPushEmptyProtection";
184
    
185
    /** Naming load cache at start */
186
    static final String NAMING_LOAD_CACHE_AT_START = "namingLoadCacheAtStart";
187
    
188
    /** Naming client beat thread count */
189
    static final String NAMING_CLIENT_BEAT_THREAD_COUNT = "namingClientBeatThreadCount";
190
    
191
    /** Naming polling thread count */
192
    static final String NAMING_POLLING_THREAD_COUNT = "namingPollingThreadCount";
193
    
194
    /** Naming polling max thread count */
195
    static final String NAMING_POLLING_MAX_THREAD_COUNT = "namingPollingMaxThreadCount";
196
    
197
    /** Naming cache registry directory */
198
    static final String NAMING_CACHE_REGISTRY_DIR = "namingCacheRegistryDir";
199
    
200
    /** Naming request domain retry count */
201
    static final String NAMING_REQUEST_DOMAIN_RETRY_COUNT = "namingRequestDomainMaxRetryCount";
202
    
203
    /** Naming async query subscribe service */
204
    static final String NAMING_ASYNC_QUERY_SUBSCRIBE_SERVICE = "namingAsyncQuerySubscribeService";
205
    
206
    /** Client worker thread count */
207
    static final String CLIENT_WORKER_THREAD_COUNT = "clientWorkerThreadCount";
208
    
209
    /** Client worker max thread count */
210
    static final String CLIENT_WORKER_MAX_THREAD_COUNT = "clientWorkerMaxThreadCount";
211
    
212
    /** Redo delay time */
213
    static final String REDO_DELAY_TIME = "redoDelayTime";
214
    
215
    /** Redo delay thread count */
216
    static final String REDO_DELAY_THREAD_COUNT = "redoDelayThreadCount";
217
    
218
    /** Signature region ID */
219
    static final String SIGNATURE_REGION_ID = "signatureRegionId";
220
    
221
    /** Log all properties */
222
    static final String LOG_ALL_PROPERTIES = "logAllProperties";
223
    
224
    /** Is use RAM info parsing */
225
    static final String IS_USE_RAM_INFO_PARSING = "isUseRamInfoParsing";
226
    
227
    /** Enable client metrics */
228
    static final String ENABLE_CLIENT_METRICS = "enableClientMetrics";
229
    
230
    /** Server name (deprecated) */
231
    @Deprecated
232
    static final String SERVER_NAME = "serverName";
233
    
234
    /** Is adapt cluster name usage (deprecated) */
235
    @Deprecated
236
    static final String IS_ADAPT_CLUSTER_NAME_USAGE = "isAdaptClusterNameUsage";
237
    
238
    /** System environment constants */
239
    static class SystemEnv {
240
        static final String ALIBABA_ALIWARE_ENDPOINT_PORT = "ALIBABA_ALIWARE_ENDPOINT_PORT";
241
        static final String ALIBABA_ALIWARE_ENDPOINT_CONTEXT_PATH = "ALIBABA_ALIWARE_ENDPOINT_CONTEXT_PATH";
242
        static final String ALIBABA_ALIWARE_NAMESPACE = "ALIBABA_ALIWARE_NAMESPACE";
243
        static final String ALIBABA_ALIWARE_ENDPOINT_URL = "ALIBABA_ALIWARE_ENDPOINT_URL";
244
    }
245
}
246
```
247

248
**Usage Examples:**
249

250
```java
251
import com.alibaba.nacos.api.PropertyKeyConst;
252
import java.util.Properties;
253

254
// Basic configuration
255
Properties props = new Properties();
256
props.setProperty(PropertyKeyConst.SERVER_ADDR, "localhost:8848");
257
props.setProperty(PropertyKeyConst.NAMESPACE, "production");
258

259
// Authentication configuration
260
props.setProperty(PropertyKeyConst.USERNAME, "admin");
261
props.setProperty(PropertyKeyConst.PASSWORD, "secret");
262

263
// Cloud configuration with access keys
264
props.setProperty(PropertyKeyConst.ACCESS_KEY, "your-access-key");
265
props.setProperty(PropertyKeyConst.SECRET_KEY, "your-secret-key");
266
props.setProperty(PropertyKeyConst.ENDPOINT, "nacos.cloud.example.com");
267

268
// Performance tuning
269
props.setProperty(PropertyKeyConst.CONFIG_LONG_POLL_TIMEOUT, "60000"); // 60 seconds
270
props.setProperty(PropertyKeyConst.CONFIG_RETRY_TIME, "3000"); // 3 seconds
271
props.setProperty(PropertyKeyConst.MAX_RETRY, "5");
272

273
// Naming service configuration
274
props.setProperty(PropertyKeyConst.CLUSTER_NAME, "default");
275
props.setProperty(PropertyKeyConst.NAMING_LOAD_CACHE_AT_START, "true");
276
props.setProperty(PropertyKeyConst.NAMING_CLIENT_BEAT_THREAD_COUNT, "2");
277

278
// Additional configuration options
279
props.setProperty(PropertyKeyConst.ENABLE_REMOTE_SYNC_CONFIG, "true");
280
props.setProperty(PropertyKeyConst.CONFIG_REQUEST_TIMEOUT, "10000"); // 10 seconds
281
```
282

283
### SystemPropertyKeyConst
284

285
System property keys for JVM parameters that control Nacos behavior at the system level.
286

287
```java { .api }
288
/**
289
 * System property keys for JVM parameters
290
 */
291
interface SystemPropertyKeyConst {
292
    /** Naming server port for service exposure */
293
    String NAMING_SERVER_PORT = "nacos.naming.exposed.port";
294
    
295
    /** Enable cloud namespace parsing */
296
    String IS_USE_CLOUD_NAMESPACE_PARSING = "nacos.use.cloud.namespace.parsing";
297
    
298
    /** ANS (Application Naming Service) namespace */
299
    String ANS_NAMESPACE = "ans.namespace";
300
    
301
    /** Enable endpoint parsing rule */
302
    String IS_USE_ENDPOINT_PARSING_RULE = "nacos.use.endpoint.parsing.rule";
303
    
304
    /** Enable RAM (Resource Access Management) info parsing */
305
    String IS_USE_RAM_INFO_PARSING = "nacos.use.ram.info.parsing";
306
}
307
```
308

309
**Usage Examples:**
310

311
```java
312
// Set system properties before creating Nacos services
313
System.setProperty(SystemPropertyKeyConst.NAMING_SERVER_PORT, "8080");
314
System.setProperty(SystemPropertyKeyConst.IS_USE_CLOUD_NAMESPACE_PARSING, "true");
315
System.setProperty(SystemPropertyKeyConst.IS_USE_ENDPOINT_PARSING_RULE, "true");
316

317
// Or set via JVM arguments:
318
// -Dnacos.naming.exposed.port=8080
319
// -Dnacos.use.cloud.namespace.parsing=true
320
// -Dnacos.use.endpoint.parsing.rule=true
321
```
322

323
### Configuration Validation
324

325
Common patterns for validating and setting up Nacos properties:
326

327
```java
328
import com.alibaba.nacos.api.PropertyKeyConst;
329
import com.alibaba.nacos.api.utils.StringUtils;
330

331
public class NacosConfigValidator {
332
    
333
    public static Properties validateAndSetup(Properties properties) {
334
        Properties validatedProps = new Properties(properties);
335
        
336
        // Ensure server address is provided
337
        String serverAddr = validatedProps.getProperty(PropertyKeyConst.SERVER_ADDR);
338
        if (StringUtils.isBlank(serverAddr)) {
339
            throw new IllegalArgumentException("serverAddr must be provided");
340
        }
341
        
342
        // Set default namespace if not provided
343
        if (StringUtils.isBlank(validatedProps.getProperty(PropertyKeyConst.NAMESPACE))) {
344
            validatedProps.setProperty(PropertyKeyConst.NAMESPACE, "public");
345
        }
346
        
347
        // Set default encoding if not provided
348
        if (StringUtils.isBlank(validatedProps.getProperty(PropertyKeyConst.ENCODE))) {
349
            validatedProps.setProperty(PropertyKeyConst.ENCODE, "UTF-8");
350
        }
351
        
352
        // Set default timeouts if not provided
353
        if (StringUtils.isBlank(validatedProps.getProperty(PropertyKeyConst.CONFIG_LONG_POLL_TIMEOUT))) {
354
            validatedProps.setProperty(PropertyKeyConst.CONFIG_LONG_POLL_TIMEOUT, "30000");
355
        }
356
        
357
        if (StringUtils.isBlank(validatedProps.getProperty(PropertyKeyConst.MAX_RETRY))) {
358
            validatedProps.setProperty(PropertyKeyConst.MAX_RETRY, "3");
359
        }
360
        
361
        return validatedProps;
362
    }
363
}
364

365
// Usage
366
Properties props = new Properties();
367
props.setProperty(PropertyKeyConst.SERVER_ADDR, "localhost:8848");
368
Properties validatedProps = NacosConfigValidator.validateAndSetup(props);
369
ConfigService configService = NacosFactory.createConfigService(validatedProps);
370
```
371

372
### Error Handling
373

374
Common error scenarios and handling patterns when using factory methods:
375

376
```java
377
import com.alibaba.nacos.api.exception.NacosException;
378

379
try {
380
    Properties properties = new Properties();
381
    properties.setProperty(PropertyKeyConst.SERVER_ADDR, "localhost:8848");
382
    
383
    ConfigService configService = NacosFactory.createConfigService(properties);
384
    NamingService namingService = NacosFactory.createNamingService(properties);
385
    
386
} catch (NacosException e) {
387
    switch (e.getErrCode()) {
388
        case NacosException.CLIENT_INVALID_PARAM:
389
            // Handle invalid parameters (e.g., missing server address)
390
            logger.error("Invalid configuration parameters", e);
391
            break;
392
        case NacosException.CLIENT_DISCONNECT:
393
            // Handle connection issues
394
            logger.error("Failed to connect to Nacos server", e);
395
            break;
396
        case NacosException.SERVER_ERROR:
397
            // Handle server-side errors
398
            logger.error("Nacos server error", e);
399
            break;
400
        default:
401
            // Handle other errors
402
            logger.error("Unexpected error creating Nacos service", e);
403
            break;
404
    }
405
}
406
```