0
# Metadata Management
1

2
Apache Dubbo's metadata management system provides comprehensive service metadata collection, storage, and retrieval capabilities. It supports service discovery optimization, contract management, and runtime service introspection through configurable metadata backends.
3

4
## Capabilities
5

6
### Metadata Report
7

8
Central metadata storage and management for service definitions and configurations.
9

10
```java { .api }
11
/**
12
 * Metadata report interface for storing and retrieving service metadata
13
 */
14
@SPI("zookeeper")
15
public interface MetadataReport {
16
    /**
17
     * Store provider metadata
18
     * @param providerMetaDataIdentifier Provider metadata identifier
19
     * @param serviceDefinition Service definition
20
     */
21
    void storeProviderMetadata(MetadataIdentifier providerMetaDataIdentifier, 
22
                              String serviceDefinition);
23
    
24
    /**
25
     * Store consumer metadata
26
     * @param consumerMetadataIdentifier Consumer metadata identifier
27
     * @param serviceParameterString Service parameters
28
     */
29
    void storeConsumerMetadata(MetadataIdentifier consumerMetadataIdentifier, 
30
                              String serviceParameterString);
31
    
32
    /**
33
     * Save service metadata
34
     * @param serviceMetadataIdentifier Service metadata identifier
35
     * @param url Service URL
36
     */
37
    void saveServiceMetadata(ServiceMetadataIdentifier serviceMetadataIdentifier, URL url);
38
    
39
    /**
40
     * Remove service metadata
41
     * @param serviceMetadataIdentifier Service metadata identifier
42
     */
43
    void removeServiceMetadata(ServiceMetadataIdentifier serviceMetadataIdentifier);
44
    
45
    /**
46
     * Get exported URLs
47
     * @param serviceMetadataIdentifier Service metadata identifier
48
     * @return List of exported URLs
49
     */
50
    List<String> getExportedURLs(ServiceMetadataIdentifier serviceMetadataIdentifier);
51
    
52
    /**
53
     * Save subscribed data
54
     * @param subscriberMetadataIdentifier Subscriber metadata identifier
55
     * @param urls Subscribed URLs
56
     */
57
    void saveSubscribedData(SubscriberMetadataIdentifier subscriberMetadataIdentifier, 
58
                           Set<String> urls);
59
    
60
    /**
61
     * Get subscribed URLs  
62
     * @param subscriberMetadataIdentifier Subscriber metadata identifier
63
     * @return Subscribed URLs
64
     */
65
    List<String> getSubscribedURLs(SubscriberMetadataIdentifier subscriberMetadataIdentifier);
66
    
67
    /**
68
     * Get service definition
69
     * @param metadataIdentifier Metadata identifier
70
     * @return Service definition
71
     */
72
    String getServiceDefinition(MetadataIdentifier metadataIdentifier);
73
}
74

75
/**
76
 * Metadata report factory
77
 */
78
@SPI("zookeeper")
79
public interface MetadataReportFactory {
80
    /**
81
     * Create metadata report instance
82
     * @param url Configuration URL
83
     * @return Metadata report instance
84
     */
85
    MetadataReport getMetadataReport(URL url);
86
}
87
```
88

89
### Metadata Configuration
90

91
Configuration for metadata reporting and management.
92

