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}