/*
 *                 Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 *
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2004 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.netbeans.api.project;

import org.openide.filesystems.FileObject;
import org.openide.util.Lookup;

/**
 * Represents one IDE project in memory.
 * 

 * Never cast a project instance to any subtype. The project
 * manager is free to wrap any project in an unspecified proxy for its own
 * purposes. For extensibility, use {@link #getLookup}.
 * 
 * 

 * 
Note that this API is primarily of interest to project type provider
 * modules, and to infrastructure and generic GUI. Most other modules providing
 * tools or services should not need to explicitly model projects, and
 * should not be using this API much or at all.
 * 
 * @author Jesse Glick
 */
public interface Project extends Lookup.Provider {
    
    /**
     * Gets an associated directory where the project metadata and possibly sources live.
     * In the case of a typical Ant project, this is the top directory, not the
     * project metadata subdirectory.
     * @return a directory
     */
    FileObject getProjectDirectory();
    
    /**
     * Get any optional abilities of this project.
     * 

     * 
If you are providing a project, there are a number of interfaces
     * which you should consider implementing and including in lookup, some of which
     * are described below. If you are using a project from another module,
     * there are some cases where you will want to ask a project for a particular
     * object in lookup (e.g. ExtensibleMetadataProvider) but in most
     * cases you should not; in the case of queries, always call the static query
     * API helper method, rather than looking for the query implementation objects
     * yourself. In the case of ProjectInformation and Sources,
     * use {@link ProjectUtils} rather than directly searching the project lookup.
     * 
     * 
The following abilities are recommended:
     * 

     * 
{@link org.netbeans.api.project.ProjectInformation}
     * 
LogicalViewProvider
     * 
CustomizerProvider
     * 
{@link org.netbeans.api.project.Sources}
     * 
{@link org.netbeans.spi.project.ActionProvider}
     * 
{@link org.netbeans.spi.project.SubprojectProvider}
     * 
{@link org.netbeans.spi.project.AuxiliaryConfiguration}
     * 
{@link org.netbeans.spi.project.CacheDirectoryProvider}
     * 
     * 
You might also have e.g.:
     * 

     * 
{@link org.netbeans.spi.queries.FileBuiltQueryImplementation}
     * 
ProjectOpenedHook
     * 
RecommendedTemplates
     * 
PrivilegedTemplates
     * 
ClassPathProvider
     * 
SourceForBinaryQueryImplementation
     * 
JavadocForBinaryQueryImplementation
     * 
AccessibilityQueryImplementation
     * 
ProjectXmlSavedHook
     * 
AntArtifactProvider
     * 
UnitTestForSourceQueryImplementation
     * 
     * 
Typical implementation:
     * 
     * private final Lookup lookup = Lookups.fixed(new Object[] {
     *     new MyAbility1(this),
     *     // ...
     * });
     * public Lookup getLookup() {
     *     return lookup;
     * }
     * 
     * 
     * @return a set of abilities
     */
    Lookup getLookup();
    
}