Package com.azure.core.util

Class CoreUtils

java.lang.Object
com.azure.core.util.CoreUtils
public final class CoreUtils extends Object
This class contains utility methods useful for building client libraries.

  • Method Details

    • clone

      public static byte[] clone(byte[] source)
      Creates a copy of the source byte array.
      Parameters:
      source - Array to make copy of
      Returns:
      A copy of the array, or null if source was null.

    • clone

      public static int[] clone(int[] source)
      Creates a copy of the source int array.
      Parameters:
      source - Array to make copy of
      Returns:
      A copy of the array, or null if source was null.

    • clone

      public static <T> T[] clone(T[] source)
      Creates a copy of the source array.
      Type Parameters:
      T - Generic representing the type of the source array.
      Parameters:
      source - Array being copied.
      Returns:
      A copy of the array or null if source was null.

    • isNullOrEmpty

      public static boolean isNullOrEmpty(Object[] array)
      Checks if the array is null or empty.
      Parameters:
      array - Array being checked for nullness or emptiness.
      Returns:
      True if the array is null or empty, false otherwise.

    • isNullOrEmpty

      public static boolean isNullOrEmpty(Collection<?> collection)
      Checks if the collection is null or empty.
      Parameters:
      collection - Collection being checked for nullness or emptiness.
      Returns:
      True if the collection is null or empty, false otherwise.

    • isNullOrEmpty

      public static boolean isNullOrEmpty(Map<?,?> map)
      Checks if the map is null or empty.
      Parameters:
      map - Map being checked for nullness or emptiness.
      Returns:
      True if the map is null or empty, false otherwise.

    • isNullOrEmpty

      public static boolean isNullOrEmpty(CharSequence charSequence)
      Checks if the character sequence is null or empty.
      Parameters:
      charSequence - Character sequence being checked for nullness or emptiness.
      Returns:
      True if the character sequence is null or empty, false otherwise.

    • arrayToString

      public static <T> String arrayToString(T[] array, Function<T,String> mapper)
      Turns an array into a string mapping each element to a string and delimits them using a coma.
      Type Parameters:
      T - Generic representing the type of the array.
      Parameters:
      array - Array being formatted to a string.
      mapper - Function that maps each element to a string.
      Returns:
      Array with each element mapped and delimited, otherwise null if the array is empty or null.

    • findFirstOfType

      public static <T> T findFirstOfType(Object[] args, Class<T> clazz)
      Returns the first instance of the given class from an array of Objects.
      Type Parameters:
      T - Generic type
      Parameters:
      args - Array of objects to search through to find the first instance of the given `clazz` type.
      clazz - The type trying to be found.
      Returns:
      The first object of the desired type, otherwise null.

    • extractAndFetch

      @Deprecated public static <T> org.reactivestreams.Publisher<T> extractAndFetch(PagedResponse<T> page, Context context, BiFunction<String,Context,org.reactivestreams.Publisher<T>> content)
      Deprecated.
      Use localized implementation.
      Extracts and combines the generic items from all the pages linked together.
      Type Parameters:
      T - The type of the item being returned by the paged response.
      Parameters:
      page - The paged response from server holding generic items.
      context - Metadata that is passed into the function that fetches the items from the next page.
      content - The function which fetches items from the next page.
      Returns:
      The publisher holding all the generic items combined.

    • getProperties

      public static Map<String,String> getProperties(String propertiesFileName)
      Helper method that returns an immutable Map of properties defined in propertiesFileName.
      Parameters:
      propertiesFileName - The file name defining the properties.
      Returns:
      an immutable Map.

    • bomAwareToString

      public static String bomAwareToString(byte[] bytes, String contentType)
      Attempts to convert a byte stream into the properly encoded String.

      This utility method will attempt to find the encoding for the String in this order.

      1. Find the byte order mark in the byte array.
      2. Find the charset in the Content-Type header.
      3. Default to UTF-8.
      Parameters:
      bytes - Byte array.
      contentType - Content-Type header value.
      Returns:
      A string representation of the byte array encoded to the found encoding.

    • getApplicationId

      public static String getApplicationId(ClientOptions clientOptions, HttpLogOptions logOptions)
      Retrieves the application ID from either a ClientOptions or HttpLogOptions.

      This method first checks clientOptions for having an application ID then logOptions, finally returning null if neither are set.

      clientOptions is checked first as logOptions application ID is deprecated.

      Parameters:
      clientOptions - The ClientOptions.
      logOptions - The HttpLogOptions.
      Returns:
      The application ID from either clientOptions or logOptions, if neither are set null.

    • createHttpHeadersFromClientOptions

      public static HttpHeaders createHttpHeadersFromClientOptions(ClientOptions clientOptions)
      Creates HttpHeaders from the provided ClientOptions.

      If clientOptions is null or ClientOptions.getHeaders() doesn't return any Header values null will be returned.

      Parameters:
      clientOptions - The ClientOptions used to create the HttpHeaders.
      Returns:
      HttpHeaders containing the Header values from ClientOptions.getHeaders() if clientOptions isn't null and contains Header values, otherwise null.

    • getDefaultTimeoutFromEnvironment

      public static Duration getDefaultTimeoutFromEnvironment(Configuration configuration, String timeoutPropertyName, Duration defaultTimeout, ClientLogger logger)
      Attempts to load an environment configured default timeout.

      If the environment default timeout isn't configured, defaultTimeout will be returned. If the environment default timeout is a string that isn't parseable by Long.parseLong(String), defaultTimeout will be returned. If the environment default timeout is less than 0, Duration.ZERO will be returned indicated that there is no timeout period.

      Parameters:
      configuration - The environment configurations.
      timeoutPropertyName - The default timeout property name.
      defaultTimeout - The fallback timeout to be used.
      logger - A ClientLogger to log exceptions.
      Returns:
      Either the environment configured default timeout, defaultTimeoutMillis, or 0.

    • mergeContexts

      public static Context mergeContexts(Context into, Context from)
      Merges two Contexts into a new Context.
      Parameters:
      into - Context being merged into.
      from - Context being merged.
      Returns:
      A new Context that is the merged Contexts.
      Throws:
      NullPointerException - If either into or from is null.

    • stringJoin

      public static String stringJoin(String delimiter, List<String> values)
      Optimized version of String.join(CharSequence, Iterable) when the values has a small set of object.
      Parameters:
      delimiter - Delimiter between the values.
      values - The values to join.
      Returns:
      The values joined delimited by the delimiter.
      Throws:
      NullPointerException - If delimiter or values is null.

    • bytesToHexString

      public static String bytesToHexString(byte[] bytes)
      Converts a byte array into a hex string.

      The hex string returned uses characters 0123456789abcdef, if uppercase ABCDEF is required the returned string will need to be uppercased.

      If bytes is null, null will be returned. If bytes was an empty array an empty string is returned.

      Parameters:
      bytes - The byte array to convert into a hex string.
      Returns:
      A hex string representing the bytes that were passed, or null if bytes were null.

    • extractSizeFromContentRange

      public static long extractSizeFromContentRange(String contentRange)
      Extracts the size from a Content-Range header.

      The Content-Range header can take the following forms:

      • <unit> <start>-<end>/<size>
      • <unit> <start>-<end>/*
      • <unit> */<size>
      If the <size> is represented by * this method will return -1.

      If contentRange is null a NullPointerException will be thrown, if it doesn't contain a size segment (/<size> or /*) an IllegalArgumentException will be thrown.

      Parameters:
      contentRange - The Content-Range header to extract the size from.
      Returns:
      The size contained in the Content-Range, or -1 if the size was *.
      Throws:
      NullPointerException - If contentRange is null.
      IllegalArgumentException - If contentRange doesn't contain a <size> segment.
      NumberFormatException - If the <size> segment of the contentRange isn't a valid number.

    • parseQueryParameters

      public static Iterator<Map.Entry<String,String>> parseQueryParameters(String queryParameters)
      Utility method for parsing query parameters one-by-one without the use of string splitting.

      This method provides an optimization over parsing query parameters with String.split(String) or a Pattern as it doesn't allocate any arrays to maintain values, instead it parses the query parameters linearly.

      Query parameter parsing works the following way, key=value will turn into an immutable Map.Entry where the Map.Entry.getKey() is key and the Map.Entry.getValue() is value. For query parameters without a value, key= or just key, the value will be an empty string.

      Parameters:
      queryParameters - The query parameter string.
      Returns:
      An Iterator over the query parameter key-value pairs.

    • randomUuid

      public static UUID randomUuid()
      Creates a type 4 (pseudo randomly generated) UUID.

      The UUID is generated using a non-cryptographically strong pseudo random number generator.

      Returns:
      A randomly generated UUID.

    • getResultWithTimeout

      public static <T> T getResultWithTimeout(Future<T> future, Duration timeout) throws InterruptedException, ExecutionException, TimeoutException
      Calls Future.get(long, TimeUnit) and returns the value if the future completes before the timeout is triggered. If the timeout is triggered, the future is cancelled interrupting the execution of the task that the Future represented.

      If the timeout is Duration.isZero() or is Duration.isNegative() then the timeout will be ignored and an infinite timeout will be used.

      Type Parameters:
      T - The type of value returned by the future.
      Parameters:
      future - The Future to get the value from.
      timeout - The timeout value. If the timeout is Duration.isZero() or is Duration.isNegative() then the timeout will be ignored and an infinite timeout will be used.
      Returns:
      The value from the future.
      Throws:
      NullPointerException - If future is null.
      CancellationException - If the computation was cancelled.
      ExecutionException - If the computation threw an exception.
      InterruptedException - If the current thread was interrupted while waiting.
      TimeoutException - If the wait timed out.
      RuntimeException - If the future threw an exception during processing.
      Error - If the future threw an Error during processing.

    • addShutdownHookSafely

      public static ExecutorService addShutdownHookSafely(ExecutorService executorService, Duration shutdownTimeout)
      Helper method that safely adds a Runtime.addShutdownHook(Thread) to the JVM that will close the executorService when the JVM is shutting down.

      Runtime.addShutdownHook(Thread) checks for security privileges and will throw an exception if the proper security isn't available. So, if running with a security manager, setting AZURE_ENABLE_SHUTDOWN_HOOK_WITH_PRIVILEGE to true will have this method use access controller to add the shutdown hook with privileged permissions.

      If executorService is null, no shutdown hook will be added and this method will return null.

      The shutdownTimeout is the amount of time to wait for the executorService to shutdown. If the executorService doesn't shutdown within half the timeout, it will be forcefully shutdown.

      Parameters:
      executorService - The ExecutorService to shutdown when the JVM is shutting down.
      shutdownTimeout - The amount of time to wait for the executorService to shutdown.
      Returns:
      The executorService that was passed in.
      Throws:
      NullPointerException - If shutdownTimeout is null.
      IllegalArgumentException - If shutdownTimeout is zero or negative.

    • addShutdownHookSafely

      public static Thread addShutdownHookSafely(Thread shutdownThread)
      Helper method that safely adds a Runtime.addShutdownHook(Thread) to the JVM that will run when the JVM is shutting down.

      Runtime.addShutdownHook(Thread) checks for security privileges and will throw an exception if the proper security isn't available. So, if running with a security manager, setting AZURE_ENABLE_SHUTDOWN_HOOK_WITH_PRIVILEGE to true will have this method use access controller to add the shutdown hook with privileged permissions.

      If shutdownThread is null, no shutdown hook will be added and this method will return null.

      Parameters:
      shutdownThread - The Thread that will be added as a shutdown hook.
      Returns:
      The Thread that was passed in.

    • durationToStringWithDays

      public static String durationToStringWithDays(Duration duration)
      Converts a Duration to a string in ISO-8601 format with support for a day component.

      Duration.toString() doesn't use a day component, so if the duration is greater than 24 hours it would return an ISO-8601 duration string like PT48H. This method returns an ISO-8601 duration string with a day component if the duration is greater than 24 hours, such as P2D instead of PT48H.

      Parameters:
      duration - The Duration to convert.
      Returns:
      The Duration as a string in ISO-8601 format with support for a day component, or null if the provided Duration was null.

    • parseBestOffsetDateTime

      public static OffsetDateTime parseBestOffsetDateTime(String dateString)
      Parses a string into an OffsetDateTime.

      If dateString is null, null will be returned.

      This method attempts to parse the dateString using DateTimeFormatter.parseBest(CharSequence, TemporalQuery[]). This will use OffsetDateTime.from(TemporalAccessor) as the first attempt and will fall back to LocalDateTime.from(TemporalAccessor) with setting the offset as ZoneOffset.UTC.

      Parameters:
      dateString - The string to parse into an OffsetDateTime.
      Returns:
      The parsed OffsetDateTime, or null if dateString was null.
      Throws:
      DateTimeException - If the dateString cannot be parsed by either OffsetDateTime.from(TemporalAccessor) or LocalDateTime.from(TemporalAccessor).

    • parseAuthenticateHeader

      public static List<AuthenticateChallenge> parseAuthenticateHeader(String authenticateHeader)
      Processes an authenticate header, such as HttpHeaderName.WWW_AUTHENTICATE or HttpHeaderName.PROXY_AUTHENTICATE, into a list of AuthenticateChallenge.

      If the authenticateHeader is null or empty an empty list will be returned.

      This method will parse the authenticate header as plainly as possible, meaning no casing will be changed on the scheme and no decoding will be done on the parameters. The only processing done is removal of quotes around parameter values and backslashes escaping values. Ex, "va\"lue" will be parsed as va"lue.

      In addition to processing as plainly as possible, this method will not validate the authenticate header, it will only parse it. Though, if the authenticate header has syntax errors an IllegalStateException will be thrown.

      A list of AuthenticateChallenge will be returned as it is valid for multiple authenticate challenges to use the same scheme, therefore a map cannot be used as the scheme would be the key and only one challenge would be stored.

      Parameters:
      authenticateHeader - The authenticate header to be parsed.
      Returns:
      A list of authenticate challenges.
      Throws:
      IllegalArgumentException - If the authenticateHeader has syntax errors.