plugins/org.eclipse.epsilon.executors/src/org/eclipse/epsilon/executors/IEpsilonLanguageExecutor.java - epsilon/org.eclipse.epsilon - Git at Google

 /*********************************************************************
 * Copyright (c) 2019 The University of York.
 *
 * This program and the accompanying materials are made
 * available under the terms of the Eclipse Public License 2.0
 * which is available at https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 **********************************************************************/
 package org.eclipse.epsilon.executors;

 import org.eclipse.epsilon.common.util.profiling.ProfileDiagnostic;
 import org.eclipse.epsilon.eol.IEolModule;
 import org.eclipse.epsilon.eol.models.IModel;
 import org.eclipse.epsilon.eol.types.IToolNativeTypeDelegate;
 import org.eclipse.epsilon.executors.AbstractLanguageExecutor.ExecutionInfo;

 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.Collection;
 import java.util.Map;
 import java.util.Set;

 /**
  * The IEpsilonLanguageExecutor defines a common executor API that the different Epsilon languages
  * can use to facilitate running Epsilon script in standalone applications.
  * The API allows adding the source script/code, models used for execution, and any parameters and
  * native delegates that should be accessible during execution.
  * <p>
  * The API provides 4 phases to the execution of an Epsilon Module: preProcess, execute,
  * postProcess, and dispose.
  * The 4 phases should provide enough flexibility for specific executors to correctly prepare
  * execution, execute, do any post execution processing and finally dispose the executor.
  *
  * @author Horacio Hoyos Rodriguez
  *
  */
 public interface IEpsilonLanguageExecutor extends Runnable {

     /**
      * Get the Dispose Models Flag
      * @return the value of the Dispose Models Flag
      */
     boolean isDisposeModels();

     /**
      * Set the value of the Dispose Models Flag
      * @param disposeModels
      */
     void setDisposeModels(boolean disposeModels);

     /**
      * Whether profiling of execution times is enabled.
      * @return The value of the flag.
      */
     boolean isProfilingEnabled();

     /**
      * Enables or disables profiling of execution times based on the flag.
      * @param profileExecution The value of the flag.
      */
     void setProfilingEnabled(boolean profileExecution);

     /**
      * Get the ExecutionInfo for the current module.
      * @return
      */
     ExecutionInfo getExecutionInfo();

     /**
      * The module used by the executor
      * @return
      */
     IEolModule getModule();

     /**
      * Get a human readable name of the executor
      * @return The name of the executor
      */
     String getName();

     /**
      * Get the code being executed.
      * @return
      */
     String getCode();

     /**
      * Provive the code to execute as a string
      * @param code A String containing the code to execute
      */
     void setCode(String code);

     /**
      * Assign script to execute.
      *
      * @param script the path to the script
      */
     void setScript(Path script);

     default void setScript(String scriptPath) {
     	setScript(Paths.get(scriptPath));
     }

     /**
      * Get the script assigned to the executor
      * @return
      */
     Path getScript();

     /**
      * Returns an unmodifiable view of the models used by the executor.
      *
      * @return a view of the list of models
      */
     Set<IModel> getModels();

     /**
      * Add a model to the executor. Models added to the executor should already
      * be loaded (@link IModel.load())
      *
      * @param model the model.
      * @return <code>true</code> if the model could be added.
      */
     boolean addModel(IModel model);

     default boolean addModels(IModel... models) {
     	boolean result = models != null;
     	if (result) for (IModel model : models) {
     		result &= addModel(model);
     	}
     	return result;
     }

     /**
      * Adds all of the models in the specified collection to this executor. Models
      * added to the executor should already be loaded (@link IModel.load())
      *
      * @param models the models to add.
      * @return
      * @throws EpsilonExecutorException
      */
     default boolean addModels(Collection<IModel> models) {
     	boolean result = models != null;
     	if (result) for (IModel model : models) {
     		result &= addModel(model);
     	}
     	return result;
     }

     /**
      * Remove a model from the executor.
      *
      * @param model
      * @return
      */
     boolean removeModel(IModel model);

     default boolean removeModels(IModel... models) {
     	boolean result = models != null;
     	if (result) for (IModel model : models) {
     		result &= removeModel(model);
     	}
     	return result;
     }

     /**
      * Removes from this executor all of its models that are contained in the specified
      * collection.
      * @param models
      * @return
      */
     default boolean removeModels(Collection<IModel> models) {
     	boolean result = models != null;
     	if (result) for (IModel model : models) {
     		result &= removeModel(model);
     	}
     	return result;
     }

     /**
      * Get the result of the execution
      * @return
      */
     Object getResult();

     /**
      * This method will be invoked before execution of the script
      */
     default void preProcess() {

     }

     /**
      * This method will be invoked after execution of the script
      */
     default void postProcess() {

     }

     /**
      * Execute the provided script, against the list of models using the executor's module.
      * @throws EpsilonExecutorException
      */
     void execute() throws EpsilonExecutorException;

     /**
      * Same as {@link #execute()} without checked exception.
      * @throws RuntimeException A wrapped {@linkplain EpsilonExecutorException}
      */
     @Override
     default void run() throws RuntimeException {
     	try {
     		execute();
     	}
     	catch (EpsilonExecutorException ex) {
     		throw new RuntimeException(ex);
     	}
     }

     /**
      * Disposes the executor. Implementing classes should perform any clean actions.
      * This method should be invoked after execute.
      * It is not invoked automatically because in some cases the user may need
      * to access execution information that is still in the executor's context.
      * The disposeModels flag determines if the models used by the module are also
      * disposed (default true).
      */
     void dispose();

     /**
      * Returns an unmodifiable view of the parameters used by the executor
      * @return the parameters
      */
     Map<String, ?> getParameters();

     /**
      * Add a parameter to the executor. Parameters are used to provide additional
      * information to the execution. In an Eclipse launch configuration these are
      * defined in the parameters tab.
      *
      * The {@link org.eclipse.epsilon.executors.util.ParameterUtil} provides
      * an API to facilitate creation of parameters.
      * @param name the parameter name
      * @param value the parameter value
      */
     boolean addParameter(String name, Object value);

     /**
      * Add a collection of parameters to the executor.
      * @param parameters the parameters
      * @see #addParameter(String, Object)
      */
     void addParameters(Map<String, Object> parameters);

     /**
      * Remove a parameter from the executor
      * @param parameter the parameter name
      * @see #addParameter(String, Object)
      */
     boolean removeParameter(String parameter);

     /**
      * Remove a collection of parameters from the executor.
      * @param parameters the parameters
      * @see #addParameter(String, Object)
      */
     default void removeParameters(Collection<String> parameters) {
     	parameters.forEach(this::removeParameter);
     }

     /**
      * Return an unmodifiable view of the Native Type Delegates used by the executor
      * @return
      */
     Set<IToolNativeTypeDelegate> getNativeDelegates();

     /**
      * Add Native Type Delegates to the executor
      * @param delegates A collection of IToolNativeTypeDelegate to add
      * @return
      */
     boolean addNativeDelegates(Collection<IToolNativeTypeDelegate> delegates);

     /**
      * Add a Native Type Delegates to the executor
      * @param delegate The IToolNativeTypeDelegate to add
      * @return
      */
     boolean addNativeDelegate(IToolNativeTypeDelegate delegate);

     /**
      * Remove Native Type Delegates from the executor
      * @param delegates  A collection of IToolNativeTypeDelegate to remove
      * @return
      */
     boolean removeNativeDelegates(Collection<IToolNativeTypeDelegate> delegates);

     /**
      * Remove a Native Type Delegate from the executor
      * @param delegate The IToolNativeTypeDelegate to remove
      * @return
      */
     boolean removeNativeDelegate(IToolNativeTypeDelegate delegate);
 }
	/*********************************************************************
	* Copyright (c) 2019 The University of York.
	*
	* This program and the accompanying materials are made
	* available under the terms of the Eclipse Public License 2.0
	* which is available at https://www.eclipse.org/legal/epl-2.0/
	*
	* SPDX-License-Identifier: EPL-2.0
	**********************************************************************/
	package org.eclipse.epsilon.executors;

	import org.eclipse.epsilon.common.util.profiling.ProfileDiagnostic;
	import org.eclipse.epsilon.eol.IEolModule;
	import org.eclipse.epsilon.eol.models.IModel;
	import org.eclipse.epsilon.eol.types.IToolNativeTypeDelegate;
	import org.eclipse.epsilon.executors.AbstractLanguageExecutor.ExecutionInfo;

	import java.nio.file.Path;
	import java.nio.file.Paths;
	import java.util.Collection;
	import java.util.Map;
	import java.util.Set;

	/**
	* The IEpsilonLanguageExecutor defines a common executor API that the different Epsilon languages
	* can use to facilitate running Epsilon script in standalone applications.
	* The API allows adding the source script/code, models used for execution, and any parameters and
	* native delegates that should be accessible during execution.
	* <p>
	* The API provides 4 phases to the execution of an Epsilon Module: preProcess, execute,
	* postProcess, and dispose.
	* The 4 phases should provide enough flexibility for specific executors to correctly prepare
	* execution, execute, do any post execution processing and finally dispose the executor.
	*
	* @author Horacio Hoyos Rodriguez
	*
	*/
	public interface IEpsilonLanguageExecutor extends Runnable {

	/**
	* Get the Dispose Models Flag
	* @return the value of the Dispose Models Flag
	*/
	boolean isDisposeModels();

	/**
	* Set the value of the Dispose Models Flag
	* @param disposeModels
	*/
	void setDisposeModels(boolean disposeModels);

	/**
	* Whether profiling of execution times is enabled.
	* @return The value of the flag.
	*/
	boolean isProfilingEnabled();

	/**
	* Enables or disables profiling of execution times based on the flag.
	* @param profileExecution The value of the flag.
	*/
	void setProfilingEnabled(boolean profileExecution);

	/**
	* Get the ExecutionInfo for the current module.
	* @return
	*/
	ExecutionInfo getExecutionInfo();

	/**
	* The module used by the executor
	* @return
	*/
	IEolModule getModule();

	/**
	* Get a human readable name of the executor
	* @return The name of the executor
	*/
	String getName();

	/**
	* Get the code being executed.
	* @return
	*/
	String getCode();

	/**
	* Provive the code to execute as a string
	* @param code A String containing the code to execute
	*/
	void setCode(String code);

	/**
	* Assign script to execute.
	*
	* @param script the path to the script
	*/
	void setScript(Path script);

	default void setScript(String scriptPath) {
	setScript(Paths.get(scriptPath));
	}

	/**
	* Get the script assigned to the executor
	* @return
	*/
	Path getScript();

	/**
	* Returns an unmodifiable view of the models used by the executor.
	*
	* @return a view of the list of models
	*/
	Set<IModel> getModels();

	/**
	* Add a model to the executor. Models added to the executor should already
	* be loaded (@link IModel.load())
	*
	* @param model the model.
	* @return <code>true</code> if the model could be added.
	*/
	boolean addModel(IModel model);

	default boolean addModels(IModel... models) {
	boolean result = models != null;
	if (result) for (IModel model : models) {
	result &= addModel(model);
	}
	return result;
	}

	/**
	* Adds all of the models in the specified collection to this executor. Models
	* added to the executor should already be loaded (@link IModel.load())
	*
	* @param models the models to add.
	* @return
	* @throws EpsilonExecutorException
	*/
	default boolean addModels(Collection<IModel> models) {
	boolean result = models != null;
	if (result) for (IModel model : models) {
	result &= addModel(model);
	}
	return result;
	}

	/**
	* Remove a model from the executor.
	*
	* @param model
	* @return
	*/
	boolean removeModel(IModel model);

	default boolean removeModels(IModel... models) {
	boolean result = models != null;
	if (result) for (IModel model : models) {
	result &= removeModel(model);
	}
	return result;
	}

	/**
	* Removes from this executor all of its models that are contained in the specified
	* collection.
	* @param models
	* @return
	*/
	default boolean removeModels(Collection<IModel> models) {
	boolean result = models != null;
	if (result) for (IModel model : models) {
	result &= removeModel(model);
	}
	return result;
	}

	/**
	* Get the result of the execution
	* @return
	*/
	Object getResult();

	/**
	* This method will be invoked before execution of the script
	*/
	default void preProcess() {

	}

	/**
	* This method will be invoked after execution of the script
	*/
	default void postProcess() {

	}

	/**
	* Execute the provided script, against the list of models using the executor's module.
	* @throws EpsilonExecutorException
	*/
	void execute() throws EpsilonExecutorException;

	/**
	* Same as {@link #execute()} without checked exception.
	* @throws RuntimeException A wrapped {@linkplain EpsilonExecutorException}
	*/
	@Override
	default void run() throws RuntimeException {
	try {
	execute();
	}
	catch (EpsilonExecutorException ex) {
	throw new RuntimeException(ex);
	}
	}

	/**
	* Disposes the executor. Implementing classes should perform any clean actions.
	* This method should be invoked after execute.
	* It is not invoked automatically because in some cases the user may need
	* to access execution information that is still in the executor's context.
	* The disposeModels flag determines if the models used by the module are also
	* disposed (default true).
	*/
	void dispose();

	/**
	* Returns an unmodifiable view of the parameters used by the executor
	* @return the parameters
	*/
	Map<String, ?> getParameters();

	/**
	* Add a parameter to the executor. Parameters are used to provide additional
	* information to the execution. In an Eclipse launch configuration these are
	* defined in the parameters tab.
	*
	* The {@link org.eclipse.epsilon.executors.util.ParameterUtil} provides
	* an API to facilitate creation of parameters.
	* @param name the parameter name
	* @param value the parameter value
	*/
	boolean addParameter(String name, Object value);

	/**
	* Add a collection of parameters to the executor.
	* @param parameters the parameters
	* @see #addParameter(String, Object)
	*/
	void addParameters(Map<String, Object> parameters);

	/**
	* Remove a parameter from the executor
	* @param parameter the parameter name
	* @see #addParameter(String, Object)
	*/
	boolean removeParameter(String parameter);

	/**
	* Remove a collection of parameters from the executor.
	* @param parameters the parameters
	* @see #addParameter(String, Object)
	*/
	default void removeParameters(Collection<String> parameters) {
	parameters.forEach(this::removeParameter);
	}

	/**
	* Return an unmodifiable view of the Native Type Delegates used by the executor
	* @return
	*/
	Set<IToolNativeTypeDelegate> getNativeDelegates();

	/**
	* Add Native Type Delegates to the executor
	* @param delegates A collection of IToolNativeTypeDelegate to add
	* @return
	*/
	boolean addNativeDelegates(Collection<IToolNativeTypeDelegate> delegates);

	/**
	* Add a Native Type Delegates to the executor
	* @param delegate The IToolNativeTypeDelegate to add
	* @return
	*/
	boolean addNativeDelegate(IToolNativeTypeDelegate delegate);

	/**
	* Remove Native Type Delegates from the executor
	* @param delegates A collection of IToolNativeTypeDelegate to remove
	* @return
	*/
	boolean removeNativeDelegates(Collection<IToolNativeTypeDelegate> delegates);

	/**
	* Remove a Native Type Delegate from the executor
	* @param delegate The IToolNativeTypeDelegate to remove
	* @return
	*/
	boolean removeNativeDelegate(IToolNativeTypeDelegate delegate);
	}