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
015package org.apache.tapestry5.services.pageload;
016
017import org.apache.tapestry5.ioc.internal.util.CollectionFactory;
018
019import java.util.Collections;
020import java.util.Locale;
021import 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 */
032public 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}