soc.util
Class SOCStringManager

java.lang.Object
  net.nand.util.i18n.mgr.StringManager
      soc.util.SOCStringManager

public class SOCStringManager
extends StringManager

String Manager for retrieving I18N localized text from .properties bundle files with special methods for formatting JSettlers objects.

See comments at the top of .properties files for more details on key-value formatting and message parameters. Remember that .properties bundle files are encoded not in UTF-8 but in ISO-8859-1:

• java.util.Properties (Java 1.5)
• Stack Overflow: How to use UTF-8 in resource properties with ResourceBundle (asked on 2011-01-11)

Introduced in v2.0.00; network messages sending localized text should check the receiver's version against VERSION_FOR_I18N.

Since:

2.0.00

Author:

lartkma

See Also:

I18n

Field Summary

private static SOCStringManager	clientManager Manager for all client strings.
private static java.lang.String[][]	GETSPECIAL_RSRC_KEYS Resource type-and-count text keys for getSpecial(SOCGame, String, Object...).
private static java.util.Hashtable<java.lang.String,SOCStringManager>	serverManagerForClientLocale Manager at server for strings sent to the client.
private static SOCStringManager	serverManagerForClientLocale_fallback Fallback for serverManagerForClientLocale using server's default locale.
static int	VERSION_FOR_I18N Minimum version (2.0.00) of client/server with I18N localization.

Fields inherited from class net.nand.util.i18n.mgr.StringManager

bundle

Constructor Summary

SOCStringManager(java.lang.String bundlePath)
Create a string manager for the bundles at bundlePath with the default locale.

SOCStringManager(java.lang.String bundlePath, java.util.Locale loc)
Create a string manager for the bundles at bundlePath with a certain Locale.

Method Summary

static SOCStringManager	getClientManager() Create or retrieve the cached client string manager, with the default Locale.
static SOCStringManager	getClientManager(java.util.Locale loc) Create or retrieve the cached client string manager, with a certain Locale.
static SOCStringManager	getFallbackServerManagerForClient() Create or retrieve the server's string manager for fallback to send text to clients with unknown locale.
static SOCStringManager	getServerManagerForClient(java.util.Locale loc) Create or retrieve the server's string manager to send text to a clients with a certain locale.
java.lang.String	getSOCResourceCount(int rtype, java.lang.Integer rcountObj) Get a resource count, such as "5 sheep"; used by getSpecial(SOCGame, String, Object...).
java.lang.String	getSpecial(SOCGame game, java.lang.String key, java.lang.Object... arguments) Get and format a localized string (with special SoC-specific parameters) with the given key.

Methods inherited from class net.nand.util.i18n.mgr.StringManager

get, get

Methods inherited from class java.lang.Object

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

Field Detail

VERSION_FOR_I18N

public static final int VERSION_FOR_I18N

Minimum version (2.0.00) of client/server with I18N localization. Network messages sending localized text should check the receiver's version against this constant.

See Also:

Constant Field Values

clientManager

private static SOCStringManager clientManager

Manager for all client strings. Static is okay because the client is seen by 1 person with 1 locale.

serverManagerForClientLocale

private static java.util.Hashtable<java.lang.String,SOCStringManager> serverManagerForClientLocale

Manager at server for strings sent to the client.

Key = locale.toString, value = SOCStringManager for server strings to clients in that locale. Uses Hashtable to gain synchronization.

serverManagerForClientLocale_fallback

private static SOCStringManager serverManagerForClientLocale_fallback

Fallback for serverManagerForClientLocale using server's default locale.

GETSPECIAL_RSRC_KEYS

private static final java.lang.String[][] GETSPECIAL_RSRC_KEYS

Resource type-and-count text keys for getSpecial(SOCGame, String, Object...). Each subarray's indexes are the same values as SOCResourceConstants.CLAY to SOCResourceConstants.WOOD. The string key at index 0 is used for resources out of range (unknown types).

See Also:

getSOCResourceCount(int, Integer)

Constructor Detail

SOCStringManager

public SOCStringManager(java.lang.String bundlePath)

Create a string manager for the bundles at bundlePath with the default locale. Remember that bundle files are encoded not in UTF-8 but in ISO-8859-1, see class javadoc.

Parameters:

bundlePath - Bundle path, will be retrieved with ResourceBundle.getBundle(String)

