de.caff.util

## Class Utility

- java.lang.Object
- - de.caff.util.Utility

-     public final class Utility
      extends java.lang.Object

  Utility contains various helpful functionality.

  Sorry, basically this is mess which cries for cleanup.

  Author:
    rammi@caff.de

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `BUILT_DATE` Built date of this class.
    `static java.util.Comparator<java.lang.String>` | `CASE_IGNORING_STRING_COMPARATOR` General comparator for strings, which ignores case.
    `static java.lang.String` | `DEFAULT_RESOURCE_PATH` Default resource path.
    `static java.net.URL[]` | `EMPTY_URL_ARRAY` Empty URL array.
    `static java.awt.image.ImageObserver` | `NULL_OBSERVER` Image observer which ignores everything.
    `static float` | `PHYS_BLUE_SCALE` Physiolocigal brightness value for blue.
    `static float` | `PHYS_GREEN_SCALE` Physiolocigal brightness value for green.
    `static float` | `PHYS_RED_SCALE` Physiolocigal brightness value for red.
    `static java.lang.String` | `RELEASE_DATE` The current version of the library.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Utility()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addEventQueueExceptionListener(EventQueueExceptionListener listener)` Add an exception listener which is called when an exception occurs during the dispatch of an AWT event.
    `static boolean` | `addToSystemClassLoader(java.net.URL... urls)` Add URLs tro the system class loader.
    `static boolean` | `areWeOnDOS()` Deprecated. name is outdated, use `areWeOnWindows()` instead
    `static boolean` | `areWeOnWindows()` Test whether our System Windows-based.
    `static <T> java.util.List<T>` | `asList(T... array)` Deprecated. Use `Types.asList(Object[])` instead.
    `static <T> java.util.List<T>` | `asList(T[] array, int length)` Deprecated. Use `Types.asList(Object[], int)` instead.
    `static <T> java.util.List<T>` | `asList(T[] array, int start, int length)` Deprecated. Use `Types.asList(Object[], int, int)` instead.
    `static java.lang.String` | `compileString(java.lang.String format, java.lang.Object... args)` Compile a formatted string with maximum 10 args.
    `static java.lang.String` | `compileString(java.lang.String tag, java.lang.Object[] args, java.util.ResourceBundle res)` Compile a formatted string with maximum 10 args.
    `static void` | `copyImageToClipboard(java.awt.Image image)` Copy an image to the system clipboard.
    `static void` | `copyTextToClipboard(java.lang.String text)` Copy text to the system clipboard.
    `static java.awt.Cursor` | `createCustomCursor(javax.swing.Icon icon, java.awt.Color bgColor, java.awt.Point hotspot, java.lang.String name, java.awt.Cursor fallback)` Try to create a custom cursor from an icon.
    `static java.awt.Cursor` | `createCustomCursor(javax.swing.Icon icon, java.awt.Color bgColor, java.lang.String name, java.awt.Cursor fallback)` Try to create a custom cursor from an icon.
    `static java.awt.image.BufferedImage` | `createFastImage(int width, int height)` Try to create an image on which graphics operations have high performance.
    `static java.awt.image.VolatileImage` | `createFastVolatileImage(java.awt.Component comp, int width, int height)` This will create a `VolatileImage` and try to increase its acceleration priority.
    `static java.io.OutputStream` | `createOptionalZip(java.lang.String outPath, java.lang.String substExt)` Create a stream which possibly points into a newly created ZIP file.
    `static java.awt.image.BufferedImage` | `createPlatformImage(int width, int height)` Create an opaque buffered image which is optimized for the current platform.
    `static java.awt.image.BufferedImage` | `createPlatformImage(int width, int height, int transparency)` Create a buffered image which is optimized for the current platform.
    `static void` | `debug(java.lang.Object x)` Print message if debug mode is on.
    `static void` | `debug(java.lang.Throwable x)` Print the stack trace if debug mode is on.
    `static boolean` | `equalBytes(byte[] arr1, int off1, byte[] arr2, int off2, int len)` Compare two byte arrays.
    `static byte[]` | `fromHexData(java.lang.String hexData)` Convert a hex data stream to a byte array.
    `static boolean` | `getBooleanParameter(java.lang.String key, boolean def)` Look for a boolean applet parameter or application property.
    `static boolean` | `getBooleanParameter(java.lang.String key, boolean def, java.lang.String... trueValues)` Look for a boolean applet parameter or application property.
    `static java.lang.String` | `getBuildDate()` Use `getBuildDate(Class)` using this class to get a built date.
    `static java.lang.String` | `getBuildDate(java.lang.Class<?> clazz)` Get the build date of a given class.
    `static java.lang.String` | `getBuildDate(java.lang.Class<?> clazz, java.lang.String defaultValue)` Get the build date of a given class.
    `static java.lang.String` | `getBuildDate(java.lang.String defaultValue)` Use `getBuildDate(Class)` using this class to get a built date.
    `static float` | `getColorBrightnessDistance(java.awt.Color color1, java.awt.Color color2)` Get the distance between two colors by comparing their brightness.
    `static java.awt.Color` | `getColorParameter(java.lang.String key, java.awt.Color def)` Look for a color applet parameter or application property.
    `static double` | `getDoubleParameter(java.lang.String key, double def)` Look for a double applet parameter or application property.
    `static <T extends java.lang.Enum<?>> T` | `getEnumParameter(java.lang.String key, T def)` Get an enum value from an applet parameter or application property.
    `static java.lang.String` | `getErrorMessage(java.lang.Throwable x)` Deprecated. use `Debug.getErrorMessage(Throwable)` instead
    `static java.lang.ClassLoader` | `getExtensionClassLoader()` Get the class loader for extension classes.
    `static float` | `getFloatParameter(java.lang.String key, float def)` Look for a float applet parameter or application property.
    `static java.awt.FontMetrics` | `getFontMetrics(java.awt.Font font)` Get a font metrics.
    `static java.awt.Frame` | `getFrame(java.awt.Component comp)` Method to get the frame parent of any component.
    `static int` | `getIntParameter(java.lang.String key, int def)` Look for an integer applet parameter or application property.
    `static int` | `getIntParameter(java.lang.String key, int def, int base)` Look for an integer applet parameter or application property.
    `static PhysicalLength` | `getLengthParameter(java.lang.String key, PhysicalLength def)` Look for a length applet parameter or application property.
    `static long` | `getLongParameter(java.lang.String key, long def)` Look for a long applet parameter of application property.
    `static long` | `getLongParameter(java.lang.String key, long def, int base)` Look for a long applet parameter of application property.
    `static float` | `getPhysiologicalBrightness(java.awt.Color color)` Get the brightness of a color.
    `static float` | `getPhysiologicalBrightness(int red, int green, int blue)` Get the physiological brightness of a RGB color.
    `static java.awt.Color` | `getPhysiologicalGray(java.awt.Color color)` Get a gray with the same brightness as a given color.
    `static Dict<java.lang.String,ParameterTypes>` | `getRequestedParameters()` Get the requested parameters.
    `static java.awt.image.BufferedImage` | `getRootComponentImage(java.awt.Component component)` Get a screen shot of a frame or dialog.
    `static java.util.List<Pair<java.lang.String>>` | `getSortedSystemProperties()` Get a list of system properties and their values, sorted alphabetically by property name.
    `static java.lang.String` | `getStackDump(java.lang.Throwable x)` Deprecated. use `Debug.getStackDump(Throwable)` instead
    `static java.lang.String` | `getStringParameter(java.lang.String key, java.lang.String def)` Look for a String applet parameter or application property.
    `static boolean` | `globEquals(java.lang.String mask, java.lang.String str)` An equal function which accepts globbing.
    `static boolean` | `isDebug()` Get the debug mode.
    `static boolean` | `isNullOrEmpty(java.lang.String str)` Is a string `null` or empty?
    `static java.awt.Image` | `loadImage(java.lang.String path)` Load an image and prepare a representation.
    `static java.awt.Image` | `loadImage(java.lang.String path, java.awt.Component renderer)` Load an image and prepare a representation.
    `static java.awt.Image` | `loadImage(java.lang.String path, java.awt.Component renderer, java.awt.image.ImageObserver observer)` Load an image and prepare a representation.
    `static java.awt.Image` | `loadImage(java.lang.String path, java.awt.image.ImageObserver observer)` Load an image and prepare a representation.
    `static java.lang.String` | `loadText(java.lang.String path)` Load a text file into a string.
    `static void` | `main(java.lang.String[] args)` Print out revisions and built dates.
    `static java.net.URL` | `openResourceViaClass(java.lang.String classResource)` Open a resource via a class.
    `static void` | `printProperties()` In debug mode: print properties to console.
    `static void` | `printProperty(java.lang.String prop)` Print a given property to the console.
    `static void` | `removeEventQueueExceptionListener(EventQueueExceptionListener listener)` Remove an exception listener which was called when an exception occurs during the dispatch of an AWT event.
    `static void` | `setDebug(boolean mode)` Set the debugging mode.
    `static void` | `setExtensionClassLoadUrls(java.net.URL... urls)` Update the extension class load mechanism by adding JAR files and file locations to load classes.
    `static void` | `setResourceDir(java.lang.String dir)` Set the resource directory.
    `static java.lang.String` | `spaces(int num)` Get a string consisting of a given number of space characters.
    `static java.lang.String` | `toASCII(java.lang.String str)` Get a string where all non-ASCII and non-printable characters are escaped by their Unicode escapes.
    `static java.lang.String` | `toHexDump(byte[] data)` Expand a byte array into a hexduimp text structure.
    `static void` | `updateExtensionClassLoader(Function1<java.lang.ClassLoader,java.lang.ClassLoader> updater)` Update the extension class loader.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### RELEASE_DATE

          public static final java.lang.String RELEASE_DATE

      The current version of the library.

    - #### PHYS_RED_SCALE

          public static final float PHYS_RED_SCALE

      Physiolocigal brightness value for red.
      See Also:
        Constant Field Values

    - #### PHYS_GREEN_SCALE

          public static final float PHYS_GREEN_SCALE

      Physiolocigal brightness value for green.
      See Also:
        Constant Field Values

    - #### PHYS_BLUE_SCALE

          public static final float PHYS_BLUE_SCALE

      Physiolocigal brightness value for blue.
      See Also:
        Constant Field Values

    - #### NULL_OBSERVER

          public static final java.awt.image.ImageObserver NULL_OBSERVER

      Image observer which ignores everything.

    - #### DEFAULT_RESOURCE_PATH

          public static final java.lang.String DEFAULT_RESOURCE_PATH

      Default resource path.
      See Also:
        Constant Field Values

    - #### BUILT_DATE

          public static final java.lang.String BUILT_DATE

      Built date of this class.

    - #### EMPTY_URL_ARRAY

          public static final java.net.URL[] EMPTY_URL_ARRAY

      Empty URL array.

    - #### CASE_IGNORING_STRING_COMPARATOR

          @NotNull
          public static final java.util.Comparator<java.lang.String> CASE_IGNORING_STRING_COMPARATOR

      General comparator for strings, which ignores case.

  - ### Constructor Detail

    - #### Utility

          public Utility()

  - ### Method Detail

    - #### setDebug

          public static void setDebug(boolean mode)

      Set the debugging mode.
      Parameters:
        `mode` - new mode

    - #### isDebug

          public static boolean isDebug()

      Get the debug mode.
      Returns:
        debug mode

    - #### getExtensionClassLoader

          @NotNull
          public static java.lang.ClassLoader getExtensionClassLoader()

      Get the class loader for extension classes.
      Returns:
        extension class loader
      See Also:
        `updateExtensionClassLoader(Function1)`

    - #### updateExtensionClassLoader

          public static void updateExtensionClassLoader(@NotNull
                                                        Function1<java.lang.ClassLoader,java.lang.ClassLoader> updater)

      Update the extension class loader.

      This special way of setting the `extension class loader` is chosen to support clean synchronization.

      Changing the class load mechanism requires certain rights and might not work in restricted environments like applets.

      Parameters:
        `updater` - updater function which is called with the current extension class loader as argument and has to return the new extension class loader. The new class loader should use the old extension class loader as its parent to allow for nested extensions. The updater function must not return `null`

    - #### addToSystemClassLoader

          public static boolean addToSystemClassLoader(@NotNull
                                                       java.net.URL... urls)

      Add URLs tro the system class loader.

      This is an evil hack, but allows to add libraries at runtime.

      This method takes care of loading additional JARs which are linked via the Class_path Manifest property, but not recursively.

      It will not work in secure restricted environments like applets.

      Parameters:
        `urls` - JAR or class directory URLs to add to the system class loader
      Returns:
        `true`: if this worked for all URLs
        `false`: if it failed, probably due to security restrictions

    - #### setExtensionClassLoadUrls

          public static void setExtensionClassLoadUrls(@NotNull
                                                       java.net.URL... urls)

      Update the extension class load mechanism by adding JAR files and file locations to load classes.

      This method takes care of loading additional JARs which are linked via the Class_path Manifest property, but not recursively.

      Changing the class load mechanism requires certain rights and might not work in restricted environments like applets.

      Parameters:
        `urls` - URLs of local JAR files and class directories, net URLs are not accepted by the underlying Java class loader extension mechanism

    - #### loadImage

          @Nullable
          public static java.awt.Image loadImage(@NotNull
                                                           java.lang.String path)

      Load an image and prepare a representation. Used for static images to be loaded in an very early stage of program execution.
      Parameters:
        `path` - path of the image file (may include loader class prepended with a `|` (pipe symbol) separator
      Returns:
        the loaded image, or `null` if the image was not found or not accessible

    - #### loadImage

          @Nullable
          public static java.awt.Image loadImage(@NotNull
                                                           java.lang.String path,
                                                           @Nullable
                                                           java.awt.image.ImageObserver observer)

      Load an image and prepare a representation. Used for static images to be loaded in an very early stage of program execution.
      Parameters:
        `path` - path of the image file (may include loader class prepended with a `|` (pipe symbol) separator
        `observer` - image observer
      Returns:
        the loaded image, or `null` if the image was not found or not accessible

    - #### loadImage

          @Nullable
          public static java.awt.Image loadImage(@NotNull
                                                           java.lang.String path,
                                                           @NotNull
                                                           java.awt.Component renderer)

      Load an image and prepare a representation. Used for static images to be loaded in an very early stage of program execution.
      Parameters:
        `path` - path of the image file (may include loader class prepended with a `|` (pipe symbol) separator
        `renderer` - renderer component for image creation
      Returns:
        the loaded image, or `null` if the image was not found or not accessible

    - #### loadImage

          @Nullable
          public static java.awt.Image loadImage(@NotNull
                                                           java.lang.String path,
                                                           @NotNull
                                                           java.awt.Component renderer,
                                                           @Nullable
                                                           java.awt.image.ImageObserver observer)

      Load an image and prepare a representation. Used for static images to be loaded in an very early stage of program execution.
      Parameters:
        `path` - path of the image file (may include loader class prepended with a `|` (pipe symbol) separator
        `renderer` - renderer component for image creation
        `observer` - image observer
      Returns:
        the loaded image, or `null` if the image was not found or not accessible

    - #### getStackDump

          @NotNull
           @Deprecated
          public static java.lang.String getStackDump(@NotNull
                                                                            java.lang.Throwable x)

      Deprecated. use `Debug.getStackDump(Throwable)` instead
      Create a stack dump from a Throwable.
      Parameters:
        `x` - the Throwable
      Returns:
        stack dump
      See Also:
        `getErrorMessage(Throwable)`

    - #### getErrorMessage

          @NotNull
           @Deprecated
          public static java.lang.String getErrorMessage(@NotNull
                                                                               java.lang.Throwable x)

      Deprecated. use `Debug.getErrorMessage(Throwable)` instead
      Get a (halfways) useful message from an exception.
      Parameters:
        `x` - exception
      Returns:
        error message
      See Also:
        `getStackDump(Throwable)`

    - #### loadText

          @NotNull
          public static java.lang.String loadText(@NotNull
                                                           java.lang.String path)

      Load a text file into a string.
      Parameters:
        `path` - name of the text file
      Returns:
        the loaded text

    - #### areWeOnDOS

          @Deprecated
          public static boolean areWeOnDOS()

      Deprecated. name is outdated, use `areWeOnWindows()` instead
      Test whether our System is DOS or Windows-based.
      Returns:
        `true` we are on Windows/DOS
        `false` we are elsewhere

    - #### areWeOnWindows

          public static boolean areWeOnWindows()

      Test whether our System Windows-based.
      Returns:
        `true` we are running on Windows
        `false` we are running elsewhere

    - #### setResourceDir

          public static void setResourceDir(@Nullable
                                            java.lang.String dir)

      Set the resource directory.
      Parameters:
        `dir` - the image directory

    - #### compileString

          @NotNull
          public static java.lang.String compileString(@NotNull
                                                                java.lang.String tag,
                                                                @NotNull
                                                                java.lang.Object[] args,
                                                                @NotNull
                                                                java.util.ResourceBundle res)

      Compile a formatted string with maximum 10 args.

            Special signs:
               %#  where hash is a digit from 0 to 9 means insert arg #
               @#  where hash is a digit from 0 to 9 means insert localized arg #
               %%  means %
               @@  means @

      Parameters:
        `tag` - resource tag for format string
        `args` - arguments for insertion
        `res` - active resource bundle
      Returns:
        String with inserted args.

    - #### compileString

          public static java.lang.String compileString(@NotNull
                                                       java.lang.String format,
                                                       java.lang.Object... args)

      Compile a formatted string with maximum 10 args.

            Special signs:
               %#  where hash is a digit from 0 to 9 means insert arg #
               %%  means %

      Parameters:
        `format` - format string
        `args` - arguments for insertion
      Returns:
        String with inserted args.

    - #### getFrame

          @NotNull
          public static java.awt.Frame getFrame(@Nullable
                                                         java.awt.Component comp)

      Method to get the frame parent of any component.
      Parameters:
        `comp` - the component to search the frame for
      Returns:
        the frame parent of the component

    - #### equalBytes

          public static boolean equalBytes(@NotNull
                                           byte[] arr1,
                                           int off1,
                                           @NotNull
                                           byte[] arr2,
                                           int off2,
                                           int len)

      Compare two byte arrays. Compare `len` bytes from array 1 starting with offset 1 with `len` bytes from array 2 starting with offset 2. Will return always `true` for `len &le;= 0`
      Parameters:
        `arr1` - array 1
        `off1` - offset 1
        `arr2` - array 2
        `off2` - offset 2
        `len` - length to compare
      Returns:
        `true` if both chunks are equal
        `false` otherwise

    - #### getBooleanParameter

          public static boolean getBooleanParameter(@NotNull
                                                    java.lang.String key,
                                                    boolean def)

      Look for a boolean applet parameter or application property. The expected value for `true` is `&quot;true&quot;`.
      Parameters:
        `key` - parameter key
        `def` - default value
      Returns:
        the parameter value (if set) or the default

    - #### getBooleanParameter

          public static boolean getBooleanParameter(@NotNull
                                                    java.lang.String key,
                                                    boolean def,
                                                    @NotNull
                                                    java.lang.String... trueValues)

      Look for a boolean applet parameter or application property. This allows for more than one or other values for `true`.
      Parameters:
        `key` - parameter key
        `def` - default value
        `trueValues` - values to be used for `true` return, compared case-insensitively.
      Returns:
        the parameter value (if set) or the default

    - #### getEnumParameter

          @NotNull
          public static <T extends java.lang.Enum<?>> T getEnumParameter(@NotNull
                                                                                  java.lang.String key,
                                                                                  @NotNull
                                                                                  T def)

      Get an enum value from an applet parameter or application property.
      Type Parameters:
        `T` - enum type
      Parameters:
        `key` - key for the value, expected to evaluate to the name of an enum of the required type
        `def` - default value, also defining the type of enum return by this method
      Returns:
        enum value from property/parameter, or `def` if unset or value is invalid

    - #### getStringParameter

          public static java.lang.String getStringParameter(@NotNull
                                                            java.lang.String key,
                                                            @Nullable
                                                            java.lang.String def)

      Look for a String applet parameter or application property.
      Parameters:
        `key` - parameter key
        `def` - default value
      Returns:
        the parameter value (if set) or the default

    - #### getColorParameter

          @Nullable
          public static java.awt.Color getColorParameter(@NotNull
                                                                   java.lang.String key,
                                                                   @Nullable
                                                                   java.awt.Color def)

      Look for a color applet parameter or application property.
      Parameters:
        `key` - parameter key
        `def` - default value
      Returns:
        the parameter value (if set) or the default

    - #### getIntParameter

          public static int getIntParameter(@NotNull
                                            java.lang.String key,
                                            int def)

      Look for an integer applet parameter or application property.
      Parameters:
        `key` - parameter key
        `def` - default value
      Returns:
        the parameter value (if set and valid) or the default

    - #### getIntParameter

          public static int getIntParameter(@NotNull
                                            java.lang.String key,
                                            int def,
                                            int base)

      Look for an integer applet parameter or application property.
      Parameters:
        `key` - parameter key
        `def` - default value
        `base` - number base
      Returns:
        the parameter value (if set and valid) or the default

    - #### getLongParameter

          public static long getLongParameter(@NotNull
                                              java.lang.String key,
                                              long def)

      Look for a long applet parameter of application property.
      Parameters:
        `key` - parameter key
        `def` - default value
      Returns:
        the parameter value (if set and valid) or the default value

    - #### getLongParameter

          public static long getLongParameter(@NotNull
                                              java.lang.String key,
                                              long def,
                                              int base)

      Look for a long applet parameter of application property.
      Parameters:
        `key` - parameter key
        `def` - default value
        `base` - number base
      Returns:
        the parameter value (if set and valid) or the default value

    - #### getDoubleParameter

          public static double getDoubleParameter(@NotNull
                                                  java.lang.String key,
                                                  double def)

      Look for a double applet parameter or application property.

      Uses percentage if ending with %.

      Parameters:
        `key` - parameter key
        `def` - default value
      Returns:
        the parameter value (if set) or the default

    - #### getFloatParameter

          public static float getFloatParameter(@NotNull
                                                java.lang.String key,
                                                float def)

      Look for a float applet parameter or application property.

      Uses percentage if ending with %.

      Parameters:
        `key` - parameter key
        `def` - default value
      Returns:
        the parameter value (if set) or the default

    - #### getLengthParameter

          public static PhysicalLength getLengthParameter(@NotNull
                                                          java.lang.String key,
                                                          PhysicalLength def)

      Look for a length applet parameter or application property.

      Uses percentage if ending with %.

      Parameters:
        `key` - parameter key
        `def` - default value
      Returns:
        the parameter value (if set) or the default

    - #### debug

          public static void debug(@Nullable
                                   java.lang.Object x)

      Print message if debug mode is on.
      Parameters:
        `x` - object which's toString is called

    - #### debug

          public static void debug(@NotNull
                                   java.lang.Throwable x)

      Print the stack trace if debug mode is on.
      Parameters:
        `x` - exception

    - #### printProperty

          public static void printProperty(@NotNull
                                           java.lang.String prop)

      Print a given property to the console. Catch possible Security exceptions. Does nothing if not in debug mode.
      Parameters:
        `prop` - poperty name

    - #### printProperties

          public static void printProperties()

      In debug mode: print properties to console.

    - #### globEquals

          public static boolean globEquals(@NotNull
                                           java.lang.String mask,
                                           @NotNull
                                           java.lang.String str)

      An equal function which accepts globbing. This method accepts the glob chars `'*'` (for any number of chars) and `'?'` (any single char).
      Parameters:
        `mask` - glob mask (containing special chars)
        `str` - string to be checked against mask
      Returns:
        whether the string matches the mask

    - #### addEventQueueExceptionListener

          public static void addEventQueueExceptionListener(@NotNull
                                                            EventQueueExceptionListener listener)

      Add an exception listener which is called when an exception occurs during the dispatch of an AWT event. Note that depending on the environment this method may throw a security exception.
      Parameters:
        `listener` - listener to add

    - #### removeEventQueueExceptionListener

          public static void removeEventQueueExceptionListener(@NotNull
                                                               EventQueueExceptionListener listener)

      Remove an exception listener which was called when an exception occurs during the dispatch of an AWT event.
      Parameters:
        `listener` - listener to remove

    - #### createCustomCursor

          @NotNull
          public static java.awt.Cursor createCustomCursor(@NotNull
                                                                    javax.swing.Icon icon,
                                                                    @NotNull
                                                                    java.awt.Color bgColor,
                                                                    @NotNull
                                                                    java.lang.String name,
                                                                    @NotNull
                                                                    java.awt.Cursor fallback)

      Try to create a custom cursor from an icon. The hot spot is set to the icon center.
      Parameters:
        `icon` - icon from which to create the cursor
        `bgColor` - background color for cursor
        `name` - name for accessibility
        `fallback` - fallback cursor taken if the image size is not supported
      Returns:
        the new cursor if it was possible to create one with the required size, or the fallback cursor

    - #### createCustomCursor

          @NotNull
          public static java.awt.Cursor createCustomCursor(@NotNull
                                                                    javax.swing.Icon icon,
                                                                    @NotNull
                                                                    java.awt.Color bgColor,
                                                                    @Nullable
                                                                    java.awt.Point hotspot,
                                                                    @NotNull
                                                                    java.lang.String name,
                                                                    @NotNull
                                                                    java.awt.Cursor fallback)

      Try to create a custom cursor from an icon.
      Parameters:
        `icon` - icon from which to create the cursor
        `bgColor` - background color for cursor
        `hotspot` - hot spot of cursor (if `null` the center of the icon is taken)
        `name` - name for accessibility
        `fallback` - fallback cursor taken if the image size is not supported
      Returns:
        the new cursor if it was possible to create one with the required size, or the fallback cursor

    - #### getFontMetrics

          public static java.awt.FontMetrics getFontMetrics(@NotNull
                                                            java.awt.Font font)

      Get a font metrics.
      Parameters:
        `font` - font for which a metrics is requested
      Returns:
        font metrics

    - #### createPlatformImage

          @NotNull
          public static java.awt.image.BufferedImage createPlatformImage(int width,
                                                                                  int height)

      Create an opaque buffered image which is optimized for the current platform.

      Please note that it's always a good idea to call the image's `flush()` method before it is discarded.

      Parameters:
        `width` - image width
        `height` - image height
      Returns:
        image of given size, optimized for the platform

    - #### createPlatformImage

          @NotNull
          public static java.awt.image.BufferedImage createPlatformImage(int width,
                                                                                  int height,
                                                                                  int transparency)

      Create a buffered image which is optimized for the current platform.

      Please note that the transparency type usually has an impact on performance. Best is opaque, followed by bitmap, and translucent images may be a drawn a lot slower.

      Regardless of that it's always a good idea to call the image's `flush()` method before it is discarded.

      Parameters:
        `width` - image width
        `height` - image height
        `transparency` - transparency type, either `Transparency.OPAQUE`, `Transparency.BITMASK`, or `Transparency.TRANSLUCENT`
      Returns:
        image of given size, optimized for the platform

    - #### createFastImage

          @Nullable
          public static java.awt.image.BufferedImage createFastImage(int width,
                                                                               int height)

      Try to create an image on which graphics operations have high performance. This will try to create a PerfBufferedImage as is provided by the PerfGraphics library of Werner Randelshofer.

      Note that it's always a good idea to call the image's `flush()` method before it is discarded.

      Parameters:
        `width` - image width
        `height` - image height
      Returns:
        fast image or `null` if the PerfGraphics lib is not available
      See Also:
        PerfGraphics page

    - #### createFastVolatileImage

          @NotNull
          public static java.awt.image.VolatileImage createFastVolatileImage(@NotNull
                                                                                      java.awt.Component comp,
                                                                                      int width,
                                                                                      int height)

      This will create a `VolatileImage` and try to increase its acceleration priority.

      Note that it's always a good idea to call the image's `flush()` method before it is discarded.

      Parameters:
        `comp` - component from which to create image
        `width` - image width
        `height` - image height
      Returns:
        volatile image, maybe accelerated

    - #### getPhysiologicalBrightness

          public static float getPhysiologicalBrightness(@NotNull
                                                         java.awt.Color color)

      Get the brightness of a color. Humans do perceive the different color components differently in respect of their brightness, which this method tries to take care off.
      Parameters:
        `color` - color which brightness is needed
      Returns:
        brightness value between `0` (black) and `1.0` (white)

    - #### getPhysiologicalBrightness

          public static float getPhysiologicalBrightness(int red,
                                                         int green,
                                                         int blue)

      Get the physiological brightness of a RGB color. The color values are expected to be in a range from `0` to `255`, otherwise the return of this method is useless.
      Parameters:
        `red` - red color value
        `green` - green color value
        `blue` - blue color value
      Returns:
        brigtness value between `0` (black) and `1` (white)

    - #### getPhysiologicalGray

          @NotNull
          public static java.awt.Color getPhysiologicalGray(@NotNull
                                                                     java.awt.Color color)

      Get a gray with the same brightness as a given color. Humans do perceive the different color components differently in respect of their brightness, which this method tries to take care off.
      Parameters:
        `color` - color to convert to gray
      Returns:
        gray color with the same brightness as the given color

    - #### getColorBrightnessDistance

          public static float getColorBrightnessDistance(@NotNull
                                                         java.awt.Color color1,
                                                         @NotNull
                                                         java.awt.Color color2)

      Get the distance between two colors by comparing their brightness.
      Parameters:
        `color1` - first color
        `color2` - second color
      Returns:
        the distance of the colors as the absolute difference of their colors, a number between `0` (same brightness) and `1` (completely different brightness)

    - #### getSortedSystemProperties

          @NotNull
          public static java.util.List<Pair<java.lang.String>> getSortedSystemProperties()

      Get a list of system properties and their values, sorted alphabetically by property name.

      Note that in restricted environments it's possible that not all properties are accessible. In that case only some properties are returned.

      Returns:
        list of pairs with property name as first and property value as second entry

    - #### toASCII

          @NotNull
          public static java.lang.String toASCII(@NotNull
                                                          java.lang.String str)

      Get a string where all non-ASCII and non-printable characters are escaped by their Unicode escapes.
      Parameters:
        `str` - string
      Returns:
        string where all non-ASCII and non-printable characters are escaped

    - #### isNullOrEmpty

          public static boolean isNullOrEmpty(@Nullable
                                              java.lang.String str)

      Is a string `null` or empty?
      Parameters:
        `str` - string to check
      Returns:
        `true` if the string is `null` or empty
        `false` otherwise

    - #### copyImageToClipboard

          public static void copyImageToClipboard(@NotNull
                                                  java.awt.Image image)

      Copy an image to the system clipboard.
      Parameters:
        `image` - the image to copy
      Throws:
        `java.lang.IllegalStateException` - if the clipboard is currently unavailable

    - #### copyTextToClipboard

          public static void copyTextToClipboard(@NotNull
                                                 java.lang.String text)

      Copy text to the system clipboard.
      Parameters:
        `text` - the text to copy
      Throws:
        `java.lang.IllegalStateException` - if the clipboard is currently unavailable

    - #### asList

          @Deprecated
           @NotNull
           @SafeVarargs
          public static <T> java.util.List<T> asList(@NotNull
                                                                                         T... array)

      Deprecated. Use `Types.asList(Object[])` instead.
      A more effective implementation of `Arrays.asList()`, useful if only an unmodifiable list is needed.

      Changes of the array will be reflected in the list return from this method, so the safest use is as a temporary object.

      Type Parameters:
        `T` - element type of array and list
      Parameters:
        `array` - the array to wrap into a list view
      Returns:
        unmodifiable list accessing the array

    - #### asList

          @Deprecated
           @NotNull
          public static <T> java.util.List<T> asList(@NotNull
                                                                           T[] array,
                                                                           int length)

      Deprecated. Use `Types.asList(Object[], int)` instead.
      A more effective implementation of `Arrays.asList()`, useful if only an unmodifiable list is needed.

      Changes of the array will be reflected in the list returned from this method, so the safest use is as a temporary object.

      Type Parameters:
        `T` - element type of array and list
      Parameters:
        `array` - the array to wrap into a list view
        `length` - the number of elements to be used from the array
      Returns:
        unmodifiable list accessing the array

    - #### asList

          @Deprecated
           @NotNull
          public static <T> java.util.List<T> asList(@NotNull
                                                                           T[] array,
                                                                           int start,
                                                                           int length)

      Deprecated. Use `Types.asList(Object[], int, int)` instead.
      A more effective implementation of `Arrays.asList()`, useful if only an unmodifiable list is needed.

      Changes of the array will be reflected in the list returned from this method.

      Type Parameters:
        `T` - element type of array and list
      Parameters:
        `array` - the array to wrap into a list view
        `start` - index of first used element of the array
        `length` - the number of elements to be used from the array
      Returns:
        unmodifiable list accessing the array

    - #### getRootComponentImage

          @Nullable
          public static java.awt.image.BufferedImage getRootComponentImage(@NotNull
                                                                                     java.awt.Component component)

      Get a screen shot of a frame or dialog.
      Parameters:
        `component` - component in the frame or dialog
      Returns:
        screen shot image or `null` if there have been problems with the graphical setup

    - #### getBuildDate

          @Nullable
          public static java.lang.String getBuildDate(@NotNull
                                                                java.lang.Class<?> clazz)

      Get the build date of a given class. This assumes that the `Built-Date` property is set in the Manifest file of the jar which provides the class.
      Parameters:
        `clazz` - class for accessing the associated manifest
      Returns:
        built date from manifest file, or `null` if no manifest is found

    - #### getBuildDate

          @NotNull
          public static java.lang.String getBuildDate(@NotNull
                                                               java.lang.Class<?> clazz,
                                                               @NotNull
                                                               java.lang.String defaultValue)

      Get the build date of a given class. This assumes that the `Built-Date` property is set in the Manifest file of the jar which provides the class.
      Parameters:
        `clazz` - class for accessing the associated manifest
        `defaultValue` - default value returned if no manifest is found
      Returns:
        built date from manifest file, or `defaultValue` if no manifest is found

    - #### getBuildDate

          @Nullable
          public static java.lang.String getBuildDate()

      Use `getBuildDate(Class)` using this class to get a built date.
      Returns:
        built date from Manifest file, or `null` if no Manifest is found

    - #### getBuildDate

          @NotNull
          public static java.lang.String getBuildDate(@NotNull
                                                               java.lang.String defaultValue)

      Use `getBuildDate(Class)` using this class to get a built date.
      Parameters:
        `defaultValue` - default value returned if no manifest is found
      Returns:
        built date from manifest file, or `defaultValue` if no manifest is found

    - #### createOptionalZip

          @NotNull
          public static java.io.OutputStream createOptionalZip(@NotNull
                                                                        java.lang.String outPath,
                                                                        @NotNull
                                                                        java.lang.String substExt)
                                                                 throws java.io.IOException

      Create a stream which possibly points into a newly created ZIP file. This does not check for prior existence of given file, so any existing file will be overwritten.
      Parameters:
        `outPath` - Output path. If it ends with a `.zip` extension the output stream goes into a zip file with the given name.
        `substExt` - if a zip file is created, the first entry will get this extension instead of `.zip`
      Returns:
        either a stream into a zip or a simple file output stream
      Throws:
        `java.io.IOException` - on errors opening the file or creating the zip header

    - #### toHexDump

          @NotNull
          public static java.lang.String toHexDump(@NotNull
                                                            byte[] data)

      Expand a byte array into a hexduimp text structure.
      Parameters:
        `data` - byte array
      Returns:
        hex editor formatted text, needs monospace font for correct display

    - #### fromHexData

          @NotNull
          public static byte[] fromHexData(@NotNull
                                                    java.lang.String hexData)

      Convert a hex data stream to a byte array.

      This extracts hexadecimal digits from the string, converts each pair to a byte, and collects these into a byte array.

      White space is accepted, but non-hexadecimal digits will result in a NumberFormatException.

      Parameters:
        `hexData` - hexadecimal digit text
      Returns:
        byte array

    - #### openResourceViaClass

          @Nullable
          public static java.net.URL openResourceViaClass(@NotNull
                                                                    java.lang.String classResource)

      Open a resource via a class.
      Parameters:
        `classResource` - class name and resource URL string separated by a `|` character
      Returns:
        resource URL or `null` if the resource is invalid or couldn't be opened

    - #### spaces

          @NotNull
          public static java.lang.String spaces(int num)

      Get a string consisting of a given number of space characters.
      Parameters:
        `num` - number of spaces
      Returns:
        string with the given number of spaces

    - #### getRequestedParameters

          @NotNull
          public static Dict<java.lang.String,ParameterTypes> getRequestedParameters()

      Get the requested parameters. This is helpful to find out which parameters were requested during the current run so far.

      Parameters are requested using the following static methods of this class:

      - `getStringParameter(String, String)`
      - `getBooleanParameter(String, boolean)`
      - `getBooleanParameter(String, boolean, String...)`
      - `getIntParameter(String, int)`
      - `getIntParameter(String, int, int)`
      - `getLongParameter(String, long)`
      - `getLongParameter(String, long, int)`
      - `getDoubleParameter(String, double)`
      - `getFloatParameter(String, float)`
      - `getEnumParameter(String, Enum)`
      - `getColorParameter(String, Color)`
      - `getLengthParameter(String, PhysicalLength)`
      Returns:
        dictionary with parameter names as keys, and the requested parameter type as values, giving an overview of the parameters requested so far

    - #### main

          public static void main(@NotNull
                                  java.lang.String[] args)

      Print out revisions and built dates. This prints out the build date of the jar containing this class (this needs special jar creation where an attribute `Implementation-Version` is included in the Manifest) and the `release date constant of this class` and of all classes which complete names are found in the arguments.
      Parameters:
        `args` - complete class names like `de.caff.util.Utility`