001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.widgets.dataview;
029
030import java.util.Collections;
031import java.util.Iterator;
032import java.util.LinkedHashMap;
033import java.util.Map;
034
035import com.google.common.base.Objects;
036
037/**
038 * Represents a filter to narrow down the list of displayed results.<p>
039 *
040 * A filter has a unique id, a set of options (consisting of a map whose keys are internal identifiers of the
041 * options and whose values are the texts to display to the user), a current value and a 'nice name' to display
042 * as caption for the filter.
043 *
044 * Filter options don't by default have a "null" (=neutral, i.e. filter is not applied) option; if you need this,
045 * add a corresponding option in your implementation of I_CmsDataView.
046 */
047public class CmsDataViewFilter {
048
049    /** The filter id. */
050    private String m_id;
051
052    /** The ordered map of filter options. */
053    private LinkedHashMap<String, String> m_options;
054
055    /** The current filter options. */
056    private String m_value;
057
058    /** The user-readable name for the filter. */
059    private String m_niceName;
060
061    /** The help text for the filter. */
062    private String m_helpText;
063
064    /**
065     * Creates a new filter.<p>
066     *
067     * @param id the filter id
068     * @param niceName the nice name
069     * @param helpText the help text for the filter
070     * @param options the ordered map of options
071     * @param value the current value
072     */
073    public CmsDataViewFilter(
074        String id,
075        String niceName,
076        String helpText,
077        LinkedHashMap<String, String> options,
078        String value) {
079        m_options = new LinkedHashMap<String, String>(options);
080        m_id = id;
081        m_niceName = niceName;
082        m_value = value;
083        m_helpText = helpText;
084        if (!m_options.containsKey(value)) {
085            throw new IllegalArgumentException("Option value " + value + " not found in " + options);
086        }
087    }
088
089    /**
090     * Creates a copy of the filter.<p>
091     *
092     * @return the copied filter
093     */
094    public CmsDataViewFilter copy() {
095
096        return new CmsDataViewFilter(m_id, m_niceName, m_helpText, m_options, m_value);
097    }
098
099    /**
100     * Creates a copy of the filter, but uses a different filter value for the copy.<p>
101     *
102     * @param value the filter value for the copy
103     * @return the copied filter
104     */
105    public CmsDataViewFilter copyWithValue(String value) {
106
107        return new CmsDataViewFilter(m_id, m_niceName, m_helpText, m_options, value);
108    }
109
110    /**
111    * @see java.lang.Object#equals(java.lang.Object)
112    */
113    @Override
114    public boolean equals(Object other) {
115
116        if (!(other instanceof CmsDataViewFilter)) {
117            return false;
118        }
119        CmsDataViewFilter otherFilter = (CmsDataViewFilter)other;
120        LinkedHashMap<String, String> otherOptions = otherFilter.m_options;
121        if (!m_id.equals(otherFilter.m_id)) {
122            return false;
123        }
124        if (!m_value.equals(otherFilter.m_value)) {
125            return false;
126        }
127        if (otherOptions.size() != m_options.size()) {
128            return false;
129        }
130        Iterator<Map.Entry<String, String>> iter1, iter2;
131        iter1 = m_options.entrySet().iterator();
132        iter2 = otherOptions.entrySet().iterator();
133        while (iter1.hasNext()) {
134            Map.Entry<String, String> entry1 = iter1.next();
135            Map.Entry<String, String> entry2 = iter2.next();
136            boolean equalKey = Objects.equal(entry1.getKey(), entry2.getKey());
137            boolean equalValue = Objects.equal(entry1.getValue(), entry2.getValue());
138            if (!equalKey || !equalValue) {
139                return false;
140            }
141        }
142        return true;
143    }
144
145    /**
146     * Gets the help text for the filter.<p>
147     *
148     * @return the help text for the filter
149     */
150    public String getHelpText() {
151
152        return m_helpText;
153    }
154
155    /**
156     * Gets the id of the filter.<p>
157     *
158     * @return the id of the filter
159     */
160    public String getId() {
161
162        return m_id;
163    }
164
165    /**
166     * Gets the user-readable name of the filter.<p>
167     *
168     * @return the user-readable name
169     */
170    public String getNiceName() {
171
172        return m_niceName;
173    }
174
175    /**
176     * The map of filter options.<p>
177     *
178     * Internally, this is stored as a LinkedHashMap, so the order of options is preserved.
179     *
180     * The keys of the map are internal identifiers for the options, while the values are the texts displayed in the GUI for the options.
181     *
182     * @return the map of filter options
183     */
184    public Map<String, String> getOptions() {
185
186        return Collections.unmodifiableMap(m_options);
187    }
188
189    /**
190     * Gets the current value.<p>
191     *
192     * @return the filter value
193     */
194    public String getValue() {
195
196        return m_value;
197    }
198
199    /**
200     * @see java.lang.Object#hashCode()
201     */
202    @Override
203    public int hashCode() {
204
205        return (31 * m_id.hashCode()) + (31 * 31 * m_options.hashCode()) + m_value.hashCode();
206    }
207}