0
# Azure Core Java Library
1

2
Azure Core provides shared primitives, abstractions, and helpers for modern Java Azure SDK client libraries. It serves as the foundational layer enabling consistent HTTP communication, authentication, serialization, error handling, and common patterns across all Azure Java SDKs.
3

4
## Package Information
5

6
- **Package Name**: azure-core
7
- **Package Type**: maven
8
- **Group ID**: com.azure
9
- **Artifact ID**: azure-core
10
- **Language**: Java
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
    <groupId>com.azure</groupId>
15
    <artifactId>azure-core</artifactId>
16
    <version>1.55.4</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import com.azure.core.http.HttpClient;
24
import com.azure.core.http.HttpPipeline;
25
import com.azure.core.http.HttpPipelineBuilder;
26
import com.azure.core.credential.TokenCredential;
27
import com.azure.core.util.BinaryData;
28
import com.azure.core.util.Context;
29
import com.azure.core.util.Configuration;
30
```
31

32
## Basic Usage
33

34
```java
35
import com.azure.core.http.*;
36
import com.azure.core.http.policy.*;
37
import com.azure.core.credential.AzureKeyCredential;
38
import com.azure.core.util.BinaryData;
39
import com.azure.core.util.Context;
40

41
// Create an HTTP pipeline with authentication and retry policies
42
HttpPipeline pipeline = new HttpPipelineBuilder()
43
    .httpClient(HttpClient.createDefault())
44
    .policies(
45
        new UserAgentPolicy("MyApp/1.0"),
46
        new BearerTokenAuthenticationPolicy(credential, "https://vault.azure.net/.default"),
47
        new RetryPolicy(),
48
        new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BASIC)
49
    )
50
    .build();
51

52
// Create and send an HTTP request
53
HttpRequest request = new HttpRequest(HttpMethod.GET, "https://api.example.com/data");
54
request.setHeader("Accept", "application/json");
55

56
// Execute the request
57
HttpResponse response = pipeline.send(request, Context.NONE).block();
58

59
// Handle binary data
60
BinaryData responseData = BinaryData.fromStream(response.getBodyAsInputStream());
61
String jsonContent = responseData.toString();
62
```
63

64
## Architecture
65

66
Azure Core is structured around several key architectural patterns:
67

68
- **HTTP Pipeline**: Modular request/response processing chain with pluggable policies for cross-cutting concerns (authentication, retry, logging, metrics)
69
- **Credential System**: Unified authentication interfaces supporting Azure Active Directory tokens, keys, and custom authentication schemes
70
- **BinaryData**: Flexible data representation supporting streams, bytes, strings, and objects with lazy serialization
71
- **Context**: Thread-safe key-value store for passing metadata through call chains
72
- **Reactive Patterns**: Reactor-based async operations with sync wrappers for blocking scenarios
73

74
This foundation enables all Azure Java SDKs to provide consistent patterns for authentication, error handling, telemetry, and HTTP communication while allowing service-specific customizations.
75

76
## Capabilities
77

78
### HTTP Operations
79

80
Core HTTP client functionality including pipeline construction, request/response handling, and policy-based middleware for authentication, retry, and logging.
81

82
```java { .api }
83
interface HttpClient {
84
    Mono<HttpResponse> send(HttpRequest request);
85
    Mono<HttpResponse> send(HttpRequest request, Context context);
86
}
87

88
class HttpPipelineBuilder {
89
    public HttpPipelineBuilder httpClient(HttpClient httpClient);
90
    public HttpPipelineBuilder policies(HttpPipelinePolicy... policies);
91
    public HttpPipeline build();
92
}
93

94
class HttpRequest {
95
    public HttpRequest(HttpMethod httpMethod, String url);
96
    public HttpRequest setHeader(String name, String value);
97
    public HttpRequest setBody(BinaryData body);
98
}
99

100
class HttpResponse {
101
    public int getStatusCode();
102
    public HttpHeaders getHeaders();
103
    public BinaryData getBody();
104
    public Flux<ByteBuffer> getBodyAsByteBuffer();
105
}
106
```
107

108
[HTTP Client Operations](./http-client.md)
109

110
### Authentication
111

112
Credential management system supporting Azure Active Directory tokens, API keys, SAS tokens, and custom authentication schemes with automatic token refresh.
113

114
```java { .api }
115
interface TokenCredential {
116
    Mono<AccessToken> getToken(TokenRequestContext request);
117
    AccessToken getTokenSync(TokenRequestContext request);
118
}
119

