-
Notifications
You must be signed in to change notification settings - Fork 2k
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
vcolin7
wants to merge
2
commits into
main
Choose a base branch
from
feature/vicolina/clientcore/remove-azure
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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>`). --> | ||
<!-- - 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) -->~~~~ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
|
||
|
@@ -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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
|
||
|
@@ -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 | ||
|
||
|
@@ -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 | ||
|
@@ -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) --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.