Copyright (c) 2005, 2012 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation
/*******************************************************************************
 * Copyright (c) 2005, 2012 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jdt.launching.environments;

import java.util.Map;
import java.util.Properties;

import org.eclipse.jdt.core.IAccessRule;
import org.eclipse.jdt.core.IJavaProject;
import org.eclipse.jdt.launching.IVMInstall;
import org.eclipse.jdt.launching.LibraryLocation;

An execution environment describes capabilities of
a Java runtime environment (IVMInstall).

An execution environment is contributed in plug-in XML via the
org.eclipse.jdt.launching.executionEnvironments extension
point.


Clients contributing execution environments may provide and implement execution environment
analyzer delegates.

See Also:
IExecutionEnvironmentAnalyzerDelegate
Since:
3.2
@noimplement
This interface is not intended to be implemented by clients.
@noextend
This interface is not intended to be extended by clients./**
 * An execution environment describes capabilities of
 * a Java runtime environment (<code>IVMInstall</code>).
 * <p>
 * An execution environment is contributed in plug-in XML via the
 * <code>org.eclipse.jdt.launching.executionEnvironments</code> extension
 * point.
 * </p>
 * <p>
 * Clients contributing execution environments may provide and implement execution environment
 * analyzer delegates.
 * </p>
 * @since 3.2
 * @see IExecutionEnvironmentAnalyzerDelegate
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IExecutionEnvironment {

	
Returns a unique identifier for this execution environment.
Corresponds to the id attribute in plug-in XML.
Returns:
unique identifier of this execution environment/**
	 * Returns a unique identifier for this execution environment.
	 * Corresponds to the <code>id</code> attribute in plug-in XML.
	 *
	 * @return unique identifier of this execution environment
	 */
	public String getId();

	
Returns a brief human-readable description of this environment.
Returns:
brief human-readable description of this environment./**
	 * Returns a brief human-readable description of this environment.
	 *
	 * @return brief human-readable description of this environment.
	 */
	public String getDescription();

	
Returns a collection of VM installs compatible with this environment,
possibly empty.
Returns:
a collection of VM installs compatible with this environment,
 possibly empty./**
	 * Returns a collection of VM installs compatible with this environment,
	 * possibly empty.
	 *
	 * @return a collection of VM installs compatible with this environment,
	 *  possibly empty.
	 */
	public IVMInstall[] getCompatibleVMs();

	
Returns whether the specified VM install is strictly compatible with
this environment. Returns true to indicate the VM install
is strictly compatible with this environment and false to indicate
the VM install represents a superset of this environment.
Params:
vm – VM install
Returns:
whether the VM install is strictly compatible with this environment/**
	 * Returns whether the specified VM install is strictly compatible with
	 * this environment. Returns <code>true</code> to indicate the VM install
	 * is strictly compatible with this environment and <code>false</code> to indicate
	 * the VM install represents a superset of this environment.
	 *
	 * @param vm VM install
	 * @return whether the VM install is strictly compatible with this environment
	 */
	public boolean isStrictlyCompatible(IVMInstall vm);

	
Returns the VM that is used by default for this execution environment,
or null if none.
Returns:
default VM for this environment or null if none/**
	 * Returns the VM that is used by default for this execution environment,
	 * or <code>null</code> if none.
	 *
	 * @return default VM for this environment or <code>null</code> if none
	 */
	public IVMInstall getDefaultVM();

	
Sets the VM to use by default for this execution environment.
Params:
vm – VM to use by default for this execution environment,
 or null to clear the default setting
Throws:
IllegalArgumentException – if the given VM is not compatible with
 this environment/**
	 * Sets the VM to use by default for this execution environment.
	 *
	 * @param vm VM to use by default for this execution environment,
	 *  or <code>null</code> to clear the default setting
	 * @exception IllegalArgumentException if the given VM is not compatible with
	 *  this environment
	 */
	public void setDefaultVM(IVMInstall vm);

	
Returns a collection of access rules to be applied to the specified VM
libraries for this execution environment in the context of the given project.
An array of access rules is returned for each library specified by
libraries, possibly empty.

Access rules for an execution environment are defined by access rule participants
contributed in a org.eclipse.jdt.launching.executionEnvironments
extension.

Params:
vm – the VM that access rules are requested for
libraries – the libraries that access rules are requested for
project – the project the access rules are requested for or null if none
Returns:
a collection of arrays of access rules - one array per library
Since:
3.3/**
	 * Returns a collection of access rules to be applied to the specified VM
	 * libraries for this execution environment in the context of the given project.
	 * An array of access rules is returned for each library specified by
	 * <code>libraries</code>, possibly empty.
	 * <p>
	 * Access rules for an execution environment are defined by access rule participants
	 * contributed in a <code>org.eclipse.jdt.launching.executionEnvironments</code>
	 * extension.
	 * </p>
	 * @param vm the VM that access rules are requested for
	 * @param libraries the libraries that access rules are requested for
	 * @param project the project the access rules are requested for or <code>null</code> if none
	 * @return a collection of arrays of access rules - one array per library
	 * @since 3.3
	 */
	public IAccessRule[][] getAccessRules(IVMInstall vm, LibraryLocation[] libraries, IJavaProject project);

	
Returns the OSGi profile properties associated with this execution environment
or null if none. Profile properties specify attributes such as Constants.FRAMEWORK_SYSTEMPACKAGES. Profile properties can be optionally contributed with an execution environment extension. 
Returns:
associated profile properties or null if none
Since:
3.5/**
	 * Returns the OSGi profile properties associated with this execution environment
	 * or <code>null</code> if none. Profile properties specify attributes such as
	 * {@link org.osgi.framework.Constants#FRAMEWORK_SYSTEMPACKAGES}. Profile properties
	 * can be optionally contributed with an execution environment extension.
	 *
	 * @return associated profile properties or <code>null</code> if none
	 * @since 3.5
	 */
	public Properties getProfileProperties();

	
Returns a collection of execution environments that are subsets of this environment.
Returns:
a collection of execution environments that are subsets of this environment
Since:
3.5/**
	 * Returns a collection of execution environments that are subsets of this environment.
	 *
	 * @return a collection of execution environments that are subsets of this environment
	 * @since 3.5
	 */
	public IExecutionEnvironment[] getSubEnvironments();

	
Returns a map of Eclipse Java compiler options specified as default settings to
use when building with this profile, or null if unspecified.
Returns:
a map of Eclipse Java compiler options associated with this profile or
	null
Since:
3.5/**
	 * Returns a map of Eclipse Java compiler options specified as default settings to
	 * use when building with this profile, or <code>null</code> if unspecified.
	 *
	 * @return a map of Eclipse Java compiler options associated with this profile or
	 * 	<code>null</code>
	 * @since 3.5
	 */
	public Map<String, String> getComplianceOptions();
}