93
```java { .api }
94
/**
95
 * Metadata report configuration
96
 */
97
public class MetadataReportConfig extends AbstractConfig {
98
    public MetadataReportConfig();
99
    
100
    /** Set metadata center address */
101
    public void setAddress(String address);
102
    public String getAddress();
103
    
104
    /** Set metadata center username */
105
    public void setUsername(String username);
106
    public String getUsername();
107
    
108
    /** Set metadata center password */
109
    public void setPassword(String password);
110
    public String getPassword();
111
    
112
    /** Set connection timeout */
113
    public void setTimeout(Integer timeout);
114
    public Integer getTimeout();
115
    
116
    /** Set retry times */
117
    public void setRetryTimes(Integer retryTimes);
118
    public Integer getRetryTimes();
119
    
120
    /** Set retry period */
121
    public void setRetryPeriod(Integer retryPeriod);
122
    public Integer getRetryPeriod();
123
    
124
    /** Set cycle report */
125
    public void setCycleReport(Boolean cycleReport);
126
    public Boolean getCycleReport();
127
    
128
    /** Set sync report */
129
    public void setSyncReport(Boolean syncReport);
130
    public Boolean getSyncReport();
131
    
132
    /** Set group */
133
    public void setGroup(String group);
134
    public String getGroup();
135
    
136
    /** Set cluster */
137
    public void setCluster(String cluster);
138
    public String getCluster();
139
    
140
    /** Set registry */
141
    public void setRegistry(String registry);
142
    public String getRegistry();
143
    
144
    /** Set file */
145
    public void setFile(String file);
146
    public String getFile();
147
    
148
    /** Set parameters */
149
    public void setParameters(Map<String, String> parameters);
150
    public Map<String, String> getParameters();
151
}
152
```
153

154
**Usage Examples:**
155

156
```java
157
import org.apache.dubbo.config.MetadataReportConfig;
158

159
// Configure metadata report
160
MetadataReportConfig metadataReport = new MetadataReportConfig();
161
metadataReport.setAddress("zookeeper://127.0.0.1:2181");
162
metadataReport.setGroup("dubbo");
163
metadataReport.setTimeout(5000);
164
metadataReport.setRetryTimes(3);
165

166
// Add to bootstrap
167
DubboBootstrap.getInstance()
168
    .metadataReport(metadataReport)
169
    .start();
170
```
171

172
### Service Metadata
173

174
Service metadata representation and management.
175

176
```java { .api }
177
/**
178
 * Service metadata containing service definition and configuration
179
 */
180
public class ServiceMetadata {
181
    public ServiceMetadata();
182
    public ServiceMetadata(String serviceName);
183
    
184
    /** Get service name */
185
    public String getServiceName();
186
    public void setServiceName(String serviceName);
187
    
188
    /** Get service version */
189
    public String getVersion();
190
    public void setVersion(String version);
191
    
192
    /** Get service group */
193
    public String getGroup();
194
    public void setGroup(String group);
195
    
196
    /** Get service type */
197
    public String getServiceType();
198
    public void setServiceType(String serviceType);
199
    
200
    /** Get target service */
201
    public Object getTarget();
202
    public void setTarget(Object target);
203
    
204
    /** Get service interface */
205
    public Class<?> getServiceInterfaceClass();
206
    public void setServiceInterfaceClass(Class<?> serviceInterfaceClass);
207
    
208
    /** Generate service key */
209
    public String generateServiceKey();
210
    
211
    /** Get method metadata */
212
    public List<MethodMetadata> getMethods();
213
    public void setMethods(List<MethodMetadata> methods);
214
    
215
    /** Add method metadata */
216
    public void addMethod(MethodMetadata methodMetadata);
217
}
218

219
/**
220
 * Method metadata for service methods
221
 */
222
public class MethodMetadata {
223
    public MethodMetadata();
224
    
225
    /** Get method name */
226
    public String getMethodName();
227
    public void setMethodName(String methodName);
228
    
229
    /** Get parameter types */
230
    public String[] getParameterTypes();
231
    public void setParameterTypes(String[] parameterTypes);
232
    
233
    /** Get return type */
234
    public String getReturnType();
235
    public void setReturnType(String returnType);
236
    
237
    /** Get method signature */
238
    public String getMethodSignature();
239
    
240
    /** Get annotations */
241
    public Map<String, Object> getAnnotations();
242
    public void setAnnotations(Map<String, Object> annotations);
243
}
244
```
245

246
### Metadata Identifiers
247

248
Unique identifiers for different types of metadata.
249

