Source code: jtemporal/TemporalMultiMap.java
1 /*
2 Copyright (C) 2002 Thomas A Beck (http://thomas.beck.name)
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public
15 License along with this library; if not, write to the Free Software
16 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */
17
18 package jtemporal;
19
20 import java.util.Set;
21
22 /**
23 * Associates at any time an object (the map holder) to zero to many objects (values),
24 * for example: Employee-Skill. <BR>
25 * You can get the set of values valid at a given time by calling the method
26 * Set valueSet(Instant key).<BR>
27 * To add a mapping, you do not specify an Instant, but a Period specifying the validity
28 * of the object. <BR><BR>
29 * <B>Note:</B> the Object value (passed to many methods) must have equals and hashCode
30 * defined consistently, as described in the java.lang.Object documentation.
31 */
32 public interface TemporalMultiMap {
33
34 /**
35 * Removes all the mappings from this map (optional operation).
36 * @throws UnsupportedOperationException if clear is not supported by this map.
37 */
38 void clear();
39
40 /**
41 * Returns the number of Period-value mappings in this map. If the
42 * map contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
43 * <tt>Integer.MAX_VALUE</tt>.
44 * @return the number of Instant-value mappings in this map.
45 * Returns 0 when the value is unknown.
46 */
47 int size(Object value);
48
49 /**
50 * Returns <tt>true</tt> if this map contains no Period-value mappings.
51 * @return <tt>true</tt> if this map contains no Period-value mappings.
52 */
53 boolean isEmpty();
54
55 /**
56 * Returns a read-only Set containing the values defined in this map at the
57 * specified instant.
58 * Returns an empty set if the map contains no mapping at this Instant.
59 * @return a read-only Set containing the values defined in this map at the
60 * specified instant.
61 * @param instant instant whose associated value is to be returned
62 */
63 Set valueSet(Instant instant);
64
65 /**
66 * Returns a read-only Set containing the values defined somewhen in this map.
67 * @return a read-only Set containing the values defined somewhen in this map.
68 * @param instant instant whose associated value is to be returned
69 */
70 Set valueSet();
71
72 /**
73 * Returns the period of the mapping valid at the specified instant for the value.
74 * @return the period of the mapping valid at the specified instant for the value.
75 * Returns <tt>null</tt> if this map does not contain a mapping for the
76 * specified instant.
77 * @throws NoSuchElementException if the value is unknown.
78 */
79 Period getPeriod(Instant instant, Object value);
80
81 /**
82 * Returns <tt>true</tt> if there is a mapping for this value at the given instant.
83 * Same as containsValue(Instant instant, Object value)
84 * @param instant instant whose presence in this map is to be tested.
85 * @param value value whose presence in this map is to be tested.
86 * @return <tt>true</tt> if there is a mapping for this value at the given instant.
87 */
88 boolean contains(Instant instant, Object value);
89
90
91 /**
92 * Returns <tt>true</tt> if if ther is a mapping for the specified value.
93 * @param value value whose presence in this map is to be tested.
94 * @return <tt>true</tt> if this map maps one or more keys to the
95 * specified value.
96 */
97 boolean containsValue(Object value);
98
99 /**
100 * Associates the specified value to the specified Period in this map.
101 * If the map previously contained a mapping to the same value, during a period
102 * overlapping this period, the periods are merged.
103 *
104 * @param p period with which the specified value is to be associated.
105 * @param value value to be associated with the specified period.
106 * @return <tt>true</tt> if one or more previous values are overwritten
107 * partialy or completely. <tt>false</tt> if there is any conflicting
108 * mapping.
109 *
110 * @throws UnsupportedOperationException if the <tt>put</tt> operation is
111 * not supported by this map.
112 * @throws ClassCastException if the class of the specified value
113 * prevents it from being stored in this map.
114 * @throws IllegalArgumentException if some aspect of this period or value
115 * prevents it from being stored in this map.
116 * @throws NullPointerException if the period or the value is <tt>null</tt>
117 */
118 boolean put(Period p, Object value);
119
120 /**
121 * Removes the mapping(s) for this period and value from this map if present
122 * (optional operation).
123 *
124 * @param p period whose mappings are to be removed from the map.
125 * @param value value whose mapping are to be removed from the map.
126 * @return <tt>true</tt> if one or more previous values are removed
127 * partialy or completely. <tt>false</tt> if there is no mapping changed.
128 * @throws UnsupportedOperationException if the <tt>remove</tt> method is
129 * not supported by this map.
130 * @throws NoSuchElementException if the value is unknown.
131 */
132 boolean remove(Period p, Object value);
133
134 /**
135 * Removes all the mapping(s) for this value from this map if present (optional
136 * operation).
137 *
138 * @param value value whose mapping are to be removed from the map.
139 * @throws UnsupportedOperationException if the <tt>remove</tt> method is
140 * not supported by this map.
141 * @throws NoSuchElementException if the value is unknown.
142 */
143 void removeValue(Object value);
144
145 /**
146 * Removes all the mapping(s) for this period from this map if present (optional
147 * operation).
148 *
149 * @param p period whose mappings are to be removed from the map.
150 * @return <tt>true</tt> if one or more previous values are removed
151 * partialy or completely. <tt>false</tt> if there is any mapping changed.
152 * @throws UnsupportedOperationException if the <tt>remove</tt> method is
153 * not supported by this map.
154 */
155 boolean removePeriod(Period p);
156
157 /**
158 * Copies all of the mappings from the specified map to this map
159 * (optional operation). These mappings will replace any mappings that
160 * this map had for any of the periods currently in the specified map.
161 *
162 * @param tm Mappings to be stored in this map.
163 *
164 * @return <tt>true</tt> if one or more previous values are overwritten
165 * partialy or completely. <tt>false</tt> if there is any conflicting
166 * mapping.
167 *
168 * @throws UnsupportedOperationException if the <tt>putAll</tt> method is
169 * not supported by this map.
170 *
171 * @throws ClassCastException if the class of a value in the
172 * specified map prevents it from being stored in this map.
173 *
174 * @throws IllegalArgumentException some aspect of a value in the
175 * specified map prevents it from being stored in this map.
176 */
177 boolean putAll(TemporalMultiMap mtm);
178
179
180 /**
181 * Returns a set view of the periods contained in this map for the give value.
182 * The set is
183 * backed by the map, so changes to the map are reflected in the set, and
184 * vice-versa. If the map is modified while an iteration over the set is
185 * in progress, the results of the iteration are undefined. The set
186 * supports element removal, which removes the corresponding mapping from
187 * the map, via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
188 * <tt>removeAll</tt> <tt>retainAll</tt>, and <tt>clear</tt> operations.
189 * It does not support the add or <tt>addAll</tt> operations.
190 *
191 * @return a set view of the periods contained in this map for the give value.
192 * @throws NoSuchElementException if the value is unknown.
193 */
194 Set periodSet(Object value);
195
196
197 /**
198 * Returns the first (lowest) instant currently defined for the given value.
199 *
200 * @return the first (lowest) instant currently defined for the given value.
201 * @throws NoSuchElementException if the value is unknown.
202 */
203 Instant firstInstant(Object value);
204
205 /**
206 * Returns the last (highest) instant currently defined for the given value.
207 *
208 * @return the last (highest) instant currently defined for the given value.
209 * @throws NoSuchElementException if the value is unknown.
210 */
211 Instant lastInstant(Object value);
212
213 /**
214 * Returns the first (lowest) period currently defined for the given value.
215 *
216 * @return the first (lowest) period currently defined for the given value.
217 * @throws NoSuchElementException if the value is unknown.
218 */
219 Period firstPeriod(Object value);
220
221 /**
222 * Returns the last (highest) period currently defined for the given value.
223 *
224 * @return the last (highest) period currently defined for the given value.
225 * @throws NoSuchElementException if the value is unknown.
226 */
227 Period lastPeriod(Object value);
228
229 /**
230 * Return a period enclosing firstInstant(value) and lastInstantvalue()
231 * @return new Period(firstInstant(value), lastInstant(value))
232 * @throws NoSuchElementException if the value is unknown.
233 * @see TemporalMultiMap#firstInstant(Object)
234 * @see TemporalMultiMap#lastInstant(Object)
235 */
236 Period extent(Object value);
237
238 /**
239 * Returns a TemporalUnaryMap which is either a copy or a view of this map,
240 * restricted to the given period. (optional operation).
241 * @throws UnsupportedOperationException if clear is not supported by this map.
242 TemporalMultiMap subMap(Period p); */
243 }