Azure Appconfiguration Java

1---
2name: azure-appconfiguration-java
3description: |
4  Azure App Configuration SDK for Java. Centralized application configuration management with key-value settings, feature flags, and snapshots.
5  Triggers: "ConfigurationClient java", "app configuration java", "feature flag java", "configuration setting java", "azure config java".
6package: com.azure:azure-data-appconfiguration
7---
8 
9# Azure App Configuration SDK for Java
10 
11Client library for Azure App Configuration, a managed service for centralizing application configurations.
12 
13## Installation
14 
15```xml
16<dependency>
17    <groupId>com.azure</groupId>
18    <artifactId>azure-data-appconfiguration</artifactId>
19    <version>1.8.0</version>
20</dependency>
21```
22 
23Or use Azure SDK BOM:
24 
25```xml
26<dependencyManagement>
27    <dependencies>
28        <dependency>
29            <groupId>com.azure</groupId>
30            <artifactId>azure-sdk-bom</artifactId>
31            <version>{bom_version}</version>
32            <type>pom</type>
33            <scope>import</scope>
34        </dependency>
35    </dependencies>
36</dependencyManagement>
37 
38<dependencies>
39    <dependency>
40        <groupId>com.azure</groupId>
41        <artifactId>azure-data-appconfiguration</artifactId>
42    </dependency>
43</dependencies>
44```
45 
46## Prerequisites
47 
48- Azure App Configuration store
49- Connection string or Entra ID credentials
50 
51## Environment Variables
52 
53```bash
54AZURE_APPCONFIG_CONNECTION_STRING=Endpoint=https://<store>.azconfig.io;Id=<id>;Secret=<secret>
55AZURE_APPCONFIG_ENDPOINT=https://<store>.azconfig.io
56```
57 
58## Client Creation
59 
60### With Connection String
61 
62```java
63import com.azure.data.appconfiguration.ConfigurationClient;
64import com.azure.data.appconfiguration.ConfigurationClientBuilder;
65 
66ConfigurationClient configClient = new ConfigurationClientBuilder()
67    .connectionString(System.getenv("AZURE_APPCONFIG_CONNECTION_STRING"))
68    .buildClient();
69```
70 
71### Async Client
72 
73```java
74import com.azure.data.appconfiguration.ConfigurationAsyncClient;
75 
76ConfigurationAsyncClient asyncClient = new ConfigurationClientBuilder()
77    .connectionString(connectionString)
78    .buildAsyncClient();
79```
80 
81### With Entra ID (Recommended)
82 
83```java
84import com.azure.identity.DefaultAzureCredentialBuilder;
85 
86ConfigurationClient configClient = new ConfigurationClientBuilder()
87    .credential(new DefaultAzureCredentialBuilder().build())
88    .endpoint(System.getenv("AZURE_APPCONFIG_ENDPOINT"))
89    .buildClient();
90```
91 
92## Key Concepts
93 
94| Concept | Description |
95|---------|-------------|
96| Configuration Setting | Key-value pair with optional label |
97| Label | Dimension for separating settings (e.g., environments) |
98| Feature Flag | Special setting for feature management |
99| Secret Reference | Setting pointing to Key Vault secret |
100| Snapshot | Point-in-time immutable view of settings |
101 
102## Configuration Setting Operations
103 
104### Create Setting (Add)
105 
106Creates only if setting doesn't exist:
107 
108```java
109import com.azure.data.appconfiguration.models.ConfigurationSetting;
110 
111ConfigurationSetting setting = configClient.addConfigurationSetting(
112    "app/database/connection", 
113    "Production", 
114    "Server=prod.db.com;Database=myapp"
115);
116```
117 
118### Create or Update Setting (Set)
119 
120Creates or overwrites:
121 
122```java
123ConfigurationSetting setting = configClient.setConfigurationSetting(
124    "app/cache/enabled", 
125    "Production", 
126    "true"
127);
128```
129 
130### Get Setting
131 
132```java
133ConfigurationSetting setting = configClient.getConfigurationSetting(
134    "app/database/connection", 
135    "Production"
136);
137System.out.println("Value: " + setting.getValue());
138System.out.println("Content-Type: " + setting.getContentType());
139System.out.println("Last Modified: " + setting.getLastModified());
140```
141 
142### Conditional Get (If Changed)
143 
144```java
145import com.azure.core.http.rest.Response;
146import com.azure.core.util.Context;
147 
148Response<ConfigurationSetting> response = configClient.getConfigurationSettingWithResponse(
149    setting,      // Setting with ETag
150    null,         // Accept datetime
151    true,         // ifChanged - only fetch if modified
152    Context.NONE
153);
154 
155if (response.getStatusCode() == 304) {
156    System.out.println("Setting not modified");
157} else {
158    ConfigurationSetting updated = response.getValue();
159}
160```
161 
162### Update Setting
163 
164```java
165ConfigurationSetting updated = configClient.setConfigurationSetting(
166    "app/cache/enabled", 
167    "Production", 
168    "false"
169);
170```
171 
172### Conditional Update (If Unchanged)
173 
174```java
175// Only update if ETag matches (no concurrent modifications)
176Response<ConfigurationSetting> response = configClient.setConfigurationSettingWithResponse(
177    setting,     // Setting with current ETag
178    true,        // ifUnchanged
179    Context.NONE
180);
181```
182 
183### Delete Setting
184 
185```java
186ConfigurationSetting deleted = configClient.deleteConfigurationSetting(
187    "app/cache/enabled", 
188    "Production"
189);
190```
191 
192### Conditional Delete
193 
194```java
195Response<ConfigurationSetting> response = configClient.deleteConfigurationSettingWithResponse(
196    setting,     // Setting with ETag
197    true,        // ifUnchanged
198    Context.NONE
199);
200```
201 
202## List and Filter Settings
203 
204### List by Key Pattern
205 
206```java
207import com.azure.data.appconfiguration.models.SettingSelector;
208import com.azure.core.http.rest.PagedIterable;
209 
210SettingSelector selector = new SettingSelector()
211    .setKeyFilter("app/*");
212 
213PagedIterable<ConfigurationSetting> settings = configClient.listConfigurationSettings(selector);
214for (ConfigurationSetting s : settings) {
215    System.out.println(s.getKey() + " = " + s.getValue());
216}
217```
218 
219### List by Label
220 
221```java
222SettingSelector selector = new SettingSelector()
223    .setKeyFilter("*")
224    .setLabelFilter("Production");
225 
226PagedIterable<ConfigurationSetting> settings = configClient.listConfigurationSettings(selector);
227```
228 
229### List by Multiple Keys
230 
231```java
232SettingSelector selector = new SettingSelector()
233    .setKeyFilter("app/database/*,app/cache/*");
234 
235PagedIterable<ConfigurationSetting> settings = configClient.listConfigurationSettings(selector);
236```
237 
238### List Revisions
239 
240```java
241SettingSelector selector = new SettingSelector()
242    .setKeyFilter("app/database/connection");
243 
244PagedIterable<ConfigurationSetting> revisions = configClient.listRevisions(selector);
245for (ConfigurationSetting revision : revisions) {
246    System.out.println("Value: " + revision.getValue() + ", Modified: " + revision.getLastModified());
247}
248```
249 
250## Feature Flags
251 
252### Create Feature Flag
253 
254```java
255import com.azure.data.appconfiguration.models.FeatureFlagConfigurationSetting;
256import com.azure.data.appconfiguration.models.FeatureFlagFilter;
257import java.util.Arrays;
258 
259FeatureFlagFilter percentageFilter = new FeatureFlagFilter("Microsoft.Percentage")
260    .addParameter("Value", 50);
261 
262FeatureFlagConfigurationSetting featureFlag = new FeatureFlagConfigurationSetting("beta-feature", true)
263    .setDescription("Beta feature rollout")
264    .setClientFilters(Arrays.asList(percentageFilter));
265 
266FeatureFlagConfigurationSetting created = (FeatureFlagConfigurationSetting)
267    configClient.addConfigurationSetting(featureFlag);
268```
269 
270### Get Feature Flag
271 
272```java
273FeatureFlagConfigurationSetting flag = (FeatureFlagConfigurationSetting)
274    configClient.getConfigurationSetting(featureFlag);
275 
276System.out.println("Feature: " + flag.getFeatureId());
277System.out.println("Enabled: " + flag.isEnabled());
278System.out.println("Filters: " + flag.getClientFilters());
279```
280 
281### Update Feature Flag
282 
283```java
284featureFlag.setEnabled(false);
285FeatureFlagConfigurationSetting updated = (FeatureFlagConfigurationSetting)
286    configClient.setConfigurationSetting(featureFlag);
287```
288 
289## Secret References
290 
291### Create Secret Reference
292 
293```java
294import com.azure.data.appconfiguration.models.SecretReferenceConfigurationSetting;
295 
296SecretReferenceConfigurationSetting secretRef = new SecretReferenceConfigurationSetting(
297    "app/secrets/api-key",
298    "https://myvault.vault.azure.net/secrets/api-key"
299);
300 
301SecretReferenceConfigurationSetting created = (SecretReferenceConfigurationSetting)
302    configClient.addConfigurationSetting(secretRef);
303```
304 
305### Get Secret Reference
306 
307```java
308SecretReferenceConfigurationSetting ref = (SecretReferenceConfigurationSetting)
309    configClient.getConfigurationSetting(secretRef);
310 
311System.out.println("Secret URI: " + ref.getSecretId());
312```
313 
314## Read-Only Settings
315 
316### Set Read-Only
317 
318```java
319ConfigurationSetting readOnly = configClient.setReadOnly(
320    "app/critical/setting", 
321    "Production", 
322    true
323);
324```
325 
326### Clear Read-Only
327 
328```java
329ConfigurationSetting writable = configClient.setReadOnly(
330    "app/critical/setting", 
331    "Production", 
332    false
333);
334```
335 
336## Snapshots
337 
338### Create Snapshot
339 
340```java
341import com.azure.data.appconfiguration.models.ConfigurationSnapshot;
342import com.azure.data.appconfiguration.models.ConfigurationSettingsFilter;
343import com.azure.core.util.polling.SyncPoller;
344import com.azure.core.util.polling.PollOperationDetails;
345 
346List<ConfigurationSettingsFilter> filters = new ArrayList<>();
347filters.add(new ConfigurationSettingsFilter("app/*"));
348 
349SyncPoller<PollOperationDetails, ConfigurationSnapshot> poller = configClient.beginCreateSnapshot(
350    "release-v1.0",
351    new ConfigurationSnapshot(filters),
352    Context.NONE
353);
354poller.setPollInterval(Duration.ofSeconds(10));
355poller.waitForCompletion();
356 
357ConfigurationSnapshot snapshot = poller.getFinalResult();
358System.out.println("Snapshot: " + snapshot.getName() + ", Status: " + snapshot.getStatus());
359```
360 
361### Get Snapshot
362 
363```java
364ConfigurationSnapshot snapshot = configClient.getSnapshot("release-v1.0");
365System.out.println("Created: " + snapshot.getCreatedAt());
366System.out.println("Items: " + snapshot.getItemCount());
367```
368 
369### List Settings in Snapshot
370 
371```java
372PagedIterable<ConfigurationSetting> settings = 
373    configClient.listConfigurationSettingsForSnapshot("release-v1.0");
374 
375for (ConfigurationSetting setting : settings) {
376    System.out.println(setting.getKey() + " = " + setting.getValue());
377}
378```
379 
380### Archive Snapshot
381 
382```java
383ConfigurationSnapshot archived = configClient.archiveSnapshot("release-v1.0");
384System.out.println("Status: " + archived.getStatus()); // archived
385```
386 
387### Recover Snapshot
388 
389```java
390ConfigurationSnapshot recovered = configClient.recoverSnapshot("release-v1.0");
391System.out.println("Status: " + recovered.getStatus()); // ready
392```
393 
394### List All Snapshots
395 
396```java
397import com.azure.data.appconfiguration.models.SnapshotSelector;
398 
399SnapshotSelector selector = new SnapshotSelector().setNameFilter("release-*");
400PagedIterable<ConfigurationSnapshot> snapshots = configClient.listSnapshots(selector);
401 
402for (ConfigurationSnapshot snap : snapshots) {
403    System.out.println(snap.getName() + " - " + snap.getStatus());
404}
405```
406 
407## Labels
408 
409### List Labels
410 
411```java
412import com.azure.data.appconfiguration.models.SettingLabelSelector;
413 
414configClient.listLabels(new SettingLabelSelector().setNameFilter("*"))
415    .forEach(label -> System.out.println("Label: " + label.getName()));
416```
417 
418## Async Operations
419 
420```java
421ConfigurationAsyncClient asyncClient = new ConfigurationClientBuilder()
422    .connectionString(connectionString)
423    .buildAsyncClient();
424 
425// Async list with reactive streams
426asyncClient.listConfigurationSettings(new SettingSelector().setLabelFilter("Production"))
427    .subscribe(
428        setting -> System.out.println(setting.getKey() + " = " + setting.getValue()),
429        error -> System.err.println("Error: " + error.getMessage()),
430        () -> System.out.println("Completed")
431    );
432```
433 
434## Error Handling
435 
436```java
437import com.azure.core.exception.HttpResponseException;
438 
439try {
440    configClient.getConfigurationSetting("nonexistent", null);
441} catch (HttpResponseException e) {
442    if (e.getResponse().getStatusCode() == 404) {
443        System.err.println("Setting not found");
444    } else {
445        System.err.println("Error: " + e.getMessage());
446    }
447}
448```
449 
450## Best Practices
451 
4521. **Use labels** — Separate configurations by environment (Dev, Staging, Production)
4532. **Use snapshots** — Create immutable snapshots for releases
4543. **Feature flags** — Use for gradual rollouts and A/B testing
4554. **Secret references** — Store sensitive values in Key Vault
4565. **Conditional requests** — Use ETags for optimistic concurrency
4576. **Read-only protection** — Lock critical production settings
4587. **Use Entra ID** — Preferred over connection strings
4598. **Async client** — Use for high-throughput scenarios
460 
461## Reference Links
462 
463| Resource | URL |
464|----------|-----|
465| Maven Package | https://central.sonatype.com/artifact/com.azure/azure-data-appconfiguration |
466| GitHub | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/appconfiguration/azure-data-appconfiguration |
467| API Documentation | https://aka.ms/java-docs |
468| Product Docs | https://learn.microsoft.com/azure/azure-app-configuration |
469| Samples | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples |
470| Troubleshooting | https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/TROUBLESHOOTING.md |
471