120
class AccessToken {
121
    public AccessToken(String token, OffsetDateTime expiresAt);
122
    public String getToken();
123
    public OffsetDateTime getExpiresAt();
124
    public boolean isExpired();
125
}
126

127
class AzureKeyCredential extends KeyCredential {
128
    public AzureKeyCredential(String key);
129
    public AzureKeyCredential update(String key);
130
}
131

132
class TokenRequestContext {
133
    public TokenRequestContext setScopes(List<String> scopes);
134
    public TokenRequestContext setTenantId(String tenantId);
135
    public TokenRequestContext setClaims(String claims);
136
}
137
```
138

139
[Authentication System](./authentication.md)
140

141
### Serialization
142

143
JSON and XML serialization utilities with pluggable serializers, binary data handling, and integration with popular Java serialization libraries.
144

145
```java { .api }
146
interface JsonSerializer {
147
    <T> T deserialize(InputStream stream, Type type);
148
    <T> T deserialize(byte[] bytes, Type type);
149
    <T> Mono<T> deserializeAsync(InputStream stream, Type type);
150
    void serialize(OutputStream stream, Object value);
151
    byte[] serializeToBytes(Object value);
152
    Mono<Void> serializeAsync(OutputStream stream, Object value);
153
}
154

155
class BinaryData {
156
    public static BinaryData fromObject(Object data);
157
    public static BinaryData fromString(String data);
158
    public static BinaryData fromBytes(byte[] data);
159
    public static BinaryData fromStream(InputStream stream);
160
    public <T> T toObject(Class<T> clazz);
161
    public <T> T toObject(TypeReference<T> typeReference);
162
    public String toString();
163
    public byte[] toBytes();
164
}
165
```
166

167
[Serialization Utilities](./serialization.md)
168

169
### Core Data Models
170

171
Essential data types including geographic objects, cloud events, Azure cloud configurations, and common model patterns used across Azure services.
172

173
```java { .api }
174
class CloudEvent {
175
    public CloudEvent(String source, String type);
176
    public CloudEvent setSubject(String subject);
177
    public CloudEvent setData(BinaryData data);
178
    public CloudEvent setDataContentType(String contentType);
179
    public String getId();
180
    public OffsetDateTime getTime();
181
}
182

183
enum AzureCloud {
184
    AZURE, AZURE_CHINA, AZURE_GERMANY, AZURE_US_GOVERNMENT;
185
    public String getActiveDirectoryEndpoint();
186
    public String getResourceManagerEndpoint();
187
}
188

189
class GeoPoint extends GeoObject {
190
    public GeoPoint(GeoPosition position);
191
    public GeoPosition getCoordinates();
192
}
193

194
class GeoPolygon extends GeoObject {
195
    public GeoPolygon(GeoLinearRing exteriorRing);
196
    public GeoLinearRing getExteriorRing();
197
    public List<GeoLinearRing> getHoles();
198
}
199
```
200

201
[Core Models and Types](./models.md)
202

203
### Utilities
204

205
Essential utilities including configuration management, logging, metrics, tracing, polling operations, and helper functions for Azure SDK development.
206

207
```java { .api }
208
class Configuration {
209
    public static Configuration getGlobalConfiguration();
210
    public String get(String name);
211
    public String get(String name, String defaultValue);
212
    public Configuration put(String name, String value);
213
    public Configuration remove(String name);
214
}
215

216
class ClientLogger {
217
    public ClientLogger(Class<?> clazz);
218
    public void info(String message);
219
    public void warning(String message);
220
    public void error(String message, Throwable throwable);
221
    public boolean canLogAtLevel(LogLevel logLevel);
222
}
223

224
class Context {
225
    public static final Context NONE;
226
    public Context addData(Object key, Object value);
227
    public Optional<Object> getData(Object key);
228
}
229

230
class SyncPoller<T, U> {
231
    public PollResponse<T> poll();
232
    public PollResponse<T> waitForCompletion();
233
    public U getFinalResult();
234
    public void cancelOperation();
235
}
236
```
237

238
[Utility Classes](./utilities.md)
239

240
### HTTP Annotations
241

242
Declarative annotations for building REST APIs with automatic HTTP request generation, parameter binding, and response handling.
243

244
```java { .api }
245
@Target(ElementType.METHOD)
246
@interface Get {
247
    String value();
248
}
249

250
@Target(ElementType.METHOD) 
251
@interface Post {
252
    String value();
253
}
254

255
@Target(ElementType.PARAMETER)
256
@interface PathParam {
257
    String value();
258
    boolean encoded() default false;
259
}
260

