Skip to content

Commit c4cd531

Browse files
JonathanGilesJonathanGiles
committed
some minor updates
1 parent 422041e commit c4cd531

7 files changed

+196
-56
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Planned structure is as follows:
66
* Concepts
77
* [Overview](overview.md)
88
* Client library concepts
9-
* [Patterns & best practices](patterns_best_practices.md)
9+
* [HTTP clients & pipeline](http_client_pipeline.md)
1010
* [Asynchronous programming](asynchronous_programming.md)
1111
* [Pagination & iteration](pagination.md)
1212
* [Long-Running operations](long_running_operations.md)

‎asynchronous_programming.md

+19-36
Large diffs are not rendered by default.

‎http_client_pipeline.md

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# HTTP clients & pipeline
2+
3+
## HTTP clients
4+
5+
The Azure SDK for Java is implemented using an `HttpClient` abstraction, which means that it has a pluggable architecture to enable support for multiple HTTP clients, as well as custom implementations when the need arises. However, because an Azure Java client library that does not know how to actually communicate over HTTP would be undesirable, the `azure-core` base library includes a default dependency on the `azure-core-http-netty` library, which means that, by default, all Azure client libraries use [Netty](https://netty.io).
6+
7+
Despite Netty being the default HTTP client used by all Azure client libraries, there are three implementations available for use by developers, depending on which dependencies they already have in their project. These are implementations for:
8+
9+
* [Netty](https://netty.io)
10+
* [OkHttp](https://square.github.io/okhttp/)
11+
* The new [HttpClient](https://openjdk.java.net/groups/net/httpclient/intro.html) introduced in JDK 11
12+
13+
As noted, by default all HTTP based SDKs add the Netty implementation as a dependency. Because this is included by default, users of the Java client libraries for Azure do not need to explicitly include any dependency.
14+
15+
### Replacing the Default HTTP Client
16+
17+
The dependency on Netty is removable if another implementation is preferred. This is done by excluding the Netty dependency in your build configuration files. In a Maven pom.xml, you would exclude the Netty dependency, and substitute another dependency. Note that the following example shows how the Netty dependency is excluded from a real dependency on the `azure-security-keyvault-secrets` library. Depending on the libraries readers are using, be sure to exclude Netty from all appropriate `com.azure` libraries, as such:
18+
19+
```xml
20+
<dependency>
21+
<groupId>com.azure</groupId>
22+
<artifactId>azure-security-keyvault-secrets</artifactId>
23+
<version>4.2.2.</version>
24+
<exclusions>
25+
<exclusion>
26+
<groupId>com.azure</groupId>
27+
<artifactId>azure-core-http-netty</artifactId>
28+
</exclusion>
29+
</exclusions>
30+
</dependency>
31+
```
32+
33+
```xml
34+
<dependency>
35+
<groupId>com.azure</groupId>
36+
<artifactId>azure-core-http-okhttp</artifactId>
37+
<version>1.3.3</version>
38+
</dependency>
39+
```
40+
41+
**NOTE**: If the Netty dependency is removed but no implementation is given in its place the application will fail to start. An `HttpClient` implementation must exist on the classpath.
42+
43+
### Configuring HTTP Clients
44+
45+
When building a service client it will default to using `HttpClient.createDefault()`, this returns a basic `HttpClient` based on the provided HTTP client implementation. If a more complex `HttpClient` is required, such as requiring a proxy, each implementation offers a builder that allows for a configured `HttpClient` to be constructed, these are `NettyAsyncHttpClientBuilder`, `OkHttpAsyncHttpClientBuilder`, and `JdkAsyncHttpClientBuilder`. These builders will share a common set of configurations such as proxying and communication port but will contain configurations that are specific to each implementation.
46+
47+
48+
The following examples show how to build an `HttpClient` that proxies through `http://localhost:3128` and authenticates with user `example` whose password is `weakPassword`.
49+
50+
#### Netty
51+
52+
```java
53+
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
54+
.proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
55+
.setCredentials("example", "weakPassword"))
56+
.build();
57+
```
58+
59+
#### OkHttp
60+
61+
```java
62+
HttpClient httpClient = new OkHttpAsyncHttpClientBuilder()
63+
.proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
64+
.setCredentials("example", "weakPassword"))
65+
.build();
66+
```
67+
68+
#### JDK 11 HttpClient
69+
70+
```java
71+
HttpClient client = new JdkAsyncHttpClientBuilder()
72+
.proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128)))
73+
.build();
74+
```
75+
76+
> **TODO:** JdkAsyncHttpClientBuilder does not have a setCredentials API?
77+
78+
The constructed `HttpClient` can now be passed into a service client builder to be used as the client it uses to communicate to the service. The following example is using it to build a Azure Storage Blob client.
79+
80+
```java
81+
BlobClient blobClient = new BlobClientBuilder()
82+
.connectionString(<connection string>)
83+
.containerName("container")
84+
.blobName("blob")
85+
.httpClient(httpClient)
86+
.build();
87+
```
88+
89+
## HTTP pipeline
90+
91+
The HTTP pipeline is one of the key components in achieving consistency and diagnosability in the Java client libraries for Azure, which are two of the core design principles for all Azure SDKs, regardless of language. An HTTP pipeline is composed of:
92+
93+
* HTTP Transport
94+
* HTTP pipeline policies
95+
96+
Users can provide their own [custom HTTP pipeline](#Custom-HTTP-Pipeline-Policy) when creating a client. If it's not provided, the client library will create one with all of the common policies required for the specific service that the library represents.
97+
98+
### HTTP Transport
99+
100+
The HTTP transport is responsible for establishing the connection to the server, as well as sending and receiving HTTP messages. It forms the gateway for the Azure SDK client libraries to interact with Azure services. As noted earlier in this document, Java by default uses [Netty](https://netty.io/) for its HTTP transport, but it also offers a pluggable HTTP Transport so that other implementations can be used where appropriate, as well as two additional HTTP transport implementations for OkHttp and the HttpClient that ships with JDK 11 and later.
101+
102+
### HTTP pipeline policies
103+
104+
A pipeline consists of a sequence of steps that are executed for each HTTP request-response roundtrip. Each policy has a dedicated purpose and will act on a request or a response or sometimes both. Because all client libraries are built on a standard 'Azure Core' layer, it will be used to ensure that each policy is executed in order in the pipeline. On the onward journey, i.e while sending a request, the policies are executed in the order in which they are added to the pipeline. When a response is received from the service, the policies are executed in the reverse order. Note that all policies added to the pipeline will be executed before the request is sent and after a response is received. The policy has to decide whether to act on the request, response or both. For example, a logging policy will log the request and response whereas the authentication policy is only interested in modifying the request.
105+
106+
The Azure Core framework will provide the policy with necessary request and response data along with any necessary context to execute the policy. The policy can then perform its operation with the given data and pass the control along to the next policy in the pipeline.
107+
108+
![image.png](./images/http-pipeline.png)
109+
110+
### HTTP Pipeline Policy Position
111+
112+
When making HTTP requests to cloud services, it is important to handle transient failures and retry failed attempts. As this is a very commonly needed functionality, Azure Core provides a retry policy that can watch for transient failures and automatically retry the request.
113+
114+
This retry policy, therefore, splits the whole pipeline into two parts. Policies that are executed before the retry policy and policies that are executed after. Policies that are added before the retry policy are executed only once per API operation and policies that are added after the retry policy will be executed as many times as the retries.
115+
116+
So, when building the HTTP pipeline, it is necessary to understand whether a policy should be executed each time a request is retried or if it is sufficient to execute it just once per API operation.
117+
118+
### Common HTTP pipeline policies
119+
120+
HTTP pipeline for REST-based services are generally configured with policies for authentication, retries, logging, telemetry and specifying request id in the header. Azure Core is pre-loaded with these commonly required HTTP policies that can be added to the pipeline.
121+
122+
| Policy | GitHub link |
123+
|-----------------------|--------------------|
124+
| Retry Policy | [RetryPolicy.java](https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/RetryPolicy.java) |
125+
| Authentication Policy | [BearerTokenAuthenticationPolicy.java](https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/BearerTokenAuthenticationPolicy.java) |
126+
| Logging Policy | [HttpLoggingPolicy.java](https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/HttpLoggingPolicy.java) |
127+
| Request ID Policy | [RequestIdPolicy.java](https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/RequestIdPolicy.java) |
128+
| Telemetry Policy | [UserAgentPolicy.java](https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/UserAgentPolicy.java) |
129+
130+
### Custom HTTP Pipeline Policy
131+
132+
The HTTP pipeline policy provides a convenient mechanism to modify or decorate the request and response. Custom policies can be added to the pipeline that is either created by the user or by the client library developer. When adding the policy to the pipeline, you can specify if this policy should be executed per-call or per-retry.
133+
134+
Creating a custom HTTP pipeline policy is as simple as extending a base policy type and implementing some abstract method. The policy can then be plugged in to the pipeline.

‎images/http-pipeline.png

85 KB
Loading

‎logging.md

+9-7
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
The Azure client libraries for Java log using [SLF4J](https://www.slf4j.org/), allowing for applications using these libraries to use their preferred logging framework. More details on logging using SLF4J can be found
44
[in the SLF4J manual](https://www.slf4j.org/manual.html).
55

6-
### Configuring Logging
6+
## Configuring Logging
77

88
By default, logging should be configured using an SLF4J-supported logging framework. This starts by including a [relevant SLF4J logging implementation as a dependency from your project](http://www.slf4j.org/manual.html#projectDep), but then continues onward to configuring your logger to work as necessary in your environment (such as setting log levels, configuring which classes do and do not log, etc). Some examples are provided below, but for more detail, refer to the documentation for your chosen logging framework.
99

@@ -21,7 +21,8 @@ Logging, as already stated, uses SLF4J, but there is a fall-back, default logger
2121
## Use `ClientLogger` for logging information.
2222

2323
Here is the code to use `ClientLogger`
24-
```
24+
25+
```java
2526
ClientLogger logger = new ClientLogger("$ClassName"); // Use the string of class name or the class type.
2627
logger.info("I am info");
2728
```
@@ -34,7 +35,7 @@ For more information related to log4j, please refer [here](http://logging.apache
3435

3536
**Adding maven dependencies**
3637

37-
```
38+
```xml
3839
<!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-log4j12 -->
3940
<dependency>
4041
<groupId>org.slf4j</groupId>
@@ -92,7 +93,7 @@ For more information related to log4j2, please refer [here](https://logging.apac
9293

9394
**Adding maven dependencies**
9495

95-
```
96+
```xml
9697
<!-- https://mvnrepository.com/artifact/org.apache.logging.log4j/log4j-slf4j-impl -->
9798
<dependency>
9899
<groupId>org.apache.logging.log4j</groupId>
@@ -149,7 +150,7 @@ To enable logback logging in config file, create a file called `logback.xml` und
149150

150151
**Adding maven dependencies**
151152

152-
```
153+
```xml
153154
<!-- https://mvnrepository.com/artifact/ch.qos.logback/logback-classic -->
154155
<dependency>
155156
<groupId>ch.qos.logback</groupId>
@@ -183,7 +184,7 @@ on configuring `logback.xml` can be found [here](https://logback.qos.ch/manual/c
183184

184185
A simple logback configuration to log to console can be configured as follows:
185186

186-
```xml
187+
```xml
187188
<?xml version="1.0" encoding="UTF-8"?>
188189
<configuration>
189190
<appender name="Console"
@@ -204,6 +205,7 @@ A simple logback configuration to log to console can be configured as follows:
204205
Spring looks at this file for various configurations including logging. You can configure your application to read logback configurations from any file. So, this is where you will link your `logback.xml` to your spring application. Add the following line to do so:
205206

206207
Create another file called `application.properties` under the same directory `./src/main/resources`.
208+
207209
```properties
208210
logging.config=classpath:logback.xml
209211
```
@@ -232,4 +234,4 @@ To configure logging to a file which is rolled over after each hour and archived
232234
<appender-ref ref="RollingFile" />
233235
</root>
234236
</configuration>
235-
```
237+
```

‎overview.md

+33-1
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,36 @@ The open-source Azure libraries for Java simplify provisioning, managing, and us
88
* The libraries support Java 8 and later, and are tested against both the Java 8 baseline as well as the latest Java 'long-term support' release.
99
* The libraries include full Java module support, which means that they are fully compliant with the requirements of a Java module and export all relevant packages for use.
1010
* The Azure SDK for Java is composed solely of over many individual Java libraries that relate to specific Azure services. There are no other tools in the "SDK".
11-
*
11+
* There are distinct "management" and "client" libraries (sometimes referred to as "management plane" and "data plane" libraries). Each set serves different purposes and is used by different kinds of code. For more details, see the following sections later in this article:
12+
* [Provision and manage Azure resources with management libraries.](#provision-and-manage-azure-resources-with-management-libraries)
13+
* [Connect to and use Azure resources with client libraries.](#connect-to-and-use-azure-resources-with-client-libraries)
14+
* Documentation for the libraries is found on the [Azure for Java Reference](https://docs.microsoft.com/java/api/overview/azure/), which is organized by Azure Service, or the [Java API browser](https://docs.microsoft.com/java/api/), which is organized by package name. At present, you often need to click to a number of layers to get to the classes and methods you care about. Allow us to apologize in advance for this sub-par experience. We're working to improve it!
15+
16+
## Other details
17+
18+
* The Azure libraries for Java build on top of the underlying Azure REST API, allowing you to use those APIs through familiar Java paradigms. However, you can always use the REST API directly from Java code, if desired.
19+
* You can find the source code for the Azure libraries on https://github.com/Azure/azure-sdk-for-java. As an open-source project, contributions are welcome!
20+
* We're currently updating the Azure libraries for Java libraries to share common cloud patterns such as authentication protocols, logging, tracing, transport protocols, buffered responses, and retries.
21+
* This shared functionality is contained in the [azure-core](https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/core/azure-core) library.
22+
* For details on the guidelines we apply to the libraries, see the [Java Guidelines: Introduction](https://azure.github.io/azure-sdk/java_introduction.html).
23+
24+
## Provision and manage Azure resources with management libraries
25+
26+
The SDK's management (or "management plane") libraries, all of which can be found in the `com.azure.resourcemanager` Maven group ID, help you create, provision and otherwise manage Azure resources from Java application code. All Azure services have corresponding management libraries.
27+
28+
With the management libraries, you can write configuration and deployment scripts to perform the same tasks that you can through the [Azure portal](https://portal.azure.com/) or the [Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli).
29+
30+
For details on working with each management library, see the README.md file located in the library's project folder in the [SDK GitHub repository](https://github.com/Azure/azure-sdk-for-java). You can also find additional code snippets in the [reference documentation](https://docs.microsoft.com/java/api) and the [Azure Samples](https://docs.microsoft.com/samples/browse/?products=azure&languages=java).
31+
32+
## Connect to and use Azure resources with client libraries
33+
34+
The SDK's client (or "data plane") libraries help you write Java application code to interact with already-provisioned services. Client libraries exist only for those services that support a client API.
35+
36+
For details on working with each client library, see the README.md file located in the library's project folder in the [SDK GitHub repository](https://github.com/Azure/azure-sdk-for-java). You can also find additional code snippets in the [reference documentation](https://docs.microsoft.com/java/api) and the [Azure Samples](https://docs.microsoft.com/samples/browse/?products=azure&languages=java).
37+
38+
## Get help and connect with the SDK team
39+
40+
Visit the [Azure libraries for Java documentation](https://aka.ms/java-docs)
41+
Post questions to the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-sdk-for-java)
42+
Open issues against the SDK on [GitHub](https://github.com/Azure/azure-sdk-for-java/issues)
43+
Mention [@AzureSDK](https://twitter.com/AzureSdk/) on Twitter

‎patterns_best_practices.md

-11
Original file line numberDiff line numberDiff line change
@@ -1,12 +1 @@
1-
# Patterns & best practices
2-
3-
> (Topics include: Introduction to Maven BOM, Creating service clients, etc)
4-
5-
The Java Azure SDK is composed of many Java client libraries - one for each service - rather than a single monolithic library for all of Azure. Despite this, the Java client libraries are designed with consistency in mind, and therefore a number of patterns have been established that users of the library can benefit from as they move from one library to another.
6-
7-
## Library installation
8-
9-
All Java client libraries for Azure are made available in Maven Central in the `com.azure` group ID. This familiar home for developers means that inclusion of a library is as simple as including the appropriate Maven group ID, artifact ID, and version number for the libraries that developers wish to use. Even better, the Azure SDK team ships a Maven BOM file that enables developers to avoid the need to specify a particular version of each Java client library - instead developers may depend on a particular BOM release and have that be used to infer the version of all Java client libraries.
10-
11-
> **TODO** link to correct location for details on all released libraries. Also include details on including the BOM and tracking its version.
121

0 commit comments

Comments
 (0)