250
```java { .api }
251
/**
252
 * Base metadata identifier
253
 */
254
public class MetadataIdentifier {
255
    public MetadataIdentifier(String serviceInterface, String version, String group, 
256
                             String side, String application);
257
    
258
    /** Get service interface */
259
    public String getServiceInterface();
260
    
261
    /** Get version */
262
    public String getVersion();
263
    
264
    /** Get group */
265
    public String getGroup();
266
    
267
    /** Get side (provider/consumer) */
268
    public String getSide();
269
    
270
    /** Get application */
271
    public String getApplication();
272
    
273
    /** Get unique key */
274
    public String getUniqueKey(KeyTypeEnum keyType);
275
    
276
    /** Get identifier key */
277
    public String getIdentifierKey();
278
}
279

280
/**
281
 * Service metadata identifier
282
 */
283
public class ServiceMetadataIdentifier extends MetadataIdentifier {
284
    public ServiceMetadataIdentifier(String serviceInterface, String version, String group, 
285
                                   String side, String revision, String protocol);
286
    
287
    /** Get revision */
288
    public String getRevision();
289
    
290
    /** Get protocol */
291
    public String getProtocol();
292
}
293

294
/**
295
 * Subscriber metadata identifier  
296
 */
297
public class SubscriberMetadataIdentifier extends MetadataIdentifier {
298
    public SubscriberMetadataIdentifier(String application, String revision);
299
    
300
    /** Get revision */
301
    public String getRevision();
302
}
303
```
304

305
### Service Definition
306

307
Structured service definition for metadata storage.
308

309
```java { .api }
310
/**
311
 * Full service definition including all metadata
312
 */
313
public class FullServiceDefinition {
314
    public FullServiceDefinition();
315
    
316
    /** Get canonical name */
317
    public String getCanonicalName();
318
    public void setCanonicalName(String canonicalName);
319
    
320
    /** Get code source */
321
    public String getCodeSource();
322
    public void setCodeSource(String codeSource);
323
    
324
    /** Get methods */
325
    public List<MethodDefinition> getMethods();
326
    public void setMethods(List<MethodDefinition> methods);
327
    
328
    /** Get types */
329
    public List<TypeDefinition> getTypes();
330
    public void setTypes(List<TypeDefinition> types);
331
    
332
    /** Get annotations */
333
    public Map<String, Object> getAnnotations();
334
    public void setAnnotations(Map<String, Object> annotations);
335
    
336
    /** Get parameters */
337
    public Map<String, String> getParameters();
338
    public void setParameters(Map<String, String> parameters);
339
}
340

341
/**
342
 * Method definition within service
343
 */
344
public class MethodDefinition {
345
    public MethodDefinition();
346
    
347
    /** Get method name */
348
    public String getName();
349
    public void setName(String name);
350
    
351
    /** Get parameter types */
352
    public String[] getParameterTypes();
353
    public void setParameterTypes(String[] parameterTypes);
354
    
355
    /** Get return type */
356
    public String getReturnType();
357
    public void setReturnType(String returnType);
358
    
359
    /** Get annotations */
360
    public Map<String, Object> getAnnotations();
361
    public void setAnnotations(Map<String, Object> annotations);
362
}
363

364
/**
365
 * Type definition for complex types
366
 */
367
public class TypeDefinition {
368
    public TypeDefinition();
369
    public TypeDefinition(String type);
370
    
371
    /** Get type identifier */
372
    public String getId();
373
    public void setId(String id);
374
    
375
    /** Get type name */
376
    public String getType();
377
    public void setType(String type);
378
    
379
    /** Get type properties */
380
    public List<String> getProperties();
381
    public void setProperties(List<String> properties);
382
    
383
    /** Get items (for collections) */
384
    public String getItems();
385
    public void setItems(String items);
386
}
387
```
388

389
### Metadata Service
390

391
Service for metadata operations and queries.
392

