0
# Client Builder Traits
1

2
Trait interfaces providing consistent configuration patterns across Azure SDK client builders. These traits ensure uniform API design and enable composable builder functionality.
3

4
## Capabilities
5

6
### EndpointTrait
7

8
Trait for configuring service endpoints in client builders.
9

10
```java { .api }
11
/**
12
 * Trait for Azure SDK client builders that support setting service endpoints.
13
 */
14
interface EndpointTrait<T> {
15
    /**
16
     * Sets the service endpoint URL.
17
     * @param endpoint The service endpoint URL
18
     * @return The updated builder object
19
     */
20
    T endpoint(String endpoint);
21
}
22
```
23

24
### HttpTrait
25

26
Trait for HTTP-specific configuration including client, pipeline, and policies.
27

28
```java { .api }
29
/**
30
 * Trait for Azure SDK client builders that support HTTP-specific configuration settings.
31
 */
32
interface HttpTrait<T> {
33
    /**
34
     * Sets the HTTP client to use for sending requests.
35
     * @param httpClient The HTTP client implementation
36
     * @return The updated builder object
37
     */
38
    T httpClient(HttpClient httpClient);
39
    
40
    /**
41
     * Sets the HTTP pipeline to use for sending requests.
42
     * @param pipeline The HTTP pipeline
43
     * @return The updated builder object
44
     */
45
    T pipeline(HttpPipeline pipeline);
46
    
47
    /**
48
     * Adds a pipeline policy to the client's pipeline.
49
     * @param pipelinePolicy The pipeline policy to add
50
     * @return The updated builder object
51
     */
52
    T addPolicy(HttpPipelinePolicy pipelinePolicy);
53
    
54
    /**
55
     * Sets the retry options for the client.
56
     * @param retryOptions The retry configuration
57
     * @return The updated builder object
58
     */
59
    T retryOptions(RetryOptions retryOptions);
60
    
61
    /**
62
     * Sets the HTTP logging options.
63
     * @param logOptions The HTTP logging configuration
64
     * @return The updated builder object
65
     */
66
    T httpLogOptions(HttpLogOptions logOptions);
67
    
68
    /**
69
     * Sets common client options.
70
     * @param clientOptions The client options
71
     * @return The updated builder object
72
     */
73
    T clientOptions(ClientOptions clientOptions);
74
}
75
```
76

77
### TokenCredentialTrait
78

79
Trait for configuring Azure Active Directory token-based authentication.
80

81
```java { .api }
82
/**
83
 * Trait for Azure SDK client builders that support TokenCredential authentication.
84
 */
85
interface TokenCredentialTrait<T> {
86
    /**
87
     * Sets the TokenCredential used to authorize requests sent by the service client.
88
     * @param credential TokenCredential used to authorize requests
89
     * @return The updated builder object
90
     */
91
    T credential(TokenCredential credential);
92
}
93
```
94

95
### AzureKeyCredentialTrait
96

97
Trait for configuring Azure key-based authentication.
98

99
```java { .api }
100
/**
101
 * Trait for Azure SDK client builders that support AzureKeyCredential authentication.
102
 */
103
interface AzureKeyCredentialTrait<T> {
104
    /**
105
     * Sets the AzureKeyCredential used to authorize requests sent by the service client.
106
     * @param credential AzureKeyCredential used to authorize requests
107
     * @return The updated builder object
108
     */
109
    T credential(AzureKeyCredential credential);
110
}
111
```
112

113
### AzureNamedKeyCredentialTrait
114

115
Trait for configuring named key authentication where both key name and value are required.
116

117
```java { .api }
118
/**
119
 * Trait for Azure SDK client builders that support AzureNamedKeyCredential authentication.
120
 */
121
interface AzureNamedKeyCredentialTrait<T> {
122
    /**
123
     * Sets the AzureNamedKeyCredential used to authorize requests sent by the service client.
124
     * @param credential AzureNamedKeyCredential used to authorize requests
125
     * @return The updated builder object
126
     */
127
    T credential(AzureNamedKeyCredential credential);
128
}
129
```
130

