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.util.value;
018
019import java.time.Duration;
020import java.time.Instant;
021import java.util.Map;
022
023import org.apache.wicket.util.string.StringValue;
024import org.apache.wicket.util.string.StringValueConversionException;
025
026
027/**
028 * A <code>Map</code> interface that holds values, parses <code>String</code>s, and exposes a
029 * variety of convenience methods.
030 * 
031 * @author Johan Compagner
032 * @author Doug Donohoe
033 * @since 1.2.6
034 */
035public interface IValueMap extends Map<String, Object>
036{
037        /**
038         * Retrieves a <code>boolean</code> value by key.
039         * 
040         * @param key
041         *            the key
042         * @return the value
043         * @throws StringValueConversionException
044         */
045        boolean getBoolean(final String key) throws StringValueConversionException;
046
047        /**
048         * Retrieves a <code>double</code> value by key.
049         * 
050         * @param key
051         *            the key
052         * @return the value
053         * @throws StringValueConversionException
054         */
055        double getDouble(final String key) throws StringValueConversionException;
056
057        /**
058         * Retrieves a <code>double</code> value by key, using a default value if not found.
059         * 
060         * @param key
061         *            the key
062         * @param defaultValue
063         *            value to use if no value is in this <code>IValueMap</code>
064         * @return the value
065         * @throws StringValueConversionException
066         */
067        double getDouble(final String key, final double defaultValue)
068                throws StringValueConversionException;
069
070        /**
071         * Retrieves a <code>Duration</code> by key.
072         * 
073         * @param key
074         *            the key
075         * @return the <code>Duration</code> value
076         * @throws StringValueConversionException
077         */
078        Duration getDuration(final String key) throws StringValueConversionException;
079
080        /**
081         * Retrieves an <code>int</code> value by key.
082         * 
083         * @param key
084         *            the key
085         * @return the value
086         * @throws StringValueConversionException
087         */
088        int getInt(final String key) throws StringValueConversionException;
089
090        /**
091         * Retrieves an <code>int</code> value by key, using a default value if not found.
092         * 
093         * @param key
094         *            the key
095         * @param defaultValue
096         *            value to use if no value is in this <code>IValueMap</code>
097         * @return the value
098         * @throws StringValueConversionException
099         */
100        int getInt(final String key, final int defaultValue) throws StringValueConversionException;
101
102        /**
103         * Retrieves a <code>long</code> value by key.
104         * 
105         * @param key
106         *            the key
107         * @return the value
108         * @throws StringValueConversionException
109         */
110        long getLong(final String key) throws StringValueConversionException;
111
112        /**
113         * Retrieves a <code>long</code> value by key, using a default value if not found.
114         * 
115         * @param key
116         *            the key
117         * @param defaultValue
118         *            value to use if no value in this <code>IValueMap</code>
119         * @return the value
120         * @throws StringValueConversionException
121         */
122        long getLong(final String key, final long defaultValue) throws StringValueConversionException;
123
124        /**
125         * Retrieves a <code>String</code> by key, using a default value if not found.
126         * 
127         * @param key
128         *            the key
129         * @param defaultValue
130         *            default value to return if value is <code>null</code>
131         * @return the <code>String</code>
132         */
133        String getString(final String key, final String defaultValue);
134
135        /**
136         * Retrieves a <code>String</code> by key.
137         * 
138         * @param key
139         *            the key
140         * @return the <code>String</code>
141         */
142        String getString(final String key);
143
144        /**
145         * Retrieves a <code>CharSequence</code> by key.
146         * 
147         * @param key
148         *            the key
149         * @return the <code>CharSequence</code>
150         */
151        CharSequence getCharSequence(final String key);
152
153        /**
154         * Retrieves a <code>String</code> array by key. If the value was a <code>String[]</code> it
155         * will be returned directly. If it was a <code>String</code> it will be converted to a
156         * <code>String</code> array of length one. If it was an array of another type, a
157         * <code>String</code> array will be made and each element will be converted to a
158         * <code>String</code>.
159         * 
160         * @param key
161         *            the key
162         * @return the <code>String</code> array of that key
163         */
164        String[] getStringArray(final String key);
165
166        /**
167         * Retrieves a <code>StringValue</code> object by key.
168         * 
169         * @param key
170         *            the key
171         * @return the <code>StringValue</code> object
172         */
173        StringValue getStringValue(final String key);
174
175        /**
176         * Retrieves a <code>Instant</code> object by key.
177         * 
178         * @param key
179         *            the key
180         * @return the <code>Instant</code> object
181         * @throws StringValueConversionException
182         */
183        Instant getInstant(final String key) throws StringValueConversionException;
184
185        /**
186         * Returns whether or not this <code>IValueMap</code> is immutable.
187         * 
188         * @return whether or not this <code>IValueMap</code> is immutable
189         */
190        boolean isImmutable();
191
192        /**
193         * Makes this <code>IValueMap</code> immutable by changing the underlying map representation to
194         * a <code>Collections.unmodifiableMap</code>. After calling this method, any attempt to modify
195         * this <code>IValueMap</code> will result in a <code>RuntimeException</code> being thrown by
196         * the <code>Collections</code> framework.
197         * 
198         * @return this <code>IValueMap</code>
199         */
200        IValueMap makeImmutable();
201
202        /**
203         * Provided that the hash key is a <code>String</code> and you need to access the value ignoring
204         * the key's case (upper- or lowercase letters), then you may use this method to get the correct
205         * writing.
206         * 
207         * @param key
208         *            the key
209         * @return the key with the correct writing
210         */
211        String getKey(final String key);
212
213        // //
214        // // getAs convenience methods
215        // //
216
217        /**
218         * Retrieves a <code>Boolean</code> value by key.
219         * 
220         * @param key
221         *            the key
222         * 
223         * @return the value or null if value is not a valid boolean or no value is in this
224         *         <code>IValueMap</code>
225         * 
226         */
227        Boolean getAsBoolean(String key);
228
229        /**
230         * Retrieves a <code>boolean</code> value by key.
231         * 
232         * @param key
233         *            the key
234         * 
235         * @param defaultValue
236         *            the default to return
237         * 
238         * @return the value or defaultValue if value is not a valid boolean or no value is in this
239         *         <code>IValueMap</code>
240         * 
241         */
242        boolean getAsBoolean(String key, boolean defaultValue);
243
244        /**
245         * Retrieves an <code>Integer</code> value by key.
246         * 
247         * @param key
248         *            the key
249         * 
250         * @return the value or null if value is not a valid integer or no value is in this
251         *         <code>IValueMap</code>
252         * 
253         */
254        Integer getAsInteger(String key);
255
256        /**
257         * Retrieves an <code>integer</code> value by key.
258         * 
259         * @param key
260         *            the key
261         * 
262         * @param defaultValue
263         *            the default to return
264         * 
265         * @return the value or defaultValue if value is not a valid integer or no value is in this
266         *         <code>IValueMap</code>
267         * 
268         */
269        int getAsInteger(String key, int defaultValue);
270
271        /**
272         * Retrieves a <code>Long</code> value by key.
273         * 
274         * @param key
275         *            the key
276         * 
277         * @return the value or null if value is not a valid long or no value is in this
278         *         <code>IValueMap</code>
279         * 
280         */
281        Long getAsLong(String key);
282
283        /**
284         * Retrieves a <code>long</code> value by key.
285         * 
286         * @param key
287         *            the key
288         * 
289         * @param defaultValue
290         *            the default to return
291         * 
292         * @return the value or defaultValue if value is not a valid long or no value is in this
293         *         <code>IValueMap</code>
294         * 
295         */
296        long getAsLong(String key, long defaultValue);
297
298        /**
299         * Retrieves a <code>Double</code> value by key.
300         * 
301         * @param key
302         *            the key
303         * 
304         * @return the value or null if value is not a valid double or no value is in this
305         *         <code>IValueMap</code>
306         * 
307         */
308        Double getAsDouble(String key);
309
310        /**
311         * Retrieves a <code>double</code> value by key.
312         * 
313         * @param key
314         *            the key
315         * 
316         * @param defaultValue
317         *            the default to return
318         * 
319         * @return the value or defaultValue if value is not a valid double or no value is in this
320         *         <code>IValueMap</code>
321         * 
322         */
323        double getAsDouble(String key, double defaultValue);
324
325        /**
326         * Retrieves a <code>Duration</code> value by key.
327         * 
328         * @param key
329         *            the key
330         * 
331         * @return the value or null if value is not a valid Duration or no value is in this
332         *         <code>IValueMap</code>
333         * 
334         */
335        Duration getAsDuration(String key);
336
337        /**
338         * Retrieves a <code>Duration</code> value by key.
339         * 
340         * @param key
341         *            the key
342         * 
343         * @param defaultValue
344         *            the default to return
345         * 
346         * @return the value or defaultValue if value is not a valid Duration or no value is in this
347         *         <code>IValueMap</code>
348         * 
349         */
350        Duration getAsDuration(String key, Duration defaultValue);
351
352        /**
353         * Retrieves a <code>Time</code> value by key.
354         * 
355         * @param key
356         *            the key
357         * 
358         * @return the value or null if value is not a valid Time or no value is in this
359         *         <code>IValueMap</code>
360         * 
361         */
362        Instant getAsInstant(String key);
363
364        /**
365         * Retrieves a <code>Time</code> value by key.
366         * 
367         * @param key
368         *            the key
369         * 
370         * @param defaultValue
371         *            the default to return
372         * 
373         * @return the value or defaultValue if value is not a valid Time or no value is in this
374         *         <code>IValueMap</code>
375         * 
376         */
377        Instant getAsTime(String key, Instant defaultValue);
378
379        /**
380         * Retrieves an <code>Enum</code> value by key.
381         * 
382         * @param <T>
383         *            type of enum
384         * 
385         * @param key
386         *            the key
387         * 
388         * @param eClass
389         *            the enumeration class
390         * 
391         * @return the value or null if value is not a valid value of the Enumeration or no value is in
392         *         this <code>IValueMap</code>
393         * 
394         */
395        <T extends Enum<T>> T getAsEnum(String key, Class<T> eClass);
396
397        /**
398         * Retrieves an <code>Enum</code> value by key.
399         * 
400         * @param <T>
401         *            type of enum
402         * 
403         * @param key
404         *            the key
405         * 
406         * @param defaultValue
407         *            the default value from the Enumeration (cannot be null)
408         * 
409         * @return the value or defaultValue if value is not a valid value of the Enumeration or no
410         *         value is in this <code>IValueMap</code>
411         * 
412         */
413        <T extends Enum<T>> T getAsEnum(String key, T defaultValue);
414
415        /**
416         * Retrieves an <code>Enum</code> value by key.
417         * 
418         * @param <T>
419         *            type of enum
420         * 
421         * @param key
422         *            the key
423         * 
424         * @param eClass
425         *            the enumeration class
426         * 
427         * @param defaultValue
428         *            the default value from the Enumeration (may be null)
429         * 
430         * @return the value or defaultValue if value is not a valid value of the Enumeration or no
431         *         value is in this <code>IValueMap</code>
432         * 
433         */
434        <T extends Enum<T>> T getAsEnum(String key, Class<T> eClass, T defaultValue);
435}