core/org.eclipse.ptp.ems.core/src/org/eclipse/ptp/ems/core/IEnvManager.java - gerrit/ptp/org.eclipse.ptp - Git at Google

 /*******************************************************************************
  * Copyright (c) 2012 University of Illinois and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  *    Jeff Overbey (Illinois) - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ptp.ems.core;

 import java.io.IOException;
 import java.util.Comparator;
 import java.util.List;

 import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.remote.core.IRemoteConnection;
 import org.eclipse.remote.core.exception.RemoteConnectionException;

 /**
  * An object which provides access to an environment management system on a remote machine.
  * <p>
  * All contributions to the {@value #ENV_MANAGER_EXTENSION_POINT_ID} extension point must implement this interface.
  *
  * @author Jeff Overbey
  *
  * @since 6.0
  */
 public interface IEnvManager {

 	/** ID for the envmanager extension point */
 	public static final String ENV_MANAGER_EXTENSION_POINT_ID = "org.eclipse.ptp.ems.core.envmanager"; //$NON-NLS-1$

 	/**
 	 * Returns a human-readable name for this environment management system.
 	 *
 	 * @return String (non-<code>null</code>)
 	 */
 	String getName();

 	/**
 	 * Returns a {@link Comparator} used to sort the strings returned by {@link #determineAvailableElements(IProgressMonitor)} and
 	 * {@link #determineDefaultElements(IProgressMonitor)} when displaying them to the user.
 	 *
 	 * @return {@link Comparator} (non-<code>null</code>)
 	 */
 	public Comparator<String> getComparator();

 	/**
 	 * Returns a short sentence that will be displayed to the user to request that items be selected from a checklist.
 	 * <p>
 	 * For example, &quot;Select modules to be loaded.&quot;
 	 *
 	 * @return String (non-<code>null</code>)
 	 */
 	public String getInstructions();

 	/**
 	 * Sets the {@link IRemoteConnection} which will be used to run commands on a remote machine.
 	 * <p>
 	 * This method must be invoked before {@link #checkForCompatibleInstallation(IProgressMonitor)},
 	 * {@link #getDescription(IProgressMonitor)}, {@link #determineAvailableElements(IProgressMonitor)},
 	 * {@link #determineDefaultElements(IProgressMonitor)}, or
 	 * {@link #createBashScript(IProgressMonitor, boolean, IEnvManagerConfig, String)}.
 	 *
 	 * @param remoteConnection
 	 *            {@link IRemoteConnection} (non-<code>null</code>)
 	 * @since 3.0
 	 */
 	void configure(IRemoteConnection remoteConnection);

 	/**
 	 * Returns true iff the remote machine is running an environment management system supported by this {@link IEnvManager}.
 	 *
 	 * @param pm
 	 *            progress monitor used to report the status of potentially long-running operations to the user (non-
 	 *            <code>null</code>)
 	 *
 	 * @return true iff the remote machine is running an environment management system supported by this {@link IEnvManager}
 	 *
 	 * @throws NullPointerException
 	 *             if {@link #configure(IRemoteConnection)} has not been called
 	 * @throws RemoteConnectionException
 	 *             if an remote connection error occurs
 	 * @throws IOException
 	 *             if an input/output error occurs
 	 */
 	public boolean checkForCompatibleInstallation(IProgressMonitor pm) throws RemoteConnectionException, IOException;

 	/**
 	 * If the remote machine is running an environment management system supported by this {@link IEnvManager}, returns a short
 	 * description of the environment management system (e.g., &quot;Modules 3.2.7&quot;); otherwise, returns <code>null</code>.
 	 *
 	 * @param pm
 	 *            progress monitor used to report the status of potentially long-running operations to the user (non-
 	 *            <code>null</code>)
 	 *
 	 * @return a short, human-readable description of the environment configuration system (e.g., &quot;SoftEnv 1.6.2&quot;), or
 	 *         <code>null</code> if a compatible environment configuration system is not present on the remote machine
 	 *
 	 * @throws NullPointerException
 	 *             if {@link #configure(IRemoteConnection)} has not been called
 	 * @throws RemoteConnectionException
 	 *             if an remote connection error occurs
 	 * @throws IOException
 	 *             if an input/output error occurs
 	 */
 	public String getDescription(IProgressMonitor pm) throws RemoteConnectionException, IOException;

 	/**
 	 * Returns the set of all environment configuration elements available on the remote machine (e.g., the result of
 	 * <code>module -t avail</code>).
 	 *
 	 * @param pm
 	 *            progress monitor used to report the status of potentially long-running operations to the user (non-
 	 *            <code>null</code>)
 	 *
 	 * @return unmodifiable Set (non-<code>null</code>)
 	 *
 	 * @throws NullPointerException
 	 *             if {@link #configure(IRemoteConnection)} has not been called
 	 * @throws RemoteConnectionException
 	 *             if an remote connection error occurs
 	 * @throws IOException
 	 *             if an input/output error occurs
 	 * @since 2.0
 	 */
 	public List<String> determineAvailableElements(IProgressMonitor pm) throws RemoteConnectionException, IOException;

 	/**
 	 * Returns the set of all environment configuration elements loaded by default upon login (e.g., the result of
 	 * <code>module -t list</code> in a login shell). Note that the ordering of modules is important and must be retained.
 	 *
 	 * @param pm
 	 *            progress monitor used to report the status of potentially long-running operations to the user (non-
 	 *            <code>null</code>)
 	 *
 	 * @return unmodifiable List (non-<code>null</code>)
 	 *
 	 * @throws NullPointerException
 	 *             if {@link #configure(IRemoteConnection)} has not been called
 	 * @throws RemoteConnectionException
 	 *             if an remote connection error occurs
 	 * @throws IOException
 	 *             if an input/output error occurs
 	 * @since 2.0
 	 */
 	public List<String> determineDefaultElements(IProgressMonitor pm) throws RemoteConnectionException, IOException;

 	/**
 	 * Returns a single Bash shell command which will configure the remote environment with the given elements and then execute the
 	 * given command.
 	 * <p>
 	 * The returned command may include sequencing, piping, I/O redirection, etc.; however, it must be possible to concatenate
 	 * additional Bash commands by appending a semicolon.
 	 *
 	 * @param separator
 	 *            string that will be inserted between consecutive Bash commands: typically, either a semicolon or a newline
 	 * @param echo
 	 *            true iff the script should &quot;echo&quot; each command prior to execution
 	 * @param config
 	 *            environment manager configuration (non-<code>null</code>)
 	 * @param commandToExecuteAfterward
 	 *            a Bash shell command to execute after the environment has been configured
 	 *
 	 * @return a single Bash shell command which will configure the remote environment with the given elements and then execute the
 	 *         given command (non-<code>null</code>)
 	 */
 	public String getBashConcatenation(String separator, boolean echo, IEnvManagerConfig config, String commandToExecuteAfterward);

 	/**
 	 * Creates a temporary file on the remote machine and writes a Bash shell script into that file which will configure the remote
 	 * environment with the given elements, execute the given command, and then delete the temporary file (shell script).
 	 *
 	 * @param pm
 	 *            progress monitor used to report the status of potentially long-running operations to the user (non-
 	 *            <code>null</code>)
 	 * @param echo
 	 *            true iff the script should &quot;echo&quot; each command prior to execution
 	 * @param config
 	 *            environment manager configuration (non-<code>null</code>)
 	 * @param commandToExecuteAfterward
 	 *            a Bash shell command to execute after the environment has been configured
 	 *
 	 * @return path to the shell script on the remote machine (non-<code>null</code>)
 	 *
 	 * @throws RemoteConnectionException
 	 *             if an remote connection error occurs
 	 * @throws IOException
 	 *             if an input/output error occurs
 	 */
 	public String createBashScript(IProgressMonitor pm, boolean echo, IEnvManagerConfig config, String commandToExecuteAfterward)
 			throws RemoteConnectionException, IOException;
 }
	/*******************************************************************************
	* Copyright (c) 2012 University of Illinois and others.
	* All rights reserved. This program and the accompanying materials
	* are made available under the terms of the Eclipse Public License v1.0
	* which accompanies this distribution, and is available at
	* http://www.eclipse.org/legal/epl-v10.html
	*
	* Contributors:
	* Jeff Overbey (Illinois) - initial API and implementation
	*******************************************************************************/
	package org.eclipse.ptp.ems.core;

	import java.io.IOException;
	import java.util.Comparator;
	import java.util.List;

	import org.eclipse.core.runtime.IProgressMonitor;
	import org.eclipse.remote.core.IRemoteConnection;
	import org.eclipse.remote.core.exception.RemoteConnectionException;

	/**
	* An object which provides access to an environment management system on a remote machine.
	* <p>
	* All contributions to the {@value #ENV_MANAGER_EXTENSION_POINT_ID} extension point must implement this interface.
	*
	* @author Jeff Overbey
	*
	* @since 6.0
	*/
	public interface IEnvManager {

	/** ID for the envmanager extension point */
	public static final String ENV_MANAGER_EXTENSION_POINT_ID = "org.eclipse.ptp.ems.core.envmanager"; //$NON-NLS-1$

	/**
	* Returns a human-readable name for this environment management system.
	*
	* @return String (non-<code>null</code>)
	*/
	String getName();

	/**
	* Returns a {@link Comparator} used to sort the strings returned by {@link #determineAvailableElements(IProgressMonitor)} and
	* {@link #determineDefaultElements(IProgressMonitor)} when displaying them to the user.
	*
	* @return {@link Comparator} (non-<code>null</code>)
	*/
	public Comparator<String> getComparator();

	/**
	* Returns a short sentence that will be displayed to the user to request that items be selected from a checklist.
	* <p>
	* For example, "Select modules to be loaded."
	*
	* @return String (non-<code>null</code>)
	*/
	public String getInstructions();

	/**
	* Sets the {@link IRemoteConnection} which will be used to run commands on a remote machine.
	* <p>
	* This method must be invoked before {@link #checkForCompatibleInstallation(IProgressMonitor)},
	* {@link #getDescription(IProgressMonitor)}, {@link #determineAvailableElements(IProgressMonitor)},
	* {@link #determineDefaultElements(IProgressMonitor)}, or
	* {@link #createBashScript(IProgressMonitor, boolean, IEnvManagerConfig, String)}.
	*
	* @param remoteConnection
	* {@link IRemoteConnection} (non-<code>null</code>)
	* @since 3.0
	*/
	void configure(IRemoteConnection remoteConnection);

	/**
	* Returns true iff the remote machine is running an environment management system supported by this {@link IEnvManager}.
	*
	* @param pm
	* progress monitor used to report the status of potentially long-running operations to the user (non-
	* <code>null</code>)
	*
	* @return true iff the remote machine is running an environment management system supported by this {@link IEnvManager}
	*
	* @throws NullPointerException
	* if {@link #configure(IRemoteConnection)} has not been called
	* @throws RemoteConnectionException
	* if an remote connection error occurs
	* @throws IOException
	* if an input/output error occurs
	*/
	public boolean checkForCompatibleInstallation(IProgressMonitor pm) throws RemoteConnectionException, IOException;

	/**
	* If the remote machine is running an environment management system supported by this {@link IEnvManager}, returns a short
	* description of the environment management system (e.g., "Modules 3.2.7"); otherwise, returns <code>null</code>.
	*
	* @param pm
	* progress monitor used to report the status of potentially long-running operations to the user (non-
	* <code>null</code>)
	*
	* @return a short, human-readable description of the environment configuration system (e.g., "SoftEnv 1.6.2"), or
	* <code>null</code> if a compatible environment configuration system is not present on the remote machine
	*
	* @throws NullPointerException
	* if {@link #configure(IRemoteConnection)} has not been called
	* @throws RemoteConnectionException
	* if an remote connection error occurs
	* @throws IOException
	* if an input/output error occurs
	*/
	public String getDescription(IProgressMonitor pm) throws RemoteConnectionException, IOException;

	/**
	* Returns the set of all environment configuration elements available on the remote machine (e.g., the result of
	* <code>module -t avail</code>).
	*
	* @param pm
	* progress monitor used to report the status of potentially long-running operations to the user (non-
	* <code>null</code>)
	*
	* @return unmodifiable Set (non-<code>null</code>)
	*
	* @throws NullPointerException
	* if {@link #configure(IRemoteConnection)} has not been called
	* @throws RemoteConnectionException
	* if an remote connection error occurs
	* @throws IOException
	* if an input/output error occurs
	* @since 2.0
	*/
	public List<String> determineAvailableElements(IProgressMonitor pm) throws RemoteConnectionException, IOException;

	/**
	* Returns the set of all environment configuration elements loaded by default upon login (e.g., the result of
	* <code>module -t list</code> in a login shell). Note that the ordering of modules is important and must be retained.
	*
	* @param pm
	* progress monitor used to report the status of potentially long-running operations to the user (non-
	* <code>null</code>)
	*
	* @return unmodifiable List (non-<code>null</code>)
	*
	* @throws NullPointerException
	* if {@link #configure(IRemoteConnection)} has not been called
	* @throws RemoteConnectionException
	* if an remote connection error occurs
	* @throws IOException
	* if an input/output error occurs
	* @since 2.0
	*/
	public List<String> determineDefaultElements(IProgressMonitor pm) throws RemoteConnectionException, IOException;

	/**
	* Returns a single Bash shell command which will configure the remote environment with the given elements and then execute the
	* given command.
	* <p>
	* The returned command may include sequencing, piping, I/O redirection, etc.; however, it must be possible to concatenate
	* additional Bash commands by appending a semicolon.
	*
	* @param separator
	* string that will be inserted between consecutive Bash commands: typically, either a semicolon or a newline
	* @param echo
	* true iff the script should "echo" each command prior to execution
	* @param config
	* environment manager configuration (non-<code>null</code>)
	* @param commandToExecuteAfterward
	* a Bash shell command to execute after the environment has been configured
	*
	* @return a single Bash shell command which will configure the remote environment with the given elements and then execute the
	* given command (non-<code>null</code>)
	*/
	public String getBashConcatenation(String separator, boolean echo, IEnvManagerConfig config, String commandToExecuteAfterward);

	/**
	* Creates a temporary file on the remote machine and writes a Bash shell script into that file which will configure the remote
	* environment with the given elements, execute the given command, and then delete the temporary file (shell script).
	*
	* @param pm
	* progress monitor used to report the status of potentially long-running operations to the user (non-
	* <code>null</code>)
	* @param echo
	* true iff the script should "echo" each command prior to execution
	* @param config
	* environment manager configuration (non-<code>null</code>)
	* @param commandToExecuteAfterward
	* a Bash shell command to execute after the environment has been configured
	*
	* @return path to the shell script on the remote machine (non-<code>null</code>)
	*
	* @throws RemoteConnectionException
	* if an remote connection error occurs
	* @throws IOException
	* if an input/output error occurs
	*/
	public String createBashScript(IProgressMonitor pm, boolean echo, IEnvManagerConfig config, String commandToExecuteAfterward)
	throws RemoteConnectionException, IOException;
	}