/*
 *                 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.spi.project.ui;

import org.netbeans.modules.project.uiapi.ProjectOpenedTrampoline;

/**
 * A hook which can be run when a project is "opened" or "closed" in the GUI.
 * 

 * The meaning of these terms is intentionally left vague, but typically opening
 * a project signals that the user may wish to work with it, so it would be a good
 * idea to make sure caches are up to date, etc. It is perfectly possible to load
 * and use (even run) projects which are not open, so any project type
 * provider using this hook cannot rely on it for basic semantics.
 * 
 * 

 * XXX run with mutex read or write held?
 * 
 * 

 * {@link #projectOpened} and {@link #projectClosed} are always called in pairs,
 * e.g. a project cannot be opened twice in a row without being closed in between.
 * Also a project left open at the end of one VM session will receive
 * {@link #projectClosed} before shutdown and (if an open project list is persisted)
 * {@link #projectOpened} sometime during the next startup.
 * 
 * 

 * An instance should be placed into a project's lookup to register it.
 * 
 * @see org.netbeans.api.project.Project#getLookup
 * @author Jesse Glick
 */
public abstract class ProjectOpenedHook {
    

    static {
        ProjectOpenedTrampoline.DEFAULT = new ProjectOpenedTrampoline() {
            public void projectOpened(ProjectOpenedHook hook) {
                hook.projectOpened();
            }
            public void projectClosed(ProjectOpenedHook hook) {
                hook.projectClosed();
            }
        };
    }

    
    /**
     * Default constructor for use by subclasses.
     */
    protected ProjectOpenedHook() {}
    
    /**
     * Called when a project is opened in the GUI.
     * 

     * 
Typical things to do here:
     * 

     * 

     * Update build scripts using
     * GeneratedFilesHelper.refreshBuildScript(...).
     * 
     * 
Call GlobalPathRegistry.register(...)
     * with source, compile, and boot paths known to the project.
     * 
Write property user.properties.file to private.properties
     * with absolute file path of the build.properties from 
     * the IDE's user directory. This makes it easier for the user to run headless 
     * builds in some cases. The IDE's user directory is defined in 
     * netbeans.user property of IDE's VM.
     * 
     * 
     */
    protected abstract void projectOpened();
    
    /**
     * Called when a project is closed in the GUI.
     * 

     * 
Typical things to do here:
     * 

     * 

     * Call
     * {@link org.netbeans.api.project.ProjectManager#saveProject}
     * as a precaution in case the project was modified in an unusual
     * way (e.g. using
     * {@link org.netbeans.spi.project.ExtensibleMetadataProvider}).
     * 
     * 
Call GlobalPathRegistry.unregister(...)
     * with the same paths are were previously registered.
     * 
     * 
     */
    protected abstract void projectClosed();
    
}