Java tutorial
/* * 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.core.util.string.interpolator.PropertyVariableInterpolator; import org.apache.wicket.resource.loader.ComponentStringResourceLoader; import org.apache.wicket.util.lang.Args; import org.apache.wicket.util.string.Strings; /** * 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 * "label.username". 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 "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. * <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} if this model is wrapped on assignment ( * {@link IComponentAssignedModel}) or 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 the * latter case 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>- This 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. Unlike the other parameters listed above this one can not be provided * as constructor parameter but rather using method {@link #setParameters(Object...)}. * </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 Bean </b> * <p> * In the next examples we will use the following class as bundle model: * <pre> * public class WeatherStation implements Serializable * { * private final String name = "Europe's main weather station"; * * private String currentStatus = "sunny"; * * private double currentTemperature = 25.7; * * private String units = "\u00B0C"; * } * </pre> * <p> * <b>Example 1 </b> * <p> * In its simplest form, the model can be used as follows: * * <pre> * public class MyPage extends WebPage<Void> * { * public MyPage(final PageParameters parameters) * { * add(new Label("username", new StringResourceModel("label.username", this))); * } * } * </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 class MyPage extends WebPage<Void> * { * public MyPage(final PageParameters parameters) * { * WeatherStation ws = new WeatherStation(); * add(new Label("weatherMessage", * new StringResourceModel("weather.${currentStatus}", this, new Model<WeatherStation>(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 class MyPage extends WebPage<Void> * { * public MyPage(final PageParameters parameters) * { * WeatherStation ws = new WeatherStation(); * add(new Label("weatherMessage", * new StringResourceModel("weather.message", this, new Model<WeatherStation>(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 class MyPage extends WebPage<Void> * { * public MyPage(final PageParameters parameters) * { * WeatherStation ws = new WeatherStation(); * IModel<WeatherStation> model = new Model<WeatherStation>(ws); * add(new Label("weatherMessage", * new StringResourceModel("weather.detail", this) * .setParameters( * new Date(), * new PropertyModel<?>(model, "currentStatus"), * new PropertyModel<?>(model, "currentTemperature"), * new PropertyModel<?>(model, "units") * ) * })); * } * } * </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> * * @see ComponentStringResourceLoader for additional information especially on the component search * order * * @author Chris Turner */ public class StringResourceModel extends LoadableDetachableModel<String> implements IComponentAssignedModel<String> { private static final long serialVersionUID = 1L; /** The key of message to get. */ private final String resourceKey; /** The relative component used for lookups. */ private final Component component; /** The wrapped model. */ private IModel<?> model; /** Optional parameters. */ private Object[] parameters; /** The default value of the message. */ private IModel<String> defaultValue; @Override public IWrapModel<String> wrapOnAssignment(Component component) { return new AssignmentWrapper(component); } private class AssignmentWrapper extends LoadableDetachableModel<String> implements IWrapModel<String> { private static final long serialVersionUID = 1L; private final Component component; /** * Construct. * * @param component */ public AssignmentWrapper(Component component) { this.component = component; } @Override public void detach() { super.detach(); StringResourceModel.this.detach(); } @Override protected void onDetach() { if (StringResourceModel.this.component == null) { StringResourceModel.this.onDetach(); } } @Override protected String load() { if (StringResourceModel.this.component != null) { // ignore assignment if component was specified explicitly return StringResourceModel.this.getObject(); } else { return getString(component); } } @Override public void setObject(String object) { StringResourceModel.this.setObject(object); } @Override public IModel<String> getWrappedModel() { return StringResourceModel.this; } } /** * Creates a new string resource model using the supplied parameters. * <p> * The relative component parameter should generally be supplied, as without it resources can * not be obtained from resource 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. * * @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 */ public StringResourceModel(final String resourceKey, final Component component, final IModel<?> model) { Args.notNull(resourceKey, "resource key"); this.resourceKey = resourceKey; this.component = component; this.model = model; } /** * Creates a new string resource model using the supplied parameters. * <p> * The relative component parameter should generally be supplied, as without it resources can * not be obtained from resource 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. * * @param resourceKey * The resource key for this string resource * @param component * The component that the resource is relative to */ public StringResourceModel(final String resourceKey, final Component component) { this(resourceKey, component, null); } /** * Creates a new string resource model using the supplied parameter. * * @param resourceKey * The resource key for this string resource * @param model * The model to use for property substitutions */ public StringResourceModel(final String resourceKey, final IModel<?> model) { this(resourceKey, null, model); } /** * Creates a new string resource model using the supplied parameter. * * @param resourceKey * The resource key for this string resource */ public StringResourceModel(final String resourceKey) { this(resourceKey, null, null); } /** * Sets the default value if the resource key is not found. * * @param defaultValue * The default value if the resource key is not found. * @return this for chaining */ public StringResourceModel setDefaultValue(final IModel<String> defaultValue) { this.defaultValue = defaultValue; return this; } /** * Sets the default value if the resource key is not found. * * @param defaultValue * The default value as string if the resource key is not found. * @return this for chaining */ public StringResourceModel setDefaultValue(final String defaultValue) { return setDefaultValue(Model.of(defaultValue)); } /** * Sets the model used for property substitutions. * * @param model * The model to use for property substitutions * @return this for chaining */ public StringResourceModel setModel(final IModel<?> model) { this.model = model; return this; } /** * Sets the parameters used for substitution. * * @param parameters * The parameters to substitute using a Java MessageFormat object * @return this for chaining */ public StringResourceModel setParameters(Object... parameters) { this.parameters = parameters; return this; } /** * Gets the localizer that is being used by this string resource model. * * @return The localizer */ public Localizer getLocalizer() { return Application.get().getResourceSettings().getLocalizer(); } /** * Gets the string currently represented by this 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. * * @return The string */ public final String getString() { return getString(component); } protected String getString(final Component component) { final Localizer localizer = getLocalizer(); String value; // Substitute any parameters if necessary Object[] parameters = getParameters(); if (parameters == null || parameters.length == 0) { // Get the string resource, doing any property substitutions as part // of the get operation value = localizer.getString(getResourceKey(), component, model, null, null, defaultValue); } else { // Get the string resource, doing not any property substitutions // that has to be done later after MessageFormat value = localizer.getString(getResourceKey(), component, null, null, null, defaultValue); if (value != null) { // Build the real parameters Object[] realParams = new Object[parameters.length]; for (int i = 0; i < parameters.length; i++) { if (parameters[i] instanceof IModel<?>) { realParams[i] = ((IModel<?>) parameters[i]).getObject(); } else if (model != null && parameters[i] instanceof String) { realParams[i] = localizer.substitutePropertyExpressions(component, (String) parameters[i], model); } else { realParams[i] = parameters[i]; } } // Escape all single quotes outside {..} if (value.indexOf('\'') != -1) { value = escapeQuotes(value); } if (model != null) { // First escape all substitute properties so that message format doesn't try to // parse that. value = Strings.replaceAll(value, "${", "$'{'").toString(); } // Apply the parameters final MessageFormat format = new MessageFormat(value, getLocale()); value = format.format(realParams); if (model != null) { // un escape the substitute properties value = Strings.replaceAll(value, "$'{'", "${").toString(); // now substitute the properties value = localizer.substitutePropertyExpressions(component, value, model); } } } // Return the string resource return value; } /** * @return The locale to use when formatting the resource value */ protected Locale getLocale() { final Locale locale; if (component != null) { locale = component.getLocale(); } else { locale = Session.exists() ? Session.get().getLocale() : Locale.getDefault(); } return locale; } /** * Replace "'" with "''" outside of "{..}" * * @param value * @return escaped message format */ private String escapeQuotes(final String value) { StringBuilder newValue = new StringBuilder(value.length() + 10); int count = 0; for (int i = 0; i < value.length(); i++) { char ch = value.charAt(i); if (ch == '{') { count += 1; } else if (ch == '}') { count -= 1; } newValue.append(ch); if ((ch == '\'') && (count == 0)) { // Escape "'" newValue.append(ch); } } return newValue.toString(); } /** * This method just returns debug information, so it won't return the localized string. Please * use getString() for that. * * @return The string for this model object */ @Override public String toString() { StringBuilder sb = new StringBuilder("StringResourceModel["); sb.append("key:"); sb.append(resourceKey); sb.append(",default:"); sb.append(defaultValue); sb.append(",params:"); if (parameters != null) { sb.append(Arrays.asList(parameters)); } sb.append(']'); return sb.toString(); } /** * Gets the Java MessageFormat substitution parameters. * * @return The substitution parameters */ protected Object[] getParameters() { return parameters; } /** * Gets the resource key for this string resource. If the resource key contains property * expressions and the model is not null then the returned value is the actual resource key with * all substitutions undertaken. * * @return The (possibly substituted) resource key */ protected final String getResourceKey() { if (model != null) { return new PropertyVariableInterpolator(resourceKey, model.getObject()) { protected String getValue(String variableName) { String result = super.getValue(variableName); // WICKET-5820 interpolate null with 'null' return result == null ? "null" : result; }; }.toString(); } else { return resourceKey; } } /** * Gets the string that this string resource model currently represents. * <p> * Note: This method is used only if this model is used directly without assignment to a * component, it is not called by the assignment wrapper returned from * {@link #wrapOnAssignment(Component)}. */ @Override protected final String load() { return getString(); } @Override public final void detach() { super.detach(); // detach any model if (model != null) { model.detach(); } // some parameters can be detachable if (parameters != null) { for (Object parameter : parameters) { if (parameter instanceof IDetachable) { ((IDetachable) parameter).detach(); } } } if (defaultValue != null) { defaultValue.detach(); } } @Override public void setObject(String object) { throw new UnsupportedOperationException(); } }