Package net.ssehub.easy.instantiation.core.model.execution

Class Executor

  • public class Executor
extends java.lang.Object
    Executes VIL scripts. This is a convenience class following the builder pattern, i.e., you create an instance, add parameter and finally execute the constructed call. Please note that some arguments may be optional from the point of view of default EASy execution! Further, projects may be given in terms of their base folder or as an IProjectDescriptor, whereby the project descriptor carries explicit information about the project and shall be preferred (except for explicit testing purposes). However, if multiple sources are given, as a convention the first one shall the top-level project that needs to be executed.
    Author:
    Holger Eichelberger

    • Field Detail

      • DEFAULT_START_RULE_NAME

        public static final java.lang.String DEFAULT_START_RULE_NAME
        Defines the default start rule name.
        See Also:
        Constant Field Values

      • DEFAULT_EXECUTABLE

        protected static final Executor.IExecutable DEFAULT_EXECUTABLE
        Implements the default executable.

      • DEFAULT_PARAMS

        private static final java.util.Set<java.lang.String> DEFAULT_PARAMS

      • arguments

        private java.util.Map<java.lang.String,​java.lang.Object> arguments

      • script

        private Script script

      • startRuleName

        private java.lang.String startRuleName

      • base

        private java.io.File base

      • frozenOnly

        private boolean frozenOnly

    • Constructor Detail

      • Executor

        public Executor​(Script script)
        Creates an executor with default arguments.
        Parameters:
        script - the script to execute
        Throws:
        java.lang.IllegalArgumentException - in case that source is null

      • Executor

        public Executor​(Script script,
                java.util.Map<java.lang.String,​java.lang.Object> arguments)
        Creates an executor with predefined arguments. This enables to execute scripts with custom parameters.
        Parameters:
        script - the script to execute (ignored if null)
        arguments - the arguments matching all par

    • Method Detail

      • addStartRuleName

        public Executor addStartRuleName​(java.lang.String startRuleName)
        Adds the start rule name as argument.
        Parameters:
        startRuleName - the start rule name, "main" by default if null or empty
        Returns:
        this executor instance

      • frozenOnly

        public Executor frozenOnly​(boolean frozenOnly)
        Switches on / off whether only frozen variables shall be able for instantiation. This enables runtime variability. Please note that this switch applies only to configurations created in this class, not configurations created outside and passed in.
        Parameters:
        frozenOnly - if true only frozen variables will be considered in a configuration instance created by this class, false else
        Returns:
        this executor instance

      • setFrozenOnly

        protected void setFrozenOnly​(boolean frozenOnly)
        Changes the frozen-only flag.
        Parameters:
        frozenOnly - the frozen-only flag

      • addSource

        public Executor addSource​(java.io.File source)
        Adds the source folder as argument. This is opposite to addSources(File[]).
        Parameters:
        source - the source folder (project)
        Returns:
        this executor instance
        Throws:
        java.lang.IllegalArgumentException - in case that source is null

      • addSource

        public Executor addSource​(IProjectDescriptor source)
        Adds the source project as argument.
        Parameters:
        source - the source project
        Returns:
        this executor instance
        Throws:
        java.lang.IllegalArgumentException - in case that source is null

      • addSources

        public Executor addSources​(java.util.List<java.io.File> sources)
        Adds the source folders as argument. This is opposite to addSource(File).
        Parameters:
        sources - the source folders (projects)
        Returns:
        this executor instance

      • addSources

        public Executor addSources​(java.io.File[] sources)
        Adds the source folders as argument. This is opposite to addSource(File).
        Parameters:
        sources - the source folders (projects)
        Returns:
        this executor instance
        Throws:
        java.lang.IllegalArgumentException - in case that sources is null or empty

      • addSources

        public Executor addSources​(IProjectDescriptor[] sources)
        Adds the source projects as argument. This is opposite to addSource(IProjectDescriptor).
        Parameters:
        sources - the source projects
        Returns:
        this executor instance
        Throws:
        java.lang.IllegalArgumentException - in case that sources is null or empty

      • addTarget

        public Executor addTarget​(java.io.File target)
        Adds the target (folder) as argument.
        Parameters:
        target - the target folder (may be null, then source is taken)
        Returns:
        this executor instance

      • addTarget

        public Executor addTarget​(IProjectDescriptor target)
        Adds the target project as argument.
        Parameters:
        target - the target project (may be null, then source is taken)
        Returns:
        this executor instance

      • addConfiguration

        public Executor addConfiguration​(Configuration config)
        Adds the configuration as argument.
        Parameters:
        config - the variability configuration
        Returns:
        this executor instance
        Throws:
        java.lang.IllegalArgumentException - in case that config is null

      • addConfiguration

        public Executor addConfiguration​(Configuration config)
        Adds the configuration as argument.
        Parameters:
        config - the variability configuration
        Returns:
        this executor instance
        Throws:
        java.lang.IllegalArgumentException - in case that config is null

      • addBase

        public Executor addBase​(java.io.File base)
        Explicitly adds an argument for the base directory for resolving property files.
        Parameters:
        base - the base directory, the target directory if null
        Returns:
        this executor instance

      • addCustomArgument

        public Executor addCustomArgument​(java.lang.String name,
                                  java.lang.Object value)
        Adds a custom argument. If possible, this method maps automatically
        • java.util.Set to setOf
        • java.util.List to sequenceOf
        • java.util.Map to mapOf
        Parameters:
        name - the name of the argument
        value - the actual value
        Returns:
        this executor instance
        Throws:
        java.lang.IllegalArgumentException - in case that name is not given

      • unknownCollectionType

        private static TypeDescriptor<?>[] unknownCollectionType()
        Returns an unknown VIL collection type.
        Returns:
        an unknown VIL collection type

      • unknownMapType

        private static TypeDescriptor<?>[] unknownMapType()
        Returns an unknown VIL map type.
        Returns:
        an unknown VIL map type

      • convertToVIL

        private static java.lang.Object convertToVIL​(java.lang.Object object)
        Converts an object to VIL, if possible.
        Parameters:
        object - the object to be converted
        Returns:
        the converted object

      • execute

        public void execute()
             throws VilException
        Executes the contained VIL build language script without observer and with default parameter checks.
        Throws:
        VilException - in case that artifact operations or script execution fails
        java.lang.IllegalArgumentException - in case that input is missing or wrong

      • execute

        public void execute​(boolean check)
             throws VilException
        Executes the contained VIL build language script without observer and possibly without default parameter checks (may be helpful in case of custom arguments).
        Parameters:
        check - carry out default parameter checks and default argument settings for EASy script execution (if disabled, full responsibility for proper execution is on caller side)
        Throws:
        VilException - in case that artifact operations or script execution fails
        java.lang.IllegalArgumentException - in case that input is missing or wrong

      • execute

        public void execute​(ProgressObserver observer,
                    boolean check)
             throws VilException
        Executes the contained VIL build language script with the given observer (mainly used within parameter conversion) and possibly without default parameter checks (may be helpful in case of custom arguments).
        Parameters:
        observer - the observer to be considered (must not be null)
        check - carry out default parameter checks and default argument settings for EASy script execution (if disabled, full responsibility for proper execution is on caller side)
        Throws:
        VilException - in case that artifact operations or script execution fails
        java.lang.IllegalArgumentException - in case that input is missing or wrong

      • getConfiguration

        protected static Configuration getConfiguration​(java.util.Map<java.lang.String,​java.lang.Object> args)
                                         throws VilException
        Returns the configuration form .
        Parameters:
        args - the (actual) execution arguments
        Returns:
        the configuration
        Throws:
        VilException - if no VIL (typed) configuration is present

      • getScript

        public Script getScript()
        The actual script.
        Returns:
        the script

      • execute

        protected void execute​(ProgressObserver observer,
                       boolean check,
                       Executor.IExecutable executable)
                throws VilException
        Executes the contained VIL build language script with the given observer (mainly used within parameter conversion) and possibly without default parameter checks (may be helpful in case of custom arguments).
        Parameters:
        observer - the observer to be considered (must not be null)
        check - carry out default parameter checks and default argument settings for EASy script execution (if disabled, full responsibility for proper execution is on caller side)
        executable - the final executable
        Throws:
        VilException - in case that artifact operations or script execution fails
        java.lang.IllegalArgumentException - in case that input is missing or wrong

      • stop

        public void stop()
        Stops the execution of a previous execute(ProgressObserver, boolean) call. Requires some form of threaded call of the execution and this method!

      • handleExecutionResult

        protected void handleExecutionResult​(RuleExecutionResult result,
                                     ITracer tracer,
                                     BuildlangExecution executor)
                              throws VilException
        Handles an execution result returned from executor.
        Parameters:
        result - the execution result
        tracer - the actual tracer instance
        executor - the executor, which emitted the execution result
        Throws:
        VilException - can be thrown to indicate in a hard way that artifact operations or script execution failed
        See Also:
        #completeExecutionError(StringBuilder)

      • reload

        protected Script reload​(Script script)
        Reloads the given script.
        Parameters:
        script - the script to be reloaded
        Returns:
        the reloaded script

      • createExecutionEnvironment

        protected BuildlangExecution createExecutionEnvironment​(ITracer tracer,
                                                        java.io.File base,
                                                        java.lang.String startRuleName,
                                                        java.util.Map<java.lang.String,​java.lang.Object> parameter)
        Creates a new execution environment.
        Parameters:
        tracer - the tracer
        base - the base directory for making files absolute
        startRuleName - the name of the start rule; if multiple source projects are given, as a convention the first one shall the top-level project that needs to be executed.
        parameter - the top-level parameter for the script to be executed
        Returns:
        the execution environment

      • checkProjectArgument

        private static void checkProjectArgument​(java.util.Map<java.lang.String,​java.lang.Object> args,
                                         java.lang.String param,
                                         ProgressObserver observer)
                                  throws VilException
        Checks a project argument.
        Parameters:
        args - the name-argument mapping
        param - the name of the parameter to be analyzed
        observer - the observer for longer operations
        Throws:
        VilException - in case that artifact operations fail
        java.lang.IllegalArgumentException - in case that input is missing or wrong

      • checkArguments

        private void checkArguments​(java.util.Map<java.lang.String,​java.lang.Object> args,
                            ProgressObserver observer)
                     throws VilException
        Checks the arguments.
        Parameters:
        args - the name-argument mapping
        observer - the observer for longer operations
        Throws:
        VilException - in case that artifact operations fail
        java.lang.IllegalArgumentException - in case that input is missing or wrong