wicket.model
Class StringResourceModel

java.lang.Object
  wicket.model.AbstractDetachableModel
      wicket.model.AbstractReadOnlyDetachableModel
          wicket.model.StringResourceModel

All Implemented Interfaces:

IDetachable, IModel, java.io.Serializable

public class StringResourceModel

extends AbstractReadOnlyDetachableModel

This model class encapsulates the full power of localization support within the Wicket framework. It combines the flexible Wicket resource loading mechanism with OGNL expressions, property models and standard Java MessageFormat substitutions. This combination should be able to solve any dynamic localization requirement that a project has.

The model should be created with four parameters, which are described in detail below:

• resourceKey - This is the most important parameter as it contains the key that should be used to obtain resources from any string resource loaders. This paramater is mandatory: a null value will throw an exception. Typically it will contain an ordinary string such as "label.username". To add extra power to the key functionality the key may also contain an OGNL expression which will be evaluated if the model parameter (see below) is not null. This allows keys to be changed dynamically as the application is running. For example, the key could be "product.${product.id}" which prior to rendering will call model.getObject().getProduct().getId() and substitute this value into the resource key before is is passed to the loader.
• component - This parameter should be a component that the string resource is relative to. In a simple application this will usually be the Page on which the component resides. For reusable components/containers that are packaged with their own string resource bundles it should be the actual component/container rather than the page. For more information on this please see ComponentStringResourceLoader. The relative component may actually be null when all resource loading is to be done from a global resource loader. However, we recommend that a relative component is still supplied even in these cases in order to 'future proof' your application with regards to changing resource loading strategies.
• model - This parameter is mandatory if either the resourceKey, the found string resource (see below) or any of the substitution parameters (see below) contain OGNL expressions. Where OGNL expressions are present they will all be evaluated relative to this model object. If there are no OGNL expressions present then this model parameter may be null
• parameters - The parameters parameter allows an array of objects to be passed for substitution on the found string resource (see below) using a standard java.text.MessageFormat object. Each parameter may be an ordinary Object, in which case it will be processed by the standard formatting rules associated with java.text.MessageFormat. Alternatively, the parameter may be an instance of IModel in which case the getObject() method will be applied prior to the parameter being passed to the java.text.MessageFormat. This allows such features dynamic parameters that are obtained using a PropertyModel object or even nested string resource models.

As well as the supplied parameters, the found string resource can contain formatting information. It may contain OGNL expressions in which case these are evaluated using the model object supplied when the string resource model is created. The string resource may also contain java.text.MessageFormat style markup for replacement of parameters. Where a string resource contains both types of formatting information then the OGNL will be applied first.

Example 1

In its simplest form, the model can be used as follows:

 
        public MyPage extends WebPage 
        {
            public MyPage(final PageParameters parameters) 
            {
                add(new Label("username", new StringResourceModel("label.username", this, null)));
            }
        }
  
 

Where the resource bundle for the page contains the entry label.username=Username

Example 2