261
@Target(ElementType.PARAMETER)
262
@interface QueryParam {
263
    String value();
264
    boolean encoded() default false;
265
    boolean multipleQueryParams() default false;
266
}
267

268
@Target(ElementType.METHOD)
269
@interface ExpectedResponses {
270
    int[] value();
271
}
272

273
@Target(ElementType.TYPE)
274
@interface ServiceInterface {
275
    String name();
276
}
277
```
278

279
[HTTP Annotations](./annotations.md)
280

281
### Client Builder Traits
282

283
Trait interfaces providing consistent configuration patterns across Azure SDK client builders, enabling composable and uniform builder functionality.
284

285
```java { .api }
286
interface HttpTrait<T> {
287
    T httpClient(HttpClient httpClient);
288
    T pipeline(HttpPipeline pipeline);
289
    T addPolicy(HttpPipelinePolicy pipelinePolicy);
290
    T retryOptions(RetryOptions retryOptions);
291
}
292

293
interface TokenCredentialTrait<T> {
294
    T credential(TokenCredential credential);
295
}
296

297
interface EndpointTrait<T> {
298
    T endpoint(String endpoint);
299
}
300

301
interface ConfigurationTrait<T> {
302
    T configuration(Configuration configuration);
303
}
304
```
305

306
[Client Builder Traits](./client-traits.md)
307

308
### HTTP Pipeline Policies
309

310
Comprehensive HTTP pipeline policies for cross-cutting concerns like authentication, retry, logging, and request modification with configurable behavior.
311

312
```java { .api }
313
interface HttpPipelinePolicy {
314
    Mono<HttpResponse> process(HttpPipelineCallContext context, HttpPipelineNextPolicy next);
315
}
316

317
class BearerTokenAuthenticationPolicy implements HttpPipelinePolicy {
318
    public BearerTokenAuthenticationPolicy(TokenCredential credential, String... scopes);
319
}
320

321
class RetryPolicy implements HttpPipelinePolicy {
322
    public RetryPolicy();
323
    public RetryPolicy(RetryOptions retryOptions);
324
}
325

326
class HttpLoggingPolicy implements HttpPipelinePolicy {
327
    public HttpLoggingPolicy();
328
    public HttpLoggingPolicy(HttpLogOptions httpLogOptions);
329
}
330

331
class UserAgentPolicy implements HttpPipelinePolicy {
332
    public UserAgentPolicy(String applicationId);
333
}
334
```
335

336
[HTTP Pipeline Policies](./http-policies.md)
337

338
### Exception Handling
339

340
Comprehensive exception hierarchy for Azure SDK operations with specialized exception types for different failure scenarios.
341

342
```java { .api }
343
class AzureException extends RuntimeException {
344
    public AzureException();
345
    public AzureException(String message);
346
    public AzureException(String message, Throwable cause);
347
}
348

349
class HttpResponseException extends AzureException {
350
    public HttpResponseException(HttpResponse response);
351
    public HttpResponseException(String message, HttpResponse response);
352
    public HttpResponse getResponse();
353
    public Object getValue();
354
}
355

356
class ClientAuthenticationException extends HttpResponseException {
357
    public ClientAuthenticationException(String message, HttpResponse response);
358
}
359

360
class ResourceNotFoundException extends HttpResponseException {
361
    public ResourceNotFoundException(String message, HttpResponse response);
362
}
363

364
class ResourceExistsException extends HttpResponseException {
365
    public ResourceExistsException(String message, HttpResponse response);
366
}
367
```
368

369
[Exception Handling](./exceptions.md)
370

371
### Cryptography and Key Management
372

373
Interfaces for key encryption and cryptographic operations with support for both synchronous and asynchronous scenarios.
374

375
```java { .api }
376
interface KeyEncryptionKey {
377
    String getKeyId();
378
    byte[] wrapKey(String algorithm, byte[] plaintext);
379
    byte[] unwrapKey(String algorithm, byte[] ciphertext);
380
}
381

382
interface AsyncKeyEncryptionKey {
383
    Mono<String> getKeyId();
384
    Mono<byte[]> wrapKey(String algorithm, byte[] plaintext);
385
    Mono<byte[]> unwrapKey(String algorithm, byte[] ciphertext);
386
}
387

388
interface KeyEncryptionKeyResolver {
389
    KeyEncryptionKey resolveKey(String keyId);
390
}
391

392
interface AsyncKeyEncryptionKeyResolver {
393
    Mono<AsyncKeyEncryptionKey> resolveKey(String keyId);
394
}
395
```
396

397
[Cryptography and Key Management](./cryptography.md)