/*
 *                 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 java.awt.Dialog;
import java.awt.Toolkit;
import java.awt.event.*;
import java.beans.PropertyChangeListener;
import java.beans.PropertyChangeSupport;
import java.io.IOException;
import java.lang.reflect.Method;
import java.net.URL;
import java.security.AllPermission;
import java.security.PermissionCollection;
import java.security.Permissions;
import java.util.Iterator;
import java.util.Observable;
import java.util.Observer;
import javax.swing.text.Keymap;

import org.openide.actions.ActionManager;
import org.openide.awt.HtmlBrowser;
import org.openide.awt.StatusDisplayer;
import org.openide.compiler.CompilationEngine;
import org.openide.cookies.ProjectCookie;
import org.openide.debugger.Debugger;
import org.openide.debugger.DebuggerNotFoundException;
import org.openide.execution.ExecutionEngine;
import org.openide.execution.NbClassLoader;
import org.openide.filesystems.Repository;
import org.openide.loaders.*;
import org.openide.modules.ModuleInfo;
import org.openide.options.ControlPanel;
import org.openide.util.HelpCtx;
import org.openide.util.Lookup;
import org.openide.util.LookupEvent;
import org.openide.util.LookupListener;
import org.openide.util.UserCancelException;
import org.openide.util.datatransfer.ExClipboard;
import org.openide.windows.IOProvider;
import org.openide.windows.OutputWriter;
import org.openide.windows.InputOutput;
import org.openide.windows.WindowManager;

/** Heart of the whole IDE.
* Provides initial access to all features in the system.
* Use {@link #getDefault} to obtain the default instance in the system.
*
* @author Jaroslav Tulach, Ales Novak, Ian Formanek, Petr Hamernik,
*   Jan Jancura, Dafe Simonek
 * @deprecated All functionality in this class is now available in other
 * places, at a finer level of granularity.
*/
public abstract class TopManager extends Object {
    /** Name of property for the debugger.
     * @deprecated use lookup listeners (and Debugger is deprecated anyway)
     */
    public static final String PROP_DEBUGGER = "debugger"; // NOI18N

    /** Name of property for the global keymap.
     * @deprecated There is no official support in Keymap for listening to changes.
     *             The Keymap impl might extend {@link Observable}, in which case you can
     *             observe it, but this is not guaranteed.
     *             More commonly, you can just listen to {@link javax.swing.Action#ACCELERATOR_KEY}.
     */
    public static final String PROP_GLOBAL_KEYMAP = "globalKeymap"; // NOI18N

    /** Name of property for the Places object.
    * This is most likely to change when a new project is opened.
     * @deprecated Places is deprecated.
    */
    public static final String PROP_PLACES = "places"; // NOI18N

    private static TopManager DEFAULT = null;
    /**
     * Get the default top manager for the system.
     * @return the default
     * @deprecated TopManager is deprecated. If you want to force initialization of the module system,
     *             try getting {@link ModuleInfo} from Lookup.
     */
    public static synchronized TopManager getDefault () {
        if (DEFAULT == null) {
            // Initialize module system, maybe.
            Lookup.getDefault().lookup(ModuleInfo.class);
            // Now find impl in lookup.
            DEFAULT = (TopManager)Lookup.getDefault().lookup(TopManager.class);
            if (DEFAULT == null) throw new IllegalStateException("No TopManager found. Was core-deprecated.jar not turned on? Lookup=" + Lookup.getDefault()); // NOI18N
        }
        return DEFAULT;
    }

    /** @deprecated Useless. */
    public static void setDefault (TopManager tm) throws SecurityException {
        throw new SecurityException ();
    }

    /** Test to check whether the top manager is initilized or not.
    * @return true if the default instance of top manager has
    * already been created
    * @deprecated Probably always true.
    */
    public static synchronized boolean isInitialized () {
        return getDefault() != null;
    }

    /** Get the Repository of user and system files.
    * @return the repository
    * @deprecated Rather use {@link Repository#getDefault}.
    */
    public Repository getRepository () {
        return Repository.getDefault ();
    }

