001package com.hammurapi.common.concurrent;
002
003import java.util.Set;
004import java.util.concurrent.Callable;
005import java.util.concurrent.Future;
006import java.util.concurrent.TimeUnit;
007
008import com.hammurapi.common.Adaptable;
009
010/**
011 * <a href="http://doc.hammurapi.com/dokuwiki/doku.php?id=products:common:concurrent:property_set">Online documentation</a>
012 * @author Pavel Vlasov
013 * 
014 * @param <KP>
015 *            Key path.
016 */
017public interface PropertySet<KP> extends Adaptable, Versionable<PropertySet<KP>> {
018        /**
019         * @return Names of properties in the set
020         */
021        Set<KP> keySet();
022
023        /**
024         * @param prefix
025         * @return Property set which operates on properties starting with given
026         *         prefix.
027         */
028        PropertySet<KP> subset(KP prefix);
029
030        /**
031         * Removes property from the set. Chained properties are shadowed (appear to
032         * be removed).
033         * 
034         * @param name
035         */
036        void remove(KP key);
037
038        /**
039         * Removes all entries from the property set
040         */
041        void clear();
042
043        /**
044         * Mounts source property set at specified prefix. E.g. if source property
045         * set has entry 'a' and prefix is 'b/' then that entry will be available as
046         * 'b/a'. Mounted entries shadow own entries.
047         * 
048         * @param prefix
049         * @param source
050         */
051        void mount(KP prefix, PropertySet<KP> source);
052
053        public void unmount(KP prefix);
054        
055        /**
056         * Copies all entries from the source property set to self.
057         * 
058         * @param source
059         */
060        void setAll(PropertySet<KP> source);
061
062//      /**
063//       * @param otherSet
064//       * @return true if all properties in this set are equal to properties in the
065//       *         other set.
066//       */
067//      boolean compareProperties(PropertySet<KP> otherSet);
068                
069        /**
070         * Retrieves property without conversion.
071         */
072        Object get(KP key);             
073
074        /**
075         * @param key
076         *            Property key.
077         * @param defaultValue
078         *            Default value.
079         * @return Property value or default value if property doesn't exist in the
080         *         property set.
081         */
082        Object get(KP key, Object defaultValue);
083
084        /**
085         * Retrieves property with conversion to target type.
086         */
087        <T> T get(KP key, Class<T> type);
088
089        /**
090         * @param key
091         *            Property key.
092         * @param type
093         *            target type.
094         * @param defaultValue
095         *            Default value.
096         * @return Property value or default value if property doesn't exist in the
097         *         property set.
098         */
099        <T> T get(KP key, Class<T> type, T defaultValue);
100
101        /**
102         * Retrieves property without conversion.
103         */
104        Object get(KP key, long timeout, TimeUnit unit);                
105
106        /**
107         * @param key
108         *            Property key.
109         * @param defaultValue
110         *            Default value.
111         * @return Property value or default value if property doesn't exist in the
112         *         property set.
113         */
114        Object get(KP key, Object defaultValue, long timeout, TimeUnit unit);
115
116        /**
117         * Retrieves property with conversion to target type.
118         */
119        <T> T get(KP key, Class<T> type, long timeout, TimeUnit unit);
120
121        /**
122         * @param key
123         *            Property key.
124         * @param type
125         *            target type.
126         * @param defaultValue
127         *            Default value.
128         * @return Property value or default value if property doesn't exist in the
129         *         property set.
130         */
131        <T> T get(KP key, Class<T> type, T defaultValue, long timeout, TimeUnit unit);
132
133        /**
134         * Sets property.
135         * 
136         * @param key
137         * @param value
138         */
139        void set(KP key, Object value);
140
141        /**
142         * Convenience method to set invocable.
143         * 
144         * @param key
145         * @param invocable
146         */
147        void setInvocable(KP key, Invocable<PropertySet<KP>, ?, KP, ?> invocable);
148
149        /**
150         * Puts callable to the property set for asynchronous invocation to retrieve
151         * value at some point in the future.
152         * 
153         * @param name
154         * @param callable
155         */
156        void cook(KP key, Callable<?> callable);
157
158        /**
159         * Puts callable to the property set for asynchronous invocation to retrieve
160         * value at some point in the future after specified delay.
161         * 
162         * @param name
163         * @param callable
164         * @param delay
165         */
166        void cook(KP key, Callable<?> callable, long delay, TimeUnit timeUnit);
167
168        /**
169         * Puts value which is not ready yet but "is being cooked by another thread"
170         * to the property set to be used at some point of time in the future.
171         * 
172         * @param name
173         * @param future
174         *            Value being cooked.
175         */
176        void cooking(KP key, Future<?> future);
177
178        /**
179         * Puts callable to the property set. Value from callable is retrieved when
180         * <code>get()</code> method for the given name is invoked.
181         * 
182         * @param name
183         * @param callable
184         */
185        void lazy(KP key, Callable<?> callable);
186
187        /**
188         * Removes callable to be cooked from the cooking queue, converting it to
189         * lazy, if it is not already cooked.
190         * 
191         * @param name
192         */
193        void cancel(KP key);
194
195        /**
196         * Cancels all unfinished background computations.
197         */
198        void cancelAll();
199        
200        // adapt - extend adaptable
201        
202        /**
203         * Invokes invocable at given key. Converts arguments to proper types if needed.
204         * Invocation is performed under the write lock, so the invocable can safely modify
205         * the property set. 
206         */
207        Object invoke(KP key, Object... args);
208        
209        // Access to shadow property set(s)
210        
211        /**
212         * Invokes invocable in the shadow property set at given key. Converts arguments to proper types if needed.
213         * The shadow invocable is provided a read-only property set as a context and thus any attempt to modify 
214         * the state of shadow property set(s) will result in exception. 
215         */
216        Object shadowInvoke(KP key, Object... args);
217        
218        /**
219         * Retrieves shadow property without conversion.
220         */
221        Object shadowGet(KP key);
222
223        /**
224         * @param key
225         *            Property key.
226         * @param defaultValue
227         *            Default value.
228         * @return Property value or default value if property doesn't exist in the
229         *         property set.
230         */
231        Object shadowGet(KP key, Object defaultValue);
232
233        /**
234         * Retrieves property with conversion to target type.
235         */
236        <T> T shadowGet(KP key, Class<T> type);
237
238        /**
239         * @param key
240         *            Property key.
241         * @param type
242         *            target type.
243         * @param defaultValue
244         *            Default value.
245         * @return Property value or default value if property doesn't exist in the
246         *         property set.
247         */
248        <T> T shadowGet(KP key, Class<T> type, T defaultValue);
249
250        /**
251         * Retrieves shadow property without conversion.
252         */
253        Object shadowGet(KP key, long timeout, TimeUnit unit);
254
255        /**
256         * @param key
257         *            Property key.
258         * @param defaultValue
259         *            Default value.
260         * @return Property value or default value if property doesn't exist in the
261         *         property set.
262         */
263        Object shadowGet(KP key, Object defaultValue, long timeout, TimeUnit unit);
264
265        /**
266         * Retrieves property with conversion to target type.
267         */
268        <T> T shadowGet(KP key, Class<T> type, long timeout, TimeUnit unit);
269
270        /**
271         * @param key
272         *            Property key.
273         * @param type
274         *            target type.
275         * @param defaultValue
276         *            Default value.
277         * @return Property value or default value if property doesn't exist in the
278         *         property set.
279         */
280        <T> T shadowGet(KP key, Class<T> type, T defaultValue, long timeout, TimeUnit unit);
281
282}