001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.request.mapper.parameter;
018
019import java.util.List;
020import java.util.Set;
021
022import org.apache.wicket.request.IRequestMapper;
023import org.apache.wicket.util.io.IClusterable;
024import org.apache.wicket.util.lang.Args;
025import org.apache.wicket.util.string.StringValue;
026
027/**
028 * Container for parameters that are identified by their name
029 * 
030 * @author igor
031 */
032public interface INamedParameters
033{
034        /**
035         * A hint where the parameter is read/parsed from.
036         */
037        enum Type
038        {
039                /**
040                 * The named parameter is set manually in the application code
041                 */
042                MANUAL,
043
044                /**
045                 * The named parameter is read/parsed from the query string
046                 */
047                QUERY_STRING,
048
049                /**
050                 * The named parameter is read/parsed from the url path
051                 */
052                PATH
053        }
054
055        /**
056         * Represents a named parameter entry. There can be multiple {@link NamedPair}s in
057         * {@link PageParameters} that have same key.
058         * 
059         * @author Matej Knopp
060         */
061        @SuppressWarnings("serial")
062        class NamedPair implements IClusterable
063        {
064                private final String key;
065                private final String value;
066                private final Type type;
067
068                /**
069                 * Creates a named parameter entry that is set manually in the application code.
070                 * 
071                 * @param key
072                 * @param value
073                 */
074                public NamedPair(final String key, final String value)
075                {
076                        this(key, value, Type.MANUAL);
077                }
078
079                /**
080                 * Creates a named parameter entry
081                 * 
082                 * @param key
083                 * @param value
084                 * @param type
085                 */
086                public NamedPair(final String key, final String value, Type type)
087                {
088                        this.key = Args.notEmpty(key, "key");
089                        this.value = Args.notNull(value, "value");
090                        this.type = Args.notNull(type, "type");
091                }
092
093                /**
094                 * @return key
095                 */
096                public String getKey()
097                {
098                        return key;
099                }
100
101                /**
102                 * @return value
103                 */
104                public String getValue()
105                {
106                        return value;
107                }
108
109                /**
110                 * @return type
111                 */
112                public Type getType()
113                {
114                        return type;
115                }
116
117                @Override
118                public boolean equals(Object o)
119                {
120                        if (this == o) return true;
121                        if (o == null || getClass() != o.getClass()) return false;
122
123                        NamedPair namedPair = (NamedPair) o;
124
125                        if (key != null ? !key.equals(namedPair.key) : namedPair.key != null) return false;
126                        if (value != null ? !value.equals(namedPair.value) : namedPair.value != null) return false;
127
128                        return true;
129                }
130
131                @Override
132                public int hashCode()
133                {
134                        int result = key != null ? key.hashCode() : 0;
135                        result = 31 * result + (value != null ? value.hashCode() : 0);
136                        return result;
137                }
138        }
139
140        /**
141         * Return set of all named parameter names.
142         * 
143         * @return named parameter names
144         */
145        Set<String> getNamedKeys();
146
147        /**
148         * Returns parameter value of named parameter with given name
149         * 
150         * @param name
151         * @return parameter value
152         */
153        StringValue get(final String name);
154
155        /**
156         * Return list of all values for named parameter with given name
157         * 
158         * @param name
159         * @return list of parameter values
160         */
161        List<StringValue> getValues(final String name);
162
163        /**
164         * @return All named parameters in exact order.
165         */
166        List<NamedPair> getAllNamed();
167
168        /**
169         * @param type
170         *          The type to filter
171         * @return All named parameters with the given type. If the type is {@code null} then returns all named parameters.
172         */
173        List<NamedPair> getAllNamedByType(Type type);
174
175        /**
176         * Returns the position of a named parameter.
177         * 
178         * @param name
179         *            the name of the parameter to look for
180         * @return the position of the parameter. {@code -1} if there is no parameter with that name.
181         */
182        int getPosition(String name);
183
184        /**
185         * Removes named parameter with given name.
186         * 
187         * @param name
188         *            the name of the parameter to remove
189         * @param values
190         *            values used as criteria. The parameter will be removed only if its value is equal
191         *            to any of the criteria.
192         * @return this
193         */
194        INamedParameters remove(final String name, String... values);
195
196        /**
197         * Adds value to named parameter with given name.
198         * 
199         * @param name
200         * @param value
201         * @param type
202         * @return this
203         */
204        INamedParameters add(final String name, final Object value, Type type);
205
206        /**
207         * Adds named parameter to a specified position. The {@link IRequestMapper}s may or may not take
208         * the order into account.
209         * 
210         * @param name
211         * @param value
212         * @param index
213         * @param type
214         * @return this
215         */
216        INamedParameters add(final String name, final Object value, final int index, Type type);
217
218        /**
219         * Sets the named parameter on specified position. The {@link IRequestMapper}s may or may not
220         * take the order into account.
221         * 
222         * @param name
223         * @param value
224         * @param index
225         * @param type
226         * @return this
227         */
228        INamedParameters set(final String name, final Object value, final int index, Type type);
229
230        /**
231         * Sets the value for named parameter with given name.
232         * 
233         * @param name
234         * @param value
235         * @param type
236         * @return this
237         */
238        INamedParameters set(final String name, final Object value, Type type);
239
240        /**
241         * Removes all named parameters.
242         * 
243         * @return this
244         */
245        INamedParameters clearNamed();
246
247}