393
```java { .api }
394
/**
395
 * Metadata service for runtime metadata operations
396
 */
397
public interface MetadataService {
398
    /** Service name for metadata service */
399
    String SERVICE_NAME = "org.apache.dubbo.metadata.MetadataService";
400
    
401
    /**
402
     * Get service definition
403
     * @param interfaceName Service interface name
404
     * @param version Service version
405
     * @param group Service group
406
     * @return Service definition
407
     */
408
    String getServiceDefinition(String interfaceName, String version, String group);
409
    
410
    /**
411
     * Get service definition by key
412
     * @param serviceKey Service key
413
     * @return Service definition
414
     */
415
    String getServiceDefinition(String serviceKey);
416
    
417
    /**
418
     * Get exported URLs
419
     * @param serviceInterface Service interface
420
     * @param group Service group
421
     * @param version Service version
422
     * @param protocol Protocol filter
423
     * @return Exported URLs
424
     */
425
    SortedSet<String> getExportedURLs(String serviceInterface, String group, 
426
                                     String version, String protocol);
427
    
428
    /**
429
     * Get exported URLs
430
     * @return All exported URLs
431
     */
432
    SortedSet<String> getExportedURLs();
433
    
434
    /**
435
     * Get subscribed URLs
436
     * @return Subscribed URLs
437
     */
438
    SortedSet<String> getSubscribedURLs();
439
    
440
    /**
441
     * Get metadata version
442
     * @return Metadata version
443
     */
444
    String getMetadataVersion();
445
    
446
    /**
447
     * Get metadata info
448
     * @param revision Metadata revision
449
     * @return Metadata info
450
     */
451
    MetadataInfo getMetadataInfo(String revision);
452
}
453

454
/**
455
 * Metadata info containing service metadata
456
 */
457
public class MetadataInfo {
458
    public MetadataInfo();
459
    public MetadataInfo(String app);
460
    
461
    /** Get application name */
462
    public String getApp();
463
    public void setApp(String app);
464
    
465
    /** Get revision */
466
    public String getRevision();
467
    public void setRevision(String revision);
468
    
469
    /** Get services */
470
    public Map<String, ServiceInfo> getServices();
471
    public void setServices(Map<String, ServiceInfo> services);
472
    
473
    /** Add service */
474
    public void addService(ServiceInfo serviceInfo);
475
    
476
    /** Get service */
477
    public ServiceInfo getService(String serviceKey);
478
}
479
```
480

481
**Usage Examples:**
482

483
```java
484
import org.apache.dubbo.metadata.MetadataService;
485

486
// Get metadata service reference
487
ReferenceConfig<MetadataService> metadataReference = new ReferenceConfig<>();
488
metadataReference.setInterface(MetadataService.class);
489
metadataReference.setGroup("dubbo");
490
metadataReference.setVersion("1.0.0");
491

492
MetadataService metadataService = metadataReference.get();
493

494
// Query service definition
495
String definition = metadataService.getServiceDefinition(
496
    "com.example.GreeterService", "1.0.0", "default");
497

498
// Get exported URLs
499
SortedSet<String> exportedUrls = metadataService.getExportedURLs();
500

501
// Get specific service URLs
502
SortedSet<String> serviceUrls = metadataService.getExportedURLs(
503
    "com.example.GreeterService", "default", "1.0.0", "dubbo");
504
```
505

506
### Metadata Storage Backends
507

508
Different storage backends for metadata persistence.
509

510
**ZooKeeper Metadata Report:**
511
```java
512
// ZooKeeper-based metadata storage
513
MetadataReportConfig metadataReport = new MetadataReportConfig();
514
metadataReport.setAddress("zookeeper://127.0.0.1:2181");
515
metadataReport.setGroup("dubbo");
516
```
517

518
**Nacos Metadata Report:**
519
```java
520
// Nacos-based metadata storage
521
MetadataReportConfig metadataReport = new MetadataReportConfig();
522
metadataReport.setAddress("nacos://127.0.0.1:8848");
523
metadataReport.setGroup("DEFAULT_GROUP");
524
metadataReport.setUsername("nacos");
525
metadataReport.setPassword("nacos");
526
```
527

