    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    }