You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Azure Core provides shared primitives, abstractions, and helpers for modern Java Azure SDK client libraries.
6
-
These libraries follow the [Azure SDK Design Guidelines for Java](https://azure.github.io/azure-sdk/java_introduction.html)
6
+
These libraries follow
7
+
the [Azure SDK Design Guidelines for Java](https://azure.github.io/azure-sdk/java_introduction.html)
7
8
and can be easily identified by package names starting with `com.azure` and module names starting with `azure-`,
8
9
e.g. `com.azure.storage.blobs` would be found within the `/sdk/storage/azure-storage-blob` directory. A more complete
9
-
list of client libraries using Azure Core can be found [here](https://azure.github.io/azure-sdk/releases/latest/#java-packages).
10
+
list of client libraries using Azure Core can be
11
+
found [here](https://azure.github.io/azure-sdk/releases/latest/#java-packages).
10
12
11
13
Azure Core allows client libraries to expose common functionality consistently, so that once you learn how to use these
12
14
APIs in one client library, you will know how to use them in other client libraries.
@@ -21,8 +23,10 @@ APIs in one client library, you will know how to use them in other client librar
21
23
22
24
#### Include the BOM file
23
25
24
-
Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number.
25
-
To learn more about the BOM, see the [AZURE SDK BOM README](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/boms/azure-sdk-bom/README.md).
26
+
Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the
27
+
library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number.
28
+
To learn more about the BOM, see
29
+
the [AZURE SDK BOM README](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/boms/azure-sdk-bom/README.md).
26
30
27
31
```xml
28
32
<dependencyManagement>
@@ -37,28 +41,31 @@ To learn more about the BOM, see the [AZURE SDK BOM README](https://github.com/A
37
41
</dependencies>
38
42
</dependencyManagement>
39
43
```
40
-
and then include the direct dependency in the dependencies section without the version tag. Typically, you won't need to install or depend on Azure Core, instead it will be transitively downloaded by your build
44
+
45
+
and then include the direct dependency in the dependencies section without the version tag. Typically, you won't need to
46
+
install or depend on Azure Core, instead it will be transitively downloaded by your build
41
47
tool when you depend on client libraries using it.
42
48
43
49
```xml
44
50
<dependencies>
45
-
<dependency>
46
-
<groupId>com.azure</groupId>
47
-
<artifactId>azure-core</artifactId>
48
-
</dependency>
51
+
<dependency>
52
+
<groupId>com.azure</groupId>
53
+
<artifactId>azure-core</artifactId>
54
+
</dependency>
49
55
</dependencies>
50
56
```
51
57
52
58
#### Include direct dependency
59
+
53
60
If you want to take dependency on a particular version of the library that is not present in the BOM,
54
61
add the direct dependency to your project as follows.
- Paging and asynchronous streams (`ContinuablePagedFlux<T>`).
74
81
- Exceptions for reporting errors from service requests consistently.
75
82
- Abstractions for representing Azure SDK credentials.
83
+
- Operation timeouts
76
84
77
85
These will be introduced by way of the examples presented below.
78
86
@@ -102,15 +110,106 @@ consumer requests more data until the consumer finishes processing or all pages
102
110
103
111
### Long Running Operations with `PollerFlux<T>`
104
112
105
-
`PollerFlux` manages sending an initial service request and requesting processing updates on a fix interval until polling is cancelled or reaches a terminal state.
113
+
`PollerFlux` manages sending an initial service request and requesting processing updates on a fix interval until
114
+
polling is cancelled or reaches a terminal state.
115
+
116
+
### Configuring Builders
117
+
118
+
Builders are used to create service clients and some `TokenCredential` implementations. They can be configured with a
119
+
variety of options, including `HttpPipeline` and `HttpClient` for HTTP-based clients and more general options such as
120
+
`Configuration` and`endpoint`. To allow for simpler integration into frameworks such as Spring and to allow generic
121
+
methods to be used for all builders `azure-core` provides a set of interfaces that can be implemented to provide
122
+
the necessary functionality.
123
+
124
+
#### HttpTrait<T>
125
+
126
+
`HttpTrait<T>` contains methods for setting key configurations for HTTP-based clients. This interface will allow you to
127
+
configure the `HttpClient`, `HttpPipeline`, `HttpPipelinePolicy`s, `RetryOptions`, `HttpLogOptions`, and `ClientOptions`
128
+
(preferably `HttpClientOptions` as it is more specific for HTTP-based service clients).
129
+
130
+
For builders that expose `HttpTrait<T>`, if an `HttpPipeline` or `HttpClient` isn't set a default instance will be
131
+
created based on classpath configurations and the `ClientOptions` based to the builder. This can cause confusion if
132
+
you're expecting specific behavior for your client, such as using a proxy that wasn't loaded from the environment. To
133
+
avoid this, it is recommended to always set the `HttpPipeline` or `HttpClient` in all clients if you're building if your
134
+
configurations aren't based on the environment running the application.
135
+
136
+
#### Credential Traits
137
+
138
+
Azure Core provides different credentials for authenticating with Azure services. Each credential type has a
139
+
corresponding trait that can be implemented to provide the credential to the client builder. The following table
140
+
lists the credential traits and the corresponding credential type.
| Connect Timeout |`setConnectTimeout(Duration)`| AZURE_REQUEST_CONNECT_TIMEOUT | 10 seconds | The amount of time for a connection to be established before timing out. |
177
+
| Write Timeout |`setWriteTimeout(Duration)`| AZURE_REQUEST_WRITE_TIMEOUT | 60 seconds | The amount of time between each request data write to the network before timing out. |
178
+
| Response Timeout |`setResponseTimeout(Duration)`| AZURE_REQUEST_RESPONSE_TIMEOUT | 60 seconds | The amount of time between finishing sending the request to receiving the first response bytes before timing out. |
179
+
| Read Timeout |`setReadTimeout(Duration)`| AZURE_REQUEST_READ_TIMEOUT | 60 seconds | The amount of time between each response data read from the network before timing out. |
180
+
181
+
Since these timeouts are closest to the network, if they trigger they will be propagated back through the `HttpPipeline`
182
+
and generally should be retried by the `RetryPolicy`.
183
+
184
+
#### HttpPipeline Timeouts
185
+
186
+
HttpPipeline timeouts are the next level of timeout handling the Azure SDKs provide. These timeouts are configured using
187
+
an `HttpPipelinePolicy` and configuring a timeout using either `Mono.timeout` for asynchronous requests or an
188
+
`ExecutorService` with a timed `get(long, TimeUnit)` for synchronous requests.
189
+
190
+
Depending on the location within the `HttpPipeline`, these timeouts may be captured by the `RetryPolicy` and retried.
191
+
If the timeout policy is `PER_RETRY` (`HttpPipelinePolicy.getPipelinePosition()`) the timeout will be captured by the
192
+
`RetryPolicy` as it will be positioned after the `RetryPolicy`, therefore in its capture scope, if it is `PER_CALL`
193
+
retrying the request will need to be handled by application logic.
194
+
195
+
#### Service Client Timeouts
196
+
197
+
Service client timeouts are the highest level of timeout handling the Azure SDKs provide. These timeouts are configured
198
+
by passing `Duration timeout` into synchronous service methods that support timeouts or by using `Mono.timeout` or
199
+
`Flux.timeout` on asynchronous service methods.
200
+
201
+
Since these timeouts are on the API call itself they cannot be captured by any retry mechanisms within the Azure SDKs
202
+
and must be handled by application logic.
106
203
107
204
## Next steps
108
205
109
-
Get started with Azure libraries that are [built using Azure Core](https://azure.github.io/azure-sdk/releases/latest/#java).
206
+
Get started with Azure libraries that
207
+
are [built using Azure Core](https://azure.github.io/azure-sdk/releases/latest/#java).
110
208
111
209
## Troubleshooting
112
210
113
-
If you encounter any bugs, please file issues via [GitHub Issues](https://github.com/Azure/azure-sdk-for-java/issues/new/choose)
211
+
If you encounter any bugs, please file issues
212
+
via [GitHub Issues](https://github.com/Azure/azure-sdk-for-java/issues/new/choose)
114
213
or checkout [StackOverflow for Azure Java SDK](https://stackoverflow.com/questions/tagged/azure-java-sdk).
115
214
116
215
### Enabling Logging
@@ -121,35 +220,36 @@ locate the root issue. View the [logging][logging] documentation for guidance ab
121
220
122
221
#### HTTP Request and Response Logging
123
222
124
-
HTTP request and response logging can be enabled by setting `HttpLogDetailLevel` in the `HttpLogOptions` used to create
223
+
HTTP request and response logging can be enabled by setting `HttpLogDetailLevel` in the `HttpLogOptions` used to create
125
224
an HTTP-based service client or by setting the environment variable or system property `AZURE_HTTP_LOG_DETAIL_LEVEL`.
126
225
The following table displays the valid options for `AZURE_HTTP_LOG_DETAIL_LEVEL` and the `HttpLogDetailLevel` it
127
226
correlates to (valid options are case-insensitive):
128
227
129
-
|`AZURE_HTTP_LOG_DETAIL_LEVEL` value |`HttpLogDetailLevel` enum |
0 commit comments