528
**Redis Metadata Report:**
529
```java
530
// Redis-based metadata storage
531
MetadataReportConfig metadataReport = new MetadataReportConfig();
532
metadataReport.setAddress("redis://127.0.0.1:6379");
533
metadataReport.setGroup("dubbo");
534
```
535

536
### Metadata Synchronization
537

538
Configuration for metadata synchronization behavior.
539

540
```java { .api }
541
/**
542
 * Metadata synchronization configuration
543
 */
544
public class MetadataSyncConfig {
545
    /** Enable sync report */
546
    private Boolean syncReport = false;
547
    
548
    /** Enable cycle report */
549
    private Boolean cycleReport = true;
550
    
551
    /** Cycle report period */
552
    private Integer cycleReportPeriod = 5000;
553
    
554
    // Getters and setters
555
    public Boolean getSyncReport() { return syncReport; }
556
    public void setSyncReport(Boolean syncReport) { this.syncReport = syncReport; }
557
    
558
    public Boolean getCycleReport() { return cycleReport; }
559
    public void setCycleReport(Boolean cycleReport) { this.cycleReport = cycleReport; }
560
    
561
    public Integer getCycleReportPeriod() { return cycleReportPeriod; }
562
    public void setCycleReportPeriod(Integer cycleReportPeriod) { 
563
        this.cycleReportPeriod = cycleReportPeriod; 
564
    }
565
}
566
```
567

568
**Configuration Examples:**
569

570
```properties
571
# Enable metadata report
572
dubbo.metadata-report.address=zookeeper://127.0.0.1:2181
573
dubbo.metadata-report.username=admin
574
dubbo.metadata-report.password=admin
575
dubbo.metadata-report.timeout=5000
576
dubbo.metadata-report.retry-times=3
577
dubbo.metadata-report.retry-period=3000
578
dubbo.metadata-report.cycle-report=true
579
dubbo.metadata-report.sync-report=false
580

581
# Metadata service configuration
582
dubbo.metadata-report.group=dubbo
583
dubbo.metadata-report.cluster=default
584
```
585

586
YAML configuration:
587
```yaml
588
dubbo:
589
  metadata-report:
590
    address: zookeeper://127.0.0.1:2181
591
    username: admin
592
    password: admin
593
    timeout: 5000
594
    retry-times: 3
595
    retry-period: 3000
596
    cycle-report: true
597
    sync-report: false
598
    group: dubbo
599
```
600

601
**Complete Metadata Setup Example:**
602

603
```java
604
import org.apache.dubbo.config.bootstrap.DubboBootstrap;
605
import org.apache.dubbo.config.MetadataReportConfig;
606

607
// Configure metadata reporting
608
MetadataReportConfig metadataReport = new MetadataReportConfig();
609
metadataReport.setAddress("zookeeper://127.0.0.1:2181");
610
metadataReport.setGroup("dubbo");
611
metadataReport.setTimeout(5000);
612
metadataReport.setRetryTimes(3);
613
metadataReport.setCycleReport(true);
614

615
// Bootstrap with metadata configuration
616
DubboBootstrap bootstrap = DubboBootstrap.getInstance();
617
bootstrap.metadataReport(metadataReport);
618

619
// Configure service with metadata
620
ServiceConfig<GreeterService> service = new ServiceConfig<>();
621
service.setInterface(GreeterService.class);
622
service.setRef(new GreeterServiceImpl());
623
service.setGroup("production");
624
service.setVersion("1.0.0");
625

626
bootstrap.service(service).start();
627

628
// Query metadata
629
MetadataService metadataService = bootstrap.getCache().get(MetadataService.class);
630
String serviceDefinition = metadataService.getServiceDefinition(
631
    "com.example.GreeterService", "1.0.0", "production");
632
```