    /** Display help.
    * @param helpCtx help context to be displayed in help window
    * @deprecated Use Help.showHelp.
    */
    public void showHelp (HelpCtx helpCtx) {
        // Awkward but should work.
        // XXX could instead just make openide-deprecated.jar depend on javahelp-api.jar.
        try {
            Class c = systemClassLoader().loadClass("org.netbeans.api.javahelp.Help"); // NOI18N
            Object o = Lookup.getDefault().lookup(c);
            if (o != null) {
                Method m = c.getMethod("showHelp", new Class[] {HelpCtx.class}); // NOI18N
                m.invoke(o, new Object[] {helpCtx});
                return;
            }
        } catch (ClassNotFoundException cnfe) {
            // ignore - maybe javahelp module is not installed, not so strange
        } catch (Exception e) {
            // potentially more serious
            ErrorManager.getDefault().notify(ErrorManager.INFORMATIONAL, e);
        }
        // Did not work.
        Toolkit.getDefaultToolkit().beep();
    }

    /** Browse a document named by some URL.
    * HtmlBrowser provides more control in certain cases.
    * @param url URL of WWW or local document to be shown
    * @see org.openide.awt.HtmlBrowser
    * @deprecated Use {@link org.openide.awt.HtmlBrowser.URLDisplayer#showURL} instead.
    */
    public void showUrl (URL url) {
        HtmlBrowser.URLDisplayer.getDefault().showURL(url);
    }

    /** Support writing to the Output Window on the main tab.
    * @return a writer for the standard IDE output
     * @deprecated Use {@link IOProvider#getStdOut} instead.
    */
    public OutputWriter getStdOut() {
        return IOProvider.getDefault().getStdOut();
    }

    /** Support reading from and writing to a specific tab on the Output Window.
    * If a tab with the supplied name already exists,
    * a new tab with the same name will be created regardless.
    * @param name desired name of the tab
    * @return an InputOutput class for accessing the new tab
     * @deprecated Use {@link IOProvider#getIO} instead.
    */
    public InputOutput getIO(String name) {
        return getIO(name, true);
    }

    /** Support reading from and writing to a specific tab on the Output Window.
    * If a tab with the supplied name already exists,
    * a new tab with the same name will be created regardless.
    * @param name desired name of the tab
    * @param newIO if true new InputOutput is returned else already used InputOutput is returned.
    * @return an InputOutput class for accessing the new tab
     * @deprecated Use {@link IOProvider#getIO} instead.
    */
    public InputOutput getIO(String name, boolean newIO) {
        return IOProvider.getDefault().getIO(name, newIO);
    }

    /** Get global system clipboard.
    *
    * @return the clipboard
    * @deprecated Rather use Lookup on {@link ExClipboard}.
    */
    public ExClipboard getClipboard () {
        return (ExClipboard)Lookup.getDefault ().lookup (ExClipboard.class);
    }
    
    
    /** Get system control panel.
    * This permits all current user options to be examined, among other things.
    * @return the control panel
    * @deprecated Not useful.
    */
    public ControlPanel getControlPanel () {
        return (ControlPanel)Lookup.getDefault ().lookup (ControlPanel.class);
    }

    /** Getter for registry of services registered to the system.
    * @return the singleton with all services
    * @deprecated better to use Lookup to access the manager 
    *    (org.openide.ServiceType.Registry)Lookup.getDefault ().lookup (org.openide.ServiceType.Registry.class)
     * or simply find a particular service directly using Lookup
    */
    public ServiceType.Registry getServices () {
        return (org.openide.ServiceType.Registry)Lookup.getDefault ().lookup (org.openide.ServiceType.Registry.class);
    }

    /** Specialized manager that provides information about
    * actions. Currently it holds list of all context sensitive 
    * actions registered in the IDE.
    *
    *
    * @return the manager
    * @deprecated better to use Lookup to access the manager 
    *    (ActionManager)Lookup.getDefault ().lookup (ActionManager.class)
    */
    public ActionManager getActionManager () {
        return (ActionManager)Lookup.getDefault ().lookup (ActionManager.class);
    }

    /** Notify the user of an otherwise unhandled Java exception.
    * This method provides a convenient way of handling exceptions
    * occurring in the IDE. If you catch an exception and wish to inform
    * the user about it (though no response is required), you may send the message
    * to this method. The manager handles the rest.
    * 

    * The default implementation uses {@link #notify} to alert the user at a critical level.
    *
    * @param ex the exception
    * @deprecated Please use {@link org.openide.ErrorManager#getDefault} and {@link org.openide.ErrorManager#notify(Throwable)} instead.
    */
    public void notifyException (final Throwable ex) {
        ErrorManager.getDefault().notify(ex);
    }