131
### AzureSasCredentialTrait
132

133
Trait for configuring Shared Access Signature authentication.
134

135
```java { .api }
136
/**
137
 * Trait for Azure SDK client builders that support AzureSasCredential authentication.
138
 */
139
interface AzureSasCredentialTrait<T> {
140
    /**
141
     * Sets the AzureSasCredential used to authorize requests sent by the service client.
142
     * @param credential AzureSasCredential used to authorize requests
143
     * @return The updated builder object
144
     */
145
    T credential(AzureSasCredential credential);
146
}
147
```
148

149
### KeyCredentialTrait
150

151
Trait for configuring generic key-based authentication.
152

153
```java { .api }
154
/**
155
 * Trait for Azure SDK client builders that support KeyCredential authentication.
156
 */
157
interface KeyCredentialTrait<T> {
158
    /**
159
     * Sets the KeyCredential used to authorize requests sent by the service client.
160
     * @param credential KeyCredential used to authorize requests
161
     * @return The updated builder object
162
     */
163
    T credential(KeyCredential credential);
164
}
165
```
166

167
### ConnectionStringTrait
168

169
Trait for configuring connection string-based authentication and configuration.
170

171
```java { .api }
172
/**
173
 * Trait for Azure SDK client builders that support connection string configuration.
174
 */
175
interface ConnectionStringTrait<T> {
176
    /**
177
     * Sets the connection string for the service.
178
     * @param connectionString Connection string containing service configuration
179
     * @return The updated builder object
180
     */
181
    T connectionString(String connectionString);
182
}
183
```
184

185
### ConfigurationTrait
186

187
Trait for configuring application configuration settings.
188

189
```java { .api }
190
/**
191
 * Trait for Azure SDK client builders that support configuration settings.
192
 */
193
interface ConfigurationTrait<T> {
194
    /**
195
     * Sets the configuration instance to use for the client.
196
     * @param configuration Configuration instance containing settings
197
     * @return The updated builder object
198
     */
199
    T configuration(Configuration configuration);
200
}
201
```
202

203
## Usage Examples
204

205
### Implementing Multiple Traits
206

