1 /*
2 * Copyright (c) 2005-2007 Creative Sphere Limited.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 *
10 * Creative Sphere - initial API and implementation
11 *
12 */
13 package org.abstracthorizon.danube.http.util;
14
15 import java.util.Collection;
16 import java.util.List;
17 import java.util.Map;
18 import java.util.Set;
19
20 /**
21 * This is interface defining a map that can, for a value, have
22 * one or more strings. It is used for request or response headers
23 * or request parameters.
24 *
25 *
26 * @author Daniel Sendula
27 */
28 public interface MultiStringMap {
29
30 /**
31 * Adds new element to the map. If no entries with given id exist than this is going to be the first.
32 * If there are already values under given id then this is going to be added as a new one
33 * @param id key
34 * @param value value to be added
35 */
36 void add(String id, String value);
37
38 /**
39 * Adds all elements from the given array.
40 * @param id key
41 * @param values array of values
42 * @see MultiStringMap#add(String, String)
43 */
44 void addAll(String id, String[] values);
45
46 /**
47 * Adds all elements from the given collection
48 * @param id key
49 * @param values collection which elements are to be added
50 * @see MultiStringMap#add(String, String)
51 */
52 void addAll(String id, Collection<String> values);
53
54 /**
55 * Replaces existing element(s), if there are any under the given key, with the given value.
56 * @param id key
57 * @param value value to be put to the map
58 */
59 void putOnly(String id, String value);
60
61 /**
62 * Replaces existing element(s), if there are any under the given key, with the given values.
63 * @param id key
64 * @param values values to be put to the map
65 * @see MultiStringMap#putOnly(String, String)
66 */
67 void putAll(String id, String[] values);
68
69 /**
70 * Replaces existing element(s), if there are any under the given key, with the given values.
71 * @param id key
72 * @param values collection of values to be put to the map
73 * @see MultiStringMap#putOnly(String, String)
74 */
75 void putAll(String id, Collection<String> values);
76
77 /**
78 * Removes all elements from the given key
79 * @param id key
80 */
81 Collection<String> removeAll(String id);
82
83 /**
84 * Removes first element from the given key. If there was only one element then there will be no more elements under
85 * the given key
86 * @param id key
87 */
88 String removeFirst(String id);
89
90 /**
91 * Removes n-th element from the given key.
92 * @param id key
93 * @param index index of the element to be removed
94 * @throws IndexOutOfBoundsException if there are no elements under the given key
95 */
96 String remove(String id, int index);
97
98 /**
99 * Returns <code>true</code> if there is at least one entry
100 * @param id key
101 * @return <code>true</code> if there is at least one entry
102 */
103 boolean containsKey(String id);
104
105 /**
106 * Returns number of entries for given key
107 * @param id key
108 * @return number of entries for given key
109 */
110 int getEntrySize(String id);
111
112 /**
113 * Retrieves element from the given key. Key must have only one element (or none) for this method to work.
114 * @param id key of the asked element
115 * @return element
116 * @throws IllegalStateException if there are more then one element under this key
117 */
118 String getOnly(String id);
119
120 /**
121 * Retrieves first element from the given key.
122 * @param id key of the asked element
123 * @return element or <code>null</code> if there are no elements given
124 */
125 String getFirst(String id);
126
127 /**
128 * Returns array of all elements under asked key. If there are no elements then it returns an empty array.
129 * @param id key of the asked elements
130 * @return an array of strings
131 */
132 String[] getAsArray(String id);
133
134 /**
135 * Returns list of all elements under asked key. If there are no elements then it returns an empty list.
136 * @param id key of the asked elements
137 * @return a list of strings
138 */
139 List<String> getAsList(String id);
140
141 /**
142 * Clears the map
143 */
144 void clear();
145
146 /**
147 * Returns list of all entries. Entries with the same key will repeat if there are more elements stored under the same key.
148 * @return list of all entries
149 */
150 Collection<Map.Entry<String, String>> getAllEntries();
151
152 /**
153 * Returns key set
154 * @return key set
155 */
156 Set<String> keySet();
157
158 /**
159 * Returns a map that contains all elements. Where there are more elements per key then implementation is responsiple of
160 * returning something sensible like an array of strings or a collection (or a list) whose elements are strings
161 * @return a map
162 */
163 Map<String, Object> getAsMap();
164
165 /**
166 * Number of keys in the map. It won't return total number of elements but just number of differnet keys in the map.
167 * @return number of keys in the map
168 */
169 int size();
170
171 }