diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/cryptography/package-info.java b/sdk/core/azure-core/src/main/java/com/azure/core/cryptography/package-info.java index 5e39ad45fb6d..5434c53876d9 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/cryptography/package-info.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/cryptography/package-info.java @@ -2,6 +2,6 @@ // Licensed under the MIT License. /** - * Package containing core cryptography interfaces + * Package containing core cryptography interfaces. */ package com.azure.core.cryptography; diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/exception/package-info.java b/sdk/core/azure-core/src/main/java/com/azure/core/exception/package-info.java index 8bd839a535ff..82842d066095 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/exception/package-info.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/exception/package-info.java @@ -2,6 +2,6 @@ // Licensed under the MIT License. /** - * Package containing core exception classes + * Package containing core exception classes. */ package com.azure.core.exception; diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/http/package-info.java b/sdk/core/azure-core/src/main/java/com/azure/core/http/package-info.java index 37a44935af1c..9a231a4ea7a7 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/http/package-info.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/http/package-info.java @@ -2,6 +2,6 @@ // Licensed under the MIT License. /** - * Package containing the HTTP abstractions between the AnnotationParser, RestProxy and HTTP client. + * Package containing HTTP abstractions between the AnnotationParser, RestProxy, and HTTP client. */ package com.azure.core.http; diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/package-info.java b/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/package-info.java index 5d138f009c81..3440337a13d9 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/package-info.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/package-info.java @@ -2,7 +2,7 @@ // Licensed under the MIT License. /** - * Package containing HttpPipelinePolicy interface and it's implementations. + * Package containing HttpPipelinePolicy interface and its implementations. */ package com.azure.core.http.policy; diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/util/logging/ClientLogger.java b/sdk/core/azure-core/src/main/java/com/azure/core/util/logging/ClientLogger.java index f735b3fef2a2..0fe19a86758f 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/util/logging/ClientLogger.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/util/logging/ClientLogger.java @@ -11,15 +11,15 @@ import java.util.Objects; /** - * This is a fluent logger helper class that wraps a plug-able {@link Logger}. + * This is a fluent logger helper class that wraps a pluggable {@link Logger}. * - *

