Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Removed most mentions of Azure from Client Core. #43455

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions sdk/clientcore/README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,32 @@
# Azure Core shared library for Java
# Client Core shared library for Java

[![Build Documentation](https://img.shields.io/badge/documentation-published-blue.svg)](https://azure.github.io/azure-sdk-for-java)
<!-- [![Build Documentation](https://img.shields.io/badge/documentation-published-blue.svg)](https://azure.github.io/azure-sdk-for-java) -->

Azure Core provides shared primitives, abstractions, and helpers for modern Java Azure SDK client libraries. These libraries follow the [Azure SDK Design Guidelines for Java](https://azure.github.io/azure-sdk/java_introduction.html) and can be easily identified by package names starting with `io.clientcore` and module names starting with `azure-`, e.g. `io.clientcore.storage.blobs` would be found within the `/sdk/storage/azure-storage-blob` directory. A more complete list of client libraries using Azure Core can be found [here](https://azure.github.io/azure-sdk/releases/latest/#java-packages).
Client Core provides shared primitives, abstractions, and helpers for modern SDK client libraries. These libraries
<!-- follow the [SDK Design Guidelines for Java](https://azure.github.io/azure-sdk/java_introduction.html) and -->
can be easily identified by package names starting with `io.clientcore` and module names starting with `core`,
e.g. `io.clientcore.core` would be found within the `/sdk/clientcore/core` directory.
<!-- A more complete list of client libraries using Core can be found [here](https://azure.github.io/azure-sdk/releases/latest/#java-packages). -->

Azure Core allows client libraries to expose common functionality in a consistent fashion, so that once you learn how to use these APIs in one client library, you will know how to use them in other client libraries.
Client Core allows client libraries to expose common functionality in a consistent fashion, so that once you learn how
to use these APIs in one client library, you will know how to use them in other client libraries.

The main shared concepts of Azure Core (and therefore all Azure client libraries using Azure Core) include:
The main shared concepts of Client Core include:

- Configuring service clients, e.g. configuring retries, logging, etc.
- Accessing HTTP response details (`Response<T>`).
- Calling long running operations (`Poller<T>`).
- Paging and asynchronous streams (`PagedFlux<T>`).
<!-- - Calling long-running operations (`Poller<T>`). -->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about just removing these instead of commenting?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good to me, I wasn't sure if we'd ever add anything related and was keeping them around just in case.

<!-- - Paging (`PagedResponse<T>`). -->
- Exceptions for reporting errors from service requests in a consistent fashion.
- Abstractions for representing Azure SDK credentials.
- Abstractions for representing credentials.

## Sub-projects

Azure Core is split into a number of sub-components:
Client Core is split into a number of sub-components:

- [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core) is the primary library, used by all client libraries to offer the functionality outlined above.
- [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-amqp](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-amqp) provides functionality related to AMQP (Advanced Message Queuing Protocol).
- [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-http-netty](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-http-netty) provides a Netty derived HTTP client.
- [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-http-okhttp](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-http-okhttp) provides an OkHttp derived HTTP client.
- [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-management](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-management) provides APIs used by the Azure management libraries, but which are redundant to client libraries.
- [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-test](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-test) provides utilities and API to make writing tests for Azure Core simpler and consistent.
- [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-tracing-opentelemetry](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core-tracing-opentelemetry) provides an OpenTelemetry based tracing library.
- [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/clientcore/core](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/clientcore/core) is the primary library, used by all client libraries to offer the functionality outlined above.
- [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/clientcore/http-okhttp3](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/clientore/http-okhttp3) provides an OkHttp derived HTTP client.

For documentation on using Azure Core, refer to the [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core readme](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core).
For documentation on using Client Core, refer to the [https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/clientcore/core readme](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/clientcore/core).

![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fcore%2FREADME.png)
<!-- ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fcore%2FREADME.png) -->~~~~
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove ~~~

70 changes: 34 additions & 36 deletions sdk/clientcore/core/README.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,21 @@
# Core shared library for Java

[![Build Documentation](https://img.shields.io/badge/documentation-published-blue.svg)](https://azure.github.io/azure-sdk-for-java)
<!-- [![Build Documentation](https://img.shields.io/badge/documentation-published-blue.svg)](https://azure.github.io/azure-sdk-for-java) -->

Core provides shared primitives, abstractions, and helpers for modern Java Core SDK client libraries.
These libraries follow
the [SDK Design Guidelines for Java](https://azure.github.io/azure-sdk/java_introduction.html)
and can be easily identified by package names starting with `io.clientcore` and module names starting with `clientcore`,
e.g. `io.clientcore.core` would be found within the `/sdk/clientcore/core` directory. A more complete
list of client libraries using Core can be found [here](https://azure.github.io/azure-sdk/releases/latest/#java-packages).
Client Core provides shared primitives, abstractions, and helpers for modern SDK client libraries. These libraries
<!-- follow the [SDK Design Guidelines for Java](https://azure.github.io/azure-sdk/java_introduction.html) and -->
can be easily identified by package names starting with `io.clientcore` and module names starting with `core`,
e.g. `io.clientcore.core` would be found within the `/sdk/clientcore/core` directory.
<!-- A more complete list of client libraries using Core can be found [here](https://azure.github.io/azure-sdk/releases/latest/#java-packages). -->

Core allows client libraries to expose common functionality consistently, so that once you learn how to use these
Client Core allows client libraries to expose common functionality consistently, so that once you learn how to use these
APIs in one client library, you will know how to use them in other client libraries.

## Getting started

### Prerequisites

- A [Java Development Kit (JDK)][jdk_link], version 8 or later.
- Here are details about [Java 8 client compatibility with Azure Certificate Authority](https://learn.microsoft.com/azure/security/fundamentals/azure-ca-details?tabs=root-and-subordinate-cas-list#client-compatibility-for-public-pkis).
- A Java Development Kit (JDK), version 8 or later.

### Include the package

Expand Down Expand Up @@ -203,19 +201,19 @@ yourself. The following table lists the HTTP timeout, the corresponding `HttpCli
set it, environment variable to control the default value, the default value if the environment value isn't set, and a
brief description of what the timeout effects.

| HTTP Timeout | `HttpClientOptions` Method | Environment Variable | Default Value | Description |
|------------------|--------------------------------|--------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------|
| Connect Timeout | `setConnectTimeout(Duration)` | AZURE_REQUEST_CONNECT_TIMEOUT | 10 seconds | The amount of time for a connection to be established before timing out. |
| 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. |
| 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. |
| 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. |
| HTTP Timeout | `HttpClientOptions` Method | Environment Variable | Default Value | Description |
|------------------|--------------------------------|--------------------------|---------------|-------------------------------------------------------------------------------------------------------------------|
| Connect Timeout | `setConnectTimeout(Duration)` | REQUEST_CONNECT_TIMEOUT | 10 seconds | The amount of time for a connection to be established before timing out. |
| Write Timeout | `setWriteTimeout(Duration)` | REQUEST_WRITE_TIMEOUT | 60 seconds | The amount of time between each request data write to the network before timing out. |
| Response Timeout | `setResponseTimeout(Duration)` | REQUEST_RESPONSE_TIMEOUT | 60 seconds | The amount of time between finishing sending the request to receiving the first response bytes before timing out. |
| Read Timeout | `setReadTimeout(Duration)` | REQUEST_READ_TIMEOUT | 60 seconds | The amount of time between each response data read from the network before timing out. |

Since these timeouts are closest to the network, if they trigger they will be propagated back through the `HttpPipeline`
and generally should be retried by the `RetryPolicy`.

#### HttpPipeline Timeouts

HttpPipeline timeouts are the next level of timeout handling the Azure SDKs provide. These timeouts are configured using
HttpPipeline timeouts are the next level of timeout handling Client Core provides. These timeouts are configured using
an `HttpPipelinePolicy` and configuring a timeout using either `Mono.timeout` for asynchronous requests or an
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

worth cleaning up the async docs in here too?

`ExecutorService` with a timed `get(long, TimeUnit)` for synchronous requests.

Expand All @@ -226,17 +224,16 @@ retrying the request will need to be handled by application logic.

#### Service Client Timeouts

Service client timeouts are the highest level of timeout handling the Azure SDKs provide. These timeouts are configured
Service client timeouts are the highest level of timeout handling the Client Core provides. These timeouts are configured
by passing `Duration timeout` into synchronous service methods that support timeouts or by using `Mono.timeout` or
`Flux.timeout` on asynchronous service methods.

Since these timeouts are on the API call itself they cannot be captured by any retry mechanisms within the Azure SDKs
Since these timeouts are on the API call itself they cannot be captured by any retry mechanisms within the Client Core
and must be handled by application logic.

## Next steps
<!-- ## Next steps

Get started with Azure libraries that
are [built using Azure Core](https://azure.github.io/azure-sdk/releases/latest/#java).
Get started with libraries that are [built using Client Core](https://azure.github.io/azure-sdk/releases/latest/#java). -->

## Troubleshooting

Expand All @@ -246,24 +243,25 @@ or checkout [StackOverflow for Azure Java SDK](https://stackoverflow.com/questio

### Enabling Logging

Azure SDKs for Java provide a consistent logging story to help aid in troubleshooting application errors and expedite
Client Core provides a consistent logging story to help aid in troubleshooting application errors and expedite
their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help
locate the root issue. View the [logging][logging] documentation for guidance about enabling logging.
locate the root issue.
<!-- View the [logging][logging] documentation for guidance about enabling logging. -->

#### HTTP Request and Response Logging

HTTP request and response logging can be enabled by setting `HttpLogDetailLevel` in the `HttpLogOptions` used to create
an HTTP-based service client or by setting the environment variable or system property `AZURE_HTTP_LOG_DETAIL_LEVEL`.
The following table displays the valid options for `AZURE_HTTP_LOG_DETAIL_LEVEL` and the `HttpLogDetailLevel` it
an HTTP-based service client or by setting the environment variable or system property `HTTP_LOG_DETAIL_LEVEL`.
The following table displays the valid options for `HTTP_LOG_DETAIL_LEVEL` and the `HttpLogDetailLevel` it
correlates to (valid options are case-insensitive):

| `AZURE_HTTP_LOG_DETAIL_LEVEL` value | `HttpLogDetailLevel` enum |
|-------------------------------------|---------------------------------------|
| `basic` | `HttpLogDetailLevel.BASIC` |
| `headers` | `HttpLogDetailLevel.HEADERS` |
| `body` | `HttpLogDetailLevel.BODY` |
| `body_and_headers` | `HttpLogDetailLevel.BODY_AND_HEADERS` |
| `bodyandheaders` | `HttpLogDetailLevel.BODY_AND_HEADERS` |
| `HTTP_LOG_DETAIL_LEVEL` value | `HttpLogDetailLevel` enum |
|-------------------------------|---------------------------------------|
| `basic` | `HttpLogDetailLevel.BASIC` |
| `headers` | `HttpLogDetailLevel.HEADERS` |
| `body` | `HttpLogDetailLevel.BODY` |
| `body_and_headers` | `HttpLogDetailLevel.BODY_AND_HEADERS` |
| `bodyandheaders` | `HttpLogDetailLevel.BODY_AND_HEADERS` |

All other values, or unsupported values, result in `HttpLogDetailLevel.NONE`, or disabled HTTP request and response
logging. Logging [must be enabled](#enabling-logging) to log HTTP requests and responses. Logging of HTTP headers
Expand Down Expand Up @@ -291,8 +289,8 @@ the [contributing guide](https://github.com/Azure/azure-sdk-for-java/blob/main/C

<!-- links -->

[logging]: https://learn.microsoft.com/azure/developer/java/sdk/logging-overview
<!-- [logging]: https://learn.microsoft.com/azure/developer/java/sdk/logging-overview -->

[jdk_link]: https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable
<!-- [jdk_link]: https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable -->

![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fcore%2Fgeneric-core%2FREADME.png)
<!-- ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fcore%2Fgeneric-core%2FREADME.png) -->
2 changes: 1 addition & 1 deletion sdk/clientcore/core/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
<packaging>jar</packaging>
<version>1.0.0-beta.1</version> <!-- {x-version-update;io.clientcore:core;current} -->

<name>Java Core Library for building client libraries for accessing web services.</name>
<name>Core Library for building Java client libraries for accessing web services.</name>
<description>This library contains core types for building Java client libraries for accessing web services.</description>
<url>https://github.com/Azure/azure-sdk-for-java</url>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ private BodyPublisherUtils() {
*/
public static HttpRequest.BodyPublisher toBodyPublisher(io.clientcore.core.http.models.HttpRequest request,
Duration writeTimeout) {
// TODO (alzimmer): azure-core was using Flux.timeout to handle write timeouts. The logic will need to be
// re-implemented to handle write timeouts in a similar manner.
// TODO (alzimmer): Handle write timeouts.
BinaryData body = request.getBody();

if (body == null) {
return noBody();
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -205,8 +205,8 @@ public String getNonProxyHosts() {
* <li>Java HTTP</li>
* </ol>
*
* Azure proxy configurations will be preferred over Java proxy configurations as they are more closely scoped to
* the purpose of the SDK. Additionally, more secure protocols, HTTPS vs HTTP, will be preferred.
* Client Core proxy configurations will be preferred over Java proxy configurations as they are more closely scoped
* to the purpose of the SDK. Additionally, more secure protocols, HTTPS vs HTTP, will be preferred.
*
* <p>
* {@code null} will be returned if no proxy was found in the environment.
Expand All @@ -229,14 +229,14 @@ public static ProxyOptions fromConfiguration(Configuration configuration) {
* <p>
* Environment configurations are loaded in this order:
* <ol>
* <li>Azure HTTPS</li>
* <li>Azure HTTP</li>
* <li>Client Core HTTPS</li>
* <li>Client Core HTTP</li>
* <li>Java HTTPS</li>
* <li>Java HTTP</li>
* </ol>
*
* Azure proxy configurations will be preferred over Java proxy configurations as they are more closely scoped to
* the purpose of the SDK. Additionally, more secure protocols, HTTPS vs HTTP, will be preferred.
* Client Core proxy configurations will be preferred over Java proxy configurations as they are more closely scoped
* to the purpose of the SDK. Additionally, more secure protocols, HTTPS vs HTTP, will be preferred.
* <p>
* {@code null} will be returned if no proxy was found in the environment.
*
Expand Down Expand Up @@ -491,7 +491,7 @@ private static String sanitizeNonProxyHosts(String[] nonProxyHosts) {
/*
* Replace the non-proxy host with the sanitized value.
*
* The body of the non-proxy host is quoted to handle scenarios such a '127.0.0.1' or '*.azure.com'
* The body of the non-proxy host is quoted to handle scenarios such a '127.0.0.1' or '*.somecloud.com'
* where without quoting the '.' in the string would be treated as the match any character instead of
* the literal '.' character.
*/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,6 @@
/**
* Utility class that handles creating and using {@code JsonSerializable} and {@code XmlSerializable} reflectively while
* they are in beta.
* <p>
* Once {@code azure-json} and {@code azure-xml} GA this can be replaced with direct usage of the types. This is
* separated out from what uses it to keep those code paths clean.
*/
public final class ReflectionSerializable {
private static final ClientLogger LOGGER = new ClientLogger(ReflectionSerializable.class);
Expand Down
Loading
Loading