Package org.apache.sis.util.resources

Class IndexedResourceBundle

java.lang.Object
java.util.ResourceBundle
org.apache.sis.util.resources.IndexedResourceBundle
All Implemented Interfaces:
Localized
Direct Known Subclasses:
Errors, Messages, Resources, Resources, Resources, Resources, Resources, Resources, Resources, Vocabulary
public class IndexedResourceBundle extends ResourceBundle implements Localized
ResourceBundle implementation accepting integers instead of strings for resource keys. Using integers allow implementations to avoid adding large string constants into their .class files and runtime images. Developers still have meaningful labels in their code (e.g. MismatchedDimension) through a set of constants defined in Keys inner classes, with the side-effect of compile-time safety. Because integer constants are inlined right into class files at compile time, the declarative classes is not loaded at run time.

Localized resources are fetched by calls to getString(short). Arguments can optionally be provided by calls to getString(short, Object, ...). If arguments are present, then the string will be formatted using MessageFormat, completed by some special cases handled by this class. Roughly speaking:

Thread safety

The same IndexedResourceBundle instance can be safely used by many threads without synchronization on the part of the caller. Subclasses should make sure that any overridden methods remain safe to call from multiple threads.
Since:
0.3
Version:
1.3

  • Field Details

    • LOCALE_KEY

      public static final String LOCALE_KEY
      Key used in properties map for localizing some aspects of the operation being executed. The getResources(Map<?,?>) methods defined in some sub-classes will look for this property.
      See Also:

    • MAX_STRING_LENGTH

      private static final int MAX_STRING_LENGTH
      Maximum string length for text inserted into another text. This parameter is used by toArray(Object). Resource strings are never cut to this length. However, text replacing "{0}" in a string like "Parameter name is {0}" will be cut to this length.
      See Also:

    • FIRST

      static final int FIRST
      First valid key index. We start at 1 rather than 0 in order to keep value 0 available for meaning "no localized message".
      Since:
      0.8
      See Also:

    • resources

      private URL resources
      The path of the binary file containing resources, or null if there are no resources or if the resources have already been loaded. The resources may be a file or an entry in a JAR file.

    • values

      private volatile String[] values
      The array of resources. Keys are an array index plus 1. For example, the value for key "14" is values[13]. This array will be loaded only when first needed. We should not load it at construction time, because some ResourceBundle objects will never ask for values. This is particularly the case for parent resources of Resources_fr_CA, Resources_en, Resources_de, etc. which will only be used if a key has not been found in the child resources.
      See Also:

    • format

      private transient AutoMessageFormat format
      The object to use for formatting messages. This object will be constructed only when first needed.

    • lastKey

      private transient short lastKey
      The key of the last resource requested. If the same resource is requested multiple times, knowing its key allows us to avoid invoking the costly MessageFormat.applyPattern(java.lang.String) method.

  • Constructor Details

    • IndexedResourceBundle

      protected IndexedResourceBundle(URL resources)
      Constructs a new resource bundle loading data from the given UTF file.
      Parameters:
      resources - the path of the binary file containing resources, or null if there are no resources. The resources may be a file or an entry in a JAR file.

  • Method Details

    • getBundle

      protected static <T extends IndexedResourceBundle> T getBundle(Class<T> base, Locale locale) throws MissingResourceException
      Returns a resource bundle of the specified class.
      Type Parameters:
      T - the resource bundle class.
      Parameters:
      base - the resource bundle class.
      locale - the locale, or null for the default locale.
      Returns:
      resources in the given locale.
      Throws:
      MissingResourceException - if resources cannot be found.
      See Also:

    • getKeyConstants

      protected KeyConstants getKeyConstants()
      Returns a handler for the constants declared in the inner Keys class. Subclasses should override this method for efficiency, but this is not mandatory.
      Returns:
      a handler for the constants declared in the inner Keys class.

    • getKeys

      public final Enumeration<String> getKeys()
      Returns an enumeration of the keys.
      Specified by:
      getKeys in class ResourceBundle
      Returns:
      all keys in this resource bundle.

    • list

      @Debug public final void list(Appendable out) throws IOException
      Lists resources to the specified stream. If a resource has more than one line, only the first line will be written. This method is used mostly for debugging purposes.
      Parameters:
      out - the destination stream.
      Throws:
      IOException - if an output operation failed.

    • ensureLoaded

      private String[] ensureLoaded(String key) throws MissingResourceException
      Ensures that resource values are loaded. If they are not, loads them immediately.
      Parameters:
      key - key for the requested resource, or null if all resources are requested. This key is used mostly for constructing messages.
      Returns:
      the resources.
      Throws:
      MissingResourceException - if this method failed to load resources.

    • handleGetObject

      protected final Object handleGetObject(String key)
      Gets an object for the given key from this resource bundle. Returns null if this resource bundle does not contain an object for the given key.
      Specified by:
      handleGetObject in class ResourceBundle
      Parameters:
      key - the key for the desired object
      Returns:
      the object for the given key, or null
      Throws:
      NullPointerException - if key is null

    • toArray

      final Object[] toArray(Object arguments)
      Returns arguments as an array, and convert some types that are not recognized by MessageFormat. If arguments is already an array, then that array or a copy of that array will be returned. If arguments is not an array, it will be placed in an array of length 1.

      All the array elements will be checked for CharSequence, InternationalString, CodeList, Throwable or Class instances. All InternationalString instances will be localized according this resource bundle locale. Any characters sequences of length greater than MAX_STRING_LENGTH will be shortened using the CharSequences.shortSentence(CharSequence, int) method.

      Note: If more cases are added, remember to update class and package javadoc.
      Parameters:
      arguments - the object to check.
      Returns:
      arguments as an array, eventually with some elements replaced.

    • getPublicType

      private static Class<?> getPublicType(Class<?> c)
      If the given class is not public, returns the first public interface or the first public super-class. This is for avoiding confusing the user with private class in message like "Value cannot be instance of XYZ".

    • appendLabel

      public final void appendLabel(short key, Appendable toAppendTo) throws IOException
      Writes the localized string identified by the given key followed by a colon. The way to write the colon depends on the language.
      API note: we do not provide a method with StringBuilder argument and without IOException clause because it is not needed by Apache SIS in practice. We found that codes invoking this method with a StringBuilder happen in contexts where an IOException is thrown elsewhere anyway.
      Parameters:
      key - the key for the desired string.
      toAppendTo - where to write the localized string followed by a colon.
      Throws:
      IOException - if an error occurred while writing to the given destination.
      Since:
      0.8

    • toLabel

      public final String toLabel(String text)
      Returns the given string followed by a colon.
      Parameters:
      text - the text to follow be a colon.
      Returns:
      the given text followed by a colon.

    • getLabel

      public final String getLabel(short key)
      Returns the localized string identified by the given key followed by a colon. This is the same functionality as appendLabel(short, Appendable) but without temporary buffer.
      Parameters:
      key - the key for the desired string.
      Returns:
      localized string followed by a colon.
      Since:
      1.1

    • colon

      private String colon()
      Returns the colon to write after localized text.

    • getString

      public final String getString(short key) throws MissingResourceException
      Gets a string for the given key from this resource bundle or one of its parents.
      Parameters:
      key - the key for the desired string.
      Returns:
      the string for the given key.
      Throws:
      MissingResourceException - if no object for the given key can be found.

    • getString

      public final String getString(short key, Object arg0) throws MissingResourceException
      Gets a string for the given key and formats it with the specified argument. The message is formatted using MessageFormat. Calling this method is approximately equivalent to calling: If arg0 is not already an array, it will be placed into an array of length 1. Using MessageFormat, all occurrences of "{0}", "{1}", "{2}" in the resource string will be replaced by arg0[0], arg0[1], arg0[2], etc.
      Parameters:
      key - the key for the desired string.
      arg0 - a single object or an array of objects to be formatted and substituted.
      Returns:
      the string for the given key.
      Throws:
      MissingResourceException - if no object for the given key can be found.
      See Also:

    • getString

      public final String getString(short key, Object arg0, Object arg1) throws MissingResourceException
      Gets a string for the given key and replaces all occurrences of "{0}", "{1}", with values of arg0, arg1, etc.
      Parameters:
      key - the key for the desired string.
      arg0 - value to substitute for "{0}".
      arg1 - value to substitute for "{1}".
      Returns:
      the formatted string for the given key.
      Throws:
      MissingResourceException - if no object for the given key can be found.

    • getString

      public final String getString(short key, Object arg0, Object arg1, Object arg2) throws MissingResourceException
      Gets a string for the given key and replaces all occurrences of "{0}", "{1}", with values of arg0, arg1, etc.
      Parameters:
      key - the key for the desired string.
      arg0 - value to substitute for "{0}".
      arg1 - value to substitute for "{1}".
      arg2 - value to substitute for "{2}".
      Returns:
      the formatted string for the given key.
      Throws:
      MissingResourceException - if no object for the given key can be found.

    • getString

      public final String getString(short key, Object arg0, Object arg1, Object arg2, Object arg3) throws MissingResourceException
      Gets a string for the given key and replaces all occurrences of "{0}", "{1}", with values of arg0, arg1, etc.
      Parameters:
      key - the key for the desired string.
      arg0 - value to substitute for "{0}".
      arg1 - value to substitute for "{1}".
      arg2 - value to substitute for "{2}".
      arg3 - value to substitute for "{3}".
      Returns:
      the formatted string for the given key.
      Throws:
      MissingResourceException - if no object for the given key can be found.

    • getString

      public final String getString(short key, Object arg0, Object arg1, Object arg2, Object arg3, Object arg4) throws MissingResourceException
      Gets a string for the given key and replaces all occurrences of "{0}", "{1}", with values of arg0, arg1, etc.
      Parameters:
      key - the key for the desired string.
      arg0 - value to substitute for "{0}".
      arg1 - value to substitute for "{1}".
      arg2 - value to substitute for "{2}".
      arg3 - value to substitute for "{3}".
      arg4 - value to substitute for "{4}".
      Returns:
      the formatted string for the given key.
      Throws:
      MissingResourceException - if no object for the given key can be found.

    • getLogRecord

      public final LogRecord getLogRecord(Level level, short key)
      Gets a localized log record.
      Parameters:
      level - the log record level.
      key - the resource key.
      Returns:
      the log record.

    • getLogRecord

      public final LogRecord getLogRecord(Level level, short key, Object arg0)
      Gets a localized log record.
      Parameters:
      level - the log record level.
      key - the resource key.
      arg0 - the parameter for the log message, which may be an array.
      Returns:
      the log record.

    • getLogRecord

      public final LogRecord getLogRecord(Level level, short key, Object arg0, Object arg1)
      Gets a localized log record.
      Parameters:
      level - the log record level.
      key - the resource key.
      arg0 - the first parameter.
      arg1 - the second parameter.
      Returns:
      the log record.

    • getLogRecord

      public final LogRecord getLogRecord(Level level, short key, Object arg0, Object arg1, Object arg2)
      Gets a localized log record.
      Parameters:
      level - the log record level.
      key - the resource key.
      arg0 - the first parameter.
      arg1 - the second parameter.
      arg2 - the third parameter.
      Returns:
      the log record.

    • getLogRecord

      public final LogRecord getLogRecord(Level level, short key, Object arg0, Object arg1, Object arg2, Object arg3)
      Gets a localized log record.
      Parameters:
      level - the log record level.
      key - the resource key.
      arg0 - the first parameter.
      arg1 - the second parameter.
      arg2 - the third parameter.
      arg3 - the fourth parameter.
      Returns:
      the log record.

    • getLocale

      protected static Locale getLocale(Map<?,?> properties)
      Returns the locale specified in the given map, or null if none. Value of unexpected type are ignored.
      Parameters:
      properties - the map of properties, or null if none.
      Returns:
      the locale found in the given map, or null if none.
      Since:
      0.8

    • toString

      public String toString()
      Returns a string representation of this object. This method is for debugging purposes only.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this resources bundle.