/*
 *                 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-2003 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.openide;

import org.openide.nodes.Node;
import org.openide.loaders.DataFilter;
import org.openide.loaders.DataFolder;

/** Provides access to all basic components ("places") in the IDE.
* One can obtain folders for templates, project files,
* a node for the repository, etc.
* @deprecated Nothing here remains undeprecated.
* @author Jaroslav Tulach
*/
public interface Places {
    /** Interesting places for nodes.
    * @return group of interesting nodes
     * @deprecated Nothing left to use.
    */
    public Nodes nodes ();

    /** Interesting places for data objects.
    * @return group of interesting data objects
    * @deprecated Just as easy to access folders by resource name.
    */
    public Folders folders ();

    /** Provides access to important node places.
     * @deprecated Nothing left to use.
    */
    public interface Nodes {
        /** Get the Repository node.
         * @return the node
         * @deprecated Use {@link org.openide.loaders.RepositoryNodeFactory#repository} instead.
        */
        public Node repository ();

        /** Get a Repository node with a given data filter.
         * @param f the requested filter
         * @return the node
         * @deprecated Use {@link org.openide.loaders.RepositoryNodeFactory#repository} instead.
         */
        public Node repository(DataFilter f);

        /** Get a root of packages with a given data filter.
         * Note: This method is no longer supported.
         * @param f the requested filter
         * @return the node
         * @deprecated From version 3.10 no longer supported.
         * Please use the ClassPath API instead.
         */
        public Node packages (DataFilter f);

        /** Get a node with all installed loaders.
         * @return the node
         * @deprecated Should not be needed by modules.
        */
        public Node loaderPool ();

        /** Get the control panel node.
         * @return the node
         * @deprecated Typically no longer meaningful.
        */
        public Node controlPanel ();

        /** Get the project settings node.
         * @return the node
         * @deprecated Typically no longer meaningful.
        */
        public Node project ();

        /** Get the environment node.
         * This node holds all transient information about
        * the IDE.
         * @return the node
         * @deprecated Should not be needed by modules.
        */
        public Node environment ();

        /** Get the session node.
        * This node holds all global information about the IDE.
        * @return the node
        * @deprecated Typically no longer meaningful.
        */
        public Node session ();

        /** Get a node with all workspaces.
         * @return the node
         * @deprecated Should not be needed by modules.
         */
        public Node workspaces ();

        /** Get the Repository settings node.
         * @return the node
         * @deprecated Should not be needed by modules.
         */
        public Node repositorySettings ();

        /** Get the Desktop node for the current project.
         * This node can change when a new project is selected.
         * 
Warning! do not assume that this node
         * does anything in particular. It is just a node, its contents
         * are unspecified, though it might have some useful cookies.
         * If you are looking for the IDE's "current project"
         * or similar information you are likely to be disappointed.
         * @return the node
         * @deprecated Semantics are very ill-defined and prior usages will probably no longer work.
        */
        public Node projectDesktop ();

        /** Get all root nodes.
         * These nodes are the ones which will be displayed as "top-level" roots.
         * Modules typically add to this set.
        * @return the nodes
         * @deprecated Should not be needed by modules.
        */
        public Node[] roots ();
    }

    /** Provides access to important folders.
     * @deprecated Most users of these folders will be using their paths directly in XML layers;
     * since these paths are necessarily defined in the APIs anyway, using a method call for each
     * location is not necessary. For example, rather than calling templates(), you can use:
     * 
     * FileObject fo = Repository.getDefault().getDefaultFileSystem().findResource("Templates");
     * if (fo != null) {
     *     DataFolder templates = DataFolder.findFolder(fo);
     * }
     * 
    */
    public interface Folders {
        /** Get the default folder for templates.
         * @return the folder
        */
        public DataFolder templates ();

        /** Get the folder for toolbars.
         * @return the folder
        */
        public DataFolder toolbars ();

        /** Get the folder for menus.
         * @return the folder
        */
        public DataFolder menus ();

        /** Get the folder for actions pool.
         * @return the folder
        */
        public DataFolder actions ();

        /** Get the folder for bookmarks.
         * @return the folder
        */
        public DataFolder bookmarks ();

        /** Get the folder for projects.
         * @return the folder
        */
        public DataFolder projects ();

        /** Get the startup folder.
         * Files in this folder implementing {@link org.openide.cookies.ExecCookie}
         * will be run upon startup of the IDE.
         * @return the folder
        */
        public DataFolder startup ();

        /** Get the welcome folder.
         * Files in this folder with instances should be used in the welcome screen.
         * @return the folder
         */
        public DataFolder welcome ();
    }
}