001package org.unix4j.variable;
002
003import org.unix4j.convert.ValueConverter;
004
005/**
006 * The variable context is an extension of the somewhat simplistic 
007 * {@link VariableResolver}. It extends the resolver by allowing registration of 
008 * delegate resolvers and adding a convenience method to return converted 
009 * variable values.
010 */
011public interface VariableContext extends VariableResolver {
012        /**
013         * Adds a variable resolver to this variable context. The last recently 
014         * added resolver has preference over previously added resolvers. This 
015         * allows hiding of variables for instance to support different variable
016         * scopes with the same variable names.
017         *  
018         * @param resolver the resolver to add
019         */
020        void addVariableResolver(VariableResolver resolver);
021
022        /**
023         * Removes the specified variable resolver if it exists and does nothing
024         * otherwise. If this resolver exists multiple times, the most recently
025         * added object is removed.
026         *  
027         * @param resolver the resolver to remove
028         */
029        void removeVariableResolver(VariableResolver resolver);
030
031        /**
032         * Returns the value of the variable given by name and converts it into the
033         * target type {@code <V>} using the given converter. Returns null if no
034         * such variable exists. An exception is thrown if the conversion fails, or
035         * which is indicated by a null value returned by the converter for a
036         * non-null input value.
037         * 
038         * @param <V>
039         *            the target value type
040         * @param name
041         *            the variable name
042         * @param converter
043         *            a converter suitable to convert values into the target type
044         *            {@code <V>}
045         * @return the converted value, or null if the variable does not exist
046         * @throws IllegalArgumentException
047         *             if the value conversion fails, that is, if the converter
048         *             returns null for the non-null input value
049         */
050        <V> V getValue(String name, ValueConverter<V> converter) throws IllegalArgumentException;
051}