Package org.zkoss.util.resource

## Class Labels

- java.lang.Object
- - org.zkoss.util.resource.Labels

-     public class Labels
      extends java.lang.Object

  Utilities to access labels. A label is a Locale-dependent string that is stored in a Locale-dependent file (*.properties).

  Specify the library property of `org.zkoss.util.resource.LabelLoader.class` in zk.xml to provide a customized label loader for debugging purpose. (since 7.0.1)

  Author:
    tomyeh

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.String` | `getLabel​(java.lang.String key)` | Returns the label of the specified key based on the current Locale, or null if no found.
    `static java.lang.String` | `getLabel​(java.lang.String key, java.lang.Object[] args)` | Returns the label of the specified key and formats it with the specified argument, or null if not found.
    `static java.lang.String` | `getLabel​(java.lang.String key, java.lang.String defValue)` | Returns the label of the specified key based on the current Locale, or the default value if no found.
    `static java.lang.String` | `getLabel​(java.lang.String key, java.lang.String defValue, java.lang.Object[] args)` | Returns the label of the specified key and formats it with the specified argument, or the default value if not found.
    `static java.lang.String` | `getRequiredLabel​(java.lang.String key)` | Returns the label of the specified key based on the current locale.
    `static java.lang.String` | `getRequiredLabel​(java.lang.String key, java.lang.Object[] args)` | Returns the label of the specified key and formats it with the specified argument, or null if not found.
    `static java.util.Map<java.lang.String,​java.lang.Object>` | `getSegmentedLabels()` | Returns the label or a map of labels associated with the key.
    `static void` | `register​(LabelLocator locator)` | Registers a locator which is used to load the Locale-dependent labels from other resource, such as servlet contexts.
    `static void` | `register​(LabelLocator2 locator)` | Registers a locator which is used to load the Locale-dependent labels from other resource, such as database.
    `static void` | `reset()` | Resets all cached labels and next call to `getLabel(String)` will cause re-loading the Locale dependent files.
    `static VariableResolver` | `setVariableResolver​(VariableResolver resolv)` | Sets the variable resolver, which is used if an EL expression is specified.

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

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

- - ### Method Detail

    - #### getLabel

          public static final java.lang.String getLabel​(java.lang.String key)

      Returns the label of the specified key based on the current Locale, or null if no found.

      The current locale is given by `Locales.getCurrent()`.

      See Also:
        `getSegmentedLabels()`

    - #### getLabel

          public static final java.lang.String getLabel​(java.lang.String key,
                                                        java.lang.Object[] args)

      Returns the label of the specified key and formats it with the specified argument, or null if not found.

      It first uses `getLabel(String)` to load the label. Then, it, if not null, invokes `MessageFormats.format(java.lang.String, java.lang.Object[], java.util.Locale)` to format it.

      The current locale is given by `Locales.getCurrent()`.

      Since:
        3.0.6

    - #### getLabel

          public static final java.lang.String getLabel​(java.lang.String key,
                                                        java.lang.String defValue)

      Returns the label of the specified key based on the current Locale, or the default value if no found.

      The current locale is given by `Locales.getCurrent()`.

      Parameters:
        `defValue` - the value being returned if the key is not found
      Since:
        3.6.0

    - #### getLabel

          public static final java.lang.String getLabel​(java.lang.String key,
                                                        java.lang.String defValue,
                                                        java.lang.Object[] args)

      Returns the label of the specified key and formats it with the specified argument, or the default value if not found.

      It first uses `getLabel(String, String)` to load the label. Then, it, if not null, invokes `MessageFormats.format(java.lang.String, java.lang.Object[], java.util.Locale)` to format it.

      The current locale is given by `Locales.getCurrent()`.

      Parameters:
        `defValue` - the value being returned if the key is not found
      Since:
        3.6.0

    - #### getSegmentedLabels

          public static final java.util.Map<java.lang.String,​java.lang.Object> getSegmentedLabels()

      Returns the label or a map of labels associated with the key. Unlike `getLabel(java.lang.String)`, if a key of the label contains dot, it will be split into multiple keys and then grouped into map. For example, the following property file will parsed into a couple of maps, and `getSegmentedLabels()` returns a map containing a single entry. The entry's key is `"a"` and the value is another map with two entries `"b"` and `"c"`. And, the value for `"b"` is another two-entries map (containing `"c"` and `"d"`).

           a.b.c=1
           a.b.d=2
           a.e=3

      This method is designed to make labels easier to be accessed in EL expressions.

      On the other hand, `getLabel(java.lang.String)` does not split them, and you could access them by, say, `getLabel("a.b.d")`.

      Since:
        5.0.7

    - #### getRequiredLabel

          public static final java.lang.String getRequiredLabel​(java.lang.String key)
                                                         throws SystemException

      Returns the label of the specified key based on the current locale. Unlike `getLabel(String)`, it throws an exception if not found.
      Throws:
        `SystemException` - if no such label
      Since:
        3.0.6

    - #### getRequiredLabel

          public static final java.lang.String getRequiredLabel​(java.lang.String key,
                                                                java.lang.Object[] args)

      Returns the label of the specified key and formats it with the specified argument, or null if not found. Unlike `getLabel(String, Object[])`, it throws an exception if not found.

      The current locale is given by `Locales.getCurrent()`.

      Throws:
        `SystemException` - if no such label
      Since:
        3.0.6

    - #### reset

          public static final void reset()

      Resets all cached labels and next call to `getLabel(String)` will cause re-loading the Locale dependent files.

    - #### setVariableResolver

          public static final VariableResolver setVariableResolver​(VariableResolver resolv)

      Sets the variable resolver, which is used if an EL expression is specified.

      Default: no resolver at all.

      Returns:
        the previous resolver, or null if no resolver.

    - #### register

          public static final void register​(LabelLocator locator)

      Registers a locator which is used to load the Locale-dependent labels from other resource, such as servlet contexts.

    - #### register

          public static final void register​(LabelLocator2 locator)

      Registers a locator which is used to load the Locale-dependent labels from other resource, such as database.
      Since:
        5.0.5