    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 java.util.Collections;
    018import java.util.Locale;
    019import java.util.Map;
    020
    021import org.apache.tapestry5.commons.util.CollectionFactory;
    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}