/*******************************************************************************
 * Copyright (c) 2003, 2006 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
 *******************************************************************************/
package org.eclipse.debug.core.sourcelookup;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IAdaptable;

/**
 * A source container is a container of source code. A source container is
 * capable of searching for source elements by name. For example, a source
 * container may be a project or a directory capable of searching for files
 * by name. A source container may be a composite container - i.e. contain
 * other source containers.
 * <p>
 * When a source container is created and added to a source director, the
 * source container's <code>dispose()</code> method is called when the
 * source director is disposed. Clients creating source containers for other
 * purposes must dispose of containers themselves.
 * </p>
 * <p>
 * Clients may implement this interface.
 * </p>
 * @see ISourceLookupParticipant
 * @see ISourceContainerType
 * @since 3.0
 */
public interface ISourceContainer extends IAdaptable {

	/**
	 * Notification this source container has been added to the given
	 * source lookup director.
	 *
	 * @param director the director this container has been added to
	 */
	public void init(ISourceLookupDirector director);

	/**
	 * Returns a collection of source elements in this container corresponding to the
	 * given name. Returns an empty collection if no source elements are found.
	 * This source container's source lookup director specifies if duplicate
	 * source elements should be searched for, via <code>isFindDuplicates()</code>.
	 * When <code>false</code> the returned collection should contain at most one
	 * source element. If this is a composite container, the containers contained
	 * by this container are also searched.
	 * <p>
	 * The format of the given name is implementation specific but generally conforms
	 * to the format of a file name. If a source container does not recognize the
	 * name format provided, an empty collection should be returned. A source container
	 * may or may not require names to be fully qualified (i.e. be qualified with directory
	 * names).
	 * </p>
	 * @param name the name of the source element to search for
	 * @return a collection of source elements corresponding to the given name
	 * @exception CoreException if an exception occurs while searching for source elements
	 */
	public Object[] findSourceElements(String name) throws CoreException;

	/**
	 * The name of this source container that can be used for presentation purposes.
	 * For example, the name of a project.
	 *
	 * @return the name of this source container
	 */
	public String getName();

	/**
	 * Returns the source containers this container is composed of. An empty
	 * collection is returned if this container is not a composite container.
	 * For example, a workspace source container may be composed of project source
	 * containers.
	 *
	 * @return the source containers this container is composed of, possibly
	 *  an empty collection
	 * @exception CoreException if unable to retrieve source containers
	 */
	public ISourceContainer[] getSourceContainers() throws CoreException;

	/**
	 * Returns whether this container is a composite container. A composite
	 * container is composed of other source containers. For example, a workspace
	 * source container may be composed of project source containers.
	 *
	 * @return whether this container is a composite container
	 */
	public boolean isComposite();

	/**
	 * Returns this container's type.
	 *
	 * @return this container's type
	 */
	public ISourceContainerType getType();

	/**
	 * Disposes this source container. This method is called when the source
	 * director associated with this source container is disposed.
	 */
	public void dispose();

}