    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}