In this example, the resource key is selected based on the evaluation of an OGNL expression:

 
        public MyPage extends WebPage 
        {
            public MyPage(final PageParameters parameters) 
            {
                WeatherStation ws = new WeatherStation();
                add(new Label("weatherMessage",
                              new StringResourceModel("weather.${currentStatus}", this, new Model(ws)));
            }
        }
  
 

Which will call the WeatherStation.getCurrentStatus() method each time the string resource model is used and where the resource bundle for the page contains the entries:

 
        weather.sunny=Don't forget sunscreen!
        weather.raining=You might need an umberella
        weather.snowing=Got your skis?
        weather.overcast=Best take a coat to be safe
  
 

Example 3

In this example the found resource string contains an OGNL expression that is substituted via the model:

 
        public MyPage extends WebPage 
        {
            public MyPage(final PageParameters parameters) 
            {
                WeatherStation ws = new WeatherStation();
                add(new Label("weatherMessage",
                              new StringResourceModel("weather.message", this, new Model(ws)));
            }
        }
  
 

Where the resource bundle contains the entry weather.message=Weather station reports that the temperature is ${currentTemperature} ${units}

Example 4

In this example, the use of substitution parameters is employed to format a quite complex message string. This is an example of the most complex and powerful use of the string resource model:

 
        public MyPage extends WebPage 
        {
            public MyPage(final PageParameters parameters) 
            {
                WeatherStation ws = new WeatherStation();
                Model model = new Model(ws);
                add(new Label("weatherMessage",
                          new StringResourceModel(
                              "weather.detail", this, model,
                              new Object[] 
                              {
                                  new Date(),
                                  new PropertyModel(model, "currentStatus"),
                                  new PropertyModel(model, "currentTemperature"),
                                  new PropertyModel(model, "units")
                              }));
            }
        }
  
 

And where the resource bundle entry is:

 
        weather.detail=The report for {0,date}, shows the temparature as {2,number,###.##} {3} \
                       and the weather to be {1}
  
 

Author:

Chris Turner

See Also:

Serialized Form

Constructor Summary

StringResourceModel(java.lang.String resourceKey, Component component, IModel model)
Construct.

StringResourceModel(java.lang.String resourceKey, Component component, IModel model, java.lang.Object[] parameters)
Creates a new string resource model using the supplied parameters.

Method Summary

Localizer	getLocalizer() Gets the localizer that is being used by this string resource model.
IModel	getNestedModel() Gets the model used for OGNL substitutions.
protected java.lang.Object[]	getParameters() Gets the Java MessageFormat substitution parameters.
protected java.lang.String	getResourceKey() Gets the resource key for this string resource.
java.lang.String	getString() Gets the string currently represented by this string resource model.
protected void	onAttach() Attaches to the given session.
protected void	onDetach() Detaches from the given session
protected java.lang.Object	onGetObject(Component component) Gets the string that this string resource model currently represents.
void	setLocalizer(Localizer localizer) Sets the localizer that is being used by this string resource model.
java.lang.String	toString() Override of the default method to return the resource string represented by this string resource model.

Methods inherited from class wicket.model.AbstractReadOnlyDetachableModel

onSetObject

Methods inherited from class wicket.model.AbstractDetachableModel

attach, detach, getObject, isAttached, setObject

Methods inherited from class java.lang.Object

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

Constructor Detail

StringResourceModel

public StringResourceModel(java.lang.String resourceKey,
                           Component component,
                           IModel model)

Construct.

Parameters:

resourceKey - The resource key for this string resource

component - The component that the resource is relative to

model - The model to use for OGNL substitutions

See Also:

StringResourceModel(String, Component, IModel, Object[])

StringResourceModel

public StringResourceModel(java.lang.String resourceKey,
                           Component component,
                           IModel model,
                           java.lang.Object[] parameters)

Creates a new string resource model using the supplied parameters.

The relative component parameter should generally be supplied, as without it resources can not be obtained from resouce bundles that are held relative to a particular component or page. However, for application that use only global resources then this parameter may be null.

The model parameter is also optional and only needs to be supplied if value substitutions are to take place on either the resource key or the actual resource strings.

The parameters parameter is also optional and is used for substitutions.

Parameters:

resourceKey - The resource key for this string resource

component - The component that the resource is relative to

model - The model to use for OGNL substitutions

parameters - The parameters to substitute using a Java MessageFormat object

Method Detail

getLocalizer

public Localizer getLocalizer()

Gets the localizer that is being used by this string resource model.

Returns:

The localizer

getNestedModel

public final IModel getNestedModel()

Gets the model used for OGNL substitutions.

Specified by:

getNestedModel in interface IModel

Specified by:

getNestedModel in class AbstractDetachableModel

Returns:

The model

See Also:

IModel.getNestedModel()

getString

public final java.lang.String getString()

Gets the string currently represented by this string resource model. The string that is returned may vary for each call to this method depending on the values contained in the model and an the parameters that were passed when this string resource model was created.

Returns:

The string

setLocalizer

public void setLocalizer(Localizer localizer)

Sets the localizer that is being used by this string resource model. This method is provided to allow the default application localizer to be overridden if required.

Parameters:

localizer - The localizer to use

toString

public java.lang.String toString()

Override of the default method to return the resource string represented by this string resource model. Useful in debugging and so on, to avoid the explicit need to call the getString() method.

Returns:

The string for this model object

getParameters

protected final java.lang.Object[] getParameters()

Gets the Java MessageFormat substitution parameters.

Returns:

The substitution parameters

getResourceKey

protected final java.lang.String getResourceKey()

Gets the resource key for this string resource. If the resource key contains OGNL and the model is null then the returned value is the actual resource key with all substitutions undertaken.

Returns:

The (possibly substituted) resource key

onAttach

protected final void onAttach()

Attaches to the given session.

Specified by:

onAttach in class AbstractDetachableModel

onDetach

protected final void onDetach()

Detaches from the given session

Specified by:

onDetach in class AbstractDetachableModel

onGetObject

protected final java.lang.Object onGetObject(Component component)

Gets the string that this string resource model currently represents. The string is returned as an object to allow it to be used generically within components.

Specified by:

onGetObject in class AbstractDetachableModel

Parameters:

component - The component asking for the object

Returns:

The object

See Also:

AbstractDetachableModel.onGetObject(Component)