/*******************************************************************************
 * Copyright (c) 2000, 2015 IBM Corporation 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:
 *     IBM Corporation - initial API and implementation
 *     Frits Jalvingh - Contribution for Bug 459831 - [launching] Support attaching 
 *     	external annotations to a JRE container
 *******************************************************************************/
package org.eclipse.jdt.launching;


import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IPath;
import org.eclipse.jdt.core.IClasspathEntry;
import org.eclipse.jdt.core.IJavaProject;

/**
 * Represents an entry on a runtime classpath. A runtime classpath entry
 * may refer to one of the following:
 * <ul>
 * 	<li>A Java project (type <code>PROJECT</code>) - a project entry refers
 * 		to all of the built classes in a project, and resolves to the output
 * 		location(s) of the associated Java project.</li>
 * 	<li>An archive (type <code>ARCHIVE</code>) - an archive refers to a jar, zip, or
 * 		folder in the workspace or in the local file system containing class
 * 		files. An archive may have attached source.</li>
 * 	<li>A variable (type <code>VARIABLE</code>) - a variable refers to a 
 * 		classpath variable, which may refer to a jar.</li>
 * 	<li>A library (type <code>CONTAINER</code>) - a container refers to classpath
 * 		container variable which refers to a collection of archives derived
 * 		dynamically, on a per project basis.</li>
 *  <li>A contributed classpath entry (type <code>OTHER</code>) - a contributed
 *      classpath entry is an extension contributed by a plug-in. The resolution
 *      of a contributed classpath entry is client defined. See
 * 		<code>IRuntimeClasspathEntry2</code>.
 * </ul>
 * <p>
 * Clients may implement this interface for contributing a classpath entry
 * type (i.e. type <code>OTHER</code>). Note, contributed classpath entries
 * are new in 3.0, and are only intended to be contributed by the Java debugger.
 * </p>
 * @since 2.0
 * @see org.eclipse.jdt.launching.IRuntimeClasspathEntry2
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IRuntimeClasspathEntry {
	
	/**
	 * Type identifier for project entries.
	 */
	public static final int PROJECT = 1;
	
	/**
	 * Type identifier for archive entries.
	 */
	public static final int ARCHIVE = 2;	
		
	/**
	 * Type identifier for variable entries.
	 */
	public static final int VARIABLE = 3;
	
	/**
	 * Type identifier for container entries.
	 */
	public static final int CONTAINER = 4;
	
	/**
	 * Type identifier for contributed entries.
	 * @since 3.0
	 */
	public static final int OTHER = 5;	

	/**
	 * Classpath property identifier for entries that appear on the
	 * bootstrap path by default.
	 */
	public static final int STANDARD_CLASSES = 1;	
	
	/**
	 * Classpath property identifier for entries that should appear on the
	 * bootstrap path explicitly.
	 */
	public static final int BOOTSTRAP_CLASSES = 2;	
		
	/**
	 * Classpath property identifier for entries that should appear on the
	 * user classpath.
	 */
	public static final int USER_CLASSES = 3;	
	
	/**
	 * Returns this classpath entry's type. The type of a runtime classpath entry is
	 * identified by one of the following constants:
	 * <ul>
	 * <li><code>PROJECT</code></li>
	 * <li><code>ARCHIVE</code></li>
	 * <li><code>VARIABLE</code></li>
	 * <li><code>CONTAINER</code></li>
	 * <li><code>OTHER</code></li>
	 * </ul>
	 * <p>
	 * Since 3.0, a type of <code>OTHER</code> may be returned.
	 * </p>
	 * @return this classpath entry's type
	 */
	public int getType();
	
	/**
	 * Returns a memento for this classpath entry.
	 * <p>
	 * Since 3.0, the memento for a contributed classpath entry (i.e. of
	 * type <code>OTHER</code>), must be in the form of an XML document,
	 * with the following element structure:
	 * <pre>
	 * <runtimeClasspathEntry id="exampleId">
	 *    <memento
	 *       key1="value1"
	 * 		 ...>
	 *    </memento>
	 * </runtimeClasspathEntry>
	 * </pre>
	 * The <code>id</code> attribute is the unique identifier of the extension
	 * that contributed this runtime classpath entry type, via the extension
	 * point <code>org.eclipse.jdt.launching.runtimeClasspathEntries</code>.
	 * The <code>memento</code> element will be used to initialize a
	 * restored runtime classpath entry, via the method
	 * <code>IRuntimeClasspathEntry2.initializeFrom(Element memento)</code>. The 
	 * attributes of the <code>memento</code> element are client defined.
	 * </p>
	 * 
	 * @return a memento for this classpath entry
	 * @exception CoreException if an exception occurs generating a memento
	 */
	public String getMemento() throws CoreException;
	
	/**
	 * Returns the path associated with this entry, or <code>null</code>
	 * if none. The format of the
	 * path returned depends on this entry's type:
	 * <ul>
	 * <li><code>PROJECT</code> - a workspace relative path to the associated
	 * 		project.</li>
	 * <li><code>ARCHIVE</code> - the absolute path of the associated archive,
	 * 		which may or may not be in the workspace.</li>
	 * <li><code>VARIABLE</code> - the path corresponding to the associated
	 * 		classpath variable entry.</li>
	 * <li><code>CONTAINER</code> - the path corresponding to the associated
	 * 		classpath container variable entry.</li>
	 * <li><code>OTHER</code> - the path returned is client defined.</li>
	 * </ul>
	 * <p>
	 * Since 3.0, this method may return <code>null</code>.
	 * </p>
	 * @return the path associated with this entry, or <code>null</code>
	 * @see org.eclipse.jdt.core.IClasspathEntry#getPath()
	 */
	public IPath getPath();
		
	/**
	 * Returns the resource associated with this entry, or <code>null</code>
	 * if none. A project, archive, or folder entry may be associated
	 * with a resource.
	 * 
	 * @return the resource associated with this entry, or <code>null</code>
	 */ 
	public IResource getResource();
	
	/**
	 * Returns the path to the source archive associated with this
	 * entry, or <code>null</code> if this classpath entry has no
	 * source attachment.
	 * <p>
	 * Only archive and variable entries may have source attachments.
	 * For archive entries, the path (if present) locates a source
	 * archive. For variable entries, the path (if present) has
	 * an analogous form and meaning as the variable path, namely the first segment 
	 * is the name of a classpath variable.
	 * </p>
	 *
	 * @return the path to the source archive, or <code>null</code> if none
	 */
	public IPath getSourceAttachmentPath();

	/**
	 * Sets the path to the source archive associated with this
	 * entry, or <code>null</code> if this classpath entry has no
	 * source attachment.
	 * <p>
	 * Only archive and variable entries may have source attachments.
	 * For archive entries, the path refers to a source
	 * archive. For variable entries, the path has
	 * an analogous form and meaning as the variable path, namely the
	 * first segment  is the name of a classpath variable.
	 * </p>
	 * <p>
	 * Note that an empty path (<code>Path.EMPTY</code>) is considered
	 * <code>null</code>.
	 * </p>
	 *
	 * @param path the path to the source archive, or <code>null</code> if none
	 */
	public void setSourceAttachmentPath(IPath path);
	
	/**
	 * Returns the path within the source archive where package fragments
	 * are located. An empty path indicates that packages are located at
	 * the root of the source archive. Returns a non-<code>null</code> value
	 * if and only if <code>getSourceAttachmentPath</code> returns 
	 * a non-<code>null</code> value.
	 *
	 * @return root path within the source archive, or <code>null</code> if
	 *    not applicable
	 */
	public IPath getSourceAttachmentRootPath();
	
	/**
	 * Sets the path within the source archive where package fragments
	 * are located. A root path indicates that packages are located at
	 * the root of the source archive. Only valid if a source attachment
	 * path is also specified.
	 * <p>
	 * Note that an empty path (<code>Path.EMPTY</code>) is considered
	 * <code>null</code>.
	 * </p>
	 * 
	 * @param path root path within the source archive, or <code>null</code>
	 */	
	public void setSourceAttachmentRootPath(IPath path);
	
	/**
	 * Returns the path to the external annotations file or directory, or <code>null</code> 
	 * if no external annotations are associated with this classpath entry.
	 * 
	 * @since 3.8
	 * @return The path to the external annotations file or directory, or <code>null</code> 
	 * 		if not present.
	 */
	public IPath getExternalAnnotationsPath();

	/**
	 * Sets the path to the external annotations file or directory. It should be set to
	 * <code>null</code> if no annotations are associated with this entry. 
	 * 
	 * @since 3.8
	 * @param path The file or directory holding external annotations.
	 */
	public void setExternalAnnotationsPath(IPath path);

	/**
	 * Returns a constant indicating where this entry should appear on the 
	 * runtime classpath by default.
	 * The value returned is one of the following:
	 * <ul>
	 * <li><code>STANDARD_CLASSES</code> - a standard entry does not need to appear
	 * 		on the runtime classpath</li>
	 * <li><code>BOOTSTRAP_CLASSES</code> - a bootstrap entry should appear on the
	 * 		boot path</li>
	 * <li><code>USER_CLASSES</code> - a user entry should appear on the path
	 * 		containing user or application classes</li>
	 * </ul>
	 * 
	 * @return where this entry should appear on the runtime classpath
	 */
	public int getClasspathProperty();
	
	/**
	 * Sets whether this entry should appear on the bootstrap classpath,
	 * the user classpath, or whether this entry is a standard bootstrap entry
	 * that does not need to appear on the classpath.
	 * The location is one of:
	 * <ul>
	 * <li><code>STANDARD_CLASSES</code> - a standard entry does not need to appear
	 * 		on the runtime classpath</li>
	 * <li><code>BOOTSTRAP_CLASSES</code> - a bootstrap entry should appear on the
	 * 		boot path</li>
	 * <li><code>USER_CLASSES</code> - a user entry should appear on the path
	 * 		conatining user or application classes</li>
	 * </ul>
	 * 
	 * @param location a classpat property constant
	 */
	public void setClasspathProperty(int location);	
	
	/**
	 * Returns an absolute path in the local file system for this entry,
	 * or <code>null</code> if none, or if this entry is of type <code>CONTAINER</code>.
	 * 
	 * @return an absolute path in the local file system for this entry,
	 *  or <code>null</code> if none
	 */
	public String getLocation();
		
	/**
	 * Returns an absolute path in the local file system for the source
	 * attachment associated with this entry entry, or <code>null</code> if none.
	 * 
	 * @return an absolute path in the local file system for the source
	 *  attachment associated with this entry entry, or <code>null</code> if none
	 */
	public String getSourceAttachmentLocation();	
	
	/**
	 * Returns a path relative to this entry's source attachment path for the
	 * root location containing source, or <code>null</code> if none.
	 * 
	 * @return a path relative to this entry's source attachment path for the
	 *  root location containing source, or <code>null</code> if none
	 */
	public String getSourceAttachmentRootLocation();		
	
	/**
	 * Returns the first segment of the path associated with this entry, or <code>null</code>
	 * if this entry is not of type <code>VARIABLE</code> or <code>CONTAINER</code>.
	 * 
	 * @return the first segment of the path associated with this entry, or <code>null</code>
	 *  if this entry is not of type <code>VARIABLE</code> or <code>CONTAINER</code>
	 */
	public String getVariableName();
	
	/**
	 * Returns a classpath entry equivalent to this runtime classpath entry,
	 * or <code>null</code> if none.
	 * <p>
	 * Since 3.0, this method may return <code>null</code>.
	 * </p>
	 * @return a classpath entry equivalent to this runtime classpath entry,
	 *  or <code>null</code>
	 * @since 2.1
	 */
	public IClasspathEntry getClasspathEntry();
	
	/**
	 * Returns the Java project associated with this runtime classpath entry
	 * or <code>null</code> if none. Runtime classpath entries of type
	 * <code>CONTAINER</code> may be associated with a project for the
	 * purposes of resolving the entries in a container. 
	 * 
	 * @return the Java project associated with this runtime classpath entry
	 * or <code>null</code> if none
	 * @since 3.0
	 */
	public IJavaProject getJavaProject();
}