001 // Copyright 2011 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry5.services.pageload;
016
017 import org.apache.tapestry5.ioc.internal.util.CollectionFactory;
018
019 import java.util.Collections;
020 import java.util.Locale;
021 import java.util.Map;
022
023 /**
024 * Encapsulates the information that is used when locating a template or message catalog associated with a component.
025 * The selector is combined with the component class name to locate the other resources. The selector defines one or
026 * more <em>axes</em> that are combined with a {@link ComponentResourceLocator} implementation to enforce a naming
027 * convention for locating resources. The primary axis is {@link Locale} (Tapestry 5.2 and earlier used a Locale
028 * instance as the selector), but Tapestry 5.3 adds support for additional axes.
029 *
030 * @since 5.3
031 */
032 public final class ComponentResourceSelector
033 {
034 public final Locale locale;
035
036 private final Map<Class, Object> axis;
037
038 public ComponentResourceSelector(Locale locale)
039 {
040 this(locale, Collections.<Class, Object>emptyMap());
041 }
042
043 private ComponentResourceSelector(Locale locale, Map<Class, Object> axis)
044 {
045 assert locale != null;
046
047 this.locale = locale;
048 this.axis = axis;
049 }
050
051 /**
052 * Returns a <em>new</em> selector with the given axis data. It is not allowed to redefine an existing axis type.
053 * Typically, the axis type is an enum type. Axis values are expected to be immutable, and to implement
054 * {@code equals()} and {@code hashCode()}.
055 *
056 * @param axisType non-blank axis key
057 * @param axisValue non-null axis value
058 * @return new selector including axis value
059 */
060 public <T> ComponentResourceSelector withAxis(Class<T> axisType, T axisValue)
061 {
062 assert axisType != null;
063 assert axisValue != null;
064
065 if (axis.containsKey(axisType))
066 throw new IllegalArgumentException(String.format("Axis type %s is already specified as %s.",
067 axisType.getName(), axis.get(axisType)));
068
069 Map<Class, Object> updated = CollectionFactory.newMap(axis);
070 updated.put(axisType, axisValue);
071
072 return new ComponentResourceSelector(locale, updated);
073 }
074
075 /**
076 * Returns a previously stored axis value, or null if no axis value of the specified type has been stored.
077 *
078 * @param <T>
079 * @param axisType
080 * @return value or null
081 */
082 public <T> T getAxis(Class<T> axisType)
083 {
084 return axisType.cast(axis.get(axisType));
085 }
086
087 /**
088 * Returns true if the object is another selector with the same locale and set of axis.
089 */
090 @Override
091 public boolean equals(Object obj)
092 {
093 if (obj == this)
094 return true;
095
096 if (!(obj instanceof ComponentResourceSelector))
097 return false;
098
099 ComponentResourceSelector other = (ComponentResourceSelector) obj;
100
101 return locale.equals(other.locale) && axis.equals(other.axis);
102 }
103
104 @Override
105 public int hashCode()
106 {
107 return 37 * locale.hashCode() + axis.hashCode();
108 }
109
110 @Override
111 public String toString()
112 {
113 return String.format("ComponentResourceSelector[%s]", toShortString());
114 }
115
116 /**
117 * Returns a string identifying the locale, and any additional axis types and values. Example,
118 * "en" or "fr com.example.Skin=RED".
119 */
120 public String toShortString()
121 {
122 StringBuilder builder = new StringBuilder();
123
124 builder.append(locale.toString());
125
126 String sep = " ";
127 for (Map.Entry<Class, Object> e : axis.entrySet())
128 {
129 builder.append(sep);
130 builder.append(e.getKey().getName());
131 builder.append("=");
132 builder.append(e.getValue().toString());
133
134 sep = ", ";
135 }
136
137 return builder.toString();
138 }
139 }