stringresourcemodel.java

Wicket一个开发Java Web应用程序框架。它使得开发web应用程序变得容易而轻松。 Wicket利用一个POJO data beans组件使得它可以与任何持久层技术相结合。

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.wicket.model;

import java.text.MessageFormat;
import java.util.Arrays;
import java.util.Locale;

import org.apache.wicket.Application;
import org.apache.wicket.Component;
import org.apache.wicket.Localizer;
import org.apache.wicket.Session;
import org.apache.wicket.WicketRuntimeException;
import org.apache.wicket.util.string.Strings;
import org.apache.wicket.util.string.interpolator.PropertyVariableInterpolator;


/**
 * This model class encapsulates the full power of localization support within the Wicket framework.
 * It combines the flexible Wicket resource loading mechanism with property expressions, property
 * models and standard Java <code>MessageFormat</code> substitutions. This combination should be
 * able to solve any dynamic localization requirement that a project has.
 * <p>
 * The model should be created with four parameters, which are described in detail below:
 * <ul>
 * <li><b>resourceKey </b>- This is the most important parameter as it contains the key that should
 * be used to obtain resources from any string resource loaders. This parameter is mandatory: a null
 * value will throw an exception. Typically it will contain an ordinary string such as
 * &quot;label.username&quot;. To add extra power to the key functionality the key may also contain
 * a property 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 &quot;product.${product.id}&quot; 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.
 * <li><b>component </b>- 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
 * {@link org.apache.wicket.resource.loader.ComponentStringResourceLoader}. The relative component
 * may actually be <code>null</code> 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.
 * <li><b>model </b>- This parameter is mandatory if either the resourceKey, the found string
 * resource (see below) or any of the substitution parameters (see below) contain property
 * expressions. Where property expressions are present they will all be evaluated relative to this
 * model object. If there are no property expressions present then this model parameter may be
 * <code>null</code>
 * <li><b>parameters </b>- The parameters parameter allows an array of objects to be passed for
 * substitution on the found string resource (see below) using a standard
 * <code>java.text.MessageFormat</code> object. Each parameter may be an ordinary Object, in which
 * case it will be processed by the standard formatting rules associated with
 * <code>java.text.MessageFormat</code>. Alternatively, the parameter may be an instance of
 * <code>IModel</code> in which case the <code>getObject()</code> method will be applied prior
 * to the parameter being passed to the <code>java.text.MessageFormat</code>. This allows such
 * features dynamic parameters that are obtained using a <code>PropertyModel</code> object or even
 * nested string resource models.
 * </ul>
 * As well as the supplied parameters, the found string resource can contain formatting information.
 * It may contain property 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
 * <code>java.text.MessageFormat</code> style markup for replacement of parameters. Where a string
 * resource contains both types of formatting information then the property expression will be
 * applied first.
 * <p>
 * <b>Example 1 </b>
 * <p>
 * In its simplest form, the model can be used as follows:
 * 
 * <pre>
 * public MyPage extends WebPage
 * {
 *    public MyPage(final PageParameters parameters)
 *    {
 *        add(new Label(&quot;username&quot;, new StringResourceModel(&quot;label.username&quot;, this, null)));
 *    }
 * }
 * </pre>
 * 
 * Where the resource bundle for the page contains the entry <code>label.username=Username</code>
 * <p>
 * <b>Example 2 </b>
 * <p>
 * In this example, the resource key is selected based on the evaluation of a property expression:
 * 
 * <pre>
 * public MyPage extends WebPage
 * {
 *     public MyPage(final PageParameters parameters)
 *     {
 *         WeatherStation ws = new WeatherStation();
 *         add(new Label(&quot;weatherMessage&quot;,
 *             new StringResourceModel(&quot;weather.${currentStatus}&quot;, this, new Model(ws)));
 *     }
 * }
 * </pre>
 * 
 * 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:
 * 
 * <pre>
 * weather.sunny=Don't forget sunscreen!
 * weather.raining=You might need an umbrella
 * weather.snowing=Got your skis?
 * weather.overcast=Best take a coat to be safe
 * </pre>
 * 
 * <p>
 * <b>Example 3 </b>
 * <p>
 * In this example the found resource string contains a property expression that is substituted via
 * the model:
 * 
 * <pre>
 * public MyPage extends WebPage
 * {
 *     public MyPage(final PageParameters parameters)
 *     {
 *         WeatherStation ws = new WeatherStation();
 *         add(new Label(&quot;weatherMessage&quot;,
 *             new StringResourceModel(&quot;weather.message&quot;, this, new Model(ws)));
 *     }
 * }
 * </pre>
 * 
 * Where the resource bundle contains the entry <code>weather.message=Weather station reports that
 * the temperature is ${currentTemperature} ${units}</code>
 * <p>
 * <b>Example 4 </b>
 * <p>
 * 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:
 * 
 * <pre>
 * public MyPage extends WebPage
 * {
 *     public MyPage(final PageParameters parameters)
 *     {
 *         WeatherStation ws = new WeatherStation();
 *         Model model = new Model(ws);
 *         add(new Label(&quot;weatherMessage&quot;,
 *             new StringResourceModel(
 *                 &quot;weather.detail&quot;, this, model,
 *                     new Object[]
 *                     {
 *                         new Date(),
 *                         new PropertyModel(model, &quot;currentStatus&quot;),
 *                         new PropertyModel(model, &quot;currentTemperature&quot;),
 *                         new PropertyModel(model, &quot;units&quot;)
 *         }));
 *     }
 * }
 * </pre>
 * 
 * And where the resource bundle entry is:
 * 
 * <pre>
 * weather.detail=The report for {0,date}, shows the temperature as {2,number,###.##} {3} \
 *     and the weather to be {1}
 * </pre>
 * 
 * @author Chris Turner
 */
public class StringResourceModel extends LoadableDetachableModel
{
	private static final long serialVersionUID = 1L;

	/** The locale to use. */
	private transient Locale locale;

	/**
	 * The localizer to be used to access localized resources and the associated locale for
	 * formatting.
	 */
	private transient Localizer localizer;

	/** The wrapped model. */
	private final IModel model;

	/** Optional parameters. */
	private final Object[] parameters;

	/** The relative component used for lookups. */
	private final Component component;

	/** The key of message to get. */
	private final String resourceKey;

	/** The default value of the message. */
	private final String defaultValue;

	/**
	 * Construct.
	 * 
	 * @param resourceKey
	 *            The resource key for this string resource
	 * @param component
	 *            The component that the resource is relative to
	 * @param model
	 *            The model to use for property substitutions
	 * @see #StringResourceModel(String, Component, IModel, Object[])
	 */
	public StringResourceModel(final String resourceKey, final Component component,
		final IModel model)
	{
		this(resourceKey, component, model, null, null);
	}

	/**
	 * Construct.
	 * 
	 * @param resourceKey
	 *            The resource key for this string resource
	 * @param component
	 *            The component that the resource is relative to
	 * @param model
	 *            The model to use for property substitutions
	 * @param defaultValue
	 *            The default value if the resource key is not found.
	 * 
	 * @see #StringResourceModel(String, Component, IModel, Object[])
	 */
	public StringResourceModel(final String resourceKey, final Component component,
		final IModel model, final String defaultValue)
	{
		this(resourceKey, component, model, null, defaultValue);
	}

	/**
	 * Creates a new string resource model using the supplied parameters.