SOCStringManager

public SOCStringManager(java.lang.String bundlePath,
                        java.util.Locale loc)

Create a string manager for the bundles at bundlePath with a certain Locale. Remember that bundle files are encoded not in UTF-8 but in ISO-8859-1, see class javadoc.

Parameters:

bundlePath - Bundle path, will be retrieved with ResourceBundle.getBundle(String, Locale)

loc - Locale to use; not null

Method Detail

getSOCResourceCount

public final java.lang.String getSOCResourceCount(int rtype,
                                                  java.lang.Integer rcountObj)
                                           throws java.util.MissingResourceException

Get a resource count, such as "5 sheep"; used by getSpecial(SOCGame, String, Object...).

Parameters:

rtype - Type of resource, in the range SOCResourceConstants.CLAY to SOCResourceConstants.WOOD

rcountObj - Resource count; uses the Integer object passed into getSpecial. As a special case, -1 will localize with the indefinite article, such as "a sheep" or "an ore". -2 will localize to the plural resource name without a count, as in "clay" or "la lana".

Returns:

A localized string such as "1 wood" or "5 clay" or "a sheep", or if rtype is out of range, "3 resources of unknown type 37"

Throws:

java.util.MissingResourceException - if no string can be found for key; this is a RuntimeException

getSpecial

public java.lang.String getSpecial(SOCGame game,
                                   java.lang.String key,
                                   java.lang.Object... arguments)
                            throws java.util.MissingResourceException,
                                   java.lang.IllegalArgumentException

Get and format a localized string (with special SoC-specific parameters) with the given key.

• {0,list} for a list of items, which will be formatted as "x, y, and z" by I18n.listItems(List, SOCStringManager). Use a List in arguments.
• {0,rsrcs} for a resource name or resource set. A resource set is passed as a SOCResourceSet in arguments. Resource names ("5 sheep") take 2 argument slots: an Integer for the count, and a resource type Integer in the range SOCResourceConstants.CLAY - SOCResourceConstants.WOOD. Special case: A count of -1 will localize with "a/an", such as "a sheep" or "an ore". A count of -2 will localize to the plural resource name without a number, for uses such as "Joe monopolized clay".
• {0,dcards} for a Development Card or list of dev cards. arguments should contain a single Integer or SOCInventoryItem, or a List of them, in the range SOCDevCardConstants.MIN - SOCDevCardConstants.TOW.

  The returned format will include indefinite articles: "a Year of Plenty", "a Market (1 VP)", etc.

Parameters:

game - Game, in case its options influence the strings (such as dev card Knight -> Warship in scenario _SC_PIRI)

key - Key to use for string retrieval. Can contain {0,rsrcs} and or {0,dcards}. You can use {1, {2, or any other slot number.

arguments - Objects to go with {0,list}, {0,rsrcs}, {0,dcards}, etc in key; see above for the expected object types.

Returns:

the localized formatted string from the manager's bundle or one of its parents

Throws:

java.util.MissingResourceException - if no string can be found for key; this is a RuntimeException

java.lang.IllegalArgumentException - if the localized pattern string has a parse error (closing '}' brace without opening '{' brace, etc)

See Also:

getSOCResourceCount(int, Integer)

getClientManager

public static SOCStringManager getClientManager()

Create or retrieve the cached client string manager, with the default Locale. If the client manager already exists, further gets will return that manager with its Locale, ignoring the default locale of the new call.

Returns:

The client manager

getClientManager

public static SOCStringManager getClientManager(java.util.Locale loc)

Create or retrieve the cached client string manager, with a certain Locale. If the client manager already exists, further gets will return that manager with its Locale, ignoring the Locale of the new call.

Parameters:

loc - Locale to use; not null

Returns:

The client manager

getServerManagerForClient

public static SOCStringManager getServerManagerForClient(java.util.Locale loc)

Create or retrieve the server's string manager to send text to a clients with a certain locale.

Parameters:

loc - Locale to use, or null for the Locale.getDefault()

Returns:

The server manager for that client locale

getFallbackServerManagerForClient

public static SOCStringManager getFallbackServerManagerForClient()

Create or retrieve the server's string manager for fallback to send text to clients with unknown locale. Can be used for messages while a client hasn't yet sent their locale.

Returns:

The server string manager with default locale