    /** Notify the user of something in a message box, possibly with feedback.
     * 
To support both GUI and non-GUI use, this method may be called
     * from any thread (providing you are not holding any locks), and
     * will block the caller's thread. In GUI mode, it will be run in the AWT
     * event thread automatically. If you wish to hold locks, or do not
     * need the result object immediately or at all, please make this call
     * asynchronously (e.g. from the request processor).
    * @param descriptor description of the notification
    * @return the option that caused the message box to be closed
     * @deprecated Use {@link org.openide.DialogDisplayer} instead.
    */
    public Object notify (NotifyDescriptor descriptor) {
        return DialogDisplayer.getDefault().notify(descriptor);
    }

    /** Get a new standard dialog.
    * The dialog is designed and created as specified in the parameter.
    * Anyone who wants a dialog with standard buttons and
    * standard behavior should use this method.
    * 
Do not cache the resulting dialog if it
    * is modal and try to reuse it! Always create a new dialog
    * using this method if you need to show a dialog again.
    * Otherwise previously closed windows can reappear.
    *
    * @param descriptor general description of the dialog
     * @deprecated Use {@link org.openide.DialogDisplayer} instead.
    */
    public Dialog createDialog (DialogDescriptor descriptor) {
        return DialogDisplayer.getDefault().createDialog(descriptor);
    }

    /** Show text in the IDE's status line.
     * Can be called at any time, but remember the text may not be updated
     * until the AWT event queue is ready for it - so if you are hogging
     * the event queue the text will not appear until you release it
     * (finish your work or display a modal dialog, for example).
    * @param text the text to be shown
    * @deprecated Use {@link StatusDisplayer} instead.
    */
    public void setStatusText(String text) {
        StatusDisplayer.getDefault().setStatusText(text);
    }

    /** Get global keyboard-shortcut map.
     * @return default root of shortcuts
    * @deprecated better to use Lookup to access the manager 
    *    (Keymap)Lookup.getDefault ().lookup (Keymap.class)
     */
    public synchronized Keymap getGlobalKeymap() {
        Keymap k = (Keymap)Lookup.getDefault ().lookup (Keymap.class);
        if (keymapListener == null && k instanceof Observable) {
            keymapListener = new Observer() {
                public void update(Observable o, Object arg) {
                    firePropertyChange(PROP_GLOBAL_KEYMAP, null, null);
                }
            };
            ((Observable)k).addObserver(keymapListener);
        }
        return k;
    }
    private Observer keymapListener = null;

    /** Get default compilation engine.
     * @return default compilation engine in the system 
     * @deprecated Please use {@link CompilationEngine#getDefault} instead.
     */
    public CompilationEngine getCompilationEngine() {
        return CompilationEngine.getDefault();
    }

    /** Get default execution engine.
     * @return default execution engine in the system
     * @deprecated Please use {@link ExecutionEngine#getDefault} instead.
     */
    public ExecutionEngine getExecutionEngine() {
        return ExecutionEngine.getDefault();
    }

    /** Get the default debugger.
    *
    * @return default debugger in the system (never null)
    * @throws DebuggerNotFoundException in case of a problem (for example, there is no debugger installed)
    * @deprecated Please look for a Debugger in Lookup.
    */
    public Debugger getDebugger() throws DebuggerNotFoundException {
        Iterator it = getDebuggerResult().allInstances().iterator();
        if (it.hasNext()) return (Debugger) it.next();
        throw new DebuggerNotFoundException();
    }
    /** the debugger listener listening on adding/removing debugger*/
    private static LookupListener debuggerLsnr = null;
    /** the lookup query finding all registered debuggers */
    private static Lookup.Result debuggerLkpRes = null;
    /** get the lookup query finding all registered debuggers */
    private synchronized Lookup.Result getDebuggerResult() {
        if (debuggerLkpRes == null) {
            debuggerLkpRes = Lookup.getDefault().lookup(new Lookup.Template(Debugger.class));
            debuggerLsnr = new LookupListener() {
                public void resultChanged(LookupEvent ev) {
                    firePropertyChange(PROP_DEBUGGER, null, null);
                }
            };
            debuggerLkpRes.addLookupListener(debuggerLsnr);
        }
        return debuggerLkpRes;
    }

    /** Save all opened objects.
     * @deprecated Use {@link org.openide.LifecycleManager#saveAll} instead.
     */
    public void saveAll () {
        LifecycleManager.getDefault().saveAll();
    }

    /** Exit the IDE.
    * This method will return only if {@link java.lang.System#exit} fails, or if at least one component of the
    * system refuses to exit (because it cannot be properly shut down).
     * @deprecated Use {@link org.openide.LifecycleManager#exit} instead.
    */
    public void exit () {
        LifecycleManager.getDefault().exit();
    }

