ui/org.eclipse.pde.core/src/org/eclipse/pde/core/target/ITargetDefinition.java

/*******************************************************************************
 * Copyright (c) 2008, 2018 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
 *     Lucas Bullen (Red Hat Inc.) - [Bug 531602] formatting munged by editor
 *******************************************************************************/
package org.eclipse.pde.core.target;

import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.MultiStatus;
import org.eclipse.jdt.launching.JavaRuntime;
import org.eclipse.osgi.service.environment.Constants;
import org.w3c.dom.Document;

/**
 * Defines a target platform. A target platform is a collection of bundles and
 * features configured for a specific environment.
 *
 * @see ITargetPlatformService Use the target platform service to work with target definitions
 *
 * @since 3.8
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface ITargetDefinition {

	/**
	 * Resolves all contents of this target definition by resolving each
	 * {@link ITargetLocation} in this target definition.
	 * <p>
	 * Returns a {@link MultiStatus} containing any non-OK statuses produced
	 * when resolving each {@link ITargetLocation}.  An OK status will be
	 * returned if no non-OK statuses are returned from the locations. A
	 * CANCEL status will be returned if the monitor is cancelled.
	 * </p><p>
	 * For more information on how a target resolves, see
	 * {@link ITargetLocation#resolve(ITargetDefinition, IProgressMonitor)}
	 * </p>
	 *
	 * @param monitor progress monitor or <code>null</code>
	 * @return resolution multi-status
	 */
	IStatus resolve(IProgressMonitor monitor);

	/**
	 * Returns whether all {@link ITargetLocation}s in this target currently in
	 * a resolved state.
	 *
	 * @return <code>true</code> if all locations are currently resolved
	 */
	boolean isResolved();

	/**
	 * Sets the XML document that stores the state of this target. The document is
	 * updated with each setter that has an affect on the target file source.
	 *
	 * @param document
	 *                     xml document or <code>null</code>
	 * @since 3.12
	 */
	void setDocument(Document document);

	/**
	 * Returns the Document that represents this target, or <code>null</code> if
	 * none
	 *
	 * @return document or <code>null</code>
	 * @since 3.12
	 */
	Document getDocument();

	/**
	 * Returns all bundles included in this target definition or <code>null</code>
	 * if this container is not resolved. Takes all the bundles available from the
	 * set target locations (returned by {@link #getAllBundles()} and applies
	 * the filters (returned by {@link #getIncluded()})
	 * to determine the final list of bundles in this target.
	 * <p>
	 * Some of the returned bundles may have non-OK statuses. These bundles may be
	 * missing some information (location, version, source target). To get a bundle's
	 * status call {@link TargetBundle#getStatus()}. Calling {@link #getStatus()}
	 * will return all problems in this target definition.
	 * </p>
	 * @return resolved bundles or <code>null</code>
	 */
	TargetBundle[] getBundles();

	/**
	 * Returns a list of all resolved bundles in this target definition or <code>null</code>.
	 * Does not filter based on any filters ({@link #getIncluded()}.
	 * Returns <code>null</code> if this target has not been resolved.
	 * Use {@link #getBundles()} to get the filtered list of bundles.
	 * <p>
	 * Some of the returned bundles may have non-OK statuses. These bundles may be
	 * missing some information (location, version, source target). To get a bundle's
	 * status call {@link TargetBundle#getStatus()}. Calling {@link #getStatus()}
	 * will return all problems in this target definition.
	 * </p>
	 *
	 * @return collection of resolved bundles or <code>null</code>
	 */
	TargetBundle[] getAllBundles();

	/**
	 * Returns the list of feature models available in this target or <code>null</code> if
	 * this target has not been resolved.
	 *
	 * @return collection of feature models or <code>null</code>
	 */
	TargetFeature[] getAllFeatures();

	/**
	 * Returns a {@link MultiStatus} containing all problems with this target.
	 * Returns an OK status if there are no problems. Returns <code>null</code>
	 * if this target has not been resolved.
	 * <p>
	 * The returned status will include all non-OK statuses returned by
	 * {@link #resolve(IProgressMonitor)} as well as any non-OK statuses found
	 * in {@link TargetBundle}s returned by {@link #getBundles()}. For more
	 * information on the statuses that can be returned see
	 * {@link ITargetLocation#getStatus()} and {@link TargetBundle#getStatus()}.
	 * </p>
	 *
	 * @return {@link MultiStatus} containing all problems with this target or
	 *         <code>null</code>
	 */
	IStatus getStatus();

	/**
	 * Returns a handle to this target definition.
	 *
	 * @return target handle
	 */
	ITargetHandle getHandle();

	/**
	 * Returns the name of this target, or <code>null</code> if none
	 *
	 * @return name or <code>null</code>
	 */
	String getName();

	/**
	 * Sets the name of this target.
	 *
	 * @param name target name or <code>null</code>
	 */
	void setName(String name);

	/**
	 * Returns the locations defined by this target, possible <code>null</code>.
	 *
	 * @return target locations or <code>null</code>
	 */
	ITargetLocation[] getTargetLocations();

	/**
	 * Sets the locations in this target definition or <code>null</code> if none.
	 *
	 * @param containers target locations or <code>null</code>
	 */
	void setTargetLocations(ITargetLocation[] containers);

	/**
	 * Returns a list of descriptors that filter the resolved plug-ins in this target.  The list may include
	 * both plug-ins and features.  The returned descriptors will have an id, may have a version and will have
	 * either {@link NameVersionDescriptor#TYPE_FEATURE} or {@link NameVersionDescriptor#TYPE_PLUGIN} as their
	 * type.  If the target is set to include all units (no filtering is being done), this method will return
	 * <code>null</code>.
	 *
	 * @see #getBundles()
	 * @see #setIncluded(NameVersionDescriptor[])
	 * @return list of name version descriptors or <code>null</code>
	 */
	NameVersionDescriptor[] getIncluded();

	/**
	 * Sets a list of descriptors to filter the resolved plug-ins in this target.  The list may include both
	 * plug-ins and features.  To include all plug-ins in the target, pass <code>null</code> as the argument.
	 * <p>
	 * The descriptions passed to this method must have an ID set.  The version may be <code>null</code>
	 * to include any version of the matches the ID.  Only descriptors with a type of {@link NameVersionDescriptor#TYPE_FEATURE}
	 * or {@link NameVersionDescriptor#TYPE_PLUGIN} will be considered.
	 * </p>
	 * @see #getBundles()
	 * @see #getIncluded()
	 * @param included list of descriptors to include in the target or <code>null</code> to include all plug-ins
	 */
	void setIncluded(NameVersionDescriptor[] included);

	/**
	 * Returns JRE container path that this target definition should be built against,
	 * or <code>null</code> if the workspace default JRE should be used. JavaRuntime can be used
	 * to resolve JRE's and execution environments from a container path.
	 *
	 * @return JRE container path or <code>null</code>
	 * @see JavaRuntime
	 */
	IPath getJREContainer();

	/**
	 * Sets the JRE that this target definition should be built against, or <code>null</code>
	 * to use the workspace default JRE. JavaRuntime should be used to generate and parse
	 * JRE container paths.
	 *
	 * @param containerPath JRE container path
	 * @see JavaRuntime
	 */
	void setJREContainer(IPath containerPath);

	/**
	 * Returns the identifier of the operating system this target is configured for,
	 * possibly <code>null</code>.
	 *
	 * @return operating system identifier or <code>null</code> to default to the
	 * 	running operating system
	 */
	String getOS();

	/**
	 * Sets the operating system this target is configured for or <code>null</code> to
	 * default to the running operating system.
	 *
	 * @param os operating system identifier - one of the operating system constants
	 * 	defined by {@link Constants} or <code>null</code> to default to the running
	 * 	operating system
	 */
	void setOS(String os);

	/**
	 * Returns the identifier of the window system this target is configured for,
	 * possibly <code>null</code>.
	 *
	 * @return window system identifier - one of the window system constants
	 * 	defined by {@link Constants}, or <code>null</code> to default to the
	 * 	running window system
	 */
	String getWS();

	/**
	 * Sets the window system this target is configured for or <code>null</code> to
	 * default to the running window system.
	 *
	 * @param ws window system identifier or <code>null</code> to default to the
	 * 	running window system
	 */
	void setWS(String ws);

	/**
	 * Returns the identifier of the architecture this target is configured for,
	 * or <code>null</code> to default to the running architecture.
	 *
	 * @return architecture identifier - one of the architecture constants
	 * 	defined by {@link Constants} or <code>null</code> to default to the running
	 * 	architecture
	 */
	String getArch();

	/**
	 * Sets the architecture this target is configured for, or <code>null</code> to default
	 * to the running architecture.
	 *
	 * @param arch architecture identifier or <code>null</code> to default to the
	 * 	running architecture.
	 */
	void setArch(String arch);

	/**
	 * Returns the identifier of the locale this target is configured for, or <code>null</code>
	 * for default.
	 *
	 * @return locale identifier or <code>null</code> for default
	 */
	String getNL();

	/**
	 * Sets the locale this target is configured for or <code>null</code> for default.
	 *
	 * @param nl locale identifier or <code>null</code> for default
	 */
	void setNL(String nl);

	/**
	 * Returns any program arguments that should be used when launching this target
	 * or <code>null</code> if none.
	 *
	 * @return program arguments or <code>null</code> if none
	 */
	String getProgramArguments();

	/**
	 * Sets any program arguments that should be used when launching this target
	 * or <code>null</code> if none.
	 *
	 * @param args program arguments or <code>null</code>
	 */
	void setProgramArguments(String args);

	/**
	 * Returns any VM arguments that should be used when launching this target
	 * or <code>null</code> if none.
	 *
	 * @return VM arguments or <code>null</code> if none
	 */
	String getVMArguments();

	/**
	 * Sets any VM arguments that should be used when launching this target
	 * or <code>null</code> if none.
	 *
	 * @param args VM arguments or <code>null</code>
	 */
	void setVMArguments(String args);

	/**
	 * Sets implicit dependencies for this target. Bundles in this collection are always
	 * considered by PDE when computing plug-in dependencies. Only symbolic names need to
	 * be specified in the given descriptors.
	 *
	 * @param bundles implicit dependencies or <code>null</code> if none
	 */
	void setImplicitDependencies(NameVersionDescriptor[] bundles);

	/**
	 * Returns the implicit dependencies set on this target or <code>null</code> if none.
	 *
	 * @return implicit dependencies or <code>null</code>
	 */
	NameVersionDescriptor[] getImplicitDependencies();
}