001package org.unix4j.context;
002
003import java.io.File;
004import java.util.Locale;
005import java.util.Map;
006import java.util.Properties;
007
008import org.unix4j.command.Command;
009import org.unix4j.convert.ConverterRegistry;
010import org.unix4j.convert.ValueConverter;
011import org.unix4j.processor.LineProcessor;
012import org.unix4j.variable.VariableContext;
013
014/**
015 * The execution context encapsulates all information relevant during the
016 * execution of a {@link Command} or chain of joined commands. It is passed to
017 * the {@link Command#execute(ExecutionContext, LineProcessor) execute(..)}
018 * method providing access to the current directory, environment variables and
019 * other information useful for the commands during their execution.
020 */
021public interface ExecutionContext {
022
023        /**
024         * Returns the current directory, never null. If the current directory has
025         * not explicitly been changed, the file specified by the {@code "user.dir"}
026         * system property is returned.
027         * 
028         * @return the current directory, the same as the {@code "user.dir"} system
029         *         property it has not been set explicitly
030         * @see System#getProperties()
031         */
032        File getCurrentDirectory();
033
034        /**
035         * Returns the given file but relative to the {@link #getCurrentDirectory()
036         * current directory} if the given file path is not absolute. Most commands
037         * should resolve files through this method since the unix4j current
038         * directory and the Java current directory are not the same.
039         * 
040         * @param file
041         *            the file to return relative to the current directory if it
042         *            denotes a relative path
043         * @return the given file relative to the execution context's
044         *         {@link #getCurrentDirectory() current directory}
045         */
046        File getRelativeToCurrentDirectory(File file);
047
048        /**
049         * Returns the user name, usually defined by the {@code "user.name"} system
050         * property.
051         * 
052         * @return the user name, usually defined by the {@code "user.name"} system
053         *         property
054         * @see System#getProperties()
055         */
056        String getUser();
057
058        /**
059         * Returns the user home directory, usually defined by the
060         * {@code "user.home"} system property.
061         * 
062         * @return the user home directory, usually defined by the
063         *         {@code "user.home"} system property
064         * @see System#getProperties()
065         */
066        File getUserHome();
067
068        File getTempDirectory();
069
070        Locale getLocale();
071
072        Map<String, String> getEnv();
073
074        Properties getSys();
075
076        VariableContext getVariableContext();
077
078        ConverterRegistry getConverterRegistry();
079
080        <V> ValueConverter<V> getValueConverterFor(Class<V> type);
081}