    /** Get default data loader pool.
    * @return default loader pool in the system
    * @deprecated Please look for the DataLoaderPool in Lookup.
    */
    public DataLoaderPool getLoaderPool () {
        return (DataLoaderPool)Lookup.getDefault ().lookup (DataLoaderPool.class);
    }

    /** Get default handler for node customization and exploration.
    * @return default node operation manager in the system
    * @deprecated Use {@link org.openide.nodes.NodeOperation#getDefault} instead.
    */
    public NodeOperation getNodeOperation ()  {
        return (NodeOperation)Lookup.getDefault ().lookup (NodeOperation.class);
    }

    /** Get object providing locations of important places in the system.
    * @return the descriptor
    * @deprecated Places is deprecated.
    */
    public Places getPlaces () {
        return (Places)Lookup.getDefault ().lookup (Places.class);
    }
        

    /** Opens specified project. Asks to save the previously opened project.
    * @exception IOException if error occurs accessing the project
    * @exception UserCancelException if the selection is interrupted by the user
     * @deprecated ProjectCookie no longer does anything useful.
    */
    public abstract void openProject (ProjectCookie project) throws IOException, UserCancelException;

    /** Get the exception manager for the IDE. It can be used to rafine
    * handling of exception and the way they are presented to the user.
    * 
    * @return the manager
    * @deprecated Please use {@link org.openide.ErrorManager#getDefault} instead.
    */
    public ErrorManager getErrorManager() {
        return ErrorManager.getDefault();
    }

    /** Get the window manager for the IDE.
    * The window manager is
    * responsible for the placement of windows and the handling of {@link org.openide.windows.TopComponent}s.
    * 

    * It is usually used only from the {@link org.openide.windows} package.
    *
    * @return default window manager
    * @deprecated As of 2.10. Now please use {@link WindowManager#getDefault} instead.
    */
    public WindowManager getWindowManager () {
        return WindowManager.getDefault ();
    }

    /** Provide access to the system classloader.
    * This classloader allows loading of
    * IDE implementation classes in the startup class path, and all installed modules as well.
    * It does not load any classes from the
    * user Repository.
    * 

    * The classloader may change from call to call, for example due to a module installation.
    * 

    * This classloader is also used as
    * the context classloader on all threads, automatically. However if a thread
    * is given a special context classloader, that is left alone (also on the thread's
    * children if created after the special context classloader is set).
    * @return the system classloader
    * @see Thread#getContextClassLoader
    * @deprecated Use Lookup on ClassLoader.
    */
    public ClassLoader systemClassLoader () {
        return (ClassLoader)Lookup.getDefault().lookup(ClassLoader.class);
    }

    /** Provide access to the user classloader.
     * This classloader can load everything provided by the {@link #systemClassLoader system one}, as
     * well as user classes in the {@link org.openide.filesystems.Repository Repository}.
    * 

    * The classloader may change from call to call, as it is affected by module and repository operations.
    * The returned classloader will reflect the current state of the
    * filesystem, taking into account modifications of .class files.
    *
    * @return the user classloader
    * @deprecated The closest replacement is 
    *             ClassPath.getClassLoader(...).
    *             Also you may try {@link NbClassLoader}, and use {@link NbClassLoader#setDefaultPermissions}
    *             with {@link AllPermission} if desired.
    */
    public ClassLoader currentClassLoader () {
        NbClassLoader l = new NbClassLoader();
        l.setDefaultPermissions(getAllPermissions());
        return l;
    }
    private static PermissionCollection allPermission;
    static synchronized PermissionCollection getAllPermissions() {
        if (allPermission == null) {
            allPermission = new Permissions();
            allPermission.add(new AllPermission());
        }
        return allPermission;
    }

    /** support for listeners */
    private PropertyChangeSupport change = new PropertyChangeSupport (this);

    /** Add a listener to property changes in the TopManager.
    * @param l the listener to add
    * @deprecated Use Lookup instead.
    */
    public void addPropertyChangeListener (PropertyChangeListener l) {
        change.addPropertyChangeListener (l);
    }

    /** Remove a listener to property changes in the TopManager.
    * @param l the listener to remove
    * @deprecated Use Lookup instead.
    */
    public void removePropertyChangeListener (PropertyChangeListener l) {
        change.addPropertyChangeListener (l);
    }

    /** Fires property change
    */
    private void firePropertyChange (String p, Object o, Object n) {
        change.firePropertyChange (p, o, n);
    }

    /** @deprecated Use {@link org.openide.nodes.NodeOperation} instead. */
    public static abstract class NodeOperation extends org.openide.nodes.NodeOperation {}

}