207
```java
208
import com.azure.core.client.traits.*;
209
import com.azure.core.http.HttpClient;
210
import com.azure.core.credential.TokenCredential;
211

212
@ServiceClientBuilder(serviceClients = {MyServiceClient.class})
213
@Fluent
214
class MyServiceClientBuilder implements 
215
    HttpTrait<MyServiceClientBuilder>,
216
    TokenCredentialTrait<MyServiceClientBuilder>,
217
    EndpointTrait<MyServiceClientBuilder>,
218
    ConfigurationTrait<MyServiceClientBuilder> {
219
    
220
    private HttpClient httpClient;
221
    private HttpPipeline pipeline;
222
    private TokenCredential credential;
223
    private String endpoint;
224
    private Configuration configuration;
225
    private List<HttpPipelinePolicy> policies = new ArrayList<>();
226
    private RetryOptions retryOptions;
227
    private HttpLogOptions httpLogOptions;
228
    private ClientOptions clientOptions;
229
    
230
    @Override
231
    public MyServiceClientBuilder httpClient(HttpClient httpClient) {
232
        this.httpClient = httpClient;
233
        return this;
234
    }
235
    
236
    @Override
237
    public MyServiceClientBuilder pipeline(HttpPipeline pipeline) {
238
        this.pipeline = pipeline;
239
        return this;
240
    }
241
    
242
    @Override
243
    public MyServiceClientBuilder addPolicy(HttpPipelinePolicy pipelinePolicy) {
244
        this.policies.add(pipelinePolicy);
245
        return this;
246
    }
247
    
248
    @Override
249
    public MyServiceClientBuilder retryOptions(RetryOptions retryOptions) {
250
        this.retryOptions = retryOptions;
251
        return this;
252
    }
253
    
254
    @Override
255
    public MyServiceClientBuilder httpLogOptions(HttpLogOptions logOptions) {
256
        this.httpLogOptions = logOptions;
257
        return this;
258
    }
259
    
260
    @Override
261
    public MyServiceClientBuilder clientOptions(ClientOptions clientOptions) {
262
        this.clientOptions = clientOptions;
263
        return this;
264
    }
265
    
266
    @Override
267
    public MyServiceClientBuilder credential(TokenCredential credential) {
268
        this.credential = credential;
269
        return this;
270
    }
271
    
272
    @Override
273
    public MyServiceClientBuilder endpoint(String endpoint) {
274
        this.endpoint = endpoint;
275
        return this;
276
    }
277
    
278
    @Override
279
    public MyServiceClientBuilder configuration(Configuration configuration) {
280
        this.configuration = configuration;
281
        return this;
282
    }
283
    
284
    public MyServiceClient buildClient() {
285
        HttpPipeline pipeline = buildPipeline();
286
        return new MyServiceClient(pipeline, endpoint);
287
    }
288
    
289
    private HttpPipeline buildPipeline() {
290
        if (pipeline != null) {
291
            return pipeline;
292
        }
293
        
294
        List<HttpPipelinePolicy> allPolicies = new ArrayList<>();
295
        
296
        // Add user agent policy
297
        allPolicies.add(new UserAgentPolicy("MyService/1.0"));
298
        
299
        // Add authentication policy
300
        if (credential != null) {
301
            allPolicies.add(new BearerTokenAuthenticationPolicy(
302
                credential, "https://myservice.azure.com/.default"));
303
        }
304
        
305
        // Add user-defined policies
306
        allPolicies.addAll(policies);
307
        
308
        // Add retry policy
309
        if (retryOptions != null) {
310
            allPolicies.add(new RetryPolicy(retryOptions));
311
        } else {
312
            allPolicies.add(new RetryPolicy());
313
        }
314
        
315
        // Add logging policy
316
        if (httpLogOptions != null) {
317
            allPolicies.add(new HttpLoggingPolicy(httpLogOptions));
318
        }
319
        
320
        return new HttpPipelineBuilder()
321
            .httpClient(httpClient != null ? httpClient : HttpClient.createDefault())
322
            .policies(allPolicies.toArray(new HttpPipelinePolicy[0]))
323
            .build();
324
    }
325
}
326
```
327

328
### Using Different Credential Traits
329

330
```java
331
// Builder supporting multiple credential types
332
@ServiceClientBuilder(serviceClients = {StorageClient.class})
333
class StorageClientBuilder implements 
334
    AzureKeyCredentialTrait<StorageClientBuilder>,
335
    AzureSasCredentialTrait<StorageClientBuilder>,
336
    TokenCredentialTrait<StorageClientBuilder>,
337
    ConnectionStringTrait<StorageClientBuilder> {
338
    
339
    private Object credential;
340
    private String connectionString;
341
    
342
    @Override
343
    public StorageClientBuilder credential(AzureKeyCredential credential) {
344
        this.credential = credential;
345
        return this;
346
    }
347
    
348
    @Override
349
    public StorageClientBuilder credential(AzureSasCredential credential) {
350
        this.credential = credential;
351
        return this;
352
    }
353
    
354
    @Override
355
    public StorageClientBuilder credential(TokenCredential credential) {
356
        this.credential = credential;
357
        return this;
358
    }
359
    
360
    @Override
361
    public StorageClientBuilder connectionString(String connectionString) {
362
        this.connectionString = connectionString;
363
        return this;
364
    }
365
    
366
    public StorageClient buildClient() {
367
        // Build client based on credential type
368
        if (connectionString != null) {
369
            return StorageClient.fromConnectionString(connectionString);
370
        } else if (credential instanceof TokenCredential) {
371
            return new StorageClient((TokenCredential) credential);
372
        } else if (credential instanceof AzureKeyCredential) {
373
            return new StorageClient((AzureKeyCredential) credential);
374
        } else if (credential instanceof AzureSasCredential) {
375
            return new StorageClient((AzureSasCredential) credential);
376
        } else {
377
            throw new IllegalStateException("No credential or connection string provided");
378
        }
379
    }
380
}
381
```
382

383
### Fluent Configuration Chain
384

385
```java
386
import com.azure.core.http.policy.*;
387

388
// Example of fluent builder configuration
389
MyServiceClient client = new MyServiceClientBuilder()
390
    .endpoint("https://myservice.azure.com")
391
    .credential(new DefaultAzureCredentialBuilder().build())
392
    .httpClient(HttpClient.createDefault())
393
    .addPolicy(new UserAgentPolicy("MyApp/1.0"))
394
    .addPolicy(new RequestIdPolicy())
395
    .retryOptions(new RetryOptions()
396
        .setMaxRetries(5)
397
        .setDelay(Duration.ofSeconds(1))
398
        .setMaxDelay(Duration.ofSeconds(30)))
399
    .httpLogOptions(new HttpLogOptions()
400
        .setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
401
        .addAllowedHeaderName("x-custom-header"))
402
    .clientOptions(new ClientOptions()
403
        .setApplicationId("MyApplication")
404
        .setHeaders(Map.of("x-client-name", "MyApp")))
405
    .configuration(Configuration.getGlobalConfiguration())
406
    .buildClient();
407
```
408

409
### Custom Configuration Trait
410

411
```java
412
// Custom trait for service-specific configuration
413
interface MyServiceConfigurationTrait<T> {
414
    T region(String region);
415
    T enableCaching(boolean enableCaching);
416
    T timeout(Duration timeout);
417
}
418

419
class MyServiceClientBuilder implements 
420
    HttpTrait<MyServiceClientBuilder>,
421
    TokenCredentialTrait<MyServiceClientBuilder>,
422
    MyServiceConfigurationTrait<MyServiceClientBuilder> {
423
    
424
    private String region;
425
    private boolean enableCaching = true;
426
    private Duration timeout = Duration.ofMinutes(5);
427
    
428
    @Override
429
    public MyServiceClientBuilder region(String region) {
430
        this.region = region;
431
        return this;
432
    }
433
    
434
    @Override
435
    public MyServiceClientBuilder enableCaching(boolean enableCaching) {
436
        this.enableCaching = enableCaching;
437
        return this;
438
    }
439
    
440
    @Override
441
    public MyServiceClientBuilder timeout(Duration timeout) {
442
        this.timeout = timeout;
443
        return this;
444
    }
445
    
446
    // ... other trait implementations
447
}
448
```
449

450
### Multi-Service Builder Pattern
451

452
```java
453
// Builder that can create multiple service clients
454
@ServiceClientBuilder(serviceClients = {ServiceAClient.class, ServiceBClient.class})
455
class MultiServiceClientBuilder implements
456
    HttpTrait<MultiServiceClientBuilder>,
457
    TokenCredentialTrait<MultiServiceClientBuilder>,
458
    EndpointTrait<MultiServiceClientBuilder> {
459
    
460
    // Shared configuration
461
    private HttpClient httpClient;
462
    private TokenCredential credential;
463
    private String baseEndpoint;
464
    
465
    public ServiceAClient buildServiceAClient() {
466
        String endpoint = baseEndpoint + "/serviceA";
467
        HttpPipeline pipeline = buildPipeline();
468
        return new ServiceAClient(pipeline, endpoint);
469
    }
470
    
471
    public ServiceBClient buildServiceBClient() {
472
        String endpoint = baseEndpoint + "/serviceB";
473
        HttpPipeline pipeline = buildPipeline();
474
        return new ServiceBClient(pipeline, endpoint);
475
    }
476
    
477
    // ... trait implementations and pipeline building
478
}
479

480
// Usage
481
MultiServiceClientBuilder builder = new MultiServiceClientBuilder()
482
    .endpoint("https://api.myservice.com")
483
    .credential(credential)
484
    .httpClient(httpClient);
485

486
ServiceAClient clientA = builder.buildServiceAClient();
487
ServiceBClient clientB = builder.buildServiceBClient();
488
```