IIndexInclude.java

/*******************************************************************************
 * Copyright (c) 2006, 2009 Wind River Systems, Inc. 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:
 *    Markus Schorn - initial API and implementation
 *    Andrew Ferguson (Symbian)
 *    Sergey Prigogin (Google)
 *******************************************************************************/
package org.eclipse.cdt.core.index;

import org.eclipse.core.runtime.CoreException;

/**
 * Interface for an include directive stored in the index.
 * 
 * @noextend This interface is not intended to be extended by clients.
 * @noimplement This interface is not intended to be implemented by clients.
 * @since 4.0
 */
public interface IIndexInclude {
	IIndexInclude[] EMPTY_INCLUDES_ARRAY = new IIndexInclude[0];

	/**
	 * Returns the file that contains this directive.
	 * @return the file performing the include
	 * @throws CoreException
	 */
	IIndexFile getIncludedBy() throws CoreException;

	/**
	 * Returns the IIndexFileLocation of the file that contains this directive.
	 * @return the IIndexFileLocation of the file performing the include
	 * @throws CoreException
	 */
	IIndexFileLocation getIncludedByLocation() throws CoreException;
	
	/**
	 * Returns the IIndexFileLocation of the file that is included by this
	 * directive. In case of an unresolved include <code>null</code>
	 * will be returned.
	 * 
	 * @return the IIndexFileLocation of the file that is included by this
	 *         directive or <code>null</code> if the include is unresolved or
	 *         inactive
	 * @throws CoreException
	 */
	IIndexFileLocation getIncludesLocation() throws CoreException;
	
	/**
	 * Returns the simple name of the directive. This skips any leading
	 * directories. E.g.: for '<sys/types.h>' 'types.h' will be returned.
	 * @throws CoreException 
	 */
	String getName() throws CoreException;

	/**
	 * Returns the name of the include. The name does not include the enclosing quotes
	 * or angle brackets. E.g.: for '<sys/types.h>' 'sys/types.h' will be returned.
	 * @throws CoreException 
	 * @since 5.1
	 */
	String getFullName() throws CoreException;

	/**
	 * Returns the character offset of the name of the include in its source file.
	 * The name does not include the enclosing quotes or angle brackets.
	 * @throws CoreException 
	 */
	int getNameOffset() throws CoreException;

	/**
	 * Returns the length of the name of the include. The name does
	 * not include the enclosing quotes or angle brackets.
	 * @throws CoreException 
	 */
	int getNameLength() throws CoreException;

	/** 
	 * Returns whether this is a system include (an include specified within angle
	 * brackets).
	 * @throws CoreException 
	 */
	boolean isSystemInclude() throws CoreException;

	/**
	 * Test whether this include is in active code (not skipped by conditional preprocessing).
	 * @return whether this include is in active code
	 * @throws CoreException
	 */
	boolean isActive() throws CoreException;

	/**
	 * Test whether this include has been resolved (found in the file system).
	 * Inactive includes are not resolved, unless they constitute a hidden dependency.
	 * This is the case when an include is inactive because it has been included before:
	 * <code>
	 *   #ifndef _header_h
	 *   #include "header.h"
	 *   #endif
	 * <code>
	 * 
	 * @return whether this is a resolved include
	 * @throws CoreException
	 */
	boolean isResolved() throws CoreException;
	
	/**
	 * Tests whether this include has been resolved using a heuristics rather than relying on
	 * the include search path.
	 * @since 5.1
	 */
	boolean isResolvedByHeuristics() throws CoreException;
}