001// Copyright 2004, 2005 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.tapestry.util;
016
017import java.util.Arrays;
018import java.util.HashMap;
019import java.util.Map;
020
021import org.apache.hivemind.util.Defense;
022
023/**
024 * A wrapper around a Map that stores query parameter values. Map keys are strings. Map values can
025 * be simple strings or array of string (or null).
026 * 
027 * @author Howard M. Lewis Ship
028 * @since 4.0
029 */
030public class QueryParameterMap
031{
032    private final Map _parameters;
033
034    public QueryParameterMap()
035    {
036        this(new HashMap());
037    }
038
039    /**
040     * Constructor around an existing Map whose keys and values are expected to conform expected use
041     * (keys are strings, values are null, string or string array). The map passed in is retained (
042     * not copied).
043     */
044
045    public QueryParameterMap(Map parameterMap)
046    {
047        Defense.notNull(parameterMap, "parameterMap");
048
049        _parameters = parameterMap;
050    }
051
052    /**
053     * Replaces the parameter value for the given name wit the new value (which may be null).
054     */
055
056    public void setParameterValue(String name, String value)
057    {
058        Defense.notNull(name, "name");
059
060        _parameters.put(name, value);
061    }
062
063    /**
064     * Replaces the parameter value for the given name wit the new list of values (which may be
065     * empty or null).
066     */
067
068    public void setParameterValues(String name, String[] values)
069    {
070        Defense.notNull(name, "name");
071
072        _parameters.put(name, values);
073    }
074
075    /**
076     * Gets a query parameter value. If an array of values was stored, this returns the first value.
077     * May return null.
078     */
079
080    public String getParameterValue(String name)
081    {
082        Defense.notNull(name, "name");
083
084        Object values = _parameters.get(name);
085
086        if (values == null || values instanceof String)
087            return (String) values;
088
089        String[] array = (String[]) values;
090
091        return array[0];
092    }
093
094    /**
095     * Returns the array of values for the specified parameter. If only a lone value was stored (via
096     * {@link #setParameterValue(String, String)}, then the value is wrapped as a string array and
097     * returned.
098     */
099    public String[] getParameterValues(String name)
100    {
101        Defense.notNull(name, "name");
102
103        Object values = _parameters.get(name);
104
105        if (values == null || values instanceof String[])
106            return (String[]) values;
107
108        String loneValue = (String) values;
109
110        return new String[]
111        { loneValue };
112    }
113
114    /**
115     * Returns the names of all parameters, sorted alphabetically.
116     */
117    public String[] getParameterNames()
118    {
119        int count = _parameters.size();
120
121        String[] result = (String[]) _parameters.keySet().toArray(new String[count]);
122
123        Arrays.sort(result);
124
125        return result;
126    }
127}