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
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:
Number
,Date
,CodeList
andInternationalString
instances are localized using the currentResourceBundle
locale.- Long
CharSequence
instances are shortened byCharSequences.shortSentence(CharSequence, int)
. Class
andThrowable
instances are summarized.
Thread safety
The sameIndexedResourceBundle
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
The keys as an enumeration.Nested classes/interfaces inherited from class java.util.ResourceBundle
ResourceBundle.Control
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) static final int
First valid key index.private AutoMessageFormat
The object to use for formatting messages.private short
The key of the last resource requested.static final String
Key used in properties map for localizing some aspects of the operation being executed.private static final int
Maximum string length for text inserted into another text.private URL
The path of the binary file containing resources, ornull
if there are no resources or if the resources have already been loaded.private String[]
The array of resources.Fields inherited from class java.util.ResourceBundle
parent
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
IndexedResourceBundle
(URL resources) Constructs a new resource bundle loading data from the given UTF file. -
Method Summary
Modifier and TypeMethodDescriptionfinal void
appendLabel
(short key, Appendable toAppendTo) Writes the localized string identified by the given key followed by a colon.private String
colon()
Returns the colon to write after localized text.private String[]
ensureLoaded
(String key) Ensures that resource values are loaded.protected static <T extends IndexedResourceBundle>
TReturns a resource bundle of the specified class.protected KeyConstants
Returns a handler for the constants declared in the innerKeys
class.final Enumeration
<String> getKeys()
Returns an enumeration of the keys.final String
getLabel
(short key) Returns the localized string identified by the given key followed by a colon.protected static Locale
Returns the locale specified in the given map, ornull
if none.final LogRecord
getLogRecord
(Level level, short key) Gets a localized log record.final LogRecord
getLogRecord
(Level level, short key, Object arg0) Gets a localized log record.final LogRecord
getLogRecord
(Level level, short key, Object arg0, Object arg1) Gets a localized log record.final LogRecord
getLogRecord
(Level level, short key, Object arg0, Object arg1, Object arg2) Gets a localized log record.final LogRecord
Gets a localized log record.private static Class
<?> getPublicType
(Class<?> c) If the given class is not public, returns the first public interface or the first public super-class.final String
getString
(short key) Gets a string for the given key from this resource bundle or one of its parents.final String
Gets a string for the given key and formats it with the specified argument.final String
Gets a string for the given key and replaces all occurrences of "{0}", "{1}", with values ofarg0
,arg1
, etc.final String
Gets a string for the given key and replaces all occurrences of "{0}", "{1}", with values ofarg0
,arg1
, etc.final String
Gets a string for the given key and replaces all occurrences of "{0}", "{1}", with values ofarg0
,arg1
, etc.final String
Gets a string for the given key and replaces all occurrences of "{0}", "{1}", with values ofarg0
,arg1
, etc.protected final Object
handleGetObject
(String key) Gets an object for the given key from this resource bundle.final void
list
(Appendable out) Lists resources to the specified stream.(package private) final Object[]
Returnsarguments
as an array, and convert some types that are not recognized byMessageFormat
.final String
Returns the given string followed by a colon.toString()
Returns a string representation of this object.Methods inherited from class java.util.ResourceBundle
clearCache, clearCache, containsKey, getBaseBundleName, getBundle, getBundle, getBundle, getBundle, getBundle, getBundle, getBundle, getBundle, getLocale, getObject, getString, getStringArray, handleKeySet, keySet, setParent
-
Field Details
-
LOCALE_KEY
Key used in properties map for localizing some aspects of the operation being executed. ThegetResources(Map<?,?>)
methods defined in some sub-classes will look for this property.- See Also:
-
MAX_STRING_LENGTH
private static final int MAX_STRING_LENGTHMaximum string length for text inserted into another text. This parameter is used bytoArray(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 FIRSTFirst 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
The path of the binary file containing resources, ornull
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
The array of resources. Keys are an array index plus 1. For example, the value for key "14" isvalues[13]
. This array will be loaded only when first needed. We should not load it at construction time, because someResourceBundle
objects will never ask for values. This is particularly the case for parent resources ofResources_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
The object to use for formatting messages. This object will be constructed only when first needed. -
lastKey
private transient short lastKeyThe key of the last resource requested. If the same resource is requested multiple times, knowing its key allows us to avoid invoking the costlyMessageFormat.applyPattern(java.lang.String)
method.
-
-
Constructor Details
-
IndexedResourceBundle
Constructs a new resource bundle loading data from the given UTF file.- Parameters:
resources
- the path of the binary file containing resources, ornull
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, ornull
for the default locale.- Returns:
- resources in the given locale.
- Throws:
MissingResourceException
- if resources cannot be found.- See Also:
-
getKeyConstants
Returns a handler for the constants declared in the innerKeys
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
Returns an enumeration of the keys.- Specified by:
getKeys
in classResourceBundle
- Returns:
- all keys in this resource bundle.
-
list
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
Ensures that resource values are loaded. If they are not, loads them immediately.- Parameters:
key
- key for the requested resource, ornull
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
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 classResourceBundle
- Parameters:
key
- the key for the desired object- Returns:
- the object for the given key, or null
- Throws:
NullPointerException
- ifkey
isnull
-
toArray
Returnsarguments
as an array, and convert some types that are not recognized byMessageFormat
. Ifarguments
is already an array, then that array or a copy of that array will be returned. Ifarguments
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
orClass
instances. AllInternationalString
instances will be localized according this resource bundle locale. Any characters sequences of length greater thanMAX_STRING_LENGTH
will be shortened using theCharSequences.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
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
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 withStringBuilder
argument and withoutIOException
clause because it is not needed by Apache SIS in practice. We found that codes invoking this method with aStringBuilder
happen in contexts where anIOException
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
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
Returns the localized string identified by the given key followed by a colon. This is the same functionality asappendLabel(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
Returns the colon to write after localized text. -
getString
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
Gets a string for the given key and formats it with the specified argument. The message is formatted usingMessageFormat
. Calling this method is approximately equivalent to calling: Ifarg0
is not already an array, it will be placed into an array of length 1. UsingMessageFormat
, all occurrences of "{0}", "{1}", "{2}" in the resource string will be replaced byarg0[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
Gets a string for the given key and replaces all occurrences of "{0}", "{1}", with values ofarg0
,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 ofarg0
,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 ofarg0
,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 ofarg0
,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
Gets a localized log record.- Parameters:
level
- the log record level.key
- the resource key.- Returns:
- the log record.
-
getLogRecord
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
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
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
Returns the locale specified in the given map, ornull
if none. Value of unexpected type are ignored.- Parameters:
properties
- the map of properties, ornull
if none.- Returns:
- the locale found in the given map, or
null
if none. - Since:
- 0.8
-
toString
Returns a string representation of this object. This method is for debugging purposes only.
-