This logger logs formattable messages that use {@code {}} as the placeholder. When a throwable is the last - * argument of the format varargs and the logger is enabled for {@link ClientLogger#verbose(String, Object...) verbose} - * logging the stack trace for the throwable will be included in the log message.

+ *

This logger logs formattable messages that use {@code {}} as the placeholder. When a {@link Throwable throwable} + * is the last argument of the format varargs and the logger is enabled for + * {@link ClientLogger#verbose(String, Object...) verbose}, the stack trace for the throwable is logged.

* *

A minimum logging level threshold is determined by the - * {@link Configuration#PROPERTY_AZURE_LOG_LEVEL AZURE_LOG_LEVEL} environment configuration, by default logging is - * disabled.

+ * {@link Configuration#PROPERTY_AZURE_LOG_LEVEL AZURE_LOG_LEVEL} environment configuration. By default logging is + * disabled.

* *

Log level hierarchy

*
    @@ -78,60 +78,64 @@ public ClientLogger(String className) { } /** - * Logs a formattable message that uses {@code {}} as the placeholder at {@code verbose} log level + * Logs a formattable message that uses {@code {}} as the placeholder at {@code verbose} log level. * - *

    Code Samples

    + *

    Code samples

    *

    - * Logging a message at verbose log level - * {@codesnippet com.azure.core.implementation.util.clientlogger.verbose} + * Logging a message at verbose log level. + * {@codesnippet com.azure.core.util.logging.clientlogger.verbose} * - * @param format The formattable message to log - * @param args Arguments for the message, if an exception is being logged last argument is the throwable. + * @param format The formattable message to log. + * @param args Arguments for the message. If an exception is being logged, the last argument should be the + * {@link Throwable}. */ public void verbose(String format, Object... args) { log(VERBOSE_LEVEL, format, args); } /** - * Logs a formattable message that uses {@code {}} as the placeholder at {@code informational} log level + * Logs a formattable message that uses {@code {}} as the placeholder at {@code informational} log level. * - *

    Code Samples

    + *

    Code samples

    *

    - * Logging a message at informational log level - * {@codesnippet com.azure.core.implementation.util.clientlogger.info} + * Logging a message at informational log level. + * {@codesnippet com.azure.core.util.logging.clientlogger.info} * * @param format The formattable message to log - * @param args Arguments for the message, if an exception is being logged last argument is the throwable. + * @param args Arguments for the message. If an exception is being logged, the last argument should be the + * {@link Throwable}. */ public void info(String format, Object... args) { log(INFORMATIONAL_LEVEL, format, args); } /** - * Logs a formattable message that uses {@code {}} as the placeholder at {@code warning} log level + * Logs a formattable message that uses {@code {}} as the placeholder at {@code warning} log level. * - *

    Code Samples

    + *

    Code samples

    *

    - * Logging a message at warning log level - * {@codesnippet com.azure.core.implementation.util.clientlogger.warning} + * Logging a message at warning log level. + * {@codesnippet com.azure.core.util.logging.clientlogger.warning} * - * @param format The formattable message to log - * @param args Arguments for the message, if an exception is being logged last argument is the throwable. + * @param format The formattable message to log. + * @param args Arguments for the message. If an exception is being logged, the last argument should be the + * {@link Throwable}. */ public void warning(String format, Object... args) { log(WARNING_LEVEL, format, args); } /** - * Logs a formattable message that uses {@code {}} as the placeholder at {@code error} log level + * Logs a formattable message that uses {@code {}} as the placeholder at {@code error} log level. * - *

    Code Samples

    + *

    Code samples

    *

    - * Logging an error with stack trace - * {@codesnippet com.azure.core.implementation.util.clientlogger.error} + * Logging an error with stack trace. + * {@codesnippet com.azure.core.util.logging.clientlogger.error} * - * @param format The formattable message to log - * @param args Arguments for the message, if an exception is being logged last argument is the throwable. + * @param format The formattable message to log. + * @param args Arguments for the message. If an exception is being logged, the last argument should be the + * {@link Throwable}. */ public void error(String format, Object... args) { log(ERROR_LEVEL, format, args); @@ -151,10 +155,10 @@ private void log(int logLevel, String format, Object... args) { } /** - * Attempts to log the {@link RuntimeException} at the warning level and returns it to be thrown. + * Logs the {@link RuntimeException} at the warning level and returns it to be thrown. * * @param runtimeException RuntimeException to be logged and returned. - * @return the passed {@code RuntimeException} + * @return The passed {@code RuntimeException}. * @throws NullPointerException If {@code runtimeException} is {@code null}. */ public RuntimeException logExceptionAsWarning(RuntimeException runtimeException) { @@ -162,10 +166,10 @@ public RuntimeException logExceptionAsWarning(RuntimeException runtimeException) } /** - * Attempts to log the {@link RuntimeException} at the error level and returns it to be thrown. + * Logs the {@link RuntimeException} at the error level and returns it to be thrown. * * @param runtimeException RuntimeException to be logged and returned. - * @return the passed {@code RuntimeException} + * @return The passed {@code RuntimeException}. * @throws NullPointerException If {@code runtimeException} is {@code null}. */ public RuntimeException logExceptionAsError(RuntimeException runtimeException) { diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/util/logging/package-info.java b/sdk/core/azure-core/src/main/java/com/azure/core/util/logging/package-info.java index 8be79d3fe823..312d35c2a517 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/util/logging/package-info.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/util/logging/package-info.java @@ -2,6 +2,6 @@ // Licensed under the MIT License. /** - * Package containing implementation-specific APIs that should not be used by end-users. + * Package containing logging APIs. */ package com.azure.core.util.logging; diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/util/package-info.java b/sdk/core/azure-core/src/main/java/com/azure/core/util/package-info.java index 6a5dc5f88872..2b6e9bec6928 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/util/package-info.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/util/package-info.java @@ -2,6 +2,6 @@ // Licensed under the MIT License. /** - * Package containing core utility classes + * Package containing core utility classes. */ package com.azure.core.util; diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/util/polling/Poller.java b/sdk/core/azure-core/src/main/java/com/azure/core/util/polling/Poller.java index 0050f79f6d4d..aad002fecdbd 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/util/polling/Poller.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/util/polling/Poller.java @@ -14,11 +14,12 @@ import java.util.function.Function; /** - * This class offers API that simplifies the task of executing long-running operations against Azure service. - * The {@link Poller} consist of poll operation, cancel operation if supported by Azure service and polling interval. + * This class offers API that simplifies the task of executing long-running operations against an Azure service. + * The {@link Poller} consists of a poll operation, a cancel operation, if it is supported by the Azure service, and a + * polling interval. + * *

    * It provides the following functionality: - * *

    * - *

    Auto Polling

    - * Auto-polling is enabled by-default. It means that the {@link Poller} starts polling as soon as its instance is - * created. The {@link Poller} will transparently call the poll operation every polling cycle and track the state of - * the long-running operation. Azure services can return {@link PollResponse#getRetryAfter()} to override the - * {@code Poller.pollInterval} defined in the {@link Poller}. The {@link Poller#getStatus()} represents the status - * returned by the successful long-running operation at the time the last auto-polling or last manual polling, whichever - * happened most recently. + *

    Auto polling

    + * Auto-polling is enabled by default. The {@link Poller} starts polling as soon as the instance is created. The + * {@link Poller} will transparently call the poll operation every polling cycle and track the state of the + * long-running operation. Azure services can return {@link PollResponse#getRetryAfter()} to override the + * {@code Poller.pollInterval} defined in the {@link Poller}. {@link #getStatus()} represents the status returned by a + * successful long-running operation at the time the last auto-polling or last manual polling, whichever happened most + * recently. * - *

    Disable Auto Polling

    - * For those scenarios which require manual control of the polling cycle, disable auto-poling by calling - * {@code setAutoPollingEnabled#false} and perform manual poll by invoking {@link Poller#poll()} function. It will call - * poll operation once and update the {@link Poller} with the latest status. + *

    Disable auto polling

    + * For those scenarios which require manual control of the polling cycle, disable auto-polling by calling + * {@link #setAutoPollingEnabled(boolean) setAutoPollingEnabled(false)}. Then perform manual polling by invoking + * {@link #poll()} function. It will call poll operation once and update {@link #getStatus()} with the latest status. * - *

    When auto-polling is disabled, the {@link Poller} will not update its status or other information, unless - * manual polling is triggered by calling {@link Poller#poll()} function. + *

    When auto-polling is disabled, the {@link Poller} will not update its status or any other information, unless + * manual polling is triggered by calling {@link #poll()} function. * - *

    The {@link Poller} will stop polling when the long-running operation is complete or it is disabled. The polling - * is considered complete based on status defined in {@link OperationStatus}. + *

    The {@link Poller} will stop polling when the long-running operation is complete or disabled. Polling is + * considered complete based on status defined in {@link OperationStatus}. * - *

    Code Samples

    + *

    Code samples

    * - *

    Instantiating and Subscribing to Poll Response

    + *

    Instantiating and subscribing to PollResponse

    * {@codesnippet com.azure.core.util.polling.poller.instantiationAndSubscribe} * - *

    Wait/Block for Polling to complete

    + *

    Wait for polling to complete

    * {@codesnippet com.azure.core.util.polling.poller.block} * - *

    Disable auto polling and polling manually

    + *

    Disable auto polling and poll manually

    * {@codesnippet com.azure.core.util.polling.poller.poll-manually} * * @param Type of poll response value @@ -106,20 +107,20 @@ public class Poller { private Disposable fluxDisposable; /** - * Create a {@link Poller} instance with poll interval and poll operation. The polling starts immediately by + * Creates a {@link Poller} instance with poll interval and poll operation. The polling starts immediately by * invoking {@code pollOperation}. The next poll cycle will be defined by {@code retryAfter} value in * {@link PollResponse}. In absence of {@code retryAfter}, the {@link Poller} will use {@code pollInterval}. * - *

    Code Sample - Create poller object

    + *

    Create poller object

    * {@codesnippet com.azure.core.util.polling.poller.initialize.interval.polloperation} * - * @param pollInterval Not-null and greater than zero poll interval. - * @param pollOperation The polling operation to be called by the {@link Poller} instance. This is a callback into - * the client library, which must never return {@code null}, and which must always have a non-null - * {@link OperationStatus}. {@link Mono} returned from poll operation should never return - * {@link Mono#error(Throwable)}.If any unexpected scenario happens in poll operation, it should be handled by - * client library and return a valid {@link PollResponse}. However if poll operation returns - * {@link Mono#error(Throwable)}, the {@link Poller} will disregard that and continue to poll. + * @param pollInterval Non null and greater than zero poll interval. + * @param pollOperation The polling operation to be called by the {@link Poller} instance. This must never return + * {@code null} and always have a non-null {@link OperationStatus}. {@link Mono} returned from poll operation + * should never return {@link Mono#error(Throwable)}. If an unexpected scenario happens during the poll + * operation, it should be handled by the client library and return a valid {@link PollResponse}. However if + * the poll operation returns {@link Mono#error(Throwable)}, the {@link Poller} will disregard it and continue + * to poll. * @throws IllegalArgumentException if {@code pollInterval} is less than or equal to zero and if * {@code pollInterval} or {@code pollOperation} are {@code null} */ @@ -128,20 +129,20 @@ public Poller(Duration pollInterval, Function, Mono, Mono * It will call cancelOperation if status is {@link OperationStatus#IN_PROGRESS} otherwise it does nothing. * - * @throws UnsupportedOperationException when cancel operation is not provided. + * @throws UnsupportedOperationException when the cancel operation is not supported by the Azure service. */ public void cancelOperation() throws UnsupportedOperationException { if (this.cancelOperation == null) { @@ -207,17 +208,14 @@ public Flux> getObserver() { } /** - * Enable user to take control of polling and trigger manual poll operation. It will call poll operation once. + * Enables user to take control of polling and trigger manual poll operation. It will call poll operation once. * This will not turn off auto polling. * - *

    Code Samples

    - * - *

    Manual Polling

    + *

    Manual polling

    *

    * {@codesnippet com.azure.core.util.polling.poller.poll-indepth} * - * @return a Mono of {@link PollResponse} This will call poll operation once. The {@link Mono} returned here could - * be subscribed for receiving {@link PollResponse} in async manner. + * @return A {@link Mono} that returns {@link PollResponse}. This will call poll operation once. */ public Mono> poll() { return this.pollOperation.apply(this.pollResponse) @@ -229,11 +227,12 @@ public Mono> poll() { } /** - * Blocks execution and wait for polling to complete. The polling is considered complete based on status defined in - * {@link OperationStatus}. - *

    It will enable auto-polling if it was disable by user. + * Blocks execution and wait for polling to complete. The polling is considered complete based on the status defined + * in {@link OperationStatus}. * - * @return returns final {@link PollResponse} when polling is complete as defined in {@link OperationStatus}. + *

    It will enable auto-polling if it was disabled by the user. + * + * @return A {@link PollResponse} when polling is complete. */ public PollResponse block() { if (!isAutoPollingEnabled()) { @@ -245,9 +244,8 @@ public PollResponse block() { /** * Blocks indefinitely until given {@link OperationStatus} is received. * - * @param statusToBlockFor The desired {@link OperationStatus} to block for and it can be any valid - * {@link OperationStatus} value. - * @return {@link PollResponse} for matching desired status. + * @param statusToBlockFor The desired {@link OperationStatus} to block for. + * @return {@link PollResponse} whose {@link PollResponse#getStatus()} matches {@code statusToBlockFor}. * @throws IllegalArgumentException If {@code statusToBlockFor} is {@code null}. */ public PollResponse blockUntil(OperationStatus statusToBlockFor) { @@ -255,8 +253,8 @@ public PollResponse blockUntil(OperationStatus statusToBlockFor) { } /** - * Blocks until given {@link OperationStatus} is received or a timeout expires if provided. A {@code null} - * {@code timeout} will cause to block indefinitely for desired status. + * Blocks until given {@code statusToBlockFor} is received or the {@code timeout} elapses. If a {@code null} + * {@code timeout} is given, it will block indefinitely. * * @param statusToBlockFor The desired {@link OperationStatus} to block for and it can be any valid * {@link OperationStatus} value. @@ -390,7 +388,7 @@ private boolean activeSubscriber() { * Indicates if auto polling is enabled. Refer to the {@link Poller} class-level JavaDoc for more details on * auto-polling. * - * @return A boolean value representing if auto-polling is enabled or not.. + * @return {@code true} if auto-polling is enabled and {@code false} otherwise. */ public boolean isAutoPollingEnabled() { return this.autoPollingEnabled; @@ -399,7 +397,7 @@ public boolean isAutoPollingEnabled() { /** * Current known status as a result of last poll event or last response from a manual polling. * - * @return current status or {@code null} if no status is available. + * @return Current status or {@code null} if no status is available. */ public OperationStatus getStatus() { return this.pollResponse != null ? this.pollResponse.getStatus() : null; diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/util/polling/package-info.java b/sdk/core/azure-core/src/main/java/com/azure/core/util/polling/package-info.java index e7e0c829d864..719d9b67f3c5 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/util/polling/package-info.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/util/polling/package-info.java @@ -2,6 +2,6 @@ // Licensed under the MIT License. /** - * Package containing API for Long Running Operations. + * Package containing API for long running operations. */ package com.azure.core.util.polling; diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/util/tracing/Tracer.java b/sdk/core/azure-core/src/main/java/com/azure/core/util/tracing/Tracer.java index 80d90c1481d2..a1752b8d26f0 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/util/tracing/Tracer.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/util/tracing/Tracer.java @@ -6,8 +6,9 @@ import com.azure.core.util.Context; /** - * Contract that all tracers must implement to be plug-able into the SDK. + * Contract that all tracers must implement to be pluggable into the SDK. * + * @see TracerProxy */ public interface Tracer { /** @@ -33,28 +34,25 @@ public interface Tracer { /** * Key for {@link Context} which indicates that the context contains the hostname. - * */ String HOST_NAME = "hostname"; /** * Key for {@link Context} which indicates that the context contains a message span context. - * */ String SPAN_CONTEXT = "span-context"; /** * Key for {@link Context} which indicates that the context contains a "Diagnostic Id" for the service call. - * */ String DIAGNOSTIC_ID_KEY = "diagnostic-id"; /** * Creates a new tracing span. *

    - * The {@code context} will be checked for containing information about a parent span. If a parent span is found, - * the new span will be added as a child. Otherwise the parent span will be created and added to the {@code context} - * and any downstream {@code start()} calls will use the created span as the parent. + * The {@code context} will be checked for information about a parent span. If a parent span is found, the new span + * will be added as a child. Otherwise, the parent span will be created and added to the {@code context} and any + * downstream {@code start()} calls will use the created span as the parent. * *

    Code samples

    * @@ -73,8 +71,8 @@ public interface Tracer { * Creates a new tracing span for AMQP calls. * *

    - * The {@code context} will be checked for containing information about a parent span. If a parent span is found the - * new span will be added as a child. Otherwise the span will be created and added to the {@code context} and any + * The {@code context} will be checked for information about a parent span. If a parent span is found, the new span + * will be added as a child. Otherwise, the parent span will be created and added to the {@code context} and any * downstream {@code start()} calls will use the created span as the parent. * *

    @@ -126,14 +124,14 @@ public interface Tracer { void end(int responseCode, Throwable error, Context context); /** - * Completes the current tracing span. + * Completes the current tracing span for AMQP calls. * *

    Code samples

    * *

    Completes the tracing span with the corresponding OpenCensus status for the given status message

    * {@codesnippet com.azure.core.util.tracing.end#string-throwable-context} * - * @param statusMessage the error or success message that occurred during the call, or {@code null} if no error + * @param statusMessage The error or success message that occurred during the call, or {@code null} if no error * occurred. * @param error {@link Throwable} that happened during the span or {@code null} if no exception occurred. * @param context Additional metadata that is passed through the call stack. @@ -142,8 +140,7 @@ public interface Tracer { void end(String statusMessage, Throwable error, Context context); /** - * Adds metadata to the current span. The {@code context} is checked for having span information, if no span - * information is found in the context no metadata is added. + * Adds metadata to the current span. If no span information is found in the context, then no metadata is added. * * @param key Name of the metadata. * @param value Value of the metadata. diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/util/tracing/TracerProxy.java b/sdk/core/azure-core/src/main/java/com/azure/core/util/tracing/TracerProxy.java index 780b613af31f..c508e4390d84 100644 --- a/sdk/core/azure-core/src/main/java/com/azure/core/util/tracing/TracerProxy.java +++ b/sdk/core/azure-core/src/main/java/com/azure/core/util/tracing/TracerProxy.java @@ -9,6 +9,8 @@ /** * This class provides a means for all client libraries to augment the context information they have received from an * end user with additional distributed tracing information, that may then be passed on to a backend for analysis. + * + * @see Tracer */ public final class TracerProxy { @@ -19,15 +21,16 @@ private TracerProxy() { } /** - * For each tracer plugged into the SDK a new tracing span is created. + * A new tracing span is created for each {@link Tracer tracer} plugged into the SDK. * - * The {@code context} will be checked for containing information about a parent span. If a parent span is found the - * new span will be added as a child, otherwise the span will be created and added to the context and any downstream - * start calls will use the created span as the parent. + * The {@code context} will be checked for information about a parent span. If a parent span is found, the new span + * will be added as a child. Otherwise, the parent span will be created and added to the {@code context} and any + * downstream {@code start()} calls will use the created span as the parent. * * @param methodName Name of the method triggering the span creation. * @param context Additional metadata that is passed through the call stack. - * @return An updated context object. + * + * @return An updated {@link Context} object. */ public static Context start(String methodName, Context context) { Context local = context; @@ -39,8 +42,8 @@ public static Context start(String methodName, Context context) { } /** - * For each tracer plugged into the SDK metadata to its current span. The {@code context} is checked for having span - * information, if no span information is found in the context no metadata is added. + * For each {@link Tracer tracer} plugged into the SDK, the key-value pair metadata is added to its current span. If + * the {@code context} does not contain a span, then no metadata is added. * * @param key Name of the metadata. * @param value Value of the metadata. @@ -51,10 +54,10 @@ public static void setAttribute(String key, String value, Context context) { } /** - * For each tracer plugged into the SDK the current tracing span is marked as completed. + * For each {@link Tracer tracer} plugged into the SDK, its current tracing span is marked as completed. * * @param responseCode Response status code if the span is in a HTTP call context. - * @param error Potential throwable that happened during the span. + * @param error {@link Throwable} that happened during the span or {@code null} if no exception occurred. * @param context Additional metadata that is passed through the call stack. */ public static void end(int responseCode, Throwable error, Context context) { @@ -62,11 +65,12 @@ public static void end(int responseCode, Throwable error, Context context) { } /** - * For each tracer plugged into the SDK the span name is set. + * Sets the span name for each {@link Tracer tracer} plugged into the SDK. * * @param spanName Name of the span. * @param context Additional metadata that is passed through the call stack. - * @return An updated context object. + * + * @return An updated {@link Context} object. */ public static Context setSpanName(String spanName, Context context) { Context local = context; diff --git a/sdk/core/azure-core/src/samples/java/com/azure/core/implementation/util/ClientLoggerJavaDocCodeSnippets.java b/sdk/core/azure-core/src/samples/java/com/azure/core/util/logging/ClientLoggerJavaDocCodeSnippets.java similarity index 64% rename from sdk/core/azure-core/src/samples/java/com/azure/core/implementation/util/ClientLoggerJavaDocCodeSnippets.java rename to sdk/core/azure-core/src/samples/java/com/azure/core/util/logging/ClientLoggerJavaDocCodeSnippets.java index c04294739668..f621b764c043 100644 --- a/sdk/core/azure-core/src/samples/java/com/azure/core/implementation/util/ClientLoggerJavaDocCodeSnippets.java +++ b/sdk/core/azure-core/src/samples/java/com/azure/core/util/logging/ClientLoggerJavaDocCodeSnippets.java @@ -1,9 +1,8 @@ // Copyright (c) Microsoft Corporation. All rights reserved. // Licensed under the MIT License. -package com.azure.core.implementation.util; +package com.azure.core.util.logging; -import com.azure.core.util.logging.ClientLogger; import java.io.File; import java.io.IOException; @@ -20,26 +19,27 @@ public void loggingSnippets() { ClientLogger logger = new ClientLogger(ClientLoggerJavaDocCodeSnippets.class); String name = getName(); - // BEGIN: com.azure.core.implementation.util.clientlogger.verbose + // BEGIN: com.azure.core.util.logging.clientlogger.verbose logger.verbose("A formattable message. Hello, {}", name); - // END: com.azure.core.implementation.util.clientlogger.verbose + // END: com.azure.core.util.logging.clientlogger.verbose - // BEGIN: com.azure.core.implementation.util.clientlogger.info + // BEGIN: com.azure.core.util.logging.clientlogger.info logger.info("A formattable message. Hello, {}", name); - // END: com.azure.core.implementation.util.clientlogger.info + // END: com.azure.core.util.logging.clientlogger.info - // BEGIN: com.azure.core.implementation.util.clientlogger.warning - logger.warning("A formattable message. Hello, {}", name); - // END: com.azure.core.implementation.util.clientlogger.warning + // BEGIN: com.azure.core.util.logging.clientlogger.warning + Throwable exception = new IllegalArgumentException("An invalid argument was encountered."); + logger.warning("A formattable message. Hello, {}", name, exception); + // END: com.azure.core.util.logging.clientlogger.warning File resource = getFile(); - // BEGIN: com.azure.core.implementation.util.clientlogger.error + // BEGIN: com.azure.core.util.logging.clientlogger.error try { upload(resource); } catch (IOException ex) { logger.error("A formattable message. Hello, {}", name, ex); } - // END: com.azure.core.implementation.util.clientlogger.error + // END: com.azure.core.util.logging.clientlogger.error } /** diff --git a/sdk/core/azure-core/src/samples/java/com/azure/core/util/polling/PollerJavaDocCodeSnippets.java b/sdk/core/azure-core/src/samples/java/com/azure/core/util/polling/PollerJavaDocCodeSnippets.java index acbdf8420ba8..d8446a658d86 100644 --- a/sdk/core/azure-core/src/samples/java/com/azure/core/util/polling/PollerJavaDocCodeSnippets.java +++ b/sdk/core/azure-core/src/samples/java/com/azure/core/util/polling/PollerJavaDocCodeSnippets.java @@ -4,80 +4,41 @@ package com.azure.core.util.polling; +import com.azure.core.util.polling.PollResponse.OperationStatus; import reactor.core.publisher.Mono; import java.time.Duration; import java.time.LocalDateTime; -import java.util.function.Function; -import com.azure.core.util.polling.PollResponse.OperationStatus; +import java.util.function.Predicate; /** * This class contains code samples for generating javadocs through doclets for {@link Poller} */ public final class PollerJavaDocCodeSnippets { - - private boolean debug = true; - - private Function, Mono>> createPollOperation( - PollResponse inProResp, - PollResponse finalPollResponse, - long sendFinalResponseInMillis - ) { - return new Function, Mono>>() { - - // Will return success after this time. - LocalDateTime timeToReturnFinalResponse - = LocalDateTime.now().plus(Duration.ofMillis(sendFinalResponseInMillis)); - - @Override - public Mono> apply(PollResponse prePollResponse) { - if (LocalDateTime.now().isBefore(timeToReturnFinalResponse)) { - System.out.println(" Service poll function called returning intermediate response " - + inProResp.getValue()); - return Mono.just(inProResp); - } else { - System.out.println(" Service poll function called returning final response " - + finalPollResponse.getValue()); - return Mono.just(finalPollResponse); - } - } - }; - } + private final Poller myPoller = new Poller<>(Duration.ofMillis(100), + response -> Mono.just(new PollResponse<>(OperationStatus.SUCCESSFULLY_COMPLETED, "Completed"))); /** * Initialise */ public void initialize() { - PollResponse finalPollResponse = - new PollResponse(OperationStatus.SUCCESSFULLY_COMPLETED, ("Operation Completed.")); - PollResponse inProgressResp = - new PollResponse(OperationStatus.IN_PROGRESS, "Operation in progress."); - - long totalTimeoutInMillis = 1000 * 2; // BEGIN: com.azure.core.util.polling.poller.initialize.interval.polloperation - // Define your custom poll operation - Function, Mono>> pollOperation = - new Function, Mono>>() { - // Will return success after this time. - LocalDateTime timeToReturnFinalResponse - = LocalDateTime.now().plus(Duration.ofMillis(800)); - @Override - public Mono> apply(PollResponse prePollResponse) { - if (LocalDateTime.now().isBefore(timeToReturnFinalResponse)) { - System.out.println("returning intermediate response " + inProgressResp.getValue()); - return Mono.just(inProgressResp); - } else { - System.out.println("returning final response " + finalPollResponse.getValue()); - return Mono.just(finalPollResponse); - } - } - }; + LocalDateTime timeToReturnFinalResponse = LocalDateTime.now().plus(Duration.ofMillis(800)); - //Create poller instance - Poller myPoller = new Poller<>(Duration.ofMillis(100), pollOperation); + // Create poller instance + Poller poller = new Poller<>(Duration.ofMillis(100), + // Define your custom poll operation + perPollResponse -> { + if (LocalDateTime.now().isBefore(timeToReturnFinalResponse)) { + System.out.println("Returning intermediate response."); + return Mono.just(new PollResponse<>(OperationStatus.IN_PROGRESS, "Operation in progress.")); + } else { + System.out.println("Returning final response."); + return Mono.just(new PollResponse<>(OperationStatus.SUCCESSFULLY_COMPLETED, "Operation completed.")); + } + }); // Default polling will start transparently. - // END: com.azure.core.util.polling.poller.initialize.interval.polloperation } @@ -85,40 +46,27 @@ public Mono> apply(PollResponse prePollResponse) { * Initialise and subscribe snippet */ public void initializeAndSubscribe() { - PollResponse finalPollResponse = - new PollResponse(OperationStatus.SUCCESSFULLY_COMPLETED, ("Operation Completed.")); - PollResponse inProgressResp = - new PollResponse(OperationStatus.IN_PROGRESS, "Operation in progress."); - - long totalTimeoutInMillis = 1000 * 2; // BEGIN: com.azure.core.util.polling.poller.instantiationAndSubscribe + LocalDateTime timeToReturnFinalResponse = LocalDateTime.now().plus(Duration.ofMillis(800)); + + // Create poller instance Duration pollInterval = Duration.ofMillis(100); - // Assumption : Poll Operation will return a String type in our example. - Function, Mono>> pollOperation = - new Function, Mono>>() { - // Will return success after this time. - LocalDateTime timeToReturnFinalResponse - = LocalDateTime.now().plus(Duration.ofMillis(800)); - - @Override - public Mono> apply(PollResponse prePollResponse) { - if (LocalDateTime.now().isBefore(timeToReturnFinalResponse)) { - System.out.println("returning intermediate response " + inProgressResp.getValue()); - return Mono.just(inProgressResp); - } else { - System.out.println("returning final response " + finalPollResponse.getValue()); - return Mono.just(finalPollResponse); - } + Poller poller = new Poller<>(pollInterval, + // Define your custom poll operation + prePollResponse -> { + if (LocalDateTime.now().isBefore(timeToReturnFinalResponse)) { + System.out.println("Returning intermediate response."); + return Mono.just(new PollResponse<>(OperationStatus.IN_PROGRESS, "Operation in progress.")); + } else { + System.out.println("Returning final response."); + return Mono.just(new PollResponse<>(OperationStatus.SUCCESSFULLY_COMPLETED, "Operation Completed.")); } - }; - - //Create poller instance - Poller myPoller = new Poller<>(pollInterval, pollOperation); + }); // Listen to poll responses - myPoller.getObserver().subscribe(pr -> { - //process poll response - System.out.println("Got Response status,value " + pr.getStatus().toString() + " " + pr.getValue()); + poller.getObserver().subscribe(response -> { + // Process poll response + System.out.printf("Got response. Status: %s, Value: %s%n", response.getStatus(), response.getValue()); }); // Do something else @@ -129,13 +77,9 @@ public Mono> apply(PollResponse prePollResponse) { * block for response */ public void block() { - - Poller myPoller = null; - // BEGIN: com.azure.core.util.polling.poller.block - PollResponse myFinalResponse = myPoller.block(); - System.out.println("Polling complete final status , value= " - + myFinalResponse.getStatus().toString() + "," + myFinalResponse.getValue()); + PollResponse response = myPoller.block(); + System.out.printf("Polling complete. Status: %s, Value: %s%n", response.getStatus(), response.getValue()); // END: com.azure.core.util.polling.poller.block } @@ -143,12 +87,9 @@ public void block() { * disable auto polling */ public void setAutoPollingFalse() { - - Poller myPoller = null; - // BEGIN: com.azure.core.util.polling.poller.disableautopolling myPoller.setAutoPollingEnabled(false); - System.out.println("Polling Enabled ? " + myPoller.isAutoPollingEnabled()); + System.out.println("Polling Enabled? " + myPoller.isAutoPollingEnabled()); // END: com.azure.core.util.polling.poller.disableautopolling } @@ -156,12 +97,9 @@ public void setAutoPollingFalse() { * enable auto polling */ public void setAutoPollingTrue() { - - Poller myPoller = null; - // BEGIN: com.azure.core.util.polling.poller.enableautopolling myPoller.setAutoPollingEnabled(true); - System.out.println("Polling Enabled ? " + myPoller.isAutoPollingEnabled()); + System.out.println("Polling Enabled? " + myPoller.isAutoPollingEnabled()); // END: com.azure.core.util.polling.poller.enableautopolling } @@ -170,52 +108,45 @@ public void setAutoPollingTrue() { * manual auto polling. */ public void poll() { - - Poller myPoller = null; - // BEGIN: com.azure.core.util.polling.poller.poll-manually + // Turns off auto polling. myPoller.setAutoPollingEnabled(false); - PollResponse pollResponse = null; - // We assume that we get SUCCESSFULLY_COMPLETED status from pollOperation when polling is complete. - while (pollResponse != null - && pollResponse.getStatus() != OperationStatus.SUCCESSFULLY_COMPLETED) { - pollResponse = myPoller.poll().block(); - try { - // Ensure that you have sufficient wait in each poll() which is suitable for your application. - Thread.sleep(500); - } catch (InterruptedException e) { - } - } - System.out.println("Polling complete with status " + myPoller.getStatus().toString()); + + // Continue to poll every 500ms until the response emitted from poll() is SUCCESSFULLY_COMPLETED. + myPoller.poll() + .repeatWhen(attemptsCompleted -> attemptsCompleted.flatMap(attempt -> Mono.delay(Duration.ofMillis(500)))) + .takeUntil(response -> response.getStatus() == OperationStatus.SUCCESSFULLY_COMPLETED) + .subscribe( + response -> System.out.printf("Status: %s. Value: %s%n", response.getStatus(), response.getValue()), + error -> System.err.printf("Exception occurred while polling: %s%n", error), + () -> System.out.printf("Polling complete with status: %s%n", myPoller.getStatus())); // END: com.azure.core.util.polling.poller.poll-manually } /** - * manual auto polling. More indepth example + * manual auto polling. More in-depth example */ public void pollIndepth() { - - Poller myPoller = null; - // BEGIN: com.azure.core.util.polling.poller.poll-indepth - // Turn off auto polling and this code will take control of polling + final Predicate> isComplete = response -> { + return response.getStatus() != OperationStatus.IN_PROGRESS + && response.getStatus() != OperationStatus.NOT_STARTED; + }; + + // Turns off auto polling myPoller.setAutoPollingEnabled(false); - PollResponse pollResponse = null; - while (pollResponse == null - || pollResponse.getStatus() == OperationStatus.IN_PROGRESS - || pollResponse.getStatus() == OperationStatus.NOT_STARTED) { - // get one poll Response at a time.. - pollResponse = myPoller.poll().block(); - System.out.println("Poll response status " + pollResponse.getStatus().toString()); - // Ensure that you have sufficient wait in each poll() which is suitable for your application. - try { - // wait before next poll. - Thread.sleep(500); - } catch (InterruptedException e) { - } - } - System.out.println("Polling complete with status " + myPoller.getStatus().toString()); + myPoller.poll() + .repeatWhen(attemptsCompleted -> { + // Retry each poll operation after 500ms. + return attemptsCompleted.flatMap(attempt -> Mono.delay(Duration.ofMillis(500))); + }) + .takeUntil(isComplete) + .filter(isComplete) + .subscribe(completed -> { + System.out.println("Completed poll response: " + completed.getStatus()); + System.out.println("Polling complete with status: " + myPoller.getStatus().toString()); + }); // END: com.azure.core.util.polling